mirror of
https://github.com/django/django.git
synced 2024-12-23 01:25:58 +00:00
811 lines
36 KiB
Plaintext
811 lines
36 KiB
Plaintext
========================
|
||
Django 1.5 release notes
|
||
========================
|
||
|
||
*February 26, 2013*
|
||
|
||
Welcome to Django 1.5!
|
||
|
||
These release notes cover the :ref:`new features <whats-new-1.5>`, as well as
|
||
some :ref:`backwards incompatible changes <backwards-incompatible-1.5>` 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 :ref:`our deprecation plan
|
||
<deprecation-removed-in-1.5>`, and we've :ref:`begun the deprecation process
|
||
for some features <deprecated-features-1.5>`.
|
||
|
||
Overview
|
||
========
|
||
|
||
The biggest new feature in Django 1.5 is the `configurable User model`_. Before
|
||
Django 1.5, applications that wanted to use Django's auth framework
|
||
(:mod:`django.contrib.auth`) were forced to use Django's definition of a "user".
|
||
In Django 1.5, you can now swap out the ``User`` model for one that you write
|
||
yourself. This could be a simple extension to the existing ``User`` model -- for
|
||
example, you could add a Twitter or Facebook ID field -- or you could completely
|
||
replace the ``User`` with one totally customized for your site.
|
||
|
||
Django 1.5 is also the first release with `Python 3 support`_! We're labeling
|
||
this support "experimental" because we don't yet consider it production-ready,
|
||
but everything's in place for you to start porting your apps to Python 3.
|
||
Our next release, Django 1.6, will support Python 3 without reservations.
|
||
|
||
Other notable new features in Django 1.5 include:
|
||
|
||
* `Support for saving a subset of model's fields`_ -
|
||
:meth:`Model.save() <django.db.models.Model.save()>` now accepts an
|
||
``update_fields`` argument, letting you specify which fields are
|
||
written back to the database when you call ``save()``. This can help
|
||
in high-concurrency operations, and can improve performance.
|
||
|
||
* Better `support for streaming responses <#explicit-streaming-responses>`_ via
|
||
the new :class:`~django.http.StreamingHttpResponse` response class.
|
||
|
||
* `GeoDjango`_ now supports PostGIS 2.0.
|
||
|
||
* ... and more; `see below <#what-s-new-in-django-1-5>`_.
|
||
|
||
Wherever possible we try to introduce new features in a backwards-compatible
|
||
manner per :doc:`our API stability policy </misc/api-stability>`.
|
||
However, as with previous releases, Django 1.5 ships with some minor
|
||
:ref:`backwards incompatible changes <backwards-incompatible-1.5>`; people
|
||
upgrading from previous versions of Django should read that list carefully.
|
||
|
||
One deprecated feature worth noting is the shift to "new-style" :ttag:`url` tag.
|
||
Prior to Django 1.3, syntax like ``{% url myview %}`` was interpreted
|
||
incorrectly (Django considered ``"myview"`` to be a literal name of a view, not
|
||
a template variable named ``myview``). Django 1.3 and above introduced the
|
||
``{% load url from future %}`` syntax to bring in the corrected behavior where
|
||
``myview`` was seen as a variable.
|
||
|
||
The upshot of this is that if you are not using ``{% load url from future %}``
|
||
in your templates, you'll need to change tags like ``{% url myview %}`` to
|
||
``{% url "myview" %}``. If you *were* using ``{% load url from future %}`` you
|
||
can simply remove that line under Django 1.5
|
||
|
||
Python compatibility
|
||
====================
|
||
|
||
Django 1.5 requires Python 2.6.5 or above, though we **highly recommend**
|
||
Python 2.7.3 or above. Support for Python 2.5 and below has been dropped.
|
||
|
||
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, and Django 1.5 supports that alpha
|
||
release.
|
||
|
||
Python 3 support
|
||
----------------
|
||
|
||
Django 1.5 introduces support for Python 3 - specifically, Python
|
||
3.2 and above. This comes in the form of a **single** codebase; you don't
|
||
need to install a different version of Django on Python 3. This means that
|
||
you can write applications targeted for just Python 2, just Python 3, or single
|
||
applications that support both platforms.
|
||
|
||
However, we're labeling this support "experimental" for now: although it's
|
||
received extensive testing via our automated test suite, it's received very
|
||
little real-world testing. We've done our best to eliminate bugs, but we can't
|
||
be sure we covered all possible uses of Django.
|
||
|
||
Some features of Django aren't available because they depend on third-party
|
||
software that hasn't been ported to Python 3 yet, including:
|
||
|
||
- the MySQL database backend (depends on MySQLdb)
|
||
- :class:`~django.db.models.ImageField` (depends on PIL)
|
||
- :class:`~django.test.LiveServerTestCase` (depends on Selenium WebDriver)
|
||
|
||
Further, Django's more than a web framework; it's an ecosystem of pluggable
|
||
components. At this point, very few third-party applications have been ported
|
||
to Python 3, so it's unlikely that a real-world application will have all its
|
||
dependencies satisfied under Python 3.
|
||
|
||
Thus, we're recommending that Django 1.5 not be used in production under Python
|
||
3. Instead, use this opportunity to begin porting applications to Python 3. If
|
||
you're an author of a pluggable component, we encourage you to start porting
|
||
now.
|
||
|
||
We plan to offer first-class, production-ready support for Python 3 in our next
|
||
release, Django 1.6.
|
||
|
||
.. _whats-new-1.5:
|
||
|
||
What's new in Django 1.5
|
||
========================
|
||
|
||
Configurable User model
|
||
-----------------------
|
||
|
||
In Django 1.5, you can now use your own model as the store for user-related
|
||
data. If your project needs a username with more than 30 characters, or if
|
||
you want to store user's names in a format other than first name/last name,
|
||
or you want to put custom profile information onto your User object, you can
|
||
now do so.
|
||
|
||
If you have a third-party reusable application that references the User model,
|
||
you may need to make some changes to the way you reference User instances. You
|
||
should also document any specific features of the User model that your
|
||
application relies upon.
|
||
|
||
See the :ref:`documentation on custom user models <auth-custom-user>` for
|
||
more details.
|
||
|
||
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``.
|
||
|
||
.. _explicit-streaming-responses:
|
||
|
||
Explicit support for streaming responses
|
||
----------------------------------------
|
||
|
||
Before Django 1.5, it was possible to create a streaming response by passing
|
||
an iterator to :class:`~django.http.HttpResponse`. But this was unreliable:
|
||
any middleware that accessed the :attr:`~django.http.HttpResponse.content`
|
||
attribute would consume the iterator prematurely.
|
||
|
||
You can now explicitly generate a streaming response with the new
|
||
:class:`~django.http.StreamingHttpResponse` class. This class exposes a
|
||
:class:`~django.http.StreamingHttpResponse.streaming_content` attribute which
|
||
is an iterator.
|
||
|
||
Since :class:`~django.http.StreamingHttpResponse` does not have a ``content``
|
||
attribute, middleware that needs access to the response content must test for
|
||
streaming responses and behave accordingly.
|
||
|
||
``{% 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 retrieve 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.
|
||
|
||
GeoDjango
|
||
---------
|
||
|
||
* :class:`~django.contrib.gis.geos.LineString` and
|
||
:class:`~django.contrib.gis.geos.MultiLineString` GEOS objects now support the
|
||
:meth:`~django.contrib.gis.geos.GEOSGeometry.interpolate()` and
|
||
:meth:`~django.contrib.gis.geos.GEOSGeometry.project()` methods
|
||
(so-called linear referencing).
|
||
|
||
* The ``wkb`` and ``hex`` properties of
|
||
:class:`~django.contrib.gis.geos.GEOSGeometry` objects preserve the Z
|
||
dimension.
|
||
|
||
* Support for PostGIS 2.0 has been added and support for GDAL < 1.5 has been
|
||
dropped.
|
||
|
||
New tutorials
|
||
-------------
|
||
|
||
Additions to the docs include a revamped :doc:`Tutorial 3</intro/tutorial03>`
|
||
and a new :doc:`tutorial on testing</intro/tutorial05>`. A new section,
|
||
"Advanced Tutorials", offers :doc:`How to write reusable apps
|
||
</intro/reusable-apps>` as well as a step-by-step guide for new contributors in
|
||
:doc:`Writing your first patch for Django </intro/contributing>`.
|
||
|
||
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 :func:`~django.core.management.call_command`. Any exception raised by
|
||
the command (mostly :exc:`~django.core.management.CommandError`) is
|
||
propagated.
|
||
|
||
Moreover, when you output errors or messages in your custom commands, you
|
||
should now use ``self.stdout.write('message')`` and
|
||
``self.stderr.write('error')`` (see the note on
|
||
:ref:`management commands output <management-commands-output>`).
|
||
|
||
* The :djadmin:`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.
|
||
|
||
* In the admin, you can now filter users by groups which they are members of.
|
||
|
||
* :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.
|
||
|
||
* The :setting:`LOGIN_URL` and :setting:`LOGIN_REDIRECT_URL` settings now also
|
||
accept view function names and
|
||
:ref:`named URL patterns <naming-url-patterns>`. This allows you to reduce
|
||
configuration duplication. More information can be found in the
|
||
:func:`~django.contrib.auth.decorators.login_required` documentation.
|
||
|
||
* Django now provides a mod_wsgi :doc:`auth handler
|
||
</howto/deployment/wsgi/apache-auth>`.
|
||
|
||
* The :meth:`QuerySet.delete() <django.db.models.query.QuerySet.delete>`
|
||
and :meth:`Model.delete() <django.db.models.Model.delete()>` can now take
|
||
fast-path in some cases. The fast-path allows for less queries and less
|
||
objects fetched into memory. See :meth:`QuerySet.delete()
|
||
<django.db.models.query.QuerySet.delete>` for details.
|
||
|
||
* An instance of ``ResolverMatch`` is stored on the request as
|
||
``resolver_match``.
|
||
|
||
* By default, all logging messages reaching the ``django`` logger when
|
||
:setting:`DEBUG` is ``True`` are sent to the console (unless you redefine the
|
||
logger in your :setting:`LOGGING` setting).
|
||
|
||
* When using :class:`~django.template.RequestContext`, it is now possible to
|
||
look up permissions by using ``{% if 'someapp.someperm' in perms %}``
|
||
in templates.
|
||
|
||
* It's not required any more to have ``404.html`` and ``500.html`` templates in
|
||
the root templates directory. Django will output some basic error messages for
|
||
both situations when those templates are not found. Of course, it's still
|
||
recommended as good practice to provide those templates in order to present
|
||
pretty error pages to the user.
|
||
|
||
* :mod:`django.contrib.auth` provides a new signal that is emitted
|
||
whenever a user fails to login successfully. See
|
||
:data:`~django.contrib.auth.signals.user_login_failed`
|
||
|
||
* The new :option:`loaddata --ignorenonexistent` option ignore data for fields
|
||
that no longer exist.
|
||
|
||
* :meth:`~django.test.SimpleTestCase.assertXMLEqual` and
|
||
:meth:`~django.test.SimpleTestCase.assertXMLNotEqual` new assertions allow
|
||
you to test equality for XML content at a semantic level, without caring for
|
||
syntax differences (spaces, attribute order, etc.).
|
||
|
||
* RemoteUserMiddleware now forces logout when the REMOTE_USER header
|
||
disappears during the same browser session.
|
||
|
||
* The :ref:`cache-based session backend <cached-sessions-backend>` can store
|
||
session data in a non-default cache.
|
||
|
||
* Multi-column indexes can now be created on models. Read the
|
||
:attr:`~django.db.models.Options.index_together` documentation for more
|
||
information.
|
||
|
||
* During Django's logging configuration verbose Deprecation warnings are
|
||
enabled and warnings are captured into the logging system. Logged warnings
|
||
are routed through the ``console`` logging handler, which by default requires
|
||
:setting:`DEBUG` to be True for output to be generated. The result is that
|
||
DeprecationWarnings should be printed to the console in development
|
||
environments the way they have been in Python versions < 2.7.
|
||
|
||
* The API for :meth:`django.contrib.admin.ModelAdmin.message_user` method has
|
||
been modified to accept additional arguments adding capabilities similar to
|
||
:func:`django.contrib.messages.add_message`. This is useful for generating
|
||
error messages from admin actions.
|
||
|
||
* The admin's list filters can now be customized per-request thanks to the new
|
||
:meth:`django.contrib.admin.ModelAdmin.get_list_filter` method.
|
||
|
||
.. _backwards-incompatible-1.5:
|
||
|
||
Backwards incompatible changes in 1.5
|
||
=====================================
|
||
|
||
.. warning::
|
||
|
||
In addition to the changes outlined in this section, be sure to review the
|
||
:ref:`deprecation plan <deprecation-removed-in-1.5>` 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.
|
||
|
||
``ALLOWED_HOSTS`` required in production
|
||
----------------------------------------
|
||
|
||
The new :setting:`ALLOWED_HOSTS` setting validates the request's ``Host``
|
||
header and protects against host-poisoning attacks. This setting is now
|
||
required whenever :setting:`DEBUG` is ``False``, or else
|
||
:meth:`django.http.HttpRequest.get_host()` will raise
|
||
:exc:`~django.core.exceptions.SuspiciousOperation`. For more details see the
|
||
:setting:`full documentation<ALLOWED_HOSTS>` for the new setting.
|
||
|
||
Managers on abstract models
|
||
---------------------------
|
||
|
||
Abstract models are able to define a custom manager, and that manager
|
||
:ref:`will be inherited by any concrete models extending the abstract model
|
||
<custom-managers-and-inheritance>`. However, if you try to use the abstract
|
||
model to call a method on the manager, an exception will now be raised.
|
||
Previously, the call would have been permitted, but would have failed as soon
|
||
as any database operation was attempted (usually with a "table does not exist"
|
||
error from the database).
|
||
|
||
If you have functionality on a manager that you have been invoking using
|
||
the abstract class, you should migrate that logic to a Python
|
||
``staticmethod`` or ``classmethod`` on the abstract class.
|
||
|
||
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 year and month archive class-based views
|
||
---------------------------------------------------
|
||
|
||
:class:`~django.views.generic.dates.YearArchiveView` and
|
||
:class:`~django.views.generic.dates.MonthArchiveView` were documented to
|
||
provide a ``date_list`` sorted in ascending order in the context, like their
|
||
function-based predecessors, but it actually was in descending order. In 1.5,
|
||
the documented order was restored. You may want to add (or remove) the
|
||
``reversed`` keyword when you're iterating on ``date_list`` in a template::
|
||
|
||
{% for date in date_list reversed %}
|
||
|
||
:class:`~django.views.generic.dates.ArchiveIndexView` still provides a
|
||
``date_list`` in descending order.
|
||
|
||
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.
|
||
|
||
Non-form data in HTTP requests
|
||
------------------------------
|
||
|
||
:attr:`request.POST <django.http.HttpRequest.POST>` will no longer include data
|
||
posted via HTTP requests with non form-specific content-types in the header.
|
||
In prior versions, data posted with content-types other than
|
||
``multipart/form-data`` or ``application/x-www-form-urlencoded`` would still
|
||
end up represented in the :attr:`request.POST <django.http.HttpRequest.POST>`
|
||
attribute. Developers wishing to access the raw POST data for these cases,
|
||
should use the :attr:`request.body <django.http.HttpRequest.body>` attribute
|
||
instead.
|
||
|
||
:data:`~django.core.signals.request_finished` signal
|
||
----------------------------------------------------
|
||
|
||
Django used to send the :data:`~django.core.signals.request_finished` signal
|
||
as soon as the view function returned a response. This interacted badly with
|
||
:ref:`streaming responses <httpresponse-streaming>` that delay content
|
||
generation.
|
||
|
||
This signal is now sent after the content is fully consumed by the WSGI
|
||
gateway. This might be backwards incompatible if you rely on the signal being
|
||
fired before sending the response content to the client. If you do, you should
|
||
consider using :doc:`middleware </topics/http/middleware>` instead.
|
||
|
||
.. note::
|
||
|
||
Some WSGI servers and middleware do not always call ``close`` on the
|
||
response object after handling a request, most notably uWSGI prior to 1.2.6
|
||
and Sentry's error reporting middleware up to 2.0.7. In those cases the
|
||
``request_finished`` signal isn't sent at all. This can result in idle
|
||
connections to database and memcache servers.
|
||
|
||
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 ``simplejson`` no longer used
|
||
-----------------------------------------------
|
||
|
||
:ref:`As explained below <simplejson-deprecation>`, Django 1.5 deprecates
|
||
``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 ``simplejson``, it may trigger errors
|
||
in some circumstances.
|
||
|
||
JSON-related features in Django 1.4 always used ``django.utils.simplejson``.
|
||
This module was actually:
|
||
|
||
- A system version of ``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 ``simplejson``.
|
||
|
||
In Django 1.5, those features use Python's :mod:`json` module, which is based
|
||
on version 2.0.9 of ``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 ``simplejson``:
|
||
|
||
- While the ``simplejson`` API is documented as always returning Unicode
|
||
strings, the optional C implementation can return a bytestring. This was
|
||
fixed in Python 2.7.
|
||
- ``simplejson.JSONEncoder`` gained a ``namedtuple_as_object`` keyword
|
||
argument in version 2.2.
|
||
|
||
More information on these incompatibilities is available in
|
||
:ticket:`ticket #18023 <18023#comment:10>`.
|
||
|
||
The net result is that, if you have installed ``simplejson`` and your code
|
||
uses Django's serialization internals directly -- for instance
|
||
``django.core.serializers.json.DjangoJSONEncoder``, the switch from
|
||
``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.
|
||
|
||
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 bytestrings, 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:`~django.core.paginator.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.
|
||
|
||
Email checks on failed admin login
|
||
----------------------------------
|
||
|
||
Prior to Django 1.5, if you attempted to log into the admin interface and
|
||
mistakenly used your email address instead of your username, the admin
|
||
interface would provide a warning advising that your email address was
|
||
not your username. In Django 1.5, the introduction of
|
||
:ref:`custom user models <auth-custom-user>` has required the removal of this
|
||
warning. This doesn't change the login behavior of the admin site; it only
|
||
affects the warning message that is displayed under one particular mode of
|
||
login failure.
|
||
|
||
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 implicit 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 unit tests (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.
|
||
|
||
Behavior of ``syncdb`` with multiple databases
|
||
----------------------------------------------
|
||
|
||
``syncdb`` now queries the database routers to determine if content
|
||
types (when :mod:`~django.contrib.contenttypes` is enabled) and permissions
|
||
(when :mod:`~django.contrib.auth` is enabled) should be created in the target
|
||
database. Previously, it created them in the default database, even when
|
||
another database was specified with the ``--database`` option.
|
||
|
||
If you use ``syncdb`` on multiple databases, you should ensure that
|
||
your routers allow synchronizing content types and permissions to only one of
|
||
them. See the docs on the :ref:`behavior of contrib apps with multiple
|
||
databases <contrib_app_multiple_databases>` for more information.
|
||
|
||
XML deserializer will not parse documents with a DTD
|
||
----------------------------------------------------
|
||
|
||
In order to prevent exposure to denial-of-service attacks related to external
|
||
entity references and entity expansion, the XML model deserializer now refuses
|
||
to parse XML documents containing a DTD (DOCTYPE definition). Since the XML
|
||
serializer does not output a DTD, this will not impact typical usage, only
|
||
cases where custom-created XML documents are passed to Django's model
|
||
deserializer.
|
||
|
||
Formsets default ``max_num``
|
||
----------------------------
|
||
|
||
A (default) value of ``None`` for the ``max_num`` argument to a formset factory
|
||
no longer defaults to allowing any number of forms in the formset. Instead, in
|
||
order to prevent memory-exhaustion attacks, it now defaults to a limit of 1000
|
||
forms. This limit can be raised by explicitly setting a higher value for
|
||
``max_num``.
|
||
|
||
Miscellaneous
|
||
-------------
|
||
|
||
* :class:`django.forms.ModelMultipleChoiceField` now returns an empty
|
||
``QuerySet`` as the empty value instead of an empty list.
|
||
|
||
* :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 ``django.utils.html.remove_tags()``.
|
||
|
||
* Uploaded files are no longer created as executable by default. If you need
|
||
them to be executable change :setting:`FILE_UPLOAD_PERMISSIONS` to your
|
||
needs. The new default value is ``0o666`` (octal) and the current umask value
|
||
is first masked out.
|
||
|
||
* The :class:`F expressions <django.db.models.F>` supported bitwise operators by
|
||
``&`` and ``|``. These operators are now available using ``.bitand()`` and
|
||
``.bitor()`` instead. The removal of ``&`` and ``|`` was done to be
|
||
consistent with :ref:`Q() expressions <complex-lookups-with-q>` and
|
||
``QuerySet`` combining where the operators are used as boolean AND and OR
|
||
operators.
|
||
|
||
* In a ``filter()`` call, when :class:`F expressions <django.db.models.F>`
|
||
contained lookups spanning multi-valued relations, they didn't always reuse
|
||
the same relations as other lookups along the same chain. This was changed,
|
||
and now F() expressions will always use the same relations as other lookups
|
||
within the same ``filter()`` call.
|
||
|
||
* The :ttag:`csrf_token` template tag is no longer enclosed in a div. If you need
|
||
HTML validation against pre-HTML5 Strict DTDs, you should add a div around it
|
||
in your pages.
|
||
|
||
* The template tags library ``adminmedia``, which only contained the
|
||
deprecated template tag ``{% admin_media_prefix %}``, was removed.
|
||
Attempting to load it with ``{% load adminmedia %}`` will fail. If your
|
||
templates still contain that line you must remove it.
|
||
|
||
* Because of an implementation oversight, it was possible to use
|
||
:doc:`django.contrib.redirects </ref/contrib/redirects>` without enabling
|
||
:doc:`django.contrib.sites </ref/contrib/sites>`. This isn't allowed any
|
||
longer. If you're using ``django.contrib.redirects``, make sure
|
||
:setting:`INSTALLED_APPS` contains ``django.contrib.sites``.
|
||
|
||
* :meth:`BoundField.label_tag <django.forms.BoundField.label_tag>` now
|
||
escapes its ``contents`` argument. To avoid the HTML escaping, use
|
||
:func:`django.utils.safestring.mark_safe` on the argument before passing it.
|
||
|
||
* Accessing reverse one-to-one relations fetched via
|
||
:meth:`~django.db.models.query.QuerySet.select_related` now raises
|
||
:exc:`~django.db.models.Model.DoesNotExist` instead of returning ``None``.
|
||
|
||
.. _deprecated-features-1.5:
|
||
|
||
Features deprecated in 1.5
|
||
==========================
|
||
|
||
``django.contrib.localflavor``
|
||
------------------------------
|
||
|
||
The localflavor contrib app has been split into separate packages.
|
||
``django.contrib.localflavor`` itself will be removed in Django 1.6,
|
||
after an accelerated deprecation.
|
||
|
||
The new packages are available on GitHub. The core team cannot
|
||
efficiently maintain these packages in the long term — it spans just a
|
||
dozen countries at this time; similar to translations, maintenance
|
||
will be handed over to interested members of the community.
|
||
|
||
``django.contrib.markup``
|
||
-------------------------
|
||
|
||
The markup contrib module has been deprecated and will follow an accelerated
|
||
deprecation schedule. Direct use of Python markup libraries or 3rd party tag
|
||
libraries is preferred to Django maintaining this functionality in the
|
||
framework.
|
||
|
||
``AUTH_PROFILE_MODULE``
|
||
-----------------------
|
||
|
||
With the introduction of :ref:`custom user models <auth-custom-user>`, there is
|
||
no longer any need for a built-in mechanism to store user profile data.
|
||
|
||
You can still define user profiles models that have a one-to-one relation with
|
||
the User model - in fact, for many applications needing to associate data with
|
||
a User account, this will be an appropriate design pattern to follow. However,
|
||
the ``AUTH_PROFILE_MODULE`` setting, and the
|
||
``django.contrib.auth.models.User.get_profile()`` method for accessing
|
||
the user profile model, should not be used any longer.
|
||
|
||
Streaming behavior of :class:`~django.http.HttpResponse`
|
||
--------------------------------------------------------
|
||
|
||
Django 1.5 deprecates the ability to stream a response by passing an iterator
|
||
to :class:`~django.http.HttpResponse`. If you rely on this behavior, switch to
|
||
:class:`~django.http.StreamingHttpResponse`. See
|
||
:ref:`explicit-streaming-responses` above.
|
||
|
||
In Django 1.7 and above, the iterator will be consumed immediately by
|
||
:class:`~django.http.HttpResponse`.
|
||
|
||
.. _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 ``simplejson``. You should now import :mod:`json`
|
||
instead of ``django.utils.simplejson``.
|
||
|
||
Unfortunately, this change might have unwanted side-effects, because of
|
||
incompatibilities between versions of ``simplejson`` -- see the
|
||
:ref:`backwards-incompatible changes <simplejson-incompatibilities>` section.
|
||
If you rely on features added to ``simplejson`` after it became Python's
|
||
:mod:`json`, you should import ``simplejson`` explicitly.
|
||
|
||
``django.utils.encoding.StrAndUnicode``
|
||
---------------------------------------
|
||
|
||
The ``django.utils.encoding.StrAndUnicode`` mix-in has been deprecated.
|
||
Define a ``__str__`` method and apply the
|
||
``django.utils.encoding.python_2_unicode_compatible`` decorator instead.
|
||
|
||
``django.utils.itercompat.product``
|
||
-----------------------------------
|
||
|
||
The ``django.utils.itercompat.product`` function has been deprecated. Use
|
||
the built-in :func:`itertools.product` instead.
|
||
|
||
``cleanup`` management command
|
||
------------------------------
|
||
|
||
The ``cleanup`` management command has been deprecated and replaced by
|
||
:djadmin:`clearsessions`.
|
||
|
||
``daily_cleanup.py`` script
|
||
---------------------------
|
||
|
||
The undocumented ``daily_cleanup.py`` script has been deprecated. Use the
|
||
:djadmin:`clearsessions` management command instead.
|
||
|
||
``depth`` keyword argument in ``select_related``
|
||
------------------------------------------------
|
||
|
||
The ``depth`` keyword argument in
|
||
:meth:`~django.db.models.query.QuerySet.select_related` has been deprecated.
|
||
You should use field names instead.
|