/docs/releases/1.3.txt

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