PageRenderTime 195ms CodeModel.GetById 35ms RepoModel.GetById 1ms app.codeStats 0ms

Plain Text | 904 lines | 683 code | 221 blank | 0 comment | 0 complexity | c16900e5ebb95e27937f5c38c1ece8c5 MD5 | raw file
Possible License(s): BSD-3-Clause
  1. ========================
  2. Django 1.3 release notes
  3. ========================
  4. *March 23, 2011*
  5. Welcome to Django 1.3!
  6. Nearly a year in the making, Django 1.3 includes quite a few `new
  7. features`_ and plenty of bug fixes and improvements to existing
  8. features. These release notes cover the new features in 1.3, as well
  9. as some `backwards-incompatible changes`_ you'll want to be aware of
  10. when upgrading from Django 1.2 or older versions.
  11. Overview
  12. ========
  13. Django 1.3's focus has mostly been on resolving smaller, long-standing
  14. feature requests, but that hasn't prevented a few fairly significant
  15. new features from landing, including:
  16. * A framework for writing `class-based views`_.
  17. * Built-in support for `using Python's logging facilities`_.
  18. * Contrib support for `easy handling of static files`_.
  19. * Django's testing framework now supports (and ships with a copy of)
  20. `the unittest2 library`_.
  21. There's plenty more, of course; see the coverage of `new features`_
  22. below for a full rundown and details.
  23. Wherever possible, of course, new features are introduced in a
  24. backwards-compatible manner per :doc:`our API stability policy
  25. </misc/api-stability>` policy. As a result of this policy, Django 1.3
  26. `begins the deprecation process for some features`_.
  27. Some changes, unfortunately, are genuinely backwards-incompatible; in
  28. most cases these are due to security issues or bugs which simply
  29. couldn't be fixed any other way. Django 1.3 includes a few of these,
  30. and descriptions of them -- along with the (minor) modifications
  31. you'll need to make to handle them -- are documented in the list of
  32. `backwards-incompatible changes`_ below.
  33. .. _new features: `What's new in Django 1.3`_
  34. .. _backwards-incompatible changes: backwards-incompatible-changes-1.3_
  35. .. _using Python's logging facilities: `Logging`_
  36. .. _easy handling of static files: `Extended static files handling`_
  37. .. _the unittest2 library: `unittest2 support`_
  38. .. _begins the deprecation process for some features: `deprecated-features-1.3`_
  39. Python compatibility
  40. ====================
  41. The release of Django 1.2 was notable for having the first shift in
  42. Django's Python compatibility policy; prior to Django 1.2, Django
  43. supported any 2.x version of Python from 2.3 up. As of Django 1.2, the
  44. minimum requirement was raised to Python 2.4.
  45. Django 1.3 continues to support Python 2.4, but will be the final
  46. Django release series to do so; beginning with Django 1.4, the minimum
  47. supported Python version will be 2.5. A document outlining our full
  48. timeline for deprecating Python 2.x and moving to Python 3.x will be
  49. published shortly after the release of Django 1.3.
  50. What's new in Django 1.3
  51. ========================
  52. Class-based views
  53. ~~~~~~~~~~~~~~~~~
  54. Django 1.3 adds a framework that allows you to use a class as a view.
  55. This means you can compose a view out of a collection of methods that
  56. can be subclassed and overridden to provide common views of data without
  57. having to write too much code.
  58. Analogs of all the old function-based generic views have been
  59. provided, along with a completely generic view base class that can be
  60. used as the basis for reusable applications that can be easily
  61. extended.
  62. See :doc:`the documentation on class-based generic views</topics/class-based-views>`
  63. for more details. There is also a document to help you :doc:`convert
  64. your function-based generic views to class-based
  65. views</topics/generic-views-migration>`.
  66. Logging
  67. ~~~~~~~
  68. Django 1.3 adds framework-level support for Python's ``logging``
  69. module. This means you can now easily configure and control logging
  70. as part of your Django project. A number of logging handlers and
  71. logging calls have been added to Django's own code as well -- most
  72. notably, the error emails sent on a HTTP 500 server error are now
  73. handled as a logging activity. See :doc:`the documentation on Django's
  74. logging interface </topics/logging>` for more details.
  75. Extended static files handling
  76. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  77. Django 1.3 ships with a new contrib app --
  78. ``django.contrib.staticfiles`` -- to help developers handle the static
  79. media files (images, CSS, Javascript, etc.) that are needed to render
  80. a complete web page.
  81. In previous versions of Django, it was common to place static assets
  82. in :setting:`MEDIA_ROOT` along with user-uploaded files, and serve
  83. them both at :setting:`MEDIA_URL`. Part of the purpose of introducing
  84. the ``staticfiles`` app is to make it easier to keep static files
  85. separate from user-uploaded files. Static assets should now go in
  86. ``static/`` subdirectories of your apps or in other static assets
  87. directories listed in :setting:`STATICFILES_DIRS`, and will be served
  88. at :setting:`STATIC_URL`.
  89. See the :doc:`reference documentation of the app </ref/contrib/staticfiles>`
  90. for more details or learn how to :doc:`manage static files
  91. </howto/static-files>`.
  92. unittest2 support
  93. ~~~~~~~~~~~~~~~~~
  94. Python 2.7 introduced some major changes to the ``unittest`` library,
  95. adding some extremely useful features. To ensure that every Django
  96. project can benefit from these new features, Django ships with a copy
  97. of unittest2_, a copy of the Python 2.7 unittest library, backported
  98. for Python 2.4 compatibility.
  99. To access this library, Django provides the ``django.utils.unittest``
  100. module alias. If you are using Python 2.7, or you have installed
  101. ``unittest2`` locally, Django will map the alias to the installed
  102. version of the unittest library. Otherwise, Django will use its own
  103. bundled version of unittest2.
  104. To take advantage of this alias, simply use::
  105. from django.utils import unittest
  106. wherever you would have historically used::
  107. import unittest
  108. If you want to continue to use the base unittest library, you can --
  109. you just won't get any of the nice new unittest2 features.
  110. .. _unittest2:
  111. Transaction context managers
  112. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  113. Users of Python 2.5 and above may now use :ref:`transaction management functions
  114. <transaction-management-functions>` as `context managers`_. For example::
  115. with transaction.autocommit():
  116. # ...
  117. .. _context managers:
  118. For more information, see :ref:`transaction-management-functions`.
  119. Configurable delete-cascade
  120. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  121. :class:`~django.db.models.ForeignKey` and
  122. :class:`~django.db.models.OneToOneField` now accept an
  123. :attr:`~django.db.models.ForeignKey.on_delete` argument to customize behavior
  124. when the referenced object is deleted. Previously, deletes were always
  125. cascaded; available alternatives now include set null, set default, set to any
  126. value, protect, or do nothing.
  127. For more information, see the :attr:`~django.db.models.ForeignKey.on_delete`
  128. documentation.
  129. Contextual markers and comments for translatable strings
  130. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  131. For translation strings with ambiguous meaning, you can now
  132. use the ``pgettext`` function to specify the context of the string.
  133. And if you just want to add some information for translators, you
  134. can also add special translator comments in the source.
  135. For more information, see :ref:`contextual-markers` and
  136. :ref:`translator-comments`.
  137. Improvements to built-in template tags
  138. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  139. A number of improvements have been made to Django's built-in template tags:
  140. * The :ttag:`include` tag now accepts a ``with`` option, allowing
  141. you to specify context variables to the included template
  142. * The :ttag:`include` tag now accepts an ``only`` option, allowing
  143. you to exclude the current context from the included context
  144. * The :ttag:`with` tag now allows you to define multiple context
  145. variables in a single :ttag:`with` block.
  146. * The :ttag:`load` tag now accepts a ``from`` argument, allowing
  147. you to load a single tag or filter from a library.
  148. TemplateResponse
  149. ~~~~~~~~~~~~~~~~
  150. It can sometimes be beneficial to allow decorators or middleware to
  151. modify a response *after* it has been constructed by the view. For
  152. example, you may want to change the template that is used, or put
  153. additional data into the context.
  154. However, you can't (easily) modify the content of a basic
  155. :class:`~django.http.HttpResponse` after it has been constructed. To
  156. overcome this limitation, Django 1.3 adds a new
  157. :class:`~django.template.response.TemplateResponse` class. Unlike basic
  158. :class:`~django.http.HttpResponse` objects,
  159. :class:`~django.template.response.TemplateResponse` objects retain the details
  160. of the template and context that was provided by the view to compute
  161. the response. The final output of the response is not computed until
  162. it is needed, later in the response process.
  163. For more details, see the :doc:`documentation </ref/template-response>`
  164. on the :class:`~django.template.response.TemplateResponse` class.
  165. Caching changes
  166. ~~~~~~~~~~~~~~~
  167. Django 1.3 sees the introduction of several improvements to the
  168. Django's caching infrastructure.
  169. Firstly, Django now supports multiple named caches. In the same way
  170. that Django 1.2 introduced support for multiple database connections,
  171. Django 1.3 allows you to use the new :setting:`CACHES` setting to
  172. define multiple named cache connections.
  173. Secondly, :ref:`versioning <cache_versioning>`, :ref:`site-wide
  174. prefixing <cache_key_prefixing>` and :ref:`transformation
  175. <cache_key_transformation>` have been added to the cache API.
  176. Thirdly, :ref:`cache key creation <using-vary-headers>` has been
  177. updated to take the request query string into account on ``GET``
  178. requests.
  179. Finally, support for pylibmc_ has been added to the memcached cache
  180. backend.
  181. For more details, see the :doc:`documentation on
  182. caching in Django</topics/cache>`.
  183. .. _pylibmc:
  184. Permissions for inactive users
  185. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  186. If you provide a custom auth backend with ``supports_inactive_user``
  187. set to ``True``, an inactive ``User`` instance will check the backend
  188. for permissions. This is useful for further centralizing the
  189. permission handling. See the :doc:`authentication docs </topics/auth>`
  190. for more details.
  191. GeoDjango
  192. ~~~~~~~~~
  193. The GeoDjango test suite is now included when
  194. :ref:`running the Django test suite <running-unit-tests>` with ````
  195. when using :ref:`spatial database backends <spatial-backends>`.
  196. :setting:`MEDIA_URL` and :setting:`STATIC_URL` must end in a slash
  197. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  198. Previously, the :setting:`MEDIA_URL` setting only required a trailing slash if
  199. it contained a suffix beyond the domain name.
  200. A trailing slash is now *required* for :setting:`MEDIA_URL` and the new
  201. :setting:`STATIC_URL` setting as long as it is not blank. This ensures there is
  202. a consistent way to combine paths in templates.
  203. Project settings which provide either of both settings without a trailing
  204. slash will now raise a ``PendingDeprecationWarning``.
  205. In Django 1.4 this same condition will raise ``DeprecationWarning``,
  206. and in Django 1.5 will raise an ``ImproperlyConfigured`` exception.
  207. Everything else
  208. ~~~~~~~~~~~~~~~
  209. Django :doc:`1.1 <1.1>` and :doc:`1.2 <1.2>` added
  210. lots of big ticket items to Django, like multiple-database support,
  211. model validation, and a session-based messages framework. However,
  212. this focus on big features came at the cost of lots of smaller
  213. features.
  214. To compensate for this, the focus of the Django 1.3 development
  215. process has been on adding lots of smaller, long standing feature
  216. requests. These include:
  217. * Improved tools for accessing and manipulating the current
  218. :class:`~django.contrib.sites.models.Site` object in
  219. :doc:`the sites framework </ref/contrib/sites>`.
  220. * A :class:`~django.test.client.RequestFactory` for mocking requests
  221. in tests.
  222. * A new test assertion --
  223. :meth:`~django.test.TestCase.assertNumQueries` -- making it
  224. easier to test the database activity associated with a view.
  225. * Support for lookups spanning relations in admin's
  226. :attr:`~django.contrib.admin.ModelAdmin.list_filter`.
  227. * Support for HTTPOnly_ cookies.
  228. * :meth:`~django.core.mail.mail_admins()` and
  229. :meth:`~django.core.mail.mail_managers()` now support easily attaching
  230. HTML content to messages.
  231. * :class:`~django.core.mail.EmailMessage` now supports CC's.
  232. * Error emails now include more of the detail and formatting of the
  233. debug server error page.
  234. * :meth:`~django.template.Library.simple_tag` now accepts a
  235. ``takes_context`` argument, making it easier to write simple
  236. template tags that require access to template context.
  237. * A new :meth:`~django.shortcuts.render()` shortcut -- an alternative
  238. to :meth:`~django.shortcuts.render_to_response()` providing a
  239. :class:`~django.template.RequestContext` by default.
  240. * Support for combining :ref:`F() expressions <query-expressions>`
  241. with timedelta values when retrieving or updating database values.
  242. .. _HTTPOnly:
  243. .. _backwards-incompatible-changes-1.3:
  244. Backwards-incompatible changes in 1.3
  245. =====================================
  246. CSRF validation now applies to AJAX requests
  247. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  248. Prior to Django 1.2.5, Django's CSRF-prevention system exempted AJAX
  249. requests from CSRF verification; due to `security issues`_ reported to
  250. us, however, *all* requests are now subjected to CSRF
  251. verification. Consult :doc:`the Django CSRF documentation
  252. </ref/contrib/csrf>` for details on how to handle CSRF verification in
  253. AJAX requests.
  254. .. _security issues:
  255. Restricted filters in admin interface
  256. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  257. Prior to Django 1.2.5, the Django administrative interface allowed
  258. filtering on any model field or relation -- not just those specified
  259. in ``list_filter`` -- via query string manipulation. Due to `security
  260. issues`_ reported to us, however, query string lookup arguments in the
  261. admin must be for fields or relations specified in ``list_filter`` or
  262. ``date_hierarchy``.
  263. Deleting a model doesn't delete associated files
  264. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  265. In earlier Django versions, when a model instance containing a
  266. :class:`~django.db.models.FileField` was deleted,
  267. :class:`~django.db.models.FileField` took it upon itself to also delete the
  268. file from the backend storage. This opened the door to several data-loss
  269. scenarios, including rolled-back transactions and fields on different models
  270. referencing the same file. In Django 1.3, when a model is deleted the
  271. :class:`~django.db.models.FileField`'s
  272. :func:`~django.db.models.FileField.delete` method won't be called. If you
  273. need cleanup of orphaned files, you'll need to handle it yourself (for
  274. instance, with a custom management command that can be run manually or
  275. scheduled to run periodically via e.g. cron).
  276. PasswordInput default rendering behavior
  277. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  278. The :class:`~django.forms.PasswordInput` form widget, intended for use
  279. with form fields which represent passwords, accepts a boolean keyword
  280. argument ``render_value`` indicating whether to send its data back to
  281. the browser when displaying a submitted form with errors. Prior to
  282. Django 1.3, this argument defaulted to ``True``, meaning that the
  283. submitted password would be sent back to the browser as part of the
  284. form. Developers who wished to add a bit of additional security by
  285. excluding that value from the redisplayed form could instantiate a
  286. :class:`~django.forms.PasswordInput` passing ``render_value=False`` .
  287. Due to the sensitive nature of passwords, however, Django 1.3 takes
  288. this step automatically; the default value of ``render_value`` is now
  289. ``False``, and developers who want the password value returned to the
  290. browser on a submission with errors (the previous behavior) must now
  291. explicitly indicate this. For example::
  292. class LoginForm(forms.Form):
  293. username = forms.CharField(max_length=100)
  294. password = forms.CharField(widget=forms.PasswordInput(render_value=True))
  295. Clearable default widget for FileField
  296. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  297. Django 1.3 now includes a :class:`~django.forms.ClearableFileInput` form widget
  298. in addition to :class:`~django.forms.FileInput`. ``ClearableFileInput`` renders
  299. with a checkbox to clear the field's value (if the field has a value and is not
  300. required); ``FileInput`` provided no means for clearing an existing file from
  301. a ``FileField``.
  302. ``ClearableFileInput`` is now the default widget for a ``FileField``, so
  303. existing forms including ``FileField`` without assigning a custom widget will
  304. need to account for the possible extra checkbox in the rendered form output.
  305. To return to the previous rendering (without the ability to clear the
  306. ``FileField``), use the ``FileInput`` widget in place of
  307. ``ClearableFileInput``. For instance, in a ``ModelForm`` for a hypothetical
  308. ``Document`` model with a ``FileField`` named ``document``::
  309. from django import forms
  310. from myapp.models import Document
  311. class DocumentForm(forms.ModelForm):
  312. class Meta:
  313. model = Document
  314. widgets = {'document': forms.FileInput}
  315. New index on database session table
  316. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  317. Prior to Django 1.3, the database table used by the database backend
  318. for the :doc:`sessions </topics/http/sessions>` app had no index on
  319. the ``expire_date`` column. As a result, date-based queries on the
  320. session table -- such as the query that is needed to purge old
  321. sessions -- would be very slow if there were lots of sessions.
  322. If you have an existing project that is using the database session
  323. backend, you don't have to do anything to accommodate this change.
  324. However, you may get a significant performance boost if you manually
  325. add the new index to the session table. The SQL that will add the
  326. index can be found by running the :djadmin:`sqlindexes` admin
  327. command::
  328. python sqlindexes sessions
  329. No more naughty words
  330. ~~~~~~~~~~~~~~~~~~~~~
  331. Django has historically provided (and enforced) a list of profanities.
  332. The :doc:`comments app </ref/contrib/comments/index>` has enforced this
  333. list of profanities, preventing people from submitting comments that
  334. contained one of those profanities.
  335. Unfortunately, the technique used to implement this profanities list
  336. was woefully naive, and prone to the `Scunthorpe problem`_. Improving
  337. the built-in filter to fix this problem would require significant
  338. effort, and since natural language processing isn't the normal domain
  339. of a web framework, we have "fixed" the problem by making the list of
  340. prohibited words an empty list.
  341. If you want to restore the old behavior, simply put a
  342. :setting:`PROFANITIES_LIST` setting in your settings file that includes the
  343. words that you want to prohibit (see the `commit that implemented this
  344. change`_ if you want to see the list of words that was historically
  345. prohibited). However, if avoiding profanities is important to you, you
  346. would be well advised to seek out a better, less naive approach to the
  347. problem.
  348. .. _Scunthorpe problem:
  349. .. _commit that implemented this change:
  350. Localflavor changes
  351. ~~~~~~~~~~~~~~~~~~~
  352. Django 1.3 introduces the following backwards-incompatible changes to
  353. local flavors:
  354. * Canada (ca) -- The province "Newfoundland and Labrador" has had its
  355. province code updated to "NL", rather than the older "NF". In
  356. addition, the Yukon Territory has had its province code corrected to
  357. "YT", instead of "YK".
  358. * Indonesia (id) -- The province "Nanggroe Aceh Darussalam (NAD)" has
  359. been removed from the province list in favor of the new official
  360. designation "Aceh (ACE)".
  361. * United States of America (us) -- The list of "states" used by
  362. ``USStateField`` has expanded to include Armed Forces postal
  363. codes. This is backwards-incompatible if you were relying on
  364. ``USStateField`` not including them.
  365. FormSet updates
  366. ~~~~~~~~~~~~~~~
  367. In Django 1.3 ``FormSet`` creation behavior is modified slightly. Historically
  368. the class didn't make a distinction between not being passed data and being
  369. passed empty dictionary. This was inconsistent with behavior in other parts of
  370. the framework. Starting with 1.3 if you pass in empty dictionary the
  371. ``FormSet`` will raise a ``ValidationError``.
  372. For example with a ``FormSet``::
  373. >>> class ArticleForm(Form):
  374. ... title = CharField()
  375. ... pub_date = DateField()
  376. >>> ArticleFormSet = formset_factory(ArticleForm)
  377. the following code will raise a ``ValidationError``::
  378. >>> ArticleFormSet({})
  379. Traceback (most recent call last):
  380. ...
  381. ValidationError: [u'ManagementForm data is missing or has been tampered with']
  382. if you need to instantiate an empty ``FormSet``, don't pass in the data or use
  383. ``None``::
  384. >>> formset = ArticleFormSet()
  385. >>> formset = ArticleFormSet(data=None)
  386. Callables in templates
  387. ~~~~~~~~~~~~~~~~~~~~~~
  388. Previously, a callable in a template would only be called automatically as part
  389. of the variable resolution process if it was retrieved via attribute
  390. lookup. This was an inconsistency that could result in confusing and unhelpful
  391. behavior::
  392. >>> Template("{{ user.get_full_name }}").render(Context({'user': user}))
  393. u'Joe Bloggs'
  394. >>> Template("{{ full_name }}").render(Context({'full_name': user.get_full_name}))
  395. u'&lt;bound method User.get_full_name of &lt;...
  396. This has been resolved in Django 1.3 - the result in both cases will be ``u'Joe
  397. Bloggs'``. Although the previous behavior was not useful for a template language
  398. designed for web designers, and was never deliberately supported, it is possible
  399. that some templates may be broken by this change.
  400. Use of custom SQL to load initial data in tests
  401. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  402. Django provides a custom SQL hooks as a way to inject hand-crafted SQL
  403. into the database synchronization process. One of the possible uses
  404. for this custom SQL is to insert data into your database. If your
  405. custom SQL contains ``INSERT`` statements, those insertions will be
  406. performed every time your database is synchronized. This includes the
  407. synchronization of any test databases that are created when you run a
  408. test suite.
  409. However, in the process of testing the Django 1.3, it was discovered
  410. that this feature has never completely worked as advertised. When
  411. using database backends that don't support transactions, or when using
  412. a TransactionTestCase, data that has been inserted using custom SQL
  413. will not be visible during the testing process.
  414. Unfortunately, there was no way to rectify this problem without
  415. introducing a backwards incompatibility. Rather than leave
  416. SQL-inserted initial data in an uncertain state, Django now enforces
  417. the policy that data inserted by custom SQL will *not* be visible
  418. during testing.
  419. This change only affects the testing process. You can still use custom
  420. SQL to load data into your production database as part of the syncdb
  421. process. If you require data to exist during test conditions, you
  422. should either insert it using :ref:`test fixtures
  423. <topics-testing-fixtures>`, or using the ``setUp()`` method of your
  424. test case.
  425. Changed priority of translation loading
  426. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  427. Work has been done to simplify, rationalize and properly document the algorithm
  428. used by Django at runtime to build translations from the different translations
  429. found on disk, namely:
  430. For translatable literals found in Python code and templates (``'django'``
  431. gettext domain):
  432. * Priorities of translations included with applications listed in the
  433. :setting:`INSTALLED_APPS` setting were changed. To provide a behavior
  434. consistent with other parts of Django that also use such setting (templates,
  435. etc.) now, when building the translation that will be made available, the
  436. apps listed first have higher precedence than the ones listed later.
  437. * Now it is possible to override the translations shipped with applications by
  438. using the :setting:`LOCALE_PATHS` setting whose translations have now higher
  439. precedence than the translations of :setting:`INSTALLED_APPS` applications.
  440. The relative priority among the values listed in this setting has also been
  441. modified so the paths listed first have higher precedence than the
  442. ones listed later.
  443. * The ``locale`` subdirectory of the directory containing the settings, that
  444. usually coincides with and is know as the *project directory* is being
  445. deprecated in this release as a source of translations. (the precedence of
  446. these translations is intermediate between applications and :setting:`LOCALE_PATHS`
  447. translations). See the `corresponding deprecated features section`_
  448. of this document.
  449. For translatable literals found in Javascript code (``'djangojs'`` gettext
  450. domain):
  451. * Similarly to the ``'django'`` domain translations: Overriding of
  452. translations shipped with applications by using the :setting:`LOCALE_PATHS`
  453. setting is now possible for this domain too. These translations have higher
  454. precedence than the translations of Python packages passed to the
  455. :ref:`javascript_catalog view <javascript_catalog-view>`. Paths listed first
  456. have higher precedence than the ones listed later.
  457. * Translations under the ``locale`` subdirectory of the *project directory*
  458. have never been taken in account for JavaScript translations and remain in
  459. the same situation considering the deprecation of such location.
  460. .. _corresponding deprecated features section: loading_of_project_level_translations_
  461. Transaction management
  462. ~~~~~~~~~~~~~~~~~~~~~~
  463. When using managed transactions -- that is, anything but the default
  464. autocommit mode -- it is important when a transaction is marked as
  465. "dirty". Dirty transactions are committed by the
  466. :func:`~django.db.transaction.commit_on_success` decorator or the
  467. :class:`~django.middleware.transaction.TransactionMiddleware`, and
  468. :func:`~django.db.transaction.commit_manually` forces them to be
  469. closed explicitly; clean transactions "get a pass", which means they
  470. are usually rolled back at the end of a request when the connection is
  471. closed.
  472. Until Django 1.3, transactions were only marked dirty when Django was
  473. aware of a modifying operation performed in them; that is, either some
  474. model was saved, some bulk update or delete was performed, or the user
  475. explicitly called ``transaction.set_dirty()``. In Django 1.3, a
  476. transaction is marked dirty when *any* database operation is
  477. performed.
  478. As a result of this change, you no longer need to set a transaction
  479. dirty explicitly when you execute raw SQL or use a data-modifying
  480. ``SELECT``. However, you *do* need to explicitly close any read-only
  481. transactions that are being managed using
  482. :func:`~django.db.transaction.commit_manually`. For example::
  483. @transaction.commit_manually
  484. def my_view(request, name):
  485. obj = get_object_or_404(MyObject, name__iexact=name)
  486. return render_to_response('template', {'object':obj})
  487. Prior to Django 1.3, this would work without error. However, under
  488. Django 1.3, this will raise a
  489. :class:`~django.db.transaction.TransactionManagementError` because
  490. the read operation that retrieves the ``MyObject`` instance leaves the
  491. transaction in a dirty state.
  492. No password reset for inactive users
  493. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  494. Prior to Django 1.3, inactive users were able to request a password reset email
  495. and reset their password. In Django 1.3 inactive users will receive the same
  496. message as a nonexistent account.
  497. .. _deprecated-features-1.3:
  498. Features deprecated in 1.3
  499. ==========================
  500. Django 1.3 deprecates some features from earlier releases.
  501. These features are still supported, but will be gradually phased out
  502. over the next few release cycles.
  503. Code taking advantage of any of the features below will raise a
  504. ``PendingDeprecationWarning`` in Django 1.3. This warning will be
  505. silent by default, but may be turned on using Python's `warnings
  506. module`_, or by running Python with a ``-Wd`` or `-Wall` flag.
  507. .. _warnings module:
  508. In Django 1.4, these warnings will become a ``DeprecationWarning``,
  509. which is *not* silent. In Django 1.5 support for these features will
  510. be removed entirely.
  511. .. seealso::
  512. For more details, see the documentation :doc:`Django's release process
  513. </internals/release-process>` and our :doc:`deprecation timeline
  514. </internals/deprecation>`.
  515. ``mod_python`` support
  516. ~~~~~~~~~~~~~~~~~~~~~~
  517. The ``mod_python`` library has not had a release since 2007 or a commit since
  518. 2008. The Apache Foundation board voted to remove ``mod_python`` from the set
  519. of active projects in its version control repositories, and its lead developer
  520. has shifted all of his efforts toward the lighter, slimmer, more stable, and
  521. more flexible ``mod_wsgi`` backend.
  522. If you are currently using the ``mod_python`` request handler, you
  523. should redeploy your Django projects using another request handler.
  524. :doc:`mod_wsgi </howto/deployment/modwsgi>` is the request handler
  525. recommended by the Django project, but :doc:`FastCGI
  526. </howto/deployment/fastcgi>` is also supported. Support for
  527. ``mod_python`` deployment will be removed in Django 1.5.
  528. Function-based generic views
  529. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  530. As a result of the introduction of class-based generic views, the
  531. function-based generic views provided by Django have been deprecated.
  532. The following modules and the views they contain have been deprecated:
  533. * :mod:`django.views.generic.create_update`
  534. * :mod:`django.views.generic.date_based`
  535. * :mod:`django.views.generic.list_detail`
  536. * :mod:`django.views.generic.simple`
  537. Test client response ``template`` attribute
  538. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  539. Django's :ref:`test client <test-client>` returns
  540. :class:`~django.test.client.Response` objects annotated with extra testing
  541. information. In Django versions prior to 1.3, this included a
  542. :attr:`~django.test.client.Response.template` attribute containing information
  543. about templates rendered in generating the response: either None, a single
  544. :class:`~django.template.Template` object, or a list of
  545. :class:`~django.template.Template` objects. This inconsistency in return values
  546. (sometimes a list, sometimes not) made the attribute difficult to work with.
  547. In Django 1.3 the :attr:`~django.test.client.Response.template` attribute is
  548. deprecated in favor of a new :attr:`~django.test.client.Response.templates`
  549. attribute, which is always a list, even if it has only a single element or no
  550. elements.
  551. ``DjangoTestRunner``
  552. ~~~~~~~~~~~~~~~~~~~~
  553. As a result of the introduction of support for unittest2, the features
  554. of :class:`django.test.simple.DjangoTestRunner` (including fail-fast
  555. and Ctrl-C test termination) have been made redundant. In view of this
  556. redundancy, :class:`~django.test.simple.DjangoTestRunner` has been
  557. turned into an empty placeholder class, and will be removed entirely
  558. in Django 1.5.
  559. Changes to :ttag:`url` and :ttag:`ssi`
  560. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  561. Most template tags will allow you to pass in either constants or
  562. variables as arguments -- for example::
  563. {% extends "base.html" %}
  564. allows you to specify a base template as a constant, but if you have a
  565. context variable ``templ`` that contains the value ``base.html``::
  566. {% extends templ %}
  567. is also legal.
  568. However, due to an accident of history, the :ttag:`url` and
  569. :ttag:`ssi` are different. These tags use the second, quoteless
  570. syntax, but interpret the argument as a constant. This means it isn't
  571. possible to use a context variable as the target of a :ttag:`url` and
  572. :ttag:`ssi` tag.
  573. Django 1.3 marks the start of the process to correct this historical
  574. accident. Django 1.3 adds a new template library -- ``future`` -- that
  575. provides alternate implementations of the :ttag:`url` and :ttag:`ssi`
  576. template tags. This ``future`` library implement behavior that makes
  577. the handling of the first argument consistent with the handling of all
  578. other variables. So, an existing template that contains::
  579. {% url sample %}
  580. should be replaced with::
  581. {% load url from future %}
  582. {% url 'sample' %}
  583. The tags implementing the old behavior have been deprecated, and in
  584. Django 1.5, the old behavior will be replaced with the new behavior.
  585. To ensure compatibility with future versions of Django, existing
  586. templates should be modified to use the new ``future`` libraries and
  587. syntax.
  588. Changes to the login methods of the admin
  589. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  590. In previous version the admin app defined login methods in multiple locations
  591. and ignored the almost identical implementation in the already used auth app.
  592. A side effect of this duplication was the missing adoption of the changes made
  593. in r12634_ to support a broader set of characters for usernames.
  594. This release refactors the admin's login mechanism to use a subclass of the
  595. :class:`~django.contrib.auth.forms.AuthenticationForm` instead of a manual
  596. form validation. The previously undocumented method
  597. ``'django.contrib.admin.sites.AdminSite.display_login_form'`` has been removed
  598. in favor of a new :attr:`~django.contrib.admin.AdminSite.login_form`
  599. attribute.
  600. .. _r12634:
  601. ``reset`` and ``sqlreset`` management commands
  602. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  603. Those commands have been deprecated. The ``flush`` and ``sqlflush`` commands
  604. can be used to delete everything. You can also use ALTER TABLE or DROP TABLE
  605. statements manually.
  606. GeoDjango
  607. ~~~~~~~~~
  608. * The function-based :setting:`TEST_RUNNER` previously used to execute
  609. the GeoDjango test suite,
  610. :func:`django.contrib.gis.tests.run_gis_tests`, was deprecated for
  611. the class-based runner,
  612. :class:`django.contrib.gis.tests.GeoDjangoTestSuiteRunner`.
  613. * Previously, calling
  614. :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` would
  615. silently do nothing when GDAL wasn't available. Now, a
  616. :class:`~django.contrib.gis.geos.GEOSException` is properly raised
  617. to indicate possible faulty application code. A warning is now
  618. raised if :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` is
  619. called when the SRID of the geometry is less than 0 or ``None``.
  620. ``CZBirthNumberField.clean``
  621. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  622. Previously this field's ``clean()`` method accepted a second, gender, argument
  623. which allowed stronger validation checks to be made, however since this
  624. argument could never actually be passed from the Django form machinery it is
  625. now pending deprecation.
  626. ``CompatCookie``
  627. ~~~~~~~~~~~~~~~~
  628. Previously, ``django.http`` exposed an undocumented ``CompatCookie`` class,
  629. which was a bug-fix wrapper around the standard library ``SimpleCookie``. As the
  630. fixes are moving upstream, this is now deprecated - you should use ``from
  631. django.http import SimpleCookie`` instead.
  632. .. _loading_of_project_level_translations:
  633. Loading of *project-level* translations
  634. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  635. This release of Django starts the deprecation process for inclusion of
  636. translations located under the so-called *project path* in the translation
  637. building process performed at runtime. The :setting:`LOCALE_PATHS` setting can
  638. be used for the same task by adding the filesystem path to a ``locale``
  639. directory containing project-level translations to the value of that setting.
  640. Rationale for this decision:
  641. * The *project path* has always been a loosely defined concept
  642. (actually, the directory used for locating project-level
  643. translations is the directory containing the settings module) and
  644. there has been a shift in other parts of the framework to stop using
  645. it as a reference for location of assets at runtime.
  646. * Detection of the ``locale`` subdirectory tends to fail when the
  647. deployment scenario is more complex than the basic one. e.g. it
  648. fails when the settings module is a directory (ticket #10765).
  649. * There are potential strange development- and deployment-time
  650. problems like the fact that the ``project_dir/locale/`` subdir can
  651. generate spurious error messages when the project directory is added
  652. to the Python path (`` runserver`` does this) and then it
  653. clashes with the equally named standard library module, this is a
  654. typical warning message::
  655. /usr/lib/python2.6/ ImportWarning: Not importing directory '/path/to/project/locale': missing
  656. import locale, copy, os, re, struct, sys
  657. * This location wasn't included in the translation building process
  658. for JavaScript literals. This deprecation removes such
  659. inconsistency.
  660. ``PermWrapper`` moved to ``django.contrib.auth.context_processors``
  661. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  662. In Django 1.2, we began the process of changing the location of the
  663. ``auth`` context processor from ``django.core.context_processors`` to
  664. ``django.contrib.auth.context_processors``. However, the
  665. ``PermWrapper`` support class was mistakenly omitted from that
  666. migration. In Django 1.3, the ``PermWrapper`` class has also been
  667. moved to ``django.contrib.auth.context_processors``, along with the
  668. ``PermLookupDict`` support class. The new classes are functionally
  669. identical to their old versions; only the module location has changed.
  670. Removal of ``XMLField``
  671. ~~~~~~~~~~~~~~~~~~~~~~~
  672. When Django was first released, Django included an
  673. :class:`~django.db.models.XMLField` that performed automatic XML validation
  674. for any field input. However, this validation function hasn't been
  675. performed since the introduction of ``newforms``, prior to the 1.0 release.
  676. As a result, ``XMLField`` as currently implemented is functionally
  677. indistinguishable from a simple :class:`~django.db.models.TextField`.
  678. For this reason, Django 1.3 has fast-tracked the deprecation of
  679. ``XMLField`` -- instead of a two-release deprecation, ``XMLField``
  680. will be removed entirely in Django 1.4.
  681. It's easy to update your code to accommodate this change -- just
  682. replace all uses of ``XMLField`` with ``TextField``, and remove the
  683. ``schema_path`` keyword argument (if it is specified).