| 1 |
======================== |
| 2 |
Django 1.5 release notes |
| 3 |
======================== |
| 4 |
|
| 5 |
*February 26, 2013* |
| 6 |
|
| 7 |
Welcome to Django 1.5! |
| 8 |
|
| 9 |
These release notes cover the :ref:`new features <whats-new-1.5>`, as well as |
| 10 |
some :ref:`backwards incompatible changes <backwards-incompatible-1.5>` you'll |
| 11 |
want to be aware of when upgrading from Django 1.4 or older versions. We've |
| 12 |
also dropped some features, which are detailed in :ref:`our deprecation plan |
| 13 |
<deprecation-removed-in-1.5>`, and we've :ref:`begun the deprecation process |
| 14 |
for some features <deprecated-features-1.5>`. |
| 15 |
|
| 16 |
Overview |
| 17 |
======== |
| 18 |
|
| 19 |
The biggest new feature in Django 1.5 is the `configurable User model`_. Before |
| 20 |
Django 1.5, applications that wanted to use Django's auth framework |
| 21 |
(:mod:`django.contrib.auth`) were forced to use Django's definition of a "user". |
| 22 |
In Django 1.5, you can now swap out the ``User`` model for one that you write |
| 23 |
yourself. This could be a simple extension to the existing ``User`` model -- for |
| 24 |
example, you could add a Twitter or Facebook ID field -- or you could completely |
| 25 |
replace the ``User`` with one totally customized for your site. |
| 26 |
|
| 27 |
Django 1.5 is also the first release with `Python 3 support`_! We're labeling |
| 28 |
this support "experimental" because we don't yet consider it production-ready, |
| 29 |
but everything's in place for you to start porting your apps to Python 3. |
| 30 |
Our next release, Django 1.6, will support Python 3 without reservations. |
| 31 |
|
| 32 |
Other notable new features in Django 1.5 include: |
| 33 |
|
| 34 |
* `Support for saving a subset of model's fields`_ - |
| 35 |
:meth:`Model.save() <django.db.models.Model.save()>` now accepts an |
| 36 |
``update_fields`` argument, letting you specify which fields are |
| 37 |
written back to the database when you call ``save()``. This can help |
| 38 |
in high-concurrency operations, and can improve performance. |
| 39 |
|
| 40 |
* Better `support for streaming responses <#explicit-streaming-responses>`_ via |
| 41 |
the new :class:`~django.http.StreamingHttpResponse` response class. |
| 42 |
|
| 43 |
* `GeoDjango`_ now supports PostGIS 2.0. |
| 44 |
|
| 45 |
* ... and more; `see below <#what-s-new-in-django-1-5>`_. |
| 46 |
|
| 47 |
Wherever possible we try to introduce new features in a backwards-compatible |
| 48 |
manner per :doc:`our API stability policy </misc/api-stability>`. |
| 49 |
However, as with previous releases, Django 1.5 ships with some minor |
| 50 |
:ref:`backwards incompatible changes <backwards-incompatible-1.5>`; people |
| 51 |
upgrading from previous versions of Django should read that list carefully. |
| 52 |
|
| 53 |
One deprecated feature worth noting is the shift to "new-style" :ttag:`url` tag. |
| 54 |
Prior to Django 1.3, syntax like ``{% url myview %}`` was interpreted |
| 55 |
incorrectly (Django considered ``"myview"`` to be a literal name of a view, not |
| 56 |
a template variable named ``myview``). Django 1.3 and above introduced the |
| 57 |
``{% load url from future %}`` syntax to bring in the corrected behavior where |
| 58 |
``myview`` was seen as a variable. |
| 59 |
|
| 60 |
The upshot of this is that if you are not using ``{% load url from future %}`` |
| 61 |
in your templates, you'll need to change tags like ``{% url myview %}`` to |
| 62 |
``{% url "myview" %}``. If you *were* using ``{% load url from future %}`` you |
| 63 |
can simply remove that line under Django 1.5 |
| 64 |
|
| 65 |
Python compatibility |
| 66 |
==================== |
| 67 |
|
| 68 |
Django 1.5 requires Python 2.6.5 or above, though we **highly recommend** |
| 69 |
Python 2.7.3 or above. Support for Python 2.5 and below has been dropped. |
| 70 |
|
| 71 |
This change should affect only a small number of Django users, as most |
| 72 |
operating-system vendors today are shipping Python 2.6 or newer as their default |
| 73 |
version. If you're still using Python 2.5, however, you'll need to stick to |
| 74 |
Django 1.4 until you can upgrade your Python version. Per :doc:`our support |
| 75 |
policy </internals/release-process>`, Django 1.4 will continue to receive |
| 76 |
security support until the release of Django 1.6. |
| 77 |
|
| 78 |
Django 1.5 does not run on a Jython final release, because Jython's latest |
| 79 |
release doesn't currently support Python 2.6. However, Jython currently does |
| 80 |
offer an alpha release featuring 2.7 support, and Django 1.5 supports that alpha |
| 81 |
release. |
| 82 |
|
| 83 |
Python 3 support |
| 84 |
---------------- |
| 85 |
|
| 86 |
Django 1.5 introduces support for Python 3 - specifically, Python |
| 87 |
3.2 and above. This comes in the form of a **single** codebase; you don't |
| 88 |
need to install a different version of Django on Python 3. This means that |
| 89 |
you can write applications targeted for just Python 2, just Python 3, or single |
| 90 |
applications that support both platforms. |
| 91 |
|
| 92 |
However, we're labeling this support "experimental" for now: although it's |
| 93 |
received extensive testing via our automated test suite, it's received very |
| 94 |
little real-world testing. We've done our best to eliminate bugs, but we can't |
| 95 |
be sure we covered all possible uses of Django. |
| 96 |
|
| 97 |
Some features of Django aren't available because they depend on third-party |
| 98 |
software that hasn't been ported to Python 3 yet, including: |
| 99 |
|
| 100 |
- the MySQL database backend (depends on MySQLdb) |
| 101 |
- :class:`~django.db.models.ImageField` (depends on PIL) |
| 102 |
- :class:`~django.test.LiveServerTestCase` (depends on Selenium WebDriver) |
| 103 |
|
| 104 |
Further, Django's more than a web framework; it's an ecosystem of pluggable |
| 105 |
components. At this point, very few third-party applications have been ported |
| 106 |
to Python 3, so it's unlikely that a real-world application will have all its |
| 107 |
dependencies satisfied under Python 3. |
| 108 |
|
| 109 |
Thus, we're recommending that Django 1.5 not be used in production under Python |
| 110 |
3. Instead, use this opportunity to begin porting applications to Python 3. If |
| 111 |
you're an author of a pluggable component, we encourage you to start porting |
| 112 |
now. |
| 113 |
|
| 114 |
We plan to offer first-class, production-ready support for Python 3 in our next |
| 115 |
release, Django 1.6. |
| 116 |
|
| 117 |
.. _whats-new-1.5: |
| 118 |
|
| 119 |
What's new in Django 1.5 |
| 120 |
======================== |
| 121 |
|
| 122 |
Configurable User model |
| 123 |
----------------------- |
| 124 |
|
| 125 |
In Django 1.5, you can now use your own model as the store for user-related |
| 126 |
data. If your project needs a username with more than 30 characters, or if |
| 127 |
you want to store user's names in a format other than first name/last name, |
| 128 |
or you want to put custom profile information onto your User object, you can |
| 129 |
now do so. |
| 130 |
|
| 131 |
If you have a third-party reusable application that references the User model, |
| 132 |
you may need to make some changes to the way you reference User instances. You |
| 133 |
should also document any specific features of the User model that your |
| 134 |
application relies upon. |
| 135 |
|
| 136 |
See the :ref:`documentation on custom user models <auth-custom-user>` for |
| 137 |
more details. |
| 138 |
|
| 139 |
Support for saving a subset of model's fields |
| 140 |
--------------------------------------------- |
| 141 |
|
| 142 |
The method :meth:`Model.save() <django.db.models.Model.save()>` has a new |
| 143 |
keyword argument ``update_fields``. By using this argument it is possible to |
| 144 |
save only a select list of model's fields. This can be useful for performance |
| 145 |
reasons or when trying to avoid overwriting concurrent changes. |
| 146 |
|
| 147 |
Deferred instances (those loaded by ``.only()`` or ``.defer()``) will |
| 148 |
automatically save just the loaded fields. If any field is set manually after |
| 149 |
load, that field will also get updated on save. |
| 150 |
|
| 151 |
See the :meth:`Model.save() <django.db.models.Model.save()>` documentation for |
| 152 |
more details. |
| 153 |
|
| 154 |
Caching of related model instances |
| 155 |
---------------------------------- |
| 156 |
|
| 157 |
When traversing relations, the ORM will avoid re-fetching objects that were |
| 158 |
previously loaded. For example, with the tutorial's models: |
| 159 |
|
| 160 |
.. code-block:: pycon |
| 161 |
|
| 162 |
>>> first_poll = Poll.objects.all()[0] |
| 163 |
>>> first_choice = first_poll.choice_set.all()[0] |
| 164 |
>>> first_choice.poll is first_poll |
| 165 |
True |
| 166 |
|
| 167 |
In Django 1.5, the third line no longer triggers a new SQL query to fetch |
| 168 |
``first_choice.poll``; it was set by the second line. |
| 169 |
|
| 170 |
For one-to-one relationships, both sides can be cached. For many-to-one |
| 171 |
relationships, only the single side of the relationship can be cached. This |
| 172 |
is particularly helpful in combination with ``prefetch_related``. |
| 173 |
|
| 174 |
.. _explicit-streaming-responses: |
| 175 |
|
| 176 |
Explicit support for streaming responses |
| 177 |
---------------------------------------- |
| 178 |
|
| 179 |
Before Django 1.5, it was possible to create a streaming response by passing |
| 180 |
an iterator to :class:`~django.http.HttpResponse`. But this was unreliable: |
| 181 |
any middleware that accessed the :attr:`~django.http.HttpResponse.content` |
| 182 |
attribute would consume the iterator prematurely. |
| 183 |
|
| 184 |
You can now explicitly generate a streaming response with the new |
| 185 |
:class:`~django.http.StreamingHttpResponse` class. This class exposes a |
| 186 |
:class:`~django.http.StreamingHttpResponse.streaming_content` attribute which |
| 187 |
is an iterator. |
| 188 |
|
| 189 |
Since :class:`~django.http.StreamingHttpResponse` does not have a ``content`` |
| 190 |
attribute, middleware that needs access to the response content must test for |
| 191 |
streaming responses and behave accordingly. |
| 192 |
|
| 193 |
``{% verbatim %}`` template tag |
| 194 |
------------------------------- |
| 195 |
|
| 196 |
To make it easier to deal with JavaScript templates which collide with Django's |
| 197 |
syntax, you can now use the :ttag:`verbatim` block tag to avoid parsing the |
| 198 |
tag's content. |
| 199 |
|
| 200 |
Retrieval of ``ContentType`` instances associated with proxy models |
| 201 |
------------------------------------------------------------------- |
| 202 |
|
| 203 |
The methods :meth:`ContentTypeManager.get_for_model() <django.contrib.contenttypes.models.ContentTypeManager.get_for_model()>` |
| 204 |
and :meth:`ContentTypeManager.get_for_models() <django.contrib.contenttypes.models.ContentTypeManager.get_for_models()>` |
| 205 |
have a new keyword argument – respectively ``for_concrete_model`` and ``for_concrete_models``. |
| 206 |
By passing ``False`` using this argument it is now possible to retrieve the |
| 207 |
:class:`ContentType <django.contrib.contenttypes.models.ContentType>` |
| 208 |
associated with proxy models. |
| 209 |
|
| 210 |
New ``view`` variable in class-based views context |
| 211 |
-------------------------------------------------- |
| 212 |
|
| 213 |
In all :doc:`generic class-based views </topics/class-based-views/index>` |
| 214 |
(or any class-based view inheriting from ``ContextMixin``), the context dictionary |
| 215 |
contains a ``view`` variable that points to the ``View`` instance. |
| 216 |
|
| 217 |
GeoDjango |
| 218 |
--------- |
| 219 |
|
| 220 |
* :class:`~django.contrib.gis.geos.LineString` and |
| 221 |
:class:`~django.contrib.gis.geos.MultiLineString` GEOS objects now support the |
| 222 |
:meth:`~django.contrib.gis.geos.GEOSGeometry.interpolate()` and |
| 223 |
:meth:`~django.contrib.gis.geos.GEOSGeometry.project()` methods |
| 224 |
(so-called linear referencing). |
| 225 |
|
| 226 |
* The ``wkb`` and ``hex`` properties of |
| 227 |
:class:`~django.contrib.gis.geos.GEOSGeometry` objects preserve the Z |
| 228 |
dimension. |
| 229 |
|
| 230 |
* Support for PostGIS 2.0 has been added and support for GDAL < 1.5 has been |
| 231 |
dropped. |
| 232 |
|
| 233 |
New tutorials |
| 234 |
------------- |
| 235 |
|
| 236 |
Additions to the docs include a revamped :doc:`Tutorial 3</intro/tutorial03>` |
| 237 |
and a new :doc:`tutorial on testing</intro/tutorial05>`. A new section, |
| 238 |
"Advanced Tutorials", offers :doc:`How to write reusable apps |
| 239 |
</intro/reusable-apps>` as well as a step-by-step guide for new contributors in |
| 240 |
:doc:`Writing your first patch for Django </intro/contributing>`. |
| 241 |
|
| 242 |
Minor features |
| 243 |
-------------- |
| 244 |
|
| 245 |
Django 1.5 also includes several smaller improvements worth noting: |
| 246 |
|
| 247 |
* The template engine now interprets ``True``, ``False`` and ``None`` as the |
| 248 |
corresponding Python objects. |
| 249 |
|
| 250 |
* :mod:`django.utils.timezone` provides a helper for converting aware |
| 251 |
datetimes between time zones. See :func:`~django.utils.timezone.localtime`. |
| 252 |
|
| 253 |
* The generic views support OPTIONS requests. |
| 254 |
|
| 255 |
* Management commands do not raise ``SystemExit`` any more when called by code |
| 256 |
from :func:`~django.core.management.call_command`. Any exception raised by |
| 257 |
the command (mostly :exc:`~django.core.management.CommandError`) is |
| 258 |
propagated. |
| 259 |
|
| 260 |
Moreover, when you output errors or messages in your custom commands, you |
| 261 |
should now use ``self.stdout.write('message')`` and |
| 262 |
``self.stderr.write('error')`` (see the note on |
| 263 |
:ref:`management commands output <management-commands-output>`). |
| 264 |
|
| 265 |
* The :djadmin:`dumpdata` management command outputs one row at a time, |
| 266 |
preventing out-of-memory errors when dumping large datasets. |
| 267 |
|
| 268 |
* In the localflavor for Canada, ``pq`` was added to the acceptable codes for |
| 269 |
Quebec. It's an old abbreviation. |
| 270 |
|
| 271 |
* The :ref:`receiver <connecting-receiver-functions>` decorator is now able to |
| 272 |
connect to more than one signal by supplying a list of signals. |
| 273 |
|
| 274 |
* In the admin, you can now filter users by groups which they are members of. |
| 275 |
|
| 276 |
* :meth:`QuerySet.bulk_create() |
| 277 |
<django.db.models.query.QuerySet.bulk_create>` now has a batch_size |
| 278 |
argument. By default the batch_size is unlimited except for SQLite where |
| 279 |
single batch is limited so that 999 parameters per query isn't exceeded. |
| 280 |
|
| 281 |
* The :setting:`LOGIN_URL` and :setting:`LOGIN_REDIRECT_URL` settings now also |
| 282 |
accept view function names and |
| 283 |
:ref:`named URL patterns <naming-url-patterns>`. This allows you to reduce |
| 284 |
configuration duplication. More information can be found in the |
| 285 |
:func:`~django.contrib.auth.decorators.login_required` documentation. |
| 286 |
|
| 287 |
* Django now provides a mod_wsgi :doc:`auth handler |
| 288 |
</howto/deployment/wsgi/apache-auth>`. |
| 289 |
|
| 290 |
* The :meth:`QuerySet.delete() <django.db.models.query.QuerySet.delete>` |
| 291 |
and :meth:`Model.delete() <django.db.models.Model.delete()>` can now take |
| 292 |
fast-path in some cases. The fast-path allows for less queries and less |
| 293 |
objects fetched into memory. See :meth:`QuerySet.delete() |
| 294 |
<django.db.models.query.QuerySet.delete>` for details. |
| 295 |
|
| 296 |
* An instance of ``ResolverMatch`` is stored on the request as |
| 297 |
``resolver_match``. |
| 298 |
|
| 299 |
* By default, all logging messages reaching the ``django`` logger when |
| 300 |
:setting:`DEBUG` is ``True`` are sent to the console (unless you redefine the |
| 301 |
logger in your :setting:`LOGGING` setting). |
| 302 |
|
| 303 |
* When using :class:`~django.template.RequestContext`, it is now possible to |
| 304 |
look up permissions by using ``{% if 'someapp.someperm' in perms %}`` |
| 305 |
in templates. |
| 306 |
|
| 307 |
* It's not required any more to have ``404.html`` and ``500.html`` templates in |
| 308 |
the root templates directory. Django will output some basic error messages for |
| 309 |
both situations when those templates are not found. It's still recommended as |
| 310 |
good practice to provide those templates in order to present pretty error |
| 311 |
pages to the user. |
| 312 |
|
| 313 |
* :mod:`django.contrib.auth` provides a new signal that is emitted |
| 314 |
whenever a user fails to login successfully. See |
| 315 |
:data:`~django.contrib.auth.signals.user_login_failed` |
| 316 |
|
| 317 |
* The new :option:`loaddata --ignorenonexistent` option ignore data for fields |
| 318 |
that no longer exist. |
| 319 |
|
| 320 |
* :meth:`~django.test.SimpleTestCase.assertXMLEqual` and |
| 321 |
:meth:`~django.test.SimpleTestCase.assertXMLNotEqual` new assertions allow |
| 322 |
you to test equality for XML content at a semantic level, without caring for |
| 323 |
syntax differences (spaces, attribute order, etc.). |
| 324 |
|
| 325 |
* RemoteUserMiddleware now forces logout when the REMOTE_USER header |
| 326 |
disappears during the same browser session. |
| 327 |
|
| 328 |
* The :ref:`cache-based session backend <cached-sessions-backend>` can store |
| 329 |
session data in a non-default cache. |
| 330 |
|
| 331 |
* Multi-column indexes can now be created on models. Read the |
| 332 |
``index_together`` documentation for more information. |
| 333 |
|
| 334 |
* During Django's logging configuration verbose Deprecation warnings are |
| 335 |
enabled and warnings are captured into the logging system. Logged warnings |
| 336 |
are routed through the ``console`` logging handler, which by default requires |
| 337 |
:setting:`DEBUG` to be True for output to be generated. The result is that |
| 338 |
DeprecationWarnings should be printed to the console in development |
| 339 |
environments the way they have been in Python versions < 2.7. |
| 340 |
|
| 341 |
* The API for :meth:`django.contrib.admin.ModelAdmin.message_user` method has |
| 342 |
been modified to accept additional arguments adding capabilities similar to |
| 343 |
:func:`django.contrib.messages.add_message`. This is useful for generating |
| 344 |
error messages from admin actions. |
| 345 |
|
| 346 |
* The admin's list filters can now be customized per-request thanks to the new |
| 347 |
:meth:`django.contrib.admin.ModelAdmin.get_list_filter` method. |
| 348 |
|
| 349 |
.. _backwards-incompatible-1.5: |
| 350 |
|
| 351 |
Backwards incompatible changes in 1.5 |
| 352 |
===================================== |
| 353 |
|
| 354 |
.. warning:: |
| 355 |
|
| 356 |
In addition to the changes outlined in this section, be sure to review the |
| 357 |
:ref:`deprecation plan <deprecation-removed-in-1.5>` for any features that |
| 358 |
have been removed. If you haven't updated your code within the |
| 359 |
deprecation timeline for a given feature, its removal may appear as a |
| 360 |
backwards incompatible change. |
| 361 |
|
| 362 |
``ALLOWED_HOSTS`` required in production |
| 363 |
---------------------------------------- |
| 364 |
|
| 365 |
The new :setting:`ALLOWED_HOSTS` setting validates the request's ``Host`` |
| 366 |
header and protects against host-poisoning attacks. This setting is now |
| 367 |
required whenever :setting:`DEBUG` is ``False``, or else |
| 368 |
:meth:`django.http.HttpRequest.get_host()` will raise |
| 369 |
:exc:`~django.core.exceptions.SuspiciousOperation`. For more details see the |
| 370 |
:setting:`full documentation<ALLOWED_HOSTS>` for the new setting. |
| 371 |
|
| 372 |
Managers on abstract models |
| 373 |
--------------------------- |
| 374 |
|
| 375 |
Abstract models are able to define a custom manager, and that manager |
| 376 |
:ref:`will be inherited by any concrete models extending the abstract model |
| 377 |
<custom-managers-and-inheritance>`. However, if you try to use the abstract |
| 378 |
model to call a method on the manager, an exception will now be raised. |
| 379 |
Previously, the call would have been permitted, but would have failed as soon |
| 380 |
as any database operation was attempted (usually with a "table does not exist" |
| 381 |
error from the database). |
| 382 |
|
| 383 |
If you have functionality on a manager that you have been invoking using |
| 384 |
the abstract class, you should migrate that logic to a Python |
| 385 |
``staticmethod`` or ``classmethod`` on the abstract class. |
| 386 |
|
| 387 |
Context in year archive class-based views |
| 388 |
----------------------------------------- |
| 389 |
|
| 390 |
For consistency with the other date-based generic views, |
| 391 |
:class:`~django.views.generic.dates.YearArchiveView` now passes ``year`` in |
| 392 |
the context as a :class:`datetime.date` rather than a string. If you are |
| 393 |
using ``{{ year }}`` in your templates, you must replace it with ``{{ |
| 394 |
year|date:"Y" }}``. |
| 395 |
|
| 396 |
``next_year`` and ``previous_year`` were also added in the context. They are |
| 397 |
calculated according to ``allow_empty`` and ``allow_future``. |
| 398 |
|
| 399 |
Context in year and month archive class-based views |
| 400 |
--------------------------------------------------- |
| 401 |
|
| 402 |
:class:`~django.views.generic.dates.YearArchiveView` and |
| 403 |
:class:`~django.views.generic.dates.MonthArchiveView` were documented to |
| 404 |
provide a ``date_list`` sorted in ascending order in the context, like their |
| 405 |
function-based predecessors, but it actually was in descending order. In 1.5, |
| 406 |
the documented order was restored. You may want to add (or remove) the |
| 407 |
``reversed`` keyword when you're iterating on ``date_list`` in a template: |
| 408 |
|
| 409 |
.. code-block:: html+django |
| 410 |
|
| 411 |
{% for date in date_list reversed %} |
| 412 |
|
| 413 |
:class:`~django.views.generic.dates.ArchiveIndexView` still provides a |
| 414 |
``date_list`` in descending order. |
| 415 |
|
| 416 |
Context in TemplateView |
| 417 |
----------------------- |
| 418 |
|
| 419 |
For consistency with the design of the other generic views, |
| 420 |
:class:`~django.views.generic.base.TemplateView` no longer passes a ``params`` |
| 421 |
dictionary into the context, instead passing the variables from the URLconf |
| 422 |
directly into the context. |
| 423 |
|
| 424 |
Non-form data in HTTP requests |
| 425 |
------------------------------ |
| 426 |
|
| 427 |
:attr:`request.POST <django.http.HttpRequest.POST>` will no longer include data |
| 428 |
posted via HTTP requests with non form-specific content-types in the header. |
| 429 |
In prior versions, data posted with content-types other than |
| 430 |
:mimetype:`multipart/form-data` or |
| 431 |
:mimetype:`application/x-www-form-urlencoded` would still end up represented in |
| 432 |
the :attr:`request.POST <django.http.HttpRequest.POST>` attribute. Developers |
| 433 |
wishing to access the raw POST data for these cases, should use the |
| 434 |
:attr:`request.body <django.http.HttpRequest.body>` attribute instead. |
| 435 |
|
| 436 |
:data:`~django.core.signals.request_finished` signal |
| 437 |
---------------------------------------------------- |
| 438 |
|
| 439 |
Django used to send the :data:`~django.core.signals.request_finished` signal |
| 440 |
as soon as the view function returned a response. This interacted badly with |
| 441 |
:ref:`streaming responses <httpresponse-streaming>` that delay content |
| 442 |
generation. |
| 443 |
|
| 444 |
This signal is now sent after the content is fully consumed by the WSGI |
| 445 |
gateway. This might be backwards incompatible if you rely on the signal being |
| 446 |
fired before sending the response content to the client. If you do, you should |
| 447 |
consider using :doc:`middleware </topics/http/middleware>` instead. |
| 448 |
|
| 449 |
.. note:: |
| 450 |
|
| 451 |
Some WSGI servers and middleware do not always call ``close`` on the |
| 452 |
response object after handling a request, most notably uWSGI prior to 1.2.6 |
| 453 |
and Sentry's error reporting middleware up to 2.0.7. In those cases the |
| 454 |
``request_finished`` signal isn't sent at all. This can result in idle |
| 455 |
connections to database and memcache servers. |
| 456 |
|
| 457 |
OPTIONS, PUT and DELETE requests in the test client |
| 458 |
--------------------------------------------------- |
| 459 |
|
| 460 |
Unlike GET and POST, these HTTP methods aren't implemented by web browsers. |
| 461 |
Rather, they're used in APIs, which transfer data in various formats such as |
| 462 |
JSON or XML. Since such requests may contain arbitrary data, Django doesn't |
| 463 |
attempt to decode their body. |
| 464 |
|
| 465 |
However, the test client used to build a query string for OPTIONS and DELETE |
| 466 |
requests like for GET, and a request body for PUT requests like for POST. This |
| 467 |
encoding was arbitrary and inconsistent with Django's behavior when it |
| 468 |
receives the requests, so it was removed in Django 1.5. |
| 469 |
|
| 470 |
If you were using the ``data`` parameter in an OPTIONS or a DELETE request, |
| 471 |
you must convert it to a query string and append it to the ``path`` parameter. |
| 472 |
|
| 473 |
If you were using the ``data`` parameter in a PUT request without a |
| 474 |
``content_type``, you must encode your data before passing it to the test |
| 475 |
client and set the ``content_type`` argument. |
| 476 |
|
| 477 |
.. _simplejson-incompatibilities: |
| 478 |
|
| 479 |
System version of ``simplejson`` no longer used |
| 480 |
----------------------------------------------- |
| 481 |
|
| 482 |
:ref:`As explained below <simplejson-deprecation>`, Django 1.5 deprecates |
| 483 |
``django.utils.simplejson`` in favor of Python 2.6's built-in :mod:`json` |
| 484 |
module. In theory, this change is harmless. Unfortunately, because of |
| 485 |
incompatibilities between versions of ``simplejson``, it may trigger errors |
| 486 |
in some circumstances. |
| 487 |
|
| 488 |
JSON-related features in Django 1.4 always used ``django.utils.simplejson``. |
| 489 |
This module was actually: |
| 490 |
|
| 491 |
- A system version of ``simplejson``, if one was available (i.e. ``import |
| 492 |
simplejson`` works), if it was more recent than Django's built-in copy or it |
| 493 |
had the C speedups, or |
| 494 |
- The :mod:`json` module from the standard library, if it was available (i.e. |
| 495 |
Python 2.6 or greater), or |
| 496 |
- A built-in copy of version 2.0.7 of ``simplejson``. |
| 497 |
|
| 498 |
In Django 1.5, those features use Python's :mod:`json` module, which is based |
| 499 |
on version 2.0.9 of ``simplejson``. |
| 500 |
|
| 501 |
There are no known incompatibilities between Django's copy of version 2.0.7 and |
| 502 |
Python's copy of version 2.0.9. However, there are some incompatibilities |
| 503 |
between other versions of ``simplejson``: |
| 504 |
|
| 505 |
- While the ``simplejson`` API is documented as always returning Unicode |
| 506 |
strings, the optional C implementation can return a bytestring. This was |
| 507 |
fixed in Python 2.7. |
| 508 |
- ``simplejson.JSONEncoder`` gained a ``namedtuple_as_object`` keyword |
| 509 |
argument in version 2.2. |
| 510 |
|
| 511 |
More information on these incompatibilities is available in |
| 512 |
:ticket:`ticket #18023 <18023#comment:10>`. |
| 513 |
|
| 514 |
The net result is that, if you have installed ``simplejson`` and your code |
| 515 |
uses Django's serialization internals directly -- for instance |
| 516 |
``django.core.serializers.json.DjangoJSONEncoder``, the switch from |
| 517 |
``simplejson`` to :mod:`json` could break your code. (In general, changes to |
| 518 |
internals aren't documented; we're making an exception here.) |
| 519 |
|
| 520 |
At this point, the maintainers of Django believe that using :mod:`json` from |
| 521 |
the standard library offers the strongest guarantee of backwards-compatibility. |
| 522 |
They recommend to use it from now on. |
| 523 |
|
| 524 |
String types of hasher method parameters |
| 525 |
---------------------------------------- |
| 526 |
|
| 527 |
If you have written a :ref:`custom password hasher <auth_password_storage>`, |
| 528 |
your ``encode()``, ``verify()`` or ``safe_summary()`` methods should accept |
| 529 |
Unicode parameters (``password``, ``salt`` or ``encoded``). If any of the |
| 530 |
hashing methods need bytestrings, you can use the |
| 531 |
:func:`~django.utils.encoding.force_bytes` utility to encode the strings. |
| 532 |
|
| 533 |
Validation of previous_page_number and next_page_number |
| 534 |
------------------------------------------------------- |
| 535 |
|
| 536 |
When using :doc:`object pagination </topics/pagination>`, |
| 537 |
the ``previous_page_number()`` and ``next_page_number()`` methods of the |
| 538 |
:class:`~django.core.paginator.Page` object did not check if the returned |
| 539 |
number was inside the existing page range. |
| 540 |
It does check it now and raises an :exc:`~django.core.paginator.InvalidPage` |
| 541 |
exception when the number is either too low or too high. |
| 542 |
|
| 543 |
Behavior of autocommit database option on PostgreSQL changed |
| 544 |
------------------------------------------------------------ |
| 545 |
|
| 546 |
PostgreSQL's autocommit option didn't work as advertised previously. It did |
| 547 |
work for single transaction block, but after the first block was left the |
| 548 |
autocommit behavior was never restored. This bug is now fixed in 1.5. While |
| 549 |
this is only a bug fix, it is worth checking your applications behavior if |
| 550 |
you are using PostgreSQL together with the autocommit option. |
| 551 |
|
| 552 |
Session not saved on 500 responses |
| 553 |
---------------------------------- |
| 554 |
|
| 555 |
Django's session middleware will skip saving the session data if the |
| 556 |
response's status code is 500. |
| 557 |
|
| 558 |
Email checks on failed admin login |
| 559 |
---------------------------------- |
| 560 |
|
| 561 |
Prior to Django 1.5, if you attempted to log into the admin interface and |
| 562 |
mistakenly used your email address instead of your username, the admin |
| 563 |
interface would provide a warning advising that your email address was |
| 564 |
not your username. In Django 1.5, the introduction of |
| 565 |
:ref:`custom user models <auth-custom-user>` has required the removal of this |
| 566 |
warning. This doesn't change the login behavior of the admin site; it only |
| 567 |
affects the warning message that is displayed under one particular mode of |
| 568 |
login failure. |
| 569 |
|
| 570 |
Changes in tests execution |
| 571 |
-------------------------- |
| 572 |
|
| 573 |
Some changes have been introduced in the execution of tests that might be |
| 574 |
backward-incompatible for some testing setups: |
| 575 |
|
| 576 |
Database flushing in ``django.test.TransactionTestCase`` |
| 577 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 578 |
|
| 579 |
Previously, the test database was truncated *before* each test run in a |
| 580 |
:class:`~django.test.TransactionTestCase`. |
| 581 |
|
| 582 |
In order to be able to run unit tests in any order and to make sure they are |
| 583 |
always isolated from each other, :class:`~django.test.TransactionTestCase` will |
| 584 |
now reset the database *after* each test run instead. |
| 585 |
|
| 586 |
No more implicit DB sequences reset |
| 587 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 588 |
|
| 589 |
:class:`~django.test.TransactionTestCase` tests used to reset primary key |
| 590 |
sequences automatically together with the database flushing actions described |
| 591 |
above. |
| 592 |
|
| 593 |
This has been changed so no sequences are implicitly reset. This can cause |
| 594 |
:class:`~django.test.TransactionTestCase` tests that depend on hard-coded |
| 595 |
primary key values to break. |
| 596 |
|
| 597 |
The new :attr:`~django.test.TransactionTestCase.reset_sequences` attribute can |
| 598 |
be used to force the old behavior for :class:`~django.test.TransactionTestCase` |
| 599 |
that might need it. |
| 600 |
|
| 601 |
Ordering of tests |
| 602 |
~~~~~~~~~~~~~~~~~ |
| 603 |
|
| 604 |
In order to make sure all ``TestCase`` code starts with a clean database, |
| 605 |
tests are now executed in the following order: |
| 606 |
|
| 607 |
* First, all unit tests (including :class:`unittest.TestCase`, |
| 608 |
:class:`~django.test.SimpleTestCase`, :class:`~django.test.TestCase` and |
| 609 |
:class:`~django.test.TransactionTestCase`) are run with no particular ordering |
| 610 |
guaranteed nor enforced among them. |
| 611 |
|
| 612 |
* Then any other tests (e.g. doctests) that may alter the database without |
| 613 |
restoring it to its original state are run. |
| 614 |
|
| 615 |
This should not cause any problems unless you have existing doctests which |
| 616 |
assume a :class:`~django.test.TransactionTestCase` executed earlier left some |
| 617 |
database state behind or unit tests that rely on some form of state being |
| 618 |
preserved after the execution of other tests. Such tests are already very |
| 619 |
fragile, and must now be changed to be able to run independently. |
| 620 |
|
| 621 |
``cleaned_data`` dictionary kept for invalid forms |
| 622 |
-------------------------------------------------- |
| 623 |
|
| 624 |
The :attr:`~django.forms.Form.cleaned_data` dictionary is now always present |
| 625 |
after form validation. When the form doesn't validate, it contains only the |
| 626 |
fields that passed validation. You should test the success of the validation |
| 627 |
with the :meth:`~django.forms.Form.is_valid()` method and not with the |
| 628 |
presence or absence of the :attr:`~django.forms.Form.cleaned_data` attribute |
| 629 |
on the form. |
| 630 |
|
| 631 |
Behavior of ``syncdb`` with multiple databases |
| 632 |
---------------------------------------------- |
| 633 |
|
| 634 |
``syncdb`` now queries the database routers to determine if content |
| 635 |
types (when :mod:`~django.contrib.contenttypes` is enabled) and permissions |
| 636 |
(when :mod:`~django.contrib.auth` is enabled) should be created in the target |
| 637 |
database. Previously, it created them in the default database, even when |
| 638 |
another database was specified with the ``--database`` option. |
| 639 |
|
| 640 |
If you use ``syncdb`` on multiple databases, you should ensure that |
| 641 |
your routers allow synchronizing content types and permissions to only one of |
| 642 |
them. See the docs on the :ref:`behavior of contrib apps with multiple |
| 643 |
databases <contrib_app_multiple_databases>` for more information. |
| 644 |
|
| 645 |
XML deserializer will not parse documents with a DTD |
| 646 |
---------------------------------------------------- |
| 647 |
|
| 648 |
In order to prevent exposure to denial-of-service attacks related to external |
| 649 |
entity references and entity expansion, the XML model deserializer now refuses |
| 650 |
to parse XML documents containing a DTD (DOCTYPE definition). Since the XML |
| 651 |
serializer does not output a DTD, this will not impact typical usage, only |
| 652 |
cases where custom-created XML documents are passed to Django's model |
| 653 |
deserializer. |
| 654 |
|
| 655 |
Formsets default ``max_num`` |
| 656 |
---------------------------- |
| 657 |
|
| 658 |
A (default) value of ``None`` for the ``max_num`` argument to a formset factory |
| 659 |
no longer defaults to allowing any number of forms in the formset. Instead, in |
| 660 |
order to prevent memory-exhaustion attacks, it now defaults to a limit of 1000 |
| 661 |
forms. This limit can be raised by explicitly setting a higher value for |
| 662 |
``max_num``. |
| 663 |
|
| 664 |
Miscellaneous |
| 665 |
------------- |
| 666 |
|
| 667 |
* :class:`django.forms.ModelMultipleChoiceField` now returns an empty |
| 668 |
``QuerySet`` as the empty value instead of an empty list. |
| 669 |
|
| 670 |
* :func:`~django.utils.http.int_to_base36` properly raises a |
| 671 |
:exc:`TypeError` instead of :exc:`ValueError` for non-integer inputs. |
| 672 |
|
| 673 |
* The ``slugify`` template filter is now available as a standard Python |
| 674 |
function at :func:`django.utils.text.slugify`. Similarly, ``remove_tags`` is |
| 675 |
available at ``django.utils.html.remove_tags()``. |
| 676 |
|
| 677 |
* Uploaded files are no longer created as executable by default. If you need |
| 678 |
them to be executable change :setting:`FILE_UPLOAD_PERMISSIONS` to your |
| 679 |
needs. The new default value is ``0o666`` (octal) and the current umask value |
| 680 |
is first masked out. |
| 681 |
|
| 682 |
* The :class:`F expressions <django.db.models.F>` supported bitwise operators by |
| 683 |
``&`` and ``|``. These operators are now available using ``.bitand()`` and |
| 684 |
``.bitor()`` instead. The removal of ``&`` and ``|`` was done to be |
| 685 |
consistent with :ref:`Q() expressions <complex-lookups-with-q>` and |
| 686 |
``QuerySet`` combining where the operators are used as boolean AND and OR |
| 687 |
operators. |
| 688 |
|
| 689 |
* In a ``filter()`` call, when :class:`F expressions <django.db.models.F>` |
| 690 |
contained lookups spanning multi-valued relations, they didn't always reuse |
| 691 |
the same relations as other lookups along the same chain. This was changed, |
| 692 |
and now F() expressions will always use the same relations as other lookups |
| 693 |
within the same ``filter()`` call. |
| 694 |
|
| 695 |
* The :ttag:`csrf_token` template tag is no longer enclosed in a div. If you need |
| 696 |
HTML validation against pre-HTML5 Strict DTDs, you should add a div around it |
| 697 |
in your pages. |
| 698 |
|
| 699 |
* The template tags library ``adminmedia``, which only contained the |
| 700 |
deprecated template tag ``{% admin_media_prefix %}``, was removed. |
| 701 |
Attempting to load it with ``{% load adminmedia %}`` will fail. If your |
| 702 |
templates still contain that line you must remove it. |
| 703 |
|
| 704 |
* Because of an implementation oversight, it was possible to use |
| 705 |
:doc:`django.contrib.redirects </ref/contrib/redirects>` without enabling |
| 706 |
:doc:`django.contrib.sites </ref/contrib/sites>`. This isn't allowed any |
| 707 |
longer. If you're using ``django.contrib.redirects``, make sure |
| 708 |
:setting:`INSTALLED_APPS` contains ``django.contrib.sites``. |
| 709 |
|
| 710 |
* :meth:`BoundField.label_tag <django.forms.BoundField.label_tag>` now |
| 711 |
escapes its ``contents`` argument. To avoid the HTML escaping, use |
| 712 |
:func:`django.utils.safestring.mark_safe` on the argument before passing it. |
| 713 |
|
| 714 |
* Accessing reverse one-to-one relations fetched via |
| 715 |
:meth:`~django.db.models.query.QuerySet.select_related` now raises |
| 716 |
:exc:`~django.db.models.Model.DoesNotExist` instead of returning ``None``. |
| 717 |
|
| 718 |
.. _deprecated-features-1.5: |
| 719 |
|
| 720 |
Features deprecated in 1.5 |
| 721 |
========================== |
| 722 |
|
| 723 |
``django.contrib.localflavor`` |
| 724 |
------------------------------ |
| 725 |
|
| 726 |
The localflavor contrib app has been split into separate packages. |
| 727 |
``django.contrib.localflavor`` itself will be removed in Django 1.6, |
| 728 |
after an accelerated deprecation. |
| 729 |
|
| 730 |
The new packages are available on GitHub. The core team cannot |
| 731 |
efficiently maintain these packages in the long term — it spans just a |
| 732 |
dozen countries at this time; similar to translations, maintenance |
| 733 |
will be handed over to interested members of the community. |
| 734 |
|
| 735 |
``django.contrib.markup`` |
| 736 |
------------------------- |
| 737 |
|
| 738 |
The markup contrib module has been deprecated and will follow an accelerated |
| 739 |
deprecation schedule. Direct use of Python markup libraries or 3rd party tag |
| 740 |
libraries is preferred to Django maintaining this functionality in the |
| 741 |
framework. |
| 742 |
|
| 743 |
``AUTH_PROFILE_MODULE`` |
| 744 |
----------------------- |
| 745 |
|
| 746 |
With the introduction of :ref:`custom user models <auth-custom-user>`, there is |
| 747 |
no longer any need for a built-in mechanism to store user profile data. |
| 748 |
|
| 749 |
You can still define user profiles models that have a one-to-one relation with |
| 750 |
the User model - in fact, for many applications needing to associate data with |
| 751 |
a User account, this will be an appropriate design pattern to follow. However, |
| 752 |
the ``AUTH_PROFILE_MODULE`` setting, and the |
| 753 |
``django.contrib.auth.models.User.get_profile()`` method for accessing |
| 754 |
the user profile model, should not be used any longer. |
| 755 |
|
| 756 |
Streaming behavior of :class:`~django.http.HttpResponse` |
| 757 |
-------------------------------------------------------- |
| 758 |
|
| 759 |
Django 1.5 deprecates the ability to stream a response by passing an iterator |
| 760 |
to :class:`~django.http.HttpResponse`. If you rely on this behavior, switch to |
| 761 |
:class:`~django.http.StreamingHttpResponse`. See |
| 762 |
:ref:`explicit-streaming-responses` above. |
| 763 |
|
| 764 |
In Django 1.7 and above, the iterator will be consumed immediately by |
| 765 |
:class:`~django.http.HttpResponse`. |
| 766 |
|
| 767 |
.. _simplejson-deprecation: |
| 768 |
|
| 769 |
``django.utils.simplejson`` |
| 770 |
--------------------------- |
| 771 |
|
| 772 |
Since Django 1.5 drops support for Python 2.5, we can now rely on the |
| 773 |
:mod:`json` module being available in Python's standard library, so we've |
| 774 |
removed our own copy of ``simplejson``. You should now import :mod:`json` |
| 775 |
instead of ``django.utils.simplejson``. |
| 776 |
|
| 777 |
Unfortunately, this change might have unwanted side-effects, because of |
| 778 |
incompatibilities between versions of ``simplejson`` -- see the |
| 779 |
:ref:`backwards-incompatible changes <simplejson-incompatibilities>` section. |
| 780 |
If you rely on features added to ``simplejson`` after it became Python's |
| 781 |
:mod:`json`, you should import ``simplejson`` explicitly. |
| 782 |
|
| 783 |
``django.utils.encoding.StrAndUnicode`` |
| 784 |
--------------------------------------- |
| 785 |
|
| 786 |
The ``django.utils.encoding.StrAndUnicode`` mix-in has been deprecated. |
| 787 |
Define a ``__str__`` method and apply the |
| 788 |
``django.utils.encoding.python_2_unicode_compatible`` decorator instead. |
| 789 |
|
| 790 |
``django.utils.itercompat.product`` |
| 791 |
----------------------------------- |
| 792 |
|
| 793 |
The ``django.utils.itercompat.product`` function has been deprecated. Use |
| 794 |
the built-in :func:`itertools.product` instead. |
| 795 |
|
| 796 |
``cleanup`` management command |
| 797 |
------------------------------ |
| 798 |
|
| 799 |
The ``cleanup`` management command has been deprecated and replaced by |
| 800 |
:djadmin:`clearsessions`. |
| 801 |
|
| 802 |
``daily_cleanup.py`` script |
| 803 |
--------------------------- |
| 804 |
|
| 805 |
The undocumented ``daily_cleanup.py`` script has been deprecated. Use the |
| 806 |
:djadmin:`clearsessions` management command instead. |
| 807 |
|
| 808 |
``depth`` keyword argument in ``select_related`` |
| 809 |
------------------------------------------------ |
| 810 |
|
| 811 |
The ``depth`` keyword argument in |
| 812 |
:meth:`~django.db.models.query.QuerySet.select_related` has been deprecated. |
| 813 |
You should use field names instead. |