361 lines
15 KiB
Plaintext
361 lines
15 KiB
Plaintext
============================================
|
||
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.smart_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.
|