Debian Codegraph @

docs/releases/1.5.txt

raw
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.