django/docs/releases/1.5.txt

============================================
Django 1.5 release notes - UNDER DEVELOPMENT
============================================

These release notes cover the `new features`_, as well
as some `backwards incompatible changes`_ you'll want to be aware of
when upgrading from Django 1.4 or older versions. We've also dropped some
features, which are detailed in :doc:`our deprecation plan
</internals/deprecation>`, and we've `begun the deprecation process for some
features`_.

.. _`new features`: `What's new in Django 1.5`_
.. _`backwards incompatible changes`: `Backwards incompatible changes in 1.5`_
.. _`begun the deprecation process for some features`: `Features deprecated in 1.5`_

Python compatibility
====================

Django 1.5 has dropped support for Python 2.5. Python 2.6.5 is now the minimum
required Python version. Django is tested and supported on Python 2.6 and
2.7.

This change should affect only a small number of Django users, as most
operating-system vendors today are shipping Python 2.6 or newer as their default
version. If you're still using Python 2.5, however, you'll need to stick to
Django 1.4 until you can upgrade your Python version. Per :doc:`our support policy
</internals/release-process>`, Django 1.4 will continue to receive security
support until the release of Django 1.6.

Django 1.5 does not run on a Jython final release, because Jython's latest release
doesn't currently support Python 2.6. However, Jython currently does offer an alpha
release featuring 2.7 support.

What's new in Django 1.5
========================

Support for saving a subset of model's fields
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The method :meth:`Model.save() <django.db.models.Model.save()>` has a new
keyword argument ``update_fields``. By using this argument it is possible to
save only a select list of model's fields. This can be useful for performance
reasons or when trying to avoid overwriting concurrent changes.

Deferred instances (those loaded by .only() or .defer()) will automatically
save just the loaded fields. If any field is set manually after load, that
field will also get updated on save.

See the :meth:`Model.save() <django.db.models.Model.save()>` documentation for
more details.

Caching of related model instances
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When traversing relations, the ORM will avoid re-fetching objects that were
previously loaded. For example, with the tutorial's models::

    >>> first_poll = Poll.objects.all()[0]
    >>> first_choice = first_poll.choice_set.all()[0]
    >>> first_choice.poll is first_poll
    True

In Django 1.5, the third line no longer triggers a new SQL query to fetch
``first_choice.poll``; it was set by the second line.

For one-to-one relationships, both sides can be cached. For many-to-one
relationships, only the single side of the relationship can be cached. This
is particularly helpful in combination with ``prefetch_related``.

``{% verbatim %}`` template tag
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To make it easier to deal with javascript templates which collide with Django's
syntax, you can now use the :ttag:`verbatim` block tag to avoid parsing the
tag's content.

Retrieval of ``ContentType`` instances associated with proxy models
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The methods :meth:`ContentTypeManager.get_for_model() <django.contrib.contenttypes.models.ContentTypeManager.get_for_model()>`
and :meth:`ContentTypeManager.get_for_models() <django.contrib.contenttypes.models.ContentTypeManager.get_for_models()>`
have a new keyword argument – respectively ``for_concrete_model`` and ``for_concrete_models``.
By passing ``False`` using this argument it is now possible to retreive the
:class:`ContentType <django.contrib.contenttypes.models.ContentType>`
associated with proxy models.

New ``view`` variable in class-based views context
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In all :doc:`generic class-based views </topics/class-based-views/index>`
(or any class-based view inheriting from ``ContextMixin``), the context dictionary
contains a ``view`` variable that points to the ``View`` instance.

Minor features
~~~~~~~~~~~~~~

Django 1.5 also includes several smaller improvements worth noting:

* The template engine now interprets ``True``, ``False`` and ``None`` as the
  corresponding Python objects.

* :mod:`django.utils.timezone` provides a helper for converting aware
  datetimes between time zones. See :func:`~django.utils.timezone.localtime`.

* The generic views support OPTIONS requests.

* Management commands do not raise ``SystemExit`` any more when called by code
  from :ref:`call_command <call-command>`. Any exception raised by the command
  (mostly :ref:`CommandError <ref-command-exceptions>`) is propagated.

* The dumpdata management command outputs one row at a time, preventing
  out-of-memory errors when dumping large datasets.

* In the localflavor for Canada, "pq" was added to the acceptable codes for
  Quebec. It's an old abbreviation.

* The :ref:`receiver <connecting-receiver-functions>` decorator is now able to
  connect to more than one signal by supplying a list of signals.

* :meth:`QuerySet.bulk_create()
  <django.db.models.query.QuerySet.bulk_create>` now has a batch_size
  argument. By default the batch_size is unlimited except for SQLite where
  single batch is limited so that 999 parameters per query isn't exceeded.

Backwards incompatible changes in 1.5
=====================================

.. warning::

    In addition to the changes outlined in this section, be sure to review the
    :doc:`deprecation plan </internals/deprecation>` for any features that
    have been removed. If you haven't updated your code within the
    deprecation timeline for a given feature, its removal may appear as a
    backwards incompatible change.

Context in year archive class-based views
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For consistency with the other date-based generic views,
:class:`~django.views.generic.dates.YearArchiveView` now passes ``year`` in
the context as a :class:`datetime.date` rather than a string.  If you are
using ``{{ year }}`` in your templates, you must replace it with ``{{
year|date:"Y" }}``.

``next_year`` and ``previous_year`` were also added in the context. They are
calculated according to ``allow_empty`` and ``allow_future``.

Context in TemplateView
~~~~~~~~~~~~~~~~~~~~~~~

For consistency with the design of the other generic views,
:class:`~django.views.generic.base.TemplateView` no longer passes a ``params``
dictionary into the context, instead passing the variables from the URLconf
directly into the context.

OPTIONS, PUT and DELETE requests in the test client
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Unlike GET and POST, these HTTP methods aren't implemented by web browsers.
Rather, they're used in APIs, which transfer data in various formats such as
JSON or XML. Since such requests may contain arbitrary data, Django doesn't
attempt to decode their body.

However, the test client used to build a query string for OPTIONS and DELETE
requests like for GET, and a request body for PUT requests like for POST. This
encoding was arbitrary and inconsistent with Django's behavior when it
receives the requests, so it was removed in Django 1.5.

If you were using the ``data`` parameter in an OPTIONS or a DELETE request,
you must convert it to a query string and append it to the ``path`` parameter.

If you were using the ``data`` parameter in a PUT request without a
``content_type``, you must encode your data before passing it to the test
client and set the ``content_type`` argument.

.. _simplejson-incompatibilities:

System version of :mod:`simplejson` no longer used
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:ref:`As explained below <simplejson-deprecation>`, Django 1.5 deprecates
:mod:`django.utils.simplejson` in favor of Python 2.6's built-in :mod:`json`
module. In theory, this change is harmless. Unfortunately, because of
incompatibilities between versions of :mod:`simplejson`, it may trigger errors
in some circumstances.

JSON-related features in Django 1.4 always used :mod:`django.utils.simplejson`.
This module was actually:

- A system version of :mod:`simplejson`, if one was available (ie. ``import
  simplejson`` works), if it was more recent than Django's built-in copy or it
  had the C speedups, or
- The :mod:`json` module from the standard library, if it was available (ie.
  Python 2.6 or greater), or
- A built-in copy of version 2.0.7 of :mod:`simplejson`.

In Django 1.5, those features use Python's :mod:`json` module, which is based
on version 2.0.9 of :mod:`simplejson`.

There are no known incompatibilities between Django's copy of version 2.0.7 and
Python's copy of version 2.0.9. However, there are some incompatibilities
between other versions of :mod:`simplejson`:

- While the :mod:`simplejson` API is documented as always returning unicode
  strings, the optional C implementation can return a byte string. This was
  fixed in Python 2.7.
- :class:`simplejson.JSONEncoder` gained a ``namedtuple_as_object`` keyword
  argument in version 2.2.

More information on these incompatibilities is available in `ticket #18023`_.

The net result is that, if you have installed :mod:`simplejson` and your code
uses Django's serialization internals directly -- for instance
:class:`django.core.serializers.json.DjangoJSONEncoder`, the switch from
:mod:`simplejson` to :mod:`json` could break your code. (In general, changes to
internals aren't documented; we're making an exception here.)

At this point, the maintainers of Django believe that using :mod:`json` from
the standard library offers the strongest guarantee of backwards-compatibility.
They recommend to use it from now on.

.. _ticket #18023: https://code.djangoproject.com/ticket/18023#comment:10

String types of hasher method parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you have written a :ref:`custom password hasher <auth_password_storage>`,
your ``encode()``, ``verify()`` or ``safe_summary()`` methods should accept
Unicode parameters (``password``, ``salt`` or ``encoded``). If any of the
hashing methods need byte strings, you can use the
:func:`~django.utils.encoding.force_bytes` utility to encode the strings.

Validation of previous_page_number and next_page_number
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When using :doc:`object pagination </topics/pagination>`,
the ``previous_page_number()`` and ``next_page_number()`` methods of the
:class:`~django.core.paginator.Page` object did not check if the returned
number was inside the existing page range.
It does check it now and raises an :exc:`InvalidPage` exception when the number
is either too low or too high.

Behavior of autocommit database option on PostgreSQL changed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

PostgreSQL's autocommit option didn't work as advertised previously. It did
work for single transaction block, but after the first block was left the
autocommit behavior was never restored. This bug is now fixed in 1.5. While
this is only a bug fix, it is worth checking your applications behavior if
you are using PostgreSQL together with the autocommit option.

Session not saved on 500 responses
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Django's session middleware will skip saving the session data if the
response's status code is 500.

Changes in tests execution
~~~~~~~~~~~~~~~~~~~~~~~~~~

Some changes have been introduced in the execution of tests that might be
backward-incompatible for some testing setups:

Database flushing in ``django.test.TransactionTestCase``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Previously, the test database was truncated *before* each test run in a
:class:`~django.test.TransactionTestCase`.

In order to be able to run unit tests in any order and to make sure they are
always isolated from each other, :class:`~django.test.TransactionTestCase` will
now reset the database *after* each test run instead.

No more implict DB sequences reset
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

:class:`~django.test.TransactionTestCase` tests used to reset primary key
sequences automatically together with the database flushing actions described
above.

This has been changed so no sequences are implicitly reset. This can cause
:class:`~django.test.TransactionTestCase` tests that depend on hard-coded
primary key values to break.

The new :attr:`~django.test.TransactionTestCase.reset_sequences` attribute can
be used to force the old behavior for :class:`~django.test.TransactionTestCase`
that might need it.

Ordering of tests
^^^^^^^^^^^^^^^^^

In order to make sure all ``TestCase`` code starts with a clean database,
tests are now executed in the following order:

* First, all unittests (including :class:`unittest.TestCase`,
  :class:`~django.test.SimpleTestCase`, :class:`~django.test.TestCase` and
  :class:`~django.test.TransactionTestCase`) are run with no particular ordering
  guaranteed nor enforced among them.

* Then any other tests (e.g. doctests) that may alter the database without
  restoring it to its original state are run.

This should not cause any problems unless you have existing doctests which
assume a :class:`~django.test.TransactionTestCase` executed earlier left some
database state behind or unit tests that rely on some form of state being
preserved after the execution of other tests. Such tests are already very
fragile, and must now be changed to be able to run independently.

`cleaned_data` dictionary kept for invalid forms
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :attr:`~django.forms.Form.cleaned_data` dictionary is now always present
after form validation. When the form doesn't validate, it contains only the
fields that passed validation. You should test the success of the validation
with the :meth:`~django.forms.Form.is_valid()` method and not with the
presence or absence of the :attr:`~django.forms.Form.cleaned_data` attribute
on the form.

Miscellaneous
~~~~~~~~~~~~~

* GeoDjango dropped support for GDAL < 1.5

* :func:`~django.utils.http.int_to_base36` properly raises a :exc:`TypeError`
  instead of :exc:`ValueError` for non-integer inputs.

* The ``slugify`` template filter is now available as a standard python
  function at :func:`django.utils.text.slugify`. Similarly, ``remove_tags`` is
  available at :func:`django.utils.html.remove_tags`.

Features deprecated in 1.5
==========================

.. _simplejson-deprecation:

``django.utils.simplejson``
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Since Django 1.5 drops support for Python 2.5, we can now rely on the
:mod:`json` module being available in Python's standard library, so we've
removed our own copy of :mod:`simplejson`. You should now import :mod:`json`
instead :mod:`django.utils.simplejson`.

Unfortunately, this change might have unwanted side-effects, because of
incompatibilities between versions of :mod:`simplejson` -- see the
:ref:`backwards-incompatible changes <simplejson-incompatibilities>` section.
If you rely on features added to :mod:`simplejson` after it became Python's
:mod:`json`, you should import :mod:`simplejson` explicitly.

``itercompat.product``
~~~~~~~~~~~~~~~~~~~~~~

The :func:`~django.utils.itercompat.product` function has been deprecated. Use
the built-in :func:`itertools.product` instead.

``django.utils.encoding.StrAndUnicode``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :class:`~django.utils.encoding.StrAndUnicode` mix-in has been deprecated.
Define a ``__str__`` method and apply the
:func:`~django.utils.encoding.python_2_unicode_compatible` decorator instead.