Debian Codegraph @

docs/releases/1.3.txt

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