========================

Django 1.2 release notes

========================

*May 17, 2010.*

Welcome to Django 1.2!

Nearly a year in the making, Django 1.2 packs an impressive list of `new

features`_ and lots of bug fixes. These release notes cover the new features,

as well as important changes you'll want to be aware of when upgrading from

Django 1.1 or older versions.

.. _new features: `What's new in Django 1.2`_

Overview

========

Django 1.2 introduces several large, important new features, including:

    * Support for `multiple database connections`_ in a single Django instance.

    * `Model validation`_ inspired by Django's form validation.

    * Vastly `improved protection against Cross-Site Request Forgery`_ (CSRF).

    * A new `user "messages" framework`_ with support for cookie- and session-based

      message for both anonymous and authenticated users.

    * Hooks for `object-level permissions`_, `permissions for anonymous users`_,

      and `more flexible username requirements`_.

    * Customization of e-mail sending via `e-mail backends`_.

    * New :ref:`"smart" if template tag <new-in-1.2-smart-if>` which supports

      comparison operators.

.. _multiple database connections: `support for multiple databases`_

.. _improved protection against Cross-Site Request Forgery: `improved CSRF protection`_

.. _user "messages" framework: `messages framework`_

.. _more flexible username requirements: `relaxed requirements for usernames`_

These are just the highlights; full details and a complete list of features `may

be found below`_.

.. _may be found below: `what's new in django 1.2`_

.. seealso::

    `Django Advent`_ covered the release of Django 1.2 with a series of

    articles and tutorials that cover some of the new features in depth.

.. _django advent: http://djangoadvent.com/

Wherever possible these features have been introduced in a backwards-compatible

manner per :doc:`our API stability policy </misc/api-stability>` policy.

However, a handful of features *have* changed in ways that, for some users, will be

backwards-incompatible. The big changes are:

    * Support for Python 2.3 has been dropped. See the full notes

      below.

    * The new CSRF protection framework is not backwards-compatible with

      the old system. Users of the old system will not be affected until

      the old system is removed in Django 1.4.

      However, upgrading to the new CSRF protection framework requires a few

      important backwards-incompatible changes, detailed in `CSRF Protection`_,

      below.

    * Authors of custom :class:`~django.db.models.Field` subclasses should be

      aware that a number of methods have had a change in prototype, detailed

      under `get_db_prep_*() methods on Field`_, below.

    * The internals of template tags have changed somewhat; authors of custom

      template tags that need to store state (e.g. custom control flow tags)

      should ensure that their code follows the new rules for `stateful template

      tags`_

    * The :func:`~django.contrib.auth.decorators.user_passes_test`,

      :func:`~django.contrib.auth.decorators.login_required`, and

      :func:`~django.contrib.auth.decorators.permission_required`, decorators

      from :mod:`django.contrib.auth` only apply to functions and no longer

      work on methods. There's a simple one-line fix `detailed below`_.

.. _detailed below: `user_passes_test, login_required and permission_required`_

Again, these are just the big features that will affect the most users. Users

upgrading from previous versions of Django are heavily encouraged to consult

the complete list of :ref:`backwards-incompatible changes

<backwards-incompatible-changes-1.2>` and the list of :ref:`deprecated

features <deprecated-features-1.2>`.

Python compatibility

====================

While not a new feature, it's important to note that Django 1.2

introduces the first shift in our Python compatibility policy since

Django's initial public debut. Previous Django releases were tested

and supported on 2.x Python versions from 2.3 up; Django 1.2, however,

drops official support for Python 2.3. As such, the minimum Python

version required for Django is now 2.4, and Django is tested and

supported on Python 2.4, 2.5 and 2.6, and will be supported on the

as-yet-unreleased Python 2.7.

This change should affect only a small number of Django users, as most

operating-system vendors today are shipping Python 2.4 or newer as

their default version. If you're still using Python 2.3, however,

you'll need to stick to Django 1.1 until you can upgrade; per

:doc:`our support policy </internals/release-process>`, Django 1.1 will

continue to receive security support until the release of Django 1.3.

A roadmap for Django's overall 2.x Python support, and eventual

transition to Python 3.x, is currently being developed, and will be

announced prior to the release of Django 1.3.

What's new in Django 1.2

========================

Support for multiple databases

------------------------------

Django 1.2 adds the ability to use :doc:`more than one database

</topics/db/multi-db>` in your Django project. Queries can be issued at a

specific database with the `using()` method on ``QuerySet`` objects. Individual

objects can be saved to a specific database by providing a ``using`` argument

when you call ``save()``.

Model validation

----------------

Model instances now have support for :ref:`validating their own data

<validating-objects>`, and both model and form fields now accept configurable

lists of :doc:`validators </ref/validators>` specifying reusable, encapsulated

validation behavior. Note, however, that validation must still be performed

explicitly. Simply invoking a model instance's ``save()`` method will not

perform any validation of the instance's data.

Improved CSRF protection

------------------------

Django now has much improved protection against :doc:`Cross-Site Request Forgery

(CSRF) attacks</ref/contrib/csrf>`. This type of attack occurs when a malicious

Web site contains a link, a form button or some JavaScript that is intended to

perform some action on your Web site, using the credentials of a logged-in user

who visits the malicious site in their browser. A related type of attack, "login

CSRF," where an attacking site tricks a user's browser into logging into a site

with someone else's credentials, is also covered.

Messages framework

------------------

Django now includes a robust and configurable :doc:`messages framework

</ref/contrib/messages>` with built-in support for cookie- and session-based

messaging, for both anonymous and authenticated clients. The messages framework

replaces the deprecated user message API and allows you to temporarily store

messages in one request and retrieve them for display in a subsequent request

(usually the next one).

Object-level permissions

------------------------

A foundation for specifying permissions at the per-object level has been added.

Although there is no implementation of this in core, a custom authentication

backend can provide this implementation and it will be used by

:class:`django.contrib.auth.models.User`. See the :doc:`authentication docs

</topics/auth>` for more information.

Permissions for anonymous users

-------------------------------

If you provide a custom auth backend with ``supports_anonymous_user`` set to

``True``, AnonymousUser will check the backend for permissions, just like

User already did.  This is useful for centralizing permission handling - apps

can always delegate the question of whether something is allowed or not to

the authorization/authentication backend. See the :doc:`authentication

docs </topics/auth>` for more details.

Relaxed requirements for usernames

----------------------------------

The built-in :class:`~django.contrib.auth.models.User` model's

:attr:`~django.contrib.auth.models.User.username` field now allows a wider range

of characters, including ``@``, ``+``, ``.`` and ``-`` characters.

E-mail backends

---------------

You can now :ref:`configure the way that Django sends e-mail

<topic-email-backends>`. Instead of using SMTP to send all e-mail, you

can now choose a configurable e-mail backend to send messages. If your

hosting provider uses a sandbox or some other non-SMTP technique for

sending mail, you can now construct an e-mail backend that will allow

Django's standard :doc:`mail sending methods</topics/email>` to use

those facilities.

This also makes it easier to debug mail sending. Django ships with

backend implementations that allow you to send e-mail to a

:ref:`file<topic-email-file-backend>`, to the

:ref:`console<topic-email-console-backend>`, or to

:ref:`memory<topic-email-memory-backend>`. You can even configure all

e-mail to be :ref:`thrown away<topic-email-dummy-backend>`.

.. _new-in-1.2-smart-if:

"Smart" :ttag:`if` tag

----------------------

The :ttag:`if` tag has been upgraded to be much more powerful. First, we've

added support for comparison operators. No longer will you have to type:

.. code-block:: html+django

    {% ifnotequal a b %}

     ...

    {% endifnotequal %}

You can now do this:

.. code-block:: html+django

    {% if a != b %}

     ...

    {% endif %}

There's really no reason to use ``{% ifequal %}`` or ``{% ifnotequal %}``

anymore, unless you're the nostalgic type.

The operators supported are ``==``, ``!=``, ``<``, ``>``, ``<=``, ``>=``,

``in`` and ``not in``, all of which work like the Python operators, in addition

to ``and``, ``or`` and ``not``, which were already supported.

Also, filters may now be used in the ``if`` expression. For example:

.. code-block:: html+django

      <div

        {% if user.email|lower == message.recipient|lower %}

          class="highlight"

        {% endif %}

      >{{ message }}</div>

Template caching

----------------

In previous versions of Django, every time you rendered a template, it

would be reloaded from disk. In Django 1.2, you can use a :ref:`cached

template loader <template-loaders>` to load templates once, then

cache the result for every subsequent render. This can lead to a

significant performance improvement if your templates are broken into

lots of smaller subtemplates (using the ``{% extends %}`` or ``{%

include %}`` tags).

As a side effect, it is now much easier to support non-Django template

languages. For more details, see the :ref:`notes on supporting

non-Django template languages<topic-template-alternate-language>`.

Natural keys in fixtures

------------------------

Fixtures can now refer to remote objects using

:ref:`topics-serialization-natural-keys`. This lookup scheme is an

alternative to the normal primary-key based object references in a

fixture, improving readability and resolving problems referring to

objects whose primary key value may not be predictable or known.

Fast failure for tests

----------------------

Both the :djadmin:`test` subcommand of ``django-admin.py`` and the

``runtests.py`` script used to run Django's own test suite now support a

``--failfast`` option. When specified, this option causes the test runner to

exit after encountering a failure instead of continuing with the test run. In

addition, the handling of ``Ctrl-C`` during a test run has been improved to

trigger a graceful exit from the test run that reports details of the tests that

were run before the interruption.

``BigIntegerField``

-------------------

Models can now use a 64-bit :class:`~django.db.models.BigIntegerField` type.

Improved localization

---------------------

Django's :doc:`internationalization framework </topics/i18n/index>` has been expanded

with locale-aware formatting and form processing. That means, if enabled, dates

and numbers on templates will be displayed using the format specified for the

current locale. Django will also use localized formats when parsing data in

forms. See :ref:`Format localization <format-localization>` for more details.

``readonly_fields`` in ``ModelAdmin``

-------------------------------------

:attr:`django.contrib.admin.ModelAdmin.readonly_fields` has been added to

enable non-editable fields in add/change pages for models and inlines. Field

and calculated values can be displayed alongside editable fields.

Customizable syntax highlighting

--------------------------------

You can now use a ``DJANGO_COLORS`` environment variable to modify or disable

the colors used by ``django-admin.py`` to provide :ref:`syntax highlighting

<syntax-coloring>`.

Syndication feeds as views

--------------------------

:doc:`Syndication feeds </ref/contrib/syndication>` can now be used directly as

views in your :doc:`URLconf </topics/http/urls>`. This means that you can

maintain complete control over the URL structure of your feeds. Like any other

view, feeds views are passed a ``request`` object, so you can do anything you

would normally do with a view, like user based access control, or making a feed

a named URL.

GeoDjango

---------

The most significant new feature for :doc:`GeoDjango </ref/contrib/gis/index>`

in 1.2 is support for multiple spatial databases.  As a result,

the following :ref:`spatial database backends <spatial-backends>`

are now included:

* :mod:`django.contrib.gis.db.backends.postgis`

* :mod:`django.contrib.gis.db.backends.mysql`

* :mod:`django.contrib.gis.db.backends.oracle`

* :mod:`django.contrib.gis.db.backends.spatialite`

GeoDjango now supports the rich capabilities added

in the `PostGIS 1.5 release <http://postgis.refractions.net/documentation/manual-1.5/>`_.

New features include suppport for the the :ref:`geography type <geography-type>`

and enabling of :ref:`distance queries <distance-queries>`

with non-point geometries on geographic coordinate systems.

Support for 3D geometry fields was added, and may be enabled

by setting the :attr:`~django.contrib.gis.db.models.GeometryField.dim`

keyword to 3 in your :class:`~django.contrib.gis.db.models.GeometryField`.

The :class:`~django.contrib.gis.db.models.Extent3D` aggregate

and :meth:`~django.contrib.gis.db.models.GeoQuerySet.extent3d` ``GeoQuerySet``

method were added as a part of this feature.

The following :class:`~django.contrib.gis.db.models.GeoQuerySet`

methods are new in 1.2:

* :meth:`~django.contrib.gis.db.models.GeoQuerySet.force_rhr`

* :meth:`~django.contrib.gis.db.models.GeoQuerySet.reverse_geom`

* :meth:`~django.contrib.gis.db.models.GeoQuerySet.geohash`

The :ref:`GEOS interface <ref-geos>` was updated to use

thread-safe C library functions when available on the platform.

The :ref:`GDAL interface <ref-gdal>` now allows the user to

set a :attr:`~django.contrib.gis.gdal.Layer.spatial_filter` on

the features returned when iterating over a

:class:`~django.contrib.gis.gdal.Layer`.

Finally, :doc:`GeoDjango's documentation </ref/contrib/gis/index>` is now

included with Django's and is no longer

hosted separately at `geodjango.org <http://geodjango.org/>`_.

.. _1.2-js-assisted-inlines:

JavaScript-assisted handling of inline related objects in the admin

-------------------------------------------------------------------

If a user has JavaScript enabled in their browser, the interface for

inline objects in the admin now allows inline objects to be

dynamically added and removed. Users without JavaScript-enabled

browsers will see no change in the behavior of inline objects.

New ``now`` template tag format specifier characters: ``c`` and ``u``

---------------------------------------------------------------------

The argument to the :ttag:`now` has gained two new format characters:

``c`` to specify that a datetime value should be formatted in ISO 8601

format, and ``u`` that allows output of the microseconds part of a

datetime or time value.

These are also available in others parts like the :tfilter:`date` and

:tfilter:`time` template filters, the ``humanize`` template tag library

and the new `format localization`_ framework.

.. _format localization: `Improved localization`_

.. _backwards-incompatible-changes-1.2:

Backwards-incompatible changes in 1.2

=====================================

Wherever possible the new features above have been introduced in a

backwards-compatible manner per :doc:`our API stability policy

</misc/api-stability>` policy. This means that practically all existing

code which worked with Django 1.1 will continue to work with Django

1.2; such code will, however, begin issuing warnings (see below for

details).

However, a handful of features *have* changed in ways that, for some

users, will be immediately backwards-incompatible. Those changes are

detailed below.

CSRF Protection

---------------

We've made large changes to the way CSRF protection works, detailed in

:doc:`the CSRF documentaton </ref/contrib/csrf>`. Here are the major changes you

should be aware of:

 * ``CsrfResponseMiddleware`` and ``CsrfMiddleware`` have been deprecated and

   will be removed completely in Django 1.4, in favor of a template tag that

   should be inserted into forms.

 * All contrib apps use a ``csrf_protect`` decorator to protect the view. This

   requires the use of the ``csrf_token`` template tag in the template. If you

   have used custom templates for contrib views, you MUST READ THE :ref:`UPGRADE

   INSTRUCTIONS <ref-csrf-upgrading-notes>` to fix those templates.

 * ``CsrfViewMiddleware`` is included in :setting:`MIDDLEWARE_CLASSES` by

   default. This turns on CSRF protection by default, so views that accept

   POST requests need to be written to work with the middleware. Instructions

   on how to do this are found in the CSRF docs.

 * All of the CSRF has moved from contrib to core (with backwards

   compatible imports in the old locations, which are deprecated and

   will cease to be supported in Django 1.4).

``get_db_prep_*()`` methods on ``Field``

----------------------------------------

Prior to Django 1.2, a custom ``Field`` had the option of defining

several functions to support conversion of Python values into

database-compatible values. A custom field might look something like::

    class CustomModelField(models.Field):

        # ...

        def db_type(self):

            # ...

        def get_db_prep_save(self, value):

            # ...

        def get_db_prep_value(self, value):

            # ...

        def get_db_prep_lookup(self, lookup_type, value):

            # ...

In 1.2, these three methods have undergone a change in prototype, and

two extra methods have been introduced::

    class CustomModelField(models.Field):

        # ...

        def db_type(self, connection):

            # ...

        def get_prep_value(self, value):

            # ...

        def get_prep_lookup(self, lookup_type, value):

            # ...

        def get_db_prep_save(self, value, connection):

            # ...

        def get_db_prep_value(self, value, connection, prepared=False):

            # ...

        def get_db_prep_lookup(self, lookup_type, value, connection, prepared=False):

            # ...

These changes are required to support multiple databases --

``db_type`` and ``get_db_prep_*`` can no longer make any assumptions

regarding the database for which it is preparing. The ``connection``

argument now provides the preparation methods with the specific

connection for which the value is being prepared.

The two new methods exist to differentiate general data-preparation

requirements from requirements that are database-specific. The

``prepared`` argument is used to indicate to the database-preparation

methods whether generic value preparation has been performed. If

an unprepared (i.e., ``prepared=False``) value is provided to the

``get_db_prep_*()`` calls, they should invoke the corresponding

``get_prep_*()`` calls to perform generic data preparation.

We've provided conversion functions that will transparently

convert functions adhering to the old prototype into functions

compatible with the new prototype. However, these conversion functions

will be removed in Django 1.4, so you should upgrade your ``Field``

definitions to use the new prototype as soon as possible.

If your ``get_db_prep_*()`` methods made no use of the database

connection, you should be able to upgrade by renaming

``get_db_prep_value()`` to ``get_prep_value()`` and

``get_db_prep_lookup()`` to ``get_prep_lookup()``. If you require

database specific conversions, then you will need to provide an

implementation ``get_db_prep_*`` that uses the ``connection``

argument to resolve database-specific values.

Stateful template tags

----------------------

Template tags that store rendering state on their ``Node`` subclass

have always been vulnerable to thread-safety and other issues; as of

Django 1.2, however, they may also cause problems when used with the

new :ref:`cached template loader<template-loaders>`.

All of the built-in Django template tags are safe to use with the cached

loader, but if you're using custom template tags that come from third

party packages, or from your own code, you should ensure that the

``Node`` implementation for each tag is thread-safe. For more

information, see

:ref:`template tag thread safety considerations<template_tag_thread_safety>`.

You may also need to update your templates if you were relying on the

implementation of Django's template tags *not* being thread safe. The

:ttag:`cycle` tag is the most likely to be affected in this way,

especially when used in conjunction with the :ttag:`include` tag.

Consider the following template fragment::

    {% for object in object_list %}

        {% include "subtemplate.html" %}

    {% endfor %}

with a ``subtemplate.html`` that reads::

    {% cycle 'even' 'odd' %}

Using the non-thread-safe, pre-Django 1.2 renderer, this would output::