Debian Codegraph @

docs/releases/1.2.txt

raw
1 ========================
2 Django 1.2 release notes
3 ========================
4
5 *May 17, 2010.*
6
7 Welcome to Django 1.2!
8
9 Nearly a year in the making, Django 1.2 packs an impressive list of :ref:`new
10 features <whats-new-1.2>` and lots of bug fixes. These release notes cover
11 the new features, as well as important changes you'll want to be aware of when
12 upgrading from Django 1.1 or older versions.
13
14 Overview
15 ========
16
17 Django 1.2 introduces several large, important new features, including:
18
19 * Support for :ref:`multiple database connections
20 <support-for-multiple-databases>` in a single Django instance.
21
22 * `Model validation`_ inspired by Django's form validation.
23
24 * Vastly :ref:`improved protection against Cross-Site Request Forgery
25 <improved-csrf-protection>` (CSRF).
26
27 * A new :ref:`user "messages" framework <messages-framework>` with support for
28 cookie- and session-based message for both anonymous and authenticated users.
29
30 * Hooks for `object-level permissions`_, `permissions for anonymous users`_,
31 and :ref:`more flexible username requirements
32 <relaxed-requirements-for-usernames>`.
33
34 * Customization of email sending via `email backends`_.
35
36 * New :ref:`"smart" if template tag <new-in-1.2-smart-if>` which supports
37 comparison operators.
38
39 These are just the highlights; full details and a complete list of features
40 :ref:`may be found below <whats-new-1.2>`.
41
42 .. seealso::
43
44 `Django Advent`_ covered the release of Django 1.2 with a series of
45 articles and tutorials that cover some of the new features in depth.
46
47 .. _django advent: https://github.com/djangoadvent/djangoadvent-articles
48
49 Wherever possible these features have been introduced in a backwards-compatible
50 manner per :doc:`our API stability policy </misc/api-stability>` policy.
51
52 However, a handful of features *have* changed in ways that, for some users, will be
53 backwards-incompatible. The big changes are:
54
55 * Support for Python 2.3 has been dropped. See the full notes
56 below.
57
58 * The new CSRF protection framework is not backwards-compatible with
59 the old system. Users of the old system will not be affected until
60 the old system is removed in Django 1.4.
61
62 However, upgrading to the new CSRF protection framework requires a few
63 important backwards-incompatible changes, detailed in `CSRF Protection`_,
64 below.
65
66 * Authors of custom :class:`~django.db.models.Field` subclasses should be
67 aware that a number of methods have had a change in prototype, detailed
68 under `get_db_prep_*() methods on Field`_, below.
69
70 * The internals of template tags have changed somewhat; authors of custom
71 template tags that need to store state (e.g. custom control flow tags)
72 should ensure that their code follows the new rules for `stateful template
73 tags`_
74
75 * The :func:`~django.contrib.auth.decorators.user_passes_test`,
76 :func:`~django.contrib.auth.decorators.login_required`, and
77 :func:`~django.contrib.auth.decorators.permission_required`, decorators
78 from :mod:`django.contrib.auth` only apply to functions and no longer
79 work on methods. There's a simple one-line fix :ref:`detailed below
80 <user-passes-test-login-required-permission-required>`.
81
82 Again, these are just the big features that will affect the most users. Users
83 upgrading from previous versions of Django are heavily encouraged to consult
84 the complete list of :ref:`backwards-incompatible changes
85 <backwards-incompatible-changes-1.2>` and the list of :ref:`deprecated
86 features <deprecated-features-1.2>`.
87
88 Python compatibility
89 ====================
90
91 While not a new feature, it's important to note that Django 1.2
92 introduces the first shift in our Python compatibility policy since
93 Django's initial public debut. Previous Django releases were tested
94 and supported on 2.x Python versions from 2.3 up; Django 1.2, however,
95 drops official support for Python 2.3. As such, the minimum Python
96 version required for Django is now 2.4, and Django is tested and
97 supported on Python 2.4, 2.5 and 2.6, and will be supported on the
98 as-yet-unreleased Python 2.7.
99
100 This change should affect only a small number of Django users, as most
101 operating-system vendors today are shipping Python 2.4 or newer as
102 their default version. If you're still using Python 2.3, however,
103 you'll need to stick to Django 1.1 until you can upgrade; per
104 :doc:`our support policy </internals/release-process>`, Django 1.1 will
105 continue to receive security support until the release of Django 1.3.
106
107 A roadmap for Django's overall 2.x Python support, and eventual
108 transition to Python 3.x, is currently being developed, and will be
109 announced prior to the release of Django 1.3.
110
111 .. _whats-new-1.2:
112
113 What's new in Django 1.2
114 ========================
115
116 .. _support-for-multiple-databases:
117
118 Support for multiple databases
119 ------------------------------
120
121 Django 1.2 adds the ability to use :doc:`more than one database
122 </topics/db/multi-db>` in your Django project. Queries can be issued at a
123 specific database with the ``using()`` method on ``QuerySet`` objects.
124 Individual objects can be saved to a specific database by providing a ``using``
125 argument when you call ``save()``.
126
127 Model validation
128 ----------------
129
130 Model instances now have support for :ref:`validating their own data
131 <validating-objects>`, and both model and form fields now accept configurable
132 lists of :doc:`validators </ref/validators>` specifying reusable, encapsulated
133 validation behavior. Note, however, that validation must still be performed
134 explicitly. Simply invoking a model instance's ``save()`` method will not
135 perform any validation of the instance's data.
136
137 .. _improved-csrf-protection:
138
139 Improved CSRF protection
140 ------------------------
141
142 Django now has much improved protection against :doc:`Cross-Site Request Forgery
143 (CSRF) attacks</ref/csrf>`. This type of attack occurs when a malicious
144 website contains a link, a form button or some JavaScript that is intended to
145 perform some action on your website, using the credentials of a logged-in user
146 who visits the malicious site in their browser. A related type of attack, "login
147 CSRF," where an attacking site tricks a user's browser into logging into a site
148 with someone else's credentials, is also covered.
149
150 .. _messages-framework:
151
152 Messages framework
153 ------------------
154
155 Django now includes a robust and configurable :doc:`messages framework
156 </ref/contrib/messages>` with built-in support for cookie- and session-based
157 messaging, for both anonymous and authenticated clients. The messages framework
158 replaces the deprecated user message API and allows you to temporarily store
159 messages in one request and retrieve them for display in a subsequent request
160 (usually the next one).
161
162 Object-level permissions
163 ------------------------
164
165 A foundation for specifying permissions at the per-object level has been added.
166 Although there is no implementation of this in core, a custom authentication
167 backend can provide this implementation and it will be used by
168 :class:`django.contrib.auth.models.User`. See the :doc:`authentication docs
169 </topics/auth/index>` for more information.
170
171 Permissions for anonymous users
172 -------------------------------
173
174 If you provide a custom auth backend with ``supports_anonymous_user`` set to
175 ``True``, AnonymousUser will check the backend for permissions, just like
176 User already did. This is useful for centralizing permission handling - apps
177 can always delegate the question of whether something is allowed or not to
178 the authorization/authentication backend. See the :doc:`authentication
179 docs </topics/auth/index>` for more details.
180
181 .. _relaxed-requirements-for-usernames:
182
183 Relaxed requirements for usernames
184 ----------------------------------
185
186 The built-in :class:`~django.contrib.auth.models.User` model's
187 :attr:`~django.contrib.auth.models.User.username` field now allows a wider range
188 of characters, including ``@``, ``+``, ``.`` and ``-`` characters.
189
190 Email backends
191 --------------
192
193 You can now :ref:`configure the way that Django sends email
194 <topic-email-backends>`. Instead of using SMTP to send all email, you
195 can now choose a configurable email backend to send messages. If your
196 hosting provider uses a sandbox or some other non-SMTP technique for
197 sending mail, you can now construct an email backend that will allow
198 Django's standard :doc:`mail sending methods</topics/email>` to use
199 those facilities.
200
201 This also makes it easier to debug mail sending. Django ships with
202 backend implementations that allow you to send email to a
203 :ref:`file<topic-email-file-backend>`, to the
204 :ref:`console<topic-email-console-backend>`, or to
205 :ref:`memory<topic-email-memory-backend>`. You can even configure all
206 email to be :ref:`thrown away<topic-email-dummy-backend>`.
207
208 .. _new-in-1.2-smart-if:
209
210 "Smart" :ttag:`if` tag
211 ----------------------
212
213 The :ttag:`if` tag has been upgraded to be much more powerful. First, we've
214 added support for comparison operators. No longer will you have to type:
215
216 .. code-block:: html+django
217
218 {% ifnotequal a b %}
219 ...
220 {% endifnotequal %}
221
222 You can now do this:
223
224 .. code-block:: html+django
225
226 {% if a != b %}
227 ...
228 {% endif %}
229
230 There's really no reason to use ``{% ifequal %}`` or ``{% ifnotequal %}``
231 anymore, unless you're the nostalgic type.
232
233 The operators supported are ``==``, ``!=``, ``<``, ``>``, ``<=``, ``>=``,
234 ``in`` and ``not in``, all of which work like the Python operators, in addition
235 to ``and``, ``or`` and ``not``, which were already supported.
236
237 Also, filters may now be used in the ``if`` expression. For example:
238
239 .. code-block:: html+django
240
241 <div
242 {% if user.email|lower == message.recipient|lower %}
243 class="highlight"
244 {% endif %}
245 >{{ message }}</div>
246
247 Template caching
248 ----------------
249
250 In previous versions of Django, every time you rendered a template, it
251 would be reloaded from disk. In Django 1.2, you can use a :ref:`cached
252 template loader <template-loaders>` to load templates once, then
253 cache the result for every subsequent render. This can lead to a
254 significant performance improvement if your templates are broken into
255 lots of smaller subtemplates (using the ``{% extends %}`` or ``{%
256 include %}`` tags).
257
258 As a side effect, it is now much easier to support non-Django template
259 languages.
260
261 Class-based template loaders
262 ----------------------------
263
264 As part of the changes made to introduce `Template caching`_ and following
265 a general trend in Django, the template loaders API has been modified
266 to use template loading mechanisms that are encapsulated in Python classes as
267 opposed to functions, the only method available until Django 1.1.
268
269 All the template loaders :ref:`shipped with Django <template-loaders>` have
270 been ported to the new API but they still implement the function-based API and
271 the template core machinery still accepts function-based loaders (builtin or
272 third party) so there is no immediate need to modify your ``TEMPLATE_LOADERS``
273 setting in existing projects, things will keep working if you leave it
274 untouched up to and including the Django 1.3 release.
275
276 If you have developed your own custom template loaders we suggest to consider
277 porting them to a class-based implementation because the code for backwards
278 compatibility with function-based loaders starts its deprecation process in
279 Django 1.2 and will be removed in Django 1.4. There is a description of the
280 API these loader classes must implement in the template API reference and you
281 can also examine the source code of the loaders shipped with Django.
282
283 Natural keys in fixtures
284 ------------------------
285
286 Fixtures can now refer to remote objects using
287 :ref:`topics-serialization-natural-keys`. This lookup scheme is an
288 alternative to the normal primary-key based object references in a
289 fixture, improving readability and resolving problems referring to
290 objects whose primary key value may not be predictable or known.
291
292 Fast failure for tests
293 ----------------------
294
295 Both the :djadmin:`test` subcommand of ``django-admin.py`` and the
296 ``runtests.py`` script used to run Django's own test suite now support a
297 ``--failfast`` option. When specified, this option causes the test runner to
298 exit after encountering a failure instead of continuing with the test run. In
299 addition, the handling of ``Ctrl-C`` during a test run has been improved to
300 trigger a graceful exit from the test run that reports details of the tests that
301 were run before the interruption.
302
303 ``BigIntegerField``
304 -------------------
305
306 Models can now use a 64-bit :class:`~django.db.models.BigIntegerField` type.
307
308 Improved localization
309 ---------------------
310
311 Django's :doc:`internationalization framework </topics/i18n/index>` has been expanded
312 with locale-aware formatting and form processing. That means, if enabled, dates
313 and numbers on templates will be displayed using the format specified for the
314 current locale. Django will also use localized formats when parsing data in
315 forms. See :doc:`/topics/i18n/formatting` for more details.
316
317 ``readonly_fields`` in ``ModelAdmin``
318 -------------------------------------
319
320 :attr:`django.contrib.admin.ModelAdmin.readonly_fields` has been added to
321 enable non-editable fields in add/change pages for models and inlines. Field
322 and calculated values can be displayed alongside editable fields.
323
324 Customizable syntax highlighting
325 --------------------------------
326
327 You can now use a :envvar:`DJANGO_COLORS` environment variable to modify or
328 disable the colors used by ``django-admin.py`` to provide :ref:`syntax
329 highlighting <syntax-coloring>`.
330
331 Syndication feeds as views
332 --------------------------
333
334 :doc:`Syndication feeds </ref/contrib/syndication>` can now be used directly as
335 views in your :doc:`URLconf </topics/http/urls>`. This means that you can
336 maintain complete control over the URL structure of your feeds. Like any other
337 view, feeds views are passed a ``request`` object, so you can do anything you
338 would normally do with a view, like user based access control, or making a feed
339 a named URL.
340
341 GeoDjango
342 ---------
343
344 The most significant new feature for :doc:`GeoDjango </ref/contrib/gis/index>`
345 in 1.2 is support for multiple spatial databases. As a result,
346 the following :ref:`spatial database backends <spatial-backends>`
347 are now included:
348
349 * ``django.contrib.gis.db.backends.postgis``
350 * ``django.contrib.gis.db.backends.mysql``
351 * ``django.contrib.gis.db.backends.oracle``
352 * ``django.contrib.gis.db.backends.spatialite``
353
354 GeoDjango now supports the rich capabilities added in the PostGIS 1.5 release.
355 New features include support for the :ref:`geography type <geography-type>`
356 and enabling of :ref:`distance queries <distance-queries>`
357 with non-point geometries on geographic coordinate systems.
358
359 Support for 3D geometry fields was added, and may be enabled
360 by setting the :attr:`~django.contrib.gis.db.models.GeometryField.dim`
361 keyword to 3 in your :class:`~django.contrib.gis.db.models.GeometryField`.
362 The :class:`~django.contrib.gis.db.models.Extent3D` aggregate
363 and ``extent3d()`` ``GeoQuerySet`` method were added as a part of this feature.
364
365 The ``force_rhr()``, ``reverse_geom()``, and ``geohash()`` ``GeoQuerySet``
366 methods are new.
367
368 The GEOS interface was updated to use thread-safe C library functions when
369 available on the platform.
370
371 The GDAL interface now allows the user to set a
372 :attr:`~django.contrib.gis.gdal.Layer.spatial_filter` on the features returned
373 when iterating over a :class:`~django.contrib.gis.gdal.Layer`.
374
375 Finally, :doc:`GeoDjango's documentation </ref/contrib/gis/index>` is now
376 included with Django's and is no longer hosted separately at ``geodjango.org``.
377
378 .. _1.2-js-assisted-inlines:
379
380 JavaScript-assisted handling of inline related objects in the admin
381 -------------------------------------------------------------------
382
383 If a user has JavaScript enabled in their browser, the interface for
384 inline objects in the admin now allows inline objects to be
385 dynamically added and removed. Users without JavaScript-enabled
386 browsers will see no change in the behavior of inline objects.
387
388 New ``now`` template tag format specifier characters: ``c`` and ``u``
389 ---------------------------------------------------------------------
390
391 The argument to the :ttag:`now` has gained two new format characters:
392 ``c`` to specify that a datetime value should be formatted in ISO 8601
393 format, and ``u`` that allows output of the microseconds part of a
394 datetime or time value.
395
396 These are also available in others parts like the :tfilter:`date` and
397 :tfilter:`time` template filters, the ``humanize`` template tag library
398 and the new `format localization`_ framework.
399
400 .. _format localization: `Improved localization`_
401
402 .. _backwards-incompatible-changes-1.2:
403
404 Backwards-incompatible changes in 1.2
405 =====================================
406
407 Wherever possible the new features above have been introduced in a
408 backwards-compatible manner per :doc:`our API stability policy
409 </misc/api-stability>` policy. This means that practically all existing
410 code which worked with Django 1.1 will continue to work with Django
411 1.2; such code will, however, begin issuing warnings (see below for
412 details).
413
414 However, a handful of features *have* changed in ways that, for some
415 users, will be immediately backwards-incompatible. Those changes are
416 detailed below.
417
418 CSRF Protection
419 ---------------
420
421 We've made large changes to the way CSRF protection works, detailed in
422 :doc:`the CSRF documentation </ref/csrf>`. Here are the major changes you
423 should be aware of:
424
425 * ``CsrfResponseMiddleware`` and ``CsrfMiddleware`` have been deprecated and
426 will be removed completely in Django 1.4, in favor of a template tag that
427 should be inserted into forms.
428
429 * All contrib apps use a ``csrf_protect`` decorator to protect the view. This
430 requires the use of the ``csrf_token`` template tag in the template. If you
431 have used custom templates for contrib views, you MUST READ THE UPGRADE
432 INSTRUCTIONS to fix those templates.
433
434 .. admonition:: Documentation removed
435
436 The upgrade notes have been removed in current Django docs. Please refer
437 to the docs for Django 1.3 or older to find these instructions.
438
439 * ``CsrfViewMiddleware`` is included in ``MIDDLEWARE_CLASSES`` by
440 default. This turns on CSRF protection by default, so views that accept
441 POST requests need to be written to work with the middleware. Instructions
442 on how to do this are found in the CSRF docs.
443
444 * All of the CSRF has moved from contrib to core (with backwards
445 compatible imports in the old locations, which are deprecated and
446 will cease to be supported in Django 1.4).
447
448 ``get_db_prep_*()`` methods on ``Field``
449 ----------------------------------------
450
451 Prior to Django 1.2, a custom ``Field`` had the option of defining
452 several functions to support conversion of Python values into
453 database-compatible values. A custom field might look something like::
454
455 class CustomModelField(models.Field):
456 ...
457
458 def db_type(self): ...
459
460 def get_db_prep_save(self, value): ...
461
462 def get_db_prep_value(self, value): ...
463
464 def get_db_prep_lookup(self, lookup_type, value): ...
465
466 In 1.2, these three methods have undergone a change in prototype, and
467 two extra methods have been introduced::
468
469 class CustomModelField(models.Field):
470 ...
471
472 def db_type(self, connection): ...
473
474 def get_prep_value(self, value): ...
475
476 def get_prep_lookup(self, lookup_type, value): ...
477
478 def get_db_prep_save(self, value, connection): ...
479
480 def get_db_prep_value(self, value, connection, prepared=False): ...
481
482 def get_db_prep_lookup(self, lookup_type, value, connection, prepared=False): ...
483
484 These changes are required to support multiple databases --
485 ``db_type`` and ``get_db_prep_*`` can no longer make any assumptions
486 regarding the database for which it is preparing. The ``connection``
487 argument now provides the preparation methods with the specific
488 connection for which the value is being prepared.
489
490 The two new methods exist to differentiate general data-preparation
491 requirements from requirements that are database-specific. The
492 ``prepared`` argument is used to indicate to the database-preparation
493 methods whether generic value preparation has been performed. If
494 an unprepared (i.e., ``prepared=False``) value is provided to the
495 ``get_db_prep_*()`` calls, they should invoke the corresponding
496 ``get_prep_*()`` calls to perform generic data preparation.
497
498 We've provided conversion functions that will transparently
499 convert functions adhering to the old prototype into functions
500 compatible with the new prototype. However, these conversion functions
501 will be removed in Django 1.4, so you should upgrade your ``Field``
502 definitions to use the new prototype as soon as possible.
503
504 If your ``get_db_prep_*()`` methods made no use of the database
505 connection, you should be able to upgrade by renaming
506 ``get_db_prep_value()`` to ``get_prep_value()`` and
507 ``get_db_prep_lookup()`` to ``get_prep_lookup()``. If you require
508 database specific conversions, then you will need to provide an
509 implementation ``get_db_prep_*`` that uses the ``connection``
510 argument to resolve database-specific values.
511
512 Stateful template tags
513 ----------------------
514
515 Template tags that store rendering state on their ``Node`` subclass
516 have always been vulnerable to thread-safety and other issues; as of
517 Django 1.2, however, they may also cause problems when used with the
518 new :ref:`cached template loader<template-loaders>`.
519
520 All of the built-in Django template tags are safe to use with the cached
521 loader, but if you're using custom template tags that come from third
522 party packages, or from your own code, you should ensure that the
523 ``Node`` implementation for each tag is thread-safe. For more
524 information, see
525 :ref:`template tag thread safety considerations<template_tag_thread_safety>`.
526
527 You may also need to update your templates if you were relying on the
528 implementation of Django's template tags *not* being thread safe. The
529 :ttag:`cycle` tag is the most likely to be affected in this way,
530 especially when used in conjunction with the :ttag:`include` tag.
531 Consider the following template fragment:
532
533 .. code-block:: html+django
534
535 {% for object in object_list %}
536 {% include "subtemplate.html" %}
537 {% endfor %}
538
539 with a ``subtemplate.html`` that reads:
540
541 .. code-block:: html+django
542
543 {% cycle 'even' 'odd' %}
544
545 Using the non-thread-safe, pre-Django 1.2 renderer, this would output:
546
547 .. code-block:: text
548
549 even odd even odd ...
550
551 Using the thread-safe Django 1.2 renderer, you will instead get:
552
553 .. code-block:: text
554
555 even even even even ...
556
557 This is because each rendering of the :ttag:`include` tag is an
558 independent rendering. When the :ttag:`cycle` tag was not thread safe,
559 the state of the :ttag:`cycle` tag would leak between multiple
560 renderings of the same :ttag:`include`. Now that the :ttag:`cycle` tag
561 is thread safe, this leakage no longer occurs.
562
563 .. _user-passes-test-login-required-permission-required:
564
565 ``user_passes_test``, ``login_required`` and ``permission_required``
566 --------------------------------------------------------------------
567
568 ``django.contrib.auth.decorators`` provides the decorators
569 ``login_required``, ``permission_required`` and
570 ``user_passes_test``. Previously it was possible to use these
571 decorators both on functions (where the first argument is 'request')
572 and on methods (where the first argument is 'self', and the second
573 argument is 'request'). Unfortunately, flaws were discovered in the
574 code supporting this: it only works in limited circumstances, and
575 produces errors that are very difficult to debug when it does not
576 work.
577
578 For this reason, the 'auto adapt' behavior has been removed, and if
579 you are using these decorators on methods, you will need to manually
580 apply :func:`django.utils.decorators.method_decorator` to convert the
581 decorator to one that works with methods. For example, you would
582 change code from this::
583
584 class MyClass(object):
585 @login_required
586 def my_view(self, request):
587 pass
588
589 to this::
590
591 from django.utils.decorators import method_decorator
592
593
594 class MyClass(object):
595 @method_decorator(login_required)
596 def my_view(self, request):
597 pass
598
599 or::
600
601 from django.utils.decorators import method_decorator
602
603 login_required_m = method_decorator(login_required)
604
605
606 class MyClass(object):
607 @login_required_m
608 def my_view(self, request):
609 pass
610
611 For those of you who've been following the development trunk, this
612 change also applies to other decorators introduced since 1.1,
613 including ``csrf_protect``, ``cache_control`` and anything created
614 using ``decorator_from_middleware``.
615
616 :ttag:`if` tag changes
617 ----------------------
618
619 Due to new features in the :ttag:`if` template tag, it no longer
620 accepts 'and', 'or' and 'not' as valid **variable** names. Previously,
621 these strings could be used as variable names. Now, the keyword status
622 is always enforced, and template code such as ``{% if not %}`` or ``{%
623 if and %}`` will throw a ``TemplateSyntaxError``. Also, ``in`` is a
624 new keyword and so is not a valid variable name in this tag.
625
626 ``LazyObject``
627 --------------
628
629 ``LazyObject`` is an undocumented-but-often-used utility class used for lazily
630 wrapping other objects of unknown type.
631
632 In Django 1.1 and earlier, it handled introspection in a non-standard way,
633 depending on wrapped objects implementing a public method named
634 ``get_all_members()``. Since this could easily lead to name clashes, it has been
635 changed to use the standard Python introspection method, involving
636 ``__members__`` and ``__dir__()``.
637
638 If you used ``LazyObject`` in your own code
639 and implemented the ``get_all_members()`` method for wrapped objects, you'll need
640 to make a couple of changes:
641
642 First, if your class does not have special requirements for introspection (i.e.,
643 you have not implemented ``__getattr__()`` or other methods that allow for
644 attributes not discoverable by normal mechanisms), you can simply remove the
645 ``get_all_members()`` method. The default implementation on ``LazyObject`` will
646 do the right thing.
647
648 If you have more complex requirements for introspection, first rename the
649 ``get_all_members()`` method to ``__dir__()``. This is the standard
650 introspection method for Python 2.6 and above. If you require support for Python
651 versions earlier than 2.6, add the following code to the class::
652
653 __members__ = property(lambda self: self.__dir__())
654
655 ``__dict__`` on model instances
656 -------------------------------
657
658 Historically, the ``__dict__`` attribute of a model instance has only contained
659 attributes corresponding to the fields on a model.
660
661 In order to support multiple database configurations, Django 1.2 has
662 added a ``_state`` attribute to object instances. This attribute will
663 appear in ``__dict__`` for a model instance. If your code relies on
664 iterating over ``__dict__`` to obtain a list of fields, you must now
665 be prepared to handle or filter out the ``_state`` attribute.
666
667 Test runner exit status code
668 ----------------------------
669
670 The exit status code of the test runners (``tests/runtests.py`` and ``python
671 manage.py test``) no longer represents the number of failed tests, because a
672 failure of 256 or more tests resulted in a wrong exit status code. The exit
673 status code for the test runner is now 0 for success (no failing tests) and 1
674 for any number of test failures. If needed, the number of test failures can be
675 found at the end of the test runner's output.
676
677 Cookie encoding
678 ---------------
679
680 To fix bugs with cookies in Internet Explorer, Safari, and possibly
681 other browsers, our encoding of cookie values was changed so that the
682 comma and semicolon are treated as non-safe characters, and are
683 therefore encoded as ``\054`` and ``\073`` respectively. This could
684 produce backwards incompatibilities, especially if you are storing
685 comma or semi-colon in cookies and have JavaScript code that parses
686 and manipulates cookie values client-side.
687
688 ``ModelForm.is_valid()`` and ``ModelForm.errors``
689 -------------------------------------------------
690
691 Much of the validation work for ModelForms has been moved down to the model
692 level. As a result, the first time you call ``ModelForm.is_valid()``, access
693 ``ModelForm.errors`` or otherwise trigger form validation, your model will be
694 cleaned in-place. This conversion used to happen when the model was saved. If
695 you need an unmodified instance of your model, you should pass a copy to the
696 ``ModelForm`` constructor.
697
698 ``BooleanField`` on MySQL
699 --------------------------
700
701 In previous versions of Django, a model's ``BooleanField`` under MySQL
702 would return its value as either ``1`` or ``0``, instead of ``True``
703 or ``False``; for most people this wasn't a problem because ``bool``
704 is a subclass of ``int`` in Python. In Django 1.2, however,
705 ``BooleanField`` on MySQL correctly returns a real ``bool``. The only
706 time this should ever be an issue is if you were expecting the
707 ``repr`` of a ``BooleanField`` to print ``1`` or ``0``.
708
709 Changes to the interpretation of ``max_num`` in FormSets
710 --------------------------------------------------------
711
712 As part of enhancements made to the handling of FormSets, the default
713 value and interpretation of the ``max_num`` parameter to the
714 :ref:`django.forms.formsets.formset_factory() <formsets-max-num>` and
715 :ref:`django.forms.models.modelformset_factory()
716 <model-formsets-max-num>` functions has changed slightly. This
717 change also affects the way the
718 :attr:`~django.contrib.admin.InlineModelAdmin.max_num` argument is used for
719 inline admin objects.
720
721 Previously, the default value for ``max_num`` was ``0`` (zero).
722 FormSets then used the boolean value of ``max_num`` to determine if a
723 limit was to be imposed on the number of generated forms. The default
724 value of ``0`` meant that there was no default limit on the number of
725 forms in a FormSet.
726
727 Starting with 1.2, the default value for ``max_num`` has been changed
728 to ``None``, and FormSets will differentiate between a value of
729 ``None`` and a value of ``0``. A value of ``None`` indicates that no
730 limit on the number of forms is to be imposed; a value of ``0``
731 indicates that a maximum of 0 forms should be imposed. This doesn't
732 necessarily mean that no forms will be displayed -- see the
733 :ref:`ModelFormSet documentation <model-formsets-max-num>` for more
734 details.
735
736 If you were manually specifying a value of ``0`` for ``max_num``, you
737 will need to update your FormSet and/or admin definitions.
738
739 .. seealso::
740
741 :ref:`1.2-js-assisted-inlines`
742
743 ``email_re``
744 ------------
745
746 An undocumented regular expression for validating email addresses has been moved
747 from ``django.form.fields`` to ``django.core.validators``. You will need to
748 update your imports if you are using it.
749
750 .. _deprecated-features-1.2:
751
752 Features deprecated in 1.2
753 ==========================
754
755 Finally, Django 1.2 deprecates some features from earlier releases.
756 These features are still supported, but will be gradually phased out
757 over the next few release cycles.
758
759 Code taking advantage of any of the features below will raise a
760 ``PendingDeprecationWarning`` in Django 1.2. This warning will be
761 silent by default, but may be turned on using Python's :mod:`warnings`
762 module, or by running Python with a ``-Wd`` or ``-Wall`` flag.
763
764 In Django 1.3, these warnings will become a ``DeprecationWarning``,
765 which is *not* silent. In Django 1.4 support for these features will
766 be removed entirely.
767
768 .. seealso::
769
770 For more details, see the documentation :doc:`Django's release process
771 </internals/release-process>` and our :doc:`deprecation timeline
772 </internals/deprecation>`.`
773
774 .. _specifying-databases:
775
776 Specifying databases
777 --------------------
778
779 Prior to Django 1.2, Django used a number of settings to control
780 access to a single database. Django 1.2 introduces support for
781 multiple databases, and as a result the way you define database
782 settings has changed.
783
784 Any existing Django settings file will continue to work as expected
785 until Django 1.4. Until then, old-style database settings will be
786 automatically translated to the new-style format.
787
788 In the old-style (pre 1.2) format, you had a number of ``DATABASE_``
789 settings in your settings file. For example::
790
791 DATABASE_NAME = "test_db"
792 DATABASE_ENGINE = "postgresql_psycopg2"
793 DATABASE_USER = "myusername"
794 DATABASE_PASSWORD = "s3krit"
795
796 These settings are now in a dictionary named
797 :setting:`DATABASES`. Each item in the dictionary corresponds to a
798 single database connection, with the name ``'default'`` describing the
799 default database connection. The setting names have also been
800 shortened. The previous sample settings would now look like this::
801
802 DATABASES = {
803 "default": {
804 "NAME": "test_db",
805 "ENGINE": "django.db.backends.postgresql_psycopg2",
806 "USER": "myusername",
807 "PASSWORD": "s3krit",
808 }
809 }
810
811 This affects the following settings:
812
813 ========================================= ==========================
814 Old setting New Setting
815 ========================================= ==========================
816 ``DATABASE_ENGINE`` :setting:`ENGINE <DATABASE-ENGINE>`
817 ``DATABASE_HOST`` :setting:`HOST`
818 ``DATABASE_NAME`` :setting:`NAME`
819 ``DATABASE_OPTIONS`` :setting:`OPTIONS`
820 ``DATABASE_PASSWORD`` :setting:`PASSWORD`
821 ``DATABASE_PORT`` :setting:`PORT`
822 ``DATABASE_USER`` :setting:`USER`
823 ``TEST_DATABASE_CHARSET`` :setting:`TEST_CHARSET`
824 ``TEST_DATABASE_COLLATION`` :setting:`TEST_COLLATION`
825 ``TEST_DATABASE_NAME`` :setting:`TEST_NAME`
826 ========================================= ==========================
827
828 These changes are also required if you have manually created a database
829 connection using ``DatabaseWrapper()`` from your database backend of choice.
830
831 In addition to the change in structure, Django 1.2 removes the special
832 handling for the built-in database backends. All database backends
833 must now be specified by a fully qualified module name (i.e.,
834 ``django.db.backends.postgresql_psycopg2``, rather than just
835 ``postgresql_psycopg2``).
836
837 ``postgresql`` database backend
838 -------------------------------
839
840 The ``psycopg1`` library has not been updated since October 2005. As a
841 result, the ``postgresql`` database backend, which uses this library,
842 has been deprecated.
843
844 If you are currently using the ``postgresql`` backend, you should
845 migrate to using the ``postgresql_psycopg2`` backend. To update your
846 code, install the ``psycopg2`` library and change the
847 :setting:`ENGINE <DATABASE-ENGINE>` setting to use
848 ``django.db.backends.postgresql_psycopg2``.
849
850 CSRF response-rewriting middleware
851 ----------------------------------
852
853 ``CsrfResponseMiddleware``, the middleware that automatically inserted
854 CSRF tokens into ``POST`` forms in outgoing pages, has been deprecated
855 in favor of a template tag method (see above), and will be removed
856 completely in Django 1.4. ``CsrfMiddleware``, which includes the
857 functionality of ``CsrfResponseMiddleware`` and
858 ``CsrfViewMiddleware``, has likewise been deprecated.
859
860 Also, the CSRF module has moved from contrib to core, and the old
861 imports are deprecated, as described in the upgrading notes.
862
863 .. admonition:: Documentation removed
864
865 The upgrade notes have been removed in current Django docs. Please refer
866 to the docs for Django 1.3 or older to find these instructions.
867
868 ``SMTPConnection``
869 ------------------
870
871 The ``SMTPConnection`` class has been deprecated in favor of a generic
872 email backend API. Old code that explicitly instantiated an instance
873 of an SMTPConnection::
874
875 from django.core.mail import SMTPConnection
876
877 connection = SMTPConnection()
878 messages = get_notification_email()
879 connection.send_messages(messages)
880
881 ...should now call :func:`~django.core.mail.get_connection` to
882 instantiate a generic email connection::
883
884 from django.core.mail import get_connection
885
886 connection = get_connection()
887 messages = get_notification_email()
888 connection.send_messages(messages)
889
890 Depending on the value of the :setting:`EMAIL_BACKEND` setting, this
891 may not return an SMTP connection. If you explicitly require an SMTP
892 connection with which to send email, you can explicitly request an
893 SMTP connection::
894
895 from django.core.mail import get_connection
896
897 connection = get_connection("django.core.mail.backends.smtp.EmailBackend")
898 messages = get_notification_email()
899 connection.send_messages(messages)
900
901 If your call to construct an instance of ``SMTPConnection`` required
902 additional arguments, those arguments can be passed to the
903 :func:`~django.core.mail.get_connection` call::
904
905 connection = get_connection(
906 "django.core.mail.backends.smtp.EmailBackend", hostname="localhost", port=1234
907 )
908
909 User Messages API
910 -----------------
911
912 The API for storing messages in the user ``Message`` model (via
913 ``user.message_set.create``) is now deprecated and will be removed in Django
914 1.4 according to the standard :doc:`release process </internals/release-process>`.
915
916 To upgrade your code, you need to replace any instances of this::
917
918 user.message_set.create("a message")
919
920 ...with the following::
921
922 from django.contrib import messages
923
924 messages.add_message(request, messages.INFO, "a message")
925
926 Additionally, if you make use of the method, you need to replace the
927 following::
928
929 for message in user.get_and_delete_messages():
930 ...
931
932 ...with::
933
934 from django.contrib import messages
935
936 for message in messages.get_messages(request):
937 ...
938
939 For more information, see the full
940 :doc:`messages documentation </ref/contrib/messages>`. You should begin to
941 update your code to use the new API immediately.
942
943 Date format helper functions
944 ----------------------------
945
946 ``django.utils.translation.get_date_formats()`` and
947 ``django.utils.translation.get_partial_date_formats()`` have been deprecated
948 in favor of the appropriate calls to ``django.utils.formats.get_format()``,
949 which is locale-aware when ``USE_L10N`` is set to ``True``, and falls
950 back to default settings if set to ``False``.
951
952 To get the different date formats, instead of writing this::
953
954 from django.utils.translation import get_date_formats
955
956 date_format, datetime_format, time_format = get_date_formats()
957
958 ...use::
959
960 from django.utils import formats
961
962 date_format = formats.get_format("DATE_FORMAT")
963 datetime_format = formats.get_format("DATETIME_FORMAT")
964 time_format = formats.get_format("TIME_FORMAT")
965
966 Or, when directly formatting a date value::
967
968 from django.utils import formats
969
970 value_formatted = formats.date_format(value, "DATETIME_FORMAT")
971
972 The same applies to the globals found in ``django.forms.fields``:
973
974 * ``DEFAULT_DATE_INPUT_FORMATS``
975 * ``DEFAULT_TIME_INPUT_FORMATS``
976 * ``DEFAULT_DATETIME_INPUT_FORMATS``
977
978 Use ``django.utils.formats.get_format()`` to get the appropriate formats.
979
980 Function-based test runners
981 ---------------------------
982
983 Django 1.2 changes the test runner tools to use a class-based
984 approach. Old style function-based test runners will still work, but
985 should be updated to use the new :ref:`class-based runners
986 <topics-testing-test_runner>`.
987
988 .. _1.2-updating-feeds:
989
990 ``Feed`` in ``django.contrib.syndication.feeds``
991 ------------------------------------------------
992
993 The ``django.contrib.syndication.feeds.Feed`` class has been
994 replaced by the :class:`django.contrib.syndication.views.Feed` class.
995 The old ``feeds.Feed`` class is deprecated, and will be removed in
996 Django 1.4.
997
998 The new class has an almost identical API, but allows instances to be
999 used as views. For example, consider the use of the old framework in
1000 the following :doc:`URLconf </topics/http/urls>`::
1001
1002 from django.conf.urls.defaults import *
1003 from myproject.feeds import LatestEntries, LatestEntriesByCategory
1004
1005 feeds = {
1006 "latest": LatestEntries,
1007 "categories": LatestEntriesByCategory,
1008 }
1009
1010 urlpatterns = patterns(
1011 "",
1012 # ...
1013 (
1014 r"^feeds/(?P<url>.*)/$",
1015 "django.contrib.syndication.views.feed",
1016 {"feed_dict": feeds},
1017 ),
1018 # ...
1019 )
1020
1021 Using the new Feed class, these feeds can be deployed directly as views::
1022
1023 from django.conf.urls.defaults import *
1024 from myproject.feeds import LatestEntries, LatestEntriesByCategory
1025
1026 urlpatterns = patterns(
1027 "",
1028 # ...
1029 (r"^feeds/latest/$", LatestEntries()),
1030 (r"^feeds/categories/(?P<category_id>\d+)/$", LatestEntriesByCategory()),
1031 # ...
1032 )
1033
1034 If you currently use the ``feed()`` view, the ``LatestEntries`` class would
1035 often not need to be modified apart from subclassing the new
1036 :class:`~django.contrib.syndication.views.Feed` class. The exception is if
1037 Django was automatically working out the name of the template to use to render
1038 the feed's description and title elements (if you were not specifying the
1039 ``title_template`` and ``description_template`` attributes). You should ensure
1040 that you always specify ``title_template`` and ``description_template``
1041 attributes, or provide ``item_title()`` and ``item_description()`` methods.
1042
1043 However, ``LatestEntriesByCategory`` uses the ``get_object()`` method
1044 with the ``bits`` argument to specify a specific category to show. In
1045 the new :class:`~django.contrib.syndication.views.Feed` class,
1046 ``get_object()`` method takes a ``request`` and arguments from the
1047 URL, so it would look like this::
1048
1049 from django.contrib.syndication.views import Feed
1050 from django.shortcuts import get_object_or_404
1051 from myproject.models import Category
1052
1053
1054 class LatestEntriesByCategory(Feed):
1055 def get_object(self, request, category_id):
1056 return get_object_or_404(Category, id=category_id)
1057
1058 # ...
1059
1060 Additionally, the ``get_feed()`` method on ``Feed`` classes now take
1061 different arguments, which may impact you if you use the ``Feed``
1062 classes directly. Instead of just taking an optional ``url`` argument,
1063 it now takes two arguments: the object returned by its own
1064 ``get_object()`` method, and the current ``request`` object.
1065
1066 To take into account ``Feed`` classes not being initialized for each
1067 request, the ``__init__()`` method now takes no arguments by default.
1068 Previously it would have taken the ``slug`` from the URL and the
1069 ``request`` object.
1070
1071 In accordance with `RSS best practices`_, RSS feeds will now include
1072 an ``atom:link`` element. You may need to update your tests to take
1073 this into account.
1074
1075 For more information, see the full :doc:`syndication framework
1076 documentation </ref/contrib/syndication>`.
1077
1078 .. _RSS best practices: https://www.rssboard.org/rss-profile
1079
1080 Technical message IDs
1081 ---------------------
1082
1083 Up to version 1.1 Django used technical message IDs
1084 to provide localizers the possibility to translate date and time formats. They
1085 were translatable :term:`translation strings <translation string>` that could
1086 be recognized because they were all upper case (for example
1087 :setting:`DATETIME_FORMAT`, :setting:`DATE_FORMAT`, :setting:`TIME_FORMAT`).
1088 They have been deprecated in favor of the new :doc:`/topics/i18n/formatting`
1089 infrastructure that allows localizers to specify that information in a
1090 ``formats.py`` file in the corresponding ``django/conf/locale/<locale name>/``
1091 directory.
1092
1093 GeoDjango
1094 ---------
1095
1096 To allow support for multiple databases, the GeoDjango database internals were
1097 changed substantially. The largest backwards-incompatible change is that
1098 the module ``django.contrib.gis.db.backend`` was renamed to
1099 :mod:`django.contrib.gis.db.backends`, where the full-fledged
1100 :ref:`spatial database backends <spatial-backends>` now exist. The
1101 following sections provide information on the most-popular APIs that
1102 were affected by these changes.
1103
1104 ``SpatialBackend``
1105 ~~~~~~~~~~~~~~~~~~
1106
1107 Prior to the creation of the separate spatial backends, the
1108 ``django.contrib.gis.db.backend.SpatialBackend`` object was
1109 provided as an abstraction to introspect on the capabilities of
1110 the spatial database. All of the attributes and routines provided by
1111 ``SpatialBackend`` are now a part of the ``ops`` attribute of the
1112 database backend.
1113
1114 The old module ``django.contrib.gis.db.backend`` is still provided
1115 for backwards-compatibility access to a ``SpatialBackend`` object,
1116 which is just an alias to the ``ops`` module of the
1117 *default* spatial database connection.
1118
1119 Users that were relying on undocumented modules and objects
1120 within ``django.contrib.gis.db.backend``, rather the abstractions
1121 provided by ``SpatialBackend``, are required to modify their code.
1122 For example, the following import which would work in 1.1 and
1123 below::
1124
1125 from django.contrib.gis.db.backend.postgis import PostGISAdaptor
1126
1127 Would need to be changed::
1128
1129 from django.db import connection
1130
1131 PostGISAdaptor = connection.ops.Adapter
1132
1133 ``SpatialRefSys`` and ``GeometryColumns`` models
1134 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1135
1136 In previous versions of GeoDjango, :mod:`django.contrib.gis.db.models`
1137 had ``SpatialRefSys`` and ``GeometryColumns`` models for querying
1138 the OGC spatial metadata tables ``spatial_ref_sys`` and ``geometry_columns``,
1139 respectively.
1140
1141 While these aliases are still provided, they are only for the
1142 *default* database connection and exist only if the default connection
1143 is using a supported spatial database backend.
1144
1145 .. note::
1146
1147 Because the table structure of the OGC spatial metadata tables
1148 differs across spatial databases, the ``SpatialRefSys`` and
1149 ``GeometryColumns`` models can no longer be associated with
1150 the ``gis`` application name. Thus, no models will be returned
1151 when using the ``get_models`` method in the following example:
1152
1153 .. code-block:: pycon
1154
1155 >>> from django.db.models import get_app, get_models
1156 >>> get_models(get_app("gis"))
1157 []
1158
1159 To get the correct ``SpatialRefSys`` and ``GeometryColumns``
1160 for your spatial database use the methods provided by the spatial backend:
1161
1162 .. code-block:: pycon
1163
1164 >>> from django.db import connections
1165 >>> SpatialRefSys = connections["my_spatialite"].ops.spatial_ref_sys()
1166 >>> GeometryColumns = connections["my_postgis"].ops.geometry_columns()
1167
1168 .. note::
1169
1170 When using the models returned from the ``spatial_ref_sys()`` and
1171 ``geometry_columns()`` method, you'll still need to use the
1172 correct database alias when querying on the non-default connection.
1173 In other words, to ensure that the models in the example above
1174 use the correct database::
1175
1176 sr_qs = SpatialRefSys.objects.using("my_spatialite").filter(...)
1177 gc_qs = GeometryColumns.objects.using("my_postgis").filter(...)
1178
1179 Language code ``no``
1180 --------------------
1181
1182 The currently used language code for Norwegian Bokmål ``no`` is being
1183 replaced by the more common language code ``nb``.
1184
1185 Function-based template loaders
1186 -------------------------------
1187
1188 Django 1.2 changes the template loading mechanism to use a class-based
1189 approach. Old style function-based template loaders will still work, but should
1190 be updated to use the new class-based template loaders.