Debian Codegraph @

docs/releases/1.8.txt

raw
1 ========================
2 Django 1.8 release notes
3 ========================
4
5 *April 1, 2015*
6
7 Welcome to Django 1.8!
8
9 These release notes cover the :ref:`new features <whats-new-1.8>`, as well as
10 some :ref:`backwards incompatible changes <backwards-incompatible-1.8>` you'll
11 want to be aware of when upgrading from Django 1.7 or older versions. We've
12 also :ref:`begun the deprecation process for some features
13 <deprecated-features-1.8>`, and some features have reached the end of their
14 deprecation process and :ref:`have been removed <removed-features-1.8>`.
15
16 See the :doc:`/howto/upgrade-version` guide if you're updating an existing
17 project.
18
19 Django 1.8 has been designated as Django's second :term:`long-term support
20 release <Long-term support release>`. It will receive security updates for at
21 least three years after its release. Support for the previous LTS, Django 1.4,
22 will end 6 months from the release date of Django 1.8.
23
24 Python compatibility
25 ====================
26
27 Django 1.8 requires Python 2.7, 3.2, 3.3, 3.4, or 3.5. We **highly recommend**
28 and only officially support the latest release of each series.
29
30 Django 1.8 is the first release to support Python 3.5.
31
32 Due to the end of upstream support for Python 3.2 in February 2016, we won't
33 test Django 1.8.x on Python 3.2 after the end of 2016.
34
35 .. _whats-new-1.8:
36
37 What's new in Django 1.8
38 ========================
39
40 ``Model._meta`` API
41 -------------------
42
43 Django now has a formalized API for :doc:`Model._meta </ref/models/meta>`,
44 providing an officially supported way to :ref:`retrieve fields
45 <model-meta-field-api>` and filter fields based on their :ref:`attributes
46 <model-field-attributes>`.
47
48 The ``Model._meta`` object has been part of Django since the days of pre-0.96
49 "Magic Removal" -- it just wasn't an official, stable API. In recognition of
50 this, we've endeavored to maintain backwards-compatibility with the old
51 API endpoint where possible. However, API endpoints that aren't part of the
52 new official API have been deprecated and will eventually be removed.
53
54 Multiple template engines
55 -------------------------
56
57 Django 1.8 defines a stable API for integrating template backends. It includes
58 built-in support for the Django template language and for
59 :class:`~django.template.backends.jinja2.Jinja2`. It supports rendering
60 templates with multiple engines within the same project. Learn more about the
61 new features in the :doc:`topic guide </topics/templates>` and check the
62 upgrade instructions in older versions of the documentation.
63
64 Security enhancements
65 ---------------------
66
67 Several features of the :pypi:`django-secure` third-party library have been
68 integrated into Django. :class:`django.middleware.security.SecurityMiddleware`
69 provides several security enhancements to the request/response cycle. The new
70 :option:`check --deploy` option allows you to check your production settings
71 file for ways to increase the security of your site.
72
73 New PostgreSQL specific functionality
74 -------------------------------------
75
76 Django now has a module with extensions for PostgreSQL specific features, such
77 as :class:`~django.contrib.postgres.fields.ArrayField`,
78 :class:`~django.contrib.postgres.fields.HStoreField`, :ref:`range-fields`, and
79 :lookup:`unaccent` lookup. A full breakdown of the features is available
80 :doc:`in the documentation </ref/contrib/postgres/index>`.
81
82 New data types
83 --------------
84
85 * Django now has a :class:`~django.db.models.UUIDField` for storing
86 universally unique identifiers. It is stored as the native ``uuid`` data type
87 on PostgreSQL and as a fixed length character field on other backends. There
88 is a corresponding :class:`form field <django.forms.UUIDField>`.
89
90 * Django now has a :class:`~django.db.models.DurationField` for storing periods
91 of time - modeled in Python by :class:`~python:datetime.timedelta`. It is
92 stored in the native ``interval`` data type on PostgreSQL, as a ``INTERVAL
93 DAY(9) TO SECOND(6)`` on Oracle, and as a ``bigint`` of microseconds on other
94 backends. Date and time related arithmetic has also been improved on all
95 backends. There is a corresponding :class:`form field
96 <django.forms.DurationField>`.
97
98 Query Expressions, Conditional Expressions, and Database Functions
99 ------------------------------------------------------------------
100
101 :doc:`Query Expressions </ref/models/expressions>` allow you to create,
102 customize, and compose complex SQL expressions. This has enabled annotate
103 to accept expressions other than aggregates. Aggregates are now able to
104 reference multiple fields, as well as perform arithmetic, similar to ``F()``
105 objects. :meth:`~django.db.models.query.QuerySet.order_by` has also gained the
106 ability to accept expressions.
107
108 :doc:`Conditional Expressions </ref/models/conditional-expressions>` allow
109 you to use :keyword:`if` ... :keyword:`elif` ... :keyword:`else` logic within
110 queries.
111
112 A collection of :doc:`database functions </ref/models/database-functions>` is
113 also included with functionality such as
114 :class:`~django.db.models.functions.Coalesce`,
115 :class:`~django.db.models.functions.Concat`, and
116 :class:`~django.db.models.functions.Substr`.
117
118 ``TestCase`` data setup
119 -----------------------
120
121 :class:`~django.test.TestCase` has been refactored to allow for data
122 initialization at the class level using transactions and savepoints. Database
123 backends which do not support transactions, like MySQL with the MyISAM storage
124 engine, will still be able to run these tests but won't benefit from the
125 improvements. Tests are now run within two nested
126 :func:`~django.db.transaction.atomic()` blocks: one for the whole class and one
127 for each test.
128
129 * The class method
130 :meth:`TestCase.setUpTestData() <django.test.TestCase.setUpTestData>` adds
131 the ability to set up test data at the class level. Using this technique can
132 speed up the tests as compared to using ``setUp()``.
133
134 * Fixture loading within ``TestCase`` is now performed once for the whole
135 ``TestCase``.
136
137 Minor features
138 --------------
139
140 :mod:`django.contrib.admin`
141 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
142
143 * :class:`~django.contrib.admin.ModelAdmin` now has a
144 :meth:`~django.contrib.admin.ModelAdmin.has_module_permission`
145 method to allow limiting access to the module on the admin index page.
146
147 * :class:`~django.contrib.admin.InlineModelAdmin` now has an attribute
148 :attr:`~django.contrib.admin.InlineModelAdmin.show_change_link` that
149 supports showing a link to an inline object's change form.
150
151 * Use the new ``django.contrib.admin.RelatedOnlyFieldListFilter`` in
152 :attr:`ModelAdmin.list_filter <django.contrib.admin.ModelAdmin.list_filter>`
153 to limit the ``list_filter`` choices to foreign objects which are attached to
154 those from the ``ModelAdmin``.
155
156 * The :meth:`ModelAdmin.delete_view()
157 <django.contrib.admin.ModelAdmin.delete_view>` displays a summary of objects
158 to be deleted on the deletion confirmation page.
159
160 * The jQuery library embedded in the admin has been upgraded to version 1.11.2.
161
162 * You can now specify :attr:`AdminSite.site_url
163 <django.contrib.admin.AdminSite.site_url>` in order to display a link to the
164 front-end site.
165
166 * You can now specify :attr:`ModelAdmin.show_full_result_count
167 <django.contrib.admin.ModelAdmin.show_full_result_count>` to control whether
168 or not the full count of objects should be displayed on a filtered admin page.
169
170 * The ``AdminSite.password_change()`` method now has an ``extra_context``
171 parameter.
172
173 * You can now control who may login to the admin site by overriding only
174 :meth:`AdminSite.has_permission()
175 <django.contrib.admin.AdminSite.has_permission>` and
176 :attr:`AdminSite.login_form <django.contrib.admin.AdminSite.login_form>`.
177 The ``base.html`` template has a new block ``usertools`` which contains the
178 user-specific header. A new context variable ``has_permission``, which gets
179 its value from :meth:`~django.contrib.admin.AdminSite.has_permission`,
180 indicates whether the user may access the site.
181
182 * Foreign key dropdowns now have buttons for changing or deleting related
183 objects using a popup.
184
185 :mod:`django.contrib.admindocs`
186 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
187
188 * reStructuredText is now parsed in model docstrings.
189
190 :mod:`django.contrib.auth`
191 ~~~~~~~~~~~~~~~~~~~~~~~~~~
192
193 * Authorization backends can now raise
194 :class:`~django.core.exceptions.PermissionDenied` in
195 :meth:`~django.contrib.auth.models.User.has_perm`
196 and :meth:`~django.contrib.auth.models.User.has_module_perms`
197 to short-circuit permission checking.
198 * :class:`~django.contrib.auth.forms.PasswordResetForm` now
199 has a method :meth:`~django.contrib.auth.forms.PasswordResetForm.send_mail`
200 that can be overridden to customize the mail to be sent.
201
202 * The ``max_length`` of :attr:`Permission.name
203 <django.contrib.auth.models.Permission.name>` has been increased from 50 to
204 255 characters. Please run the database migration.
205
206 * :attr:`~django.contrib.auth.models.CustomUser.USERNAME_FIELD` and
207 :attr:`~django.contrib.auth.models.CustomUser.REQUIRED_FIELDS` now supports
208 :class:`~django.db.models.ForeignKey`\s.
209
210 * The default iteration count for the PBKDF2 password hasher has been
211 increased by 33%. This backwards compatible change will not affect users who
212 have subclassed ``django.contrib.auth.hashers.PBKDF2PasswordHasher`` to
213 change the default value.
214
215 :mod:`django.contrib.gis`
216 ~~~~~~~~~~~~~~~~~~~~~~~~~
217
218 * A new :doc:`GeoJSON serializer </ref/contrib/gis/serializers>` is now
219 available.
220
221 * It is now allowed to include a subquery as a geographic lookup argument, for
222 example ``City.objects.filter(point__within=Country.objects.filter(continent='Africa').values('mpoly'))``.
223
224 * The SpatiaLite backend now supports ``Collect`` and ``Extent`` aggregates
225 when the database version is 3.0 or later.
226
227 * The PostGIS 2 ``CREATE EXTENSION postgis`` and the SpatiaLite
228 ``SELECT InitSpatialMetaData`` initialization commands are now automatically
229 run by :djadmin:`migrate`.
230
231 * The GDAL interface now supports retrieving properties of
232 :ref:`raster (image) data file <raster-data-source-objects>`.
233
234 * Compatibility shims for ``SpatialRefSys`` and ``GeometryColumns`` changed in
235 Django 1.2 have been removed.
236
237 * All GDAL-related exceptions are now raised with ``GDALException``. The former
238 ``OGRException`` has been kept for backwards compatibility but should not be
239 used any longer.
240
241 :mod:`django.contrib.sessions`
242 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
243
244 * Session cookie is now deleted after
245 :meth:`~django.contrib.sessions.backends.base.SessionBase.flush()` is called.
246
247 :mod:`django.contrib.sitemaps`
248 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
249
250 * The new :attr:`Sitemap.i18n <django.contrib.sitemaps.Sitemap.i18n>` attribute
251 allows you to generate a sitemap based on the :setting:`LANGUAGES` setting.
252
253 :mod:`django.contrib.sites`
254 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
255
256 * :func:`~django.contrib.sites.shortcuts.get_current_site` will now lookup
257 the current site based on :meth:`request.get_host()
258 <django.http.HttpRequest.get_host>` if the :setting:`SITE_ID` setting is not
259 defined.
260
261 * The default :class:`~django.contrib.sites.models.Site` created when running
262 ``migrate`` now respects the :setting:`SITE_ID` setting (instead of always
263 using ``pk=1``).
264
265 Cache
266 ~~~~~
267
268 * The ``incr()`` method of the
269 ``django.core.cache.backends.locmem.LocMemCache`` backend is now thread-safe.
270
271 Cryptography
272 ~~~~~~~~~~~~
273
274 * The ``max_age`` parameter of the
275 :meth:`django.core.signing.TimestampSigner.unsign` method now also accepts a
276 :py:class:`datetime.timedelta` object.
277
278 Database backends
279 ~~~~~~~~~~~~~~~~~
280
281 * The MySQL backend no longer strips microseconds from ``datetime`` values as
282 MySQL 5.6.4 and up supports fractional seconds depending on the declaration
283 of the datetime field (when ``DATETIME`` includes fractional precision greater
284 than 0). New datetime database columns created with Django 1.8 and MySQL 5.6.4
285 and up will support microseconds. See the :ref:`MySQL database notes
286 <mysql-fractional-seconds>` for more details.
287
288 * The MySQL backend no longer creates explicit indexes for foreign keys when
289 using the InnoDB storage engine, as MySQL already creates them automatically.
290
291 * The Oracle backend no longer defines the ``connection_persists_old_columns``
292 feature as ``True``. Instead, Oracle will now include a cache busting clause
293 when getting the description of a table.
294
295 Email
296 ~~~~~
297
298 * :ref:`Email backends <topic-email-backends>` now support the context manager
299 protocol for opening and closing connections.
300
301 * The SMTP email backend now supports ``keyfile`` and ``certfile``
302 authentication with the :setting:`EMAIL_SSL_CERTFILE` and
303 :setting:`EMAIL_SSL_KEYFILE` settings.
304
305 * The SMTP :class:`~django.core.mail.backends.smtp.EmailBackend` now supports
306 setting the ``timeout`` parameter with the :setting:`EMAIL_TIMEOUT` setting.
307
308 * :class:`~django.core.mail.EmailMessage` and ``EmailMultiAlternatives`` now
309 support the ``reply_to`` parameter.
310
311 File Storage
312 ~~~~~~~~~~~~
313
314 * :meth:`Storage.get_available_name()
315 <django.core.files.storage.Storage.get_available_name>` and
316 :meth:`Storage.save() <django.core.files.storage.Storage.save>`
317 now take a ``max_length`` argument to implement storage-level maximum
318 filename length constraints. Filenames exceeding this argument will get
319 truncated. This prevents a database error when appending a unique suffix to a
320 long filename that already exists on the storage. See the :ref:`deprecation
321 note <storage-max-length-update>` about adding this argument to your custom
322 storage classes.
323
324 Forms
325 ~~~~~
326
327 * Form widgets now render attributes with a value of ``True`` or ``False``
328 as HTML5 boolean attributes.
329
330 * The new :meth:`~django.forms.Form.has_error()` method allows checking
331 if a specific error has happened.
332
333 * If :attr:`~django.forms.Form.required_css_class` is defined on a form, then
334 the ``<label>`` tags for required fields will have this class present in its
335 attributes.
336
337 * The rendering of non-field errors in unordered lists (``<ul>``) now includes
338 ``nonfield`` in its list of classes to distinguish them from field-specific
339 errors.
340
341 * :class:`~django.forms.Field` now accepts a
342 :attr:`~django.forms.Field.label_suffix` argument, which will override the
343 form's :attr:`~django.forms.Form.label_suffix`. This enables customizing the
344 suffix on a per-field basis — previously it wasn't possible to override
345 a form's :attr:`~django.forms.Form.label_suffix` while using shortcuts such
346 as ``{{ form.as_p }}`` in templates.
347
348 * :class:`~django.forms.SelectDateWidget` now accepts an
349 :attr:`~django.forms.SelectDateWidget.empty_label` argument, which will
350 override the top list choice label when :class:`~django.forms.DateField`
351 is not required.
352
353 * After an :class:`~django.forms.ImageField` has been cleaned and validated, the
354 ``UploadedFile`` object will have an additional ``image`` attribute containing
355 the Pillow ``Image`` instance used to check if the file was a valid image. It
356 will also update ``UploadedFile.content_type`` with the image's content type
357 as determined by Pillow.
358
359 * You can now pass a callable that returns an iterable of choices when
360 instantiating a :class:`~django.forms.ChoiceField`.
361
362 Generic Views
363 ~~~~~~~~~~~~~
364
365 * Generic views that use :class:`~django.views.generic.list.MultipleObjectMixin`
366 may now specify the ordering applied to the
367 :attr:`~django.views.generic.list.MultipleObjectMixin.queryset` by setting
368 :attr:`~django.views.generic.list.MultipleObjectMixin.ordering` or overriding
369 :meth:`~django.views.generic.list.MultipleObjectMixin.get_ordering()`.
370
371 * The new :attr:`SingleObjectMixin.query_pk_and_slug
372 <django.views.generic.detail.SingleObjectMixin.query_pk_and_slug>`
373 attribute allows changing the behavior of
374 :meth:`~django.views.generic.detail.SingleObjectMixin.get_object()`
375 so that it'll perform its lookup using both the primary key and the slug.
376
377 * The :meth:`~django.views.generic.edit.FormMixin.get_form()` method doesn't
378 require a ``form_class`` to be provided anymore. If not provided ``form_class``
379 defaults to :meth:`~django.views.generic.edit.FormMixin.get_form_class()`.
380
381 * Placeholders in :attr:`ModelFormMixin.success_url
382 <django.views.generic.edit.ModelFormMixin.success_url>` now support the Python
383 :py:meth:`str.format()` syntax. The legacy ``%(<foo>)s`` syntax is still
384 supported but will be removed in Django 1.10.
385
386 Internationalization
387 ~~~~~~~~~~~~~~~~~~~~
388
389 * :setting:`FORMAT_MODULE_PATH` can now be a list of strings representing
390 module paths. This allows importing several format modules from different
391 reusable apps. It also allows overriding those custom formats in your main
392 Django project.
393
394 Logging
395 ~~~~~~~
396
397 * The :class:`django.utils.log.AdminEmailHandler` class now has a
398 :meth:`~django.utils.log.AdminEmailHandler.send_mail` method to make it more
399 subclass friendly.
400
401 Management Commands
402 ~~~~~~~~~~~~~~~~~~~
403
404 * Database connections are now always closed after a management command called
405 from the command line has finished doing its job.
406
407 * Commands from alternate package formats like eggs are now also discovered.
408
409 * The new :option:`dumpdata --output` option allows specifying a file to which
410 the serialized data is written.
411
412 * The new :option:`makemessages --exclude` and :option:`compilemessages
413 --exclude` options allow excluding specific locales from processing.
414
415 * :djadmin:`compilemessages` now has a ``--use-fuzzy`` or ``-f`` option which
416 includes fuzzy translations into compiled files.
417
418 * The :option:`loaddata --ignorenonexistent` option now ignores data for models
419 that no longer exist.
420
421 * :djadmin:`runserver` now uses daemon threads for faster reloading.
422
423 * :djadmin:`inspectdb` now outputs ``Meta.unique_together``. It is also able to
424 introspect :class:`~django.db.models.AutoField` for MySQL and PostgreSQL
425 databases.
426
427 * When calling management commands with options using
428 :func:`~django.core.management.call_command`, the option name can match the
429 command line option name (without the initial dashes) or the final option
430 destination variable name, but in either case, the resulting option received
431 by the command is now always the ``dest`` name specified in the command
432 option definition (as long as the command uses the :mod:`argparse` module).
433
434 * The :djadmin:`dbshell` command now supports MySQL's optional SSL certificate
435 authority setting (``--ssl-ca``).
436
437 * The new :option:`makemigrations --name` allows giving the migration(s) a
438 custom name instead of a generated one.
439
440 * The :djadmin:`loaddata` command now prevents repeated fixture loading. If
441 :setting:`FIXTURE_DIRS` contains duplicates or a default fixture directory
442 path (``app_name/fixtures``), an exception is raised.
443
444 * The new ``makemigrations --exit`` option allows exiting with an error
445 code if no migrations are created.
446
447 * The new :djadmin:`showmigrations` command allows listing all migrations and
448 their dependencies in a project.
449
450 Middleware
451 ~~~~~~~~~~
452
453 * The :attr:`CommonMiddleware.response_redirect_class
454 <django.middleware.common.CommonMiddleware.response_redirect_class>`
455 attribute allows you to customize the redirects issued by the middleware.
456
457 * A debug message will be logged to the ``django.request`` logger when a
458 middleware raises a :exc:`~django.core.exceptions.MiddlewareNotUsed` exception
459 in :setting:`DEBUG` mode.
460
461 Migrations
462 ~~~~~~~~~~
463
464 * The :class:`~django.db.migrations.operations.RunSQL` operation can now handle
465 parameters passed to the SQL statements.
466
467 * It is now possible to have migrations (most probably :ref:`data migrations
468 <data-migrations>`) for applications without models.
469
470 * Migrations can now :ref:`serialize model managers
471 <using-managers-in-migrations>` as part of the model state.
472
473 * A :ref:`generic mechanism to handle the deprecation of model fields
474 <migrations-removing-model-fields>` was added.
475
476 * The :meth:`RunPython.noop() <django.db.migrations.operations.RunPython.noop>`
477 and :attr:`RunSQL.noop <django.db.migrations.operations.RunSQL.noop>` class
478 method/attribute were added to ease in making ``RunPython`` and ``RunSQL``
479 operations reversible.
480
481 * The migration operations :class:`~django.db.migrations.operations.RunPython`
482 and :class:`~django.db.migrations.operations.RunSQL` now call the
483 :meth:`allow_migrate` method of database routers. The router can use the
484 newly introduced ``app_label`` and ``hints`` arguments to make a routing
485 decision. To take advantage of this feature you need to update the router to
486 the new ``allow_migrate`` signature, see the :ref:`deprecation section
487 <deprecated-signature-of-allow-migrate>` for more details.
488
489 Models
490 ~~~~~~
491
492 * Django now logs at most 9000 queries in ``connections.queries``, in order
493 to prevent excessive memory usage in long-running processes in debug mode.
494
495 * There is now a model ``Meta`` option to define a
496 :attr:`default related name <django.db.models.Options.default_related_name>`
497 for all relational fields of a model.
498
499 * Pickling models and querysets across different versions of Django isn't
500 officially supported (it may work, but there's no guarantee). An extra
501 variable that specifies the current Django version is now added to the
502 pickled state of models and querysets, and Django raises a ``RuntimeWarning``
503 when these objects are unpickled in a different version than the one in
504 which they were pickled.
505
506 * Added :meth:`Model.from_db() <django.db.models.Model.from_db()>` which
507 Django uses whenever objects are loaded using the ORM. The method allows
508 customizing model loading behavior.
509
510 * ``extra(select={...})`` now allows you to escape a literal ``%s`` sequence
511 using ``%%s``.
512
513 * :doc:`Custom Lookups</howto/custom-lookups>` can now be registered using
514 a decorator pattern.
515
516 * The new :attr:`Transform.bilateral <django.db.models.Transform.bilateral>`
517 attribute allows creating bilateral transformations. These transformations
518 are applied to both ``lhs`` and ``rhs`` when used in a lookup expression,
519 providing opportunities for more sophisticated lookups.
520
521 * SQL special characters (\, %, _) are now escaped properly when a pattern
522 lookup (e.g. ``contains``, ``startswith``, etc.) is used with an ``F()``
523 expression as the right-hand side. In those cases, the escaping is performed
524 by the database, which can lead to somewhat complex queries involving nested
525 ``REPLACE`` function calls.
526
527 * You can now refresh model instances by using :meth:`Model.refresh_from_db()
528 <django.db.models.Model.refresh_from_db>`.
529
530 * You can now get the set of deferred fields for a model using
531 :meth:`Model.get_deferred_fields() <django.db.models.Model.get_deferred_fields>`.
532
533 * Model field ``default``’s are now used when primary key field's are set to
534 ``None``.
535
536 Signals
537 ~~~~~~~
538
539 * Exceptions from the ``(receiver, exception)`` tuples returned by
540 :meth:`Signal.send_robust() <django.dispatch.Signal.send_robust>` now have
541 their traceback attached as a ``__traceback__`` attribute.
542
543 * The ``environ`` argument, which contains the WSGI environment structure from
544 the request, was added to the :data:`~django.core.signals.request_started`
545 signal.
546
547 * You can now import the :func:`~django.test.signals.setting_changed` signal
548 from ``django.core.signals`` to avoid loading ``django.test`` in non-test
549 situations. Django no longer does so itself.
550
551 System Check Framework
552 ~~~~~~~~~~~~~~~~~~~~~~
553
554 * :attr:`~django.core.checks.register` can now be used as a function.
555
556 Templates
557 ~~~~~~~~~
558
559 * :tfilter:`urlize` now supports domain-only links that include characters after
560 the top-level domain (e.g. ``djangoproject.com/`` and
561 ``djangoproject.com/download/``).
562
563 * :tfilter:`urlize` doesn't treat exclamation marks at the end of a domain or
564 its query string as part of the URL (the URL in e.g. ``'djangoproject.com!``
565 is ``djangoproject.com``)
566
567 * Added a :class:`locmem.Loader <django.template.loaders.locmem.Loader>`
568 class that loads Django templates from a Python dictionary.
569
570 * The :ttag:`now` tag can now store its output in a context variable with the
571 usual syntax: ``{% now 'j n Y' as varname %}``.
572
573 Requests and Responses
574 ~~~~~~~~~~~~~~~~~~~~~~
575
576 * ``WSGIRequest`` now respects paths starting with ``//``.
577
578 * The :meth:`HttpRequest.build_absolute_uri()
579 <django.http.HttpRequest.build_absolute_uri>` method now handles paths
580 starting with ``//`` correctly.
581
582 * If :setting:`DEBUG` is ``True`` and a request raises a
583 :exc:`~django.core.exceptions.SuspiciousOperation`, the response will be
584 rendered with a detailed error page.
585
586 * The ``query_string`` argument of :class:`~django.http.QueryDict` is now
587 optional, defaulting to ``None``, so a blank ``QueryDict`` can now be
588 instantiated with ``QueryDict()`` instead of ``QueryDict(None)`` or
589 ``QueryDict('')``.
590
591 * The ``GET`` and ``POST`` attributes of an :class:`~django.http.HttpRequest`
592 object are now :class:`~django.http.QueryDict`\s rather than dictionaries,
593 and the ``FILES`` attribute is now a ``MultiValueDict``.
594 This brings this class into line with the documentation and with
595 ``WSGIRequest``.
596
597 * The :attr:`HttpResponse.charset <django.http.HttpResponse.charset>` attribute
598 was added.
599
600 * ``WSGIRequestHandler`` now follows RFC in converting URI to IRI, using
601 ``uri_to_iri()``.
602
603 * The :meth:`HttpRequest.get_full_path()
604 <django.http.HttpRequest.get_full_path>` method now escapes unsafe characters
605 from the path portion of a Uniform Resource Identifier (URI) properly.
606
607 * :class:`~django.http.HttpResponse` now implements a few additional methods
608 like :meth:`~django.http.HttpResponse.getvalue` so that instances can be used
609 as stream objects.
610
611 * The new :meth:`HttpResponse.setdefault()
612 <django.http.HttpResponse.setdefault>` method allows setting a header unless
613 it has already been set.
614
615 * You can use the new :class:`~django.http.FileResponse` to stream files.
616
617 * The :func:`~django.views.decorators.http.condition` decorator for
618 conditional view processing now supports the ``If-unmodified-since`` header.
619
620 Tests
621 ~~~~~
622
623 * The :class:`RequestFactory.trace() <django.test.RequestFactory>`
624 and :class:`Client.trace() <django.test.Client.trace>` methods were
625 implemented, allowing you to create ``TRACE`` requests in your tests.
626
627 * The ``count`` argument was added to
628 :meth:`~django.test.SimpleTestCase.assertTemplateUsed`. This allows you to
629 assert that a template was rendered a specific number of times.
630
631 * The new :meth:`~django.test.SimpleTestCase.assertJSONNotEqual` assertion
632 allows you to test that two JSON fragments are not equal.
633
634 * Added options to the :djadmin:`test` command to preserve the test database
635 (:option:`--keepdb <test --keepdb>`), to run the test cases in reverse order
636 (:option:`--reverse <test --reverse>`), and to enable SQL logging for failing
637 tests (:option:`--debug-sql <test --debug-sql>`).
638
639 * Added the :attr:`~django.test.Response.resolver_match` attribute to test
640 client responses.
641
642 * Added several settings that allow customization of test tablespace parameters
643 for Oracle: :setting:`DATAFILE`, :setting:`DATAFILE_TMP`,
644 :setting:`DATAFILE_MAXSIZE` and :setting:`DATAFILE_TMP_MAXSIZE`.
645
646 * The :func:`~django.test.override_settings` decorator can now affect the
647 master router in :setting:`DATABASE_ROUTERS`.
648
649 * Added test client support for file uploads with file-like objects.
650
651 * A shared cache is now used when testing with an SQLite in-memory database when
652 using Python 3.4+ and SQLite 3.7.13+. This allows sharing the database
653 between threads.
654
655 Validators
656 ~~~~~~~~~~
657
658 * :class:`~django.core.validators.URLValidator` now supports IPv6 addresses,
659 Unicode domains, and URLs containing authentication data.
660
661 .. _backwards-incompatible-1.8:
662
663 Backwards incompatible changes in 1.8
664 =====================================
665
666 .. warning::
667
668 In addition to the changes outlined in this section, be sure to review the
669 :ref:`deprecation plan <deprecation-removed-in-1.8>` for any features that
670 have been removed. If you haven't updated your code within the
671 deprecation timeline for a given feature, its removal may appear as a
672 backwards incompatible change.
673
674 Related object operations are run in a transaction
675 --------------------------------------------------
676
677 Some operations on related objects such as
678 :meth:`~django.db.models.fields.related.RelatedManager.add()` or direct
679 assignment ran multiple data modifying queries without wrapping them in
680 transactions. To reduce the risk of data corruption, all data modifying methods
681 that affect multiple related objects (i.e. ``add()``, ``remove()``,
682 ``clear()``, and direct assignment) now perform their data modifying queries
683 from within a transaction, provided your database supports transactions.
684
685 This has one backwards incompatible side effect, signal handlers triggered from
686 these methods are now executed within the method's transaction and any
687 exception in a signal handler will prevent the whole operation.
688
689 .. _unsaved-model-instance-check-18:
690
691 Assigning unsaved objects to relations raises an error
692 ------------------------------------------------------
693
694 .. note::
695
696 To more easily allow in-memory usage of models, this change was reverted in
697 Django 1.8.4 and replaced with a check during ``model.save()``. For example:
698
699 .. code-block:: pycon
700
701 >>> book = Book.objects.create(name="Django")
702 >>> book.author = Author(name="John")
703 >>> book.save()
704 Traceback (most recent call last):
705 ...
706 ValueError: save() prohibited to prevent data loss due to unsaved related object 'author'.
707
708 A similar check on assignment to reverse one-to-one relations was removed
709 in Django 1.8.5.
710
711 Assigning unsaved objects to a :class:`~django.db.models.ForeignKey`,
712 :class:`~django.contrib.contenttypes.fields.GenericForeignKey`, and
713 :class:`~django.db.models.OneToOneField` now raises a :exc:`ValueError`.
714
715 Previously, the assignment of an unsaved object would be silently ignored.
716 For example:
717
718 .. code-block:: pycon
719
720 >>> book = Book.objects.create(name="Django")
721 >>> book.author = Author(name="John")
722 >>> book.author.save()
723 >>> book.save()
724
725 >>> Book.objects.get(name="Django")
726 >>> book.author
727 >>>
728
729 Now, an error will be raised to prevent data loss:
730
731 .. code-block:: pycon
732
733 >>> book.author = Author(name="john")
734 Traceback (most recent call last):
735 ...
736 ValueError: Cannot assign "<Author: John>": "Author" instance isn't saved in the database.
737
738 If you require allowing the assignment of unsaved instances (the old behavior)
739 and aren't concerned about the data loss possibility (e.g. you never save the
740 objects to the database), you can disable this check by using the
741 ``ForeignKey.allow_unsaved_instance_assignment`` attribute. (This attribute was
742 removed in 1.8.4 as it's no longer relevant.)
743
744 Management commands that only accept positional arguments
745 ---------------------------------------------------------
746
747 If you have written a custom management command that only accepts positional
748 arguments and you didn't specify the ``args`` command variable, you might get
749 an error like ``Error: unrecognized arguments: ...``, as variable parsing is
750 now based on :py:mod:`argparse` which doesn't implicitly accept positional
751 arguments. You can make your command backwards compatible by simply setting the
752 ``args`` class variable. However, if you don't have to keep compatibility with
753 older Django versions, it's better to implement the new
754 :meth:`~django.core.management.BaseCommand.add_arguments` method as described
755 in :doc:`/howto/custom-management-commands`.
756
757 Custom test management command arguments through test runner
758 ------------------------------------------------------------
759
760 The method to add custom arguments to the ``test`` management command through
761 the test runner has changed. Previously, you could provide an ``option_list``
762 class variable on the test runner to add more arguments (à la
763 :py:mod:`optparse`). Now to implement the same behavior, you have to create an
764 ``add_arguments(cls, parser)`` class method on the test runner and call
765 ``parser.add_argument`` to add any custom arguments, as parser is now an
766 :py:class:`argparse.ArgumentParser` instance.
767
768 Model check ensures auto-generated column names are within limits specified by database
769 ---------------------------------------------------------------------------------------
770
771 A field name that's longer than the column name length supported by a database
772 can create problems. For example, with MySQL you'll get an exception trying to
773 create the column, and with PostgreSQL the column name is truncated by the
774 database (you may see a warning in the PostgreSQL logs).
775
776 A model check has been introduced to better alert users to this scenario before
777 the actual creation of database tables.
778
779 If you have an existing model where this check seems to be a false positive,
780 for example on PostgreSQL where the name was already being truncated, simply
781 use :attr:`~django.db.models.Field.db_column` to specify the name that's being
782 used.
783
784 The check also applies to the columns generated in an implicit
785 ``ManyToManyField.through`` model. If you run into an issue there, use
786 :attr:`~django.db.models.ManyToManyField.through` to create an explicit model
787 and then specify :attr:`~django.db.models.Field.db_column` on its column(s)
788 as needed.
789
790 Query relation lookups now check object types
791 ---------------------------------------------
792
793 Querying for model lookups now checks if the object passed is of correct type
794 and raises a :exc:`ValueError` if not. Previously, Django didn't care if the
795 object was of correct type; it just used the object's related field attribute
796 (e.g. ``id``) for the lookup. Now, an error is raised to prevent incorrect
797 lookups:
798
799 .. code-block:: pycon
800
801 >>> book = Book.objects.create(name="Django")
802 >>> book = Book.objects.filter(author=book)
803 Traceback (most recent call last):
804 ...
805 ValueError: Cannot query "<Book: Django>": Must be "Author" instance.
806
807 ``select_related()`` now checks given fields
808 --------------------------------------------
809
810 ``select_related()`` now validates that the given fields actually exist.
811 Previously, nonexistent fields were silently ignored. Now, an error is raised:
812
813 .. code-block:: pycon
814
815 >>> book = Book.objects.select_related("nonexistent_field")
816 Traceback (most recent call last):
817 ...
818 FieldError: Invalid field name(s) given in select_related: 'nonexistent_field'
819
820 The validation also makes sure that the given field is relational:
821
822 .. code-block:: pycon
823
824 >>> book = Book.objects.select_related("name")
825 Traceback (most recent call last):
826 ...
827 FieldError: Non-relational field given in select_related: 'name'
828
829 Default ``EmailField.max_length`` increased to 254
830 --------------------------------------------------
831
832 The old default 75 character ``max_length`` was not capable of storing all
833 possible RFC3696/5321-compliant email addresses. In order to store all
834 possible valid email addresses, the ``max_length`` has been increased to 254
835 characters. You will need to generate and apply database migrations for your
836 affected models (or add ``max_length=75`` if you wish to keep the length on
837 your current fields). A migration for
838 :attr:`django.contrib.auth.models.User.email` is included.
839
840 Support for PostgreSQL versions older than 9.0
841 ----------------------------------------------
842
843 The end of upstream support periods was reached in July 2014 for PostgreSQL 8.4.
844 As a consequence, Django 1.8 sets 9.0 as the minimum PostgreSQL version it
845 officially supports.
846
847 This also includes dropping support for PostGIS 1.3 and 1.4 as these versions
848 are not supported on versions of PostgreSQL later than 8.4.
849
850 Django also now requires the use of Psycopg2 version 2.4.5 or higher (or 2.5+
851 if you want to use :mod:`django.contrib.postgres`).
852
853 Support for MySQL versions older than 5.5
854 -----------------------------------------
855
856 The end of upstream support periods was reached in January 2012 for MySQL 5.0
857 and December 2013 for MySQL 5.1. As a consequence, Django 1.8 sets 5.5 as the
858 minimum MySQL version it officially supports.
859
860 Support for Oracle versions older than 11.1
861 -------------------------------------------
862
863 The end of upstream support periods was reached in July 2010 for Oracle 9.2,
864 January 2012 for Oracle 10.1, and July 2013 for Oracle 10.2. As a consequence,
865 Django 1.8 sets 11.1 as the minimum Oracle version it officially supports.
866
867 Specific privileges used instead of roles for tests on Oracle
868 -------------------------------------------------------------
869
870 Earlier versions of Django granted the CONNECT and RESOURCE roles to the test
871 user on Oracle. These roles have been deprecated, so Django 1.8 uses the
872 specific underlying privileges instead. This changes the privileges required
873 of the main user for running tests (unless the project is configured to avoid
874 creating a test user). The exact privileges required now are detailed in
875 :ref:`Oracle notes <oracle-notes>`.
876
877 ``AbstractUser.last_login`` allows null values
878 ----------------------------------------------
879
880 The :attr:`AbstractUser.last_login <django.contrib.auth.models.User.last_login>`
881 field now allows null values. Previously, it defaulted to the time when the user
882 was created which was misleading if the user never logged in. If you are using
883 the default user (:class:`django.contrib.auth.models.User`), run the database
884 migration included in ``contrib.auth``.
885
886 If you are using a custom user model that inherits from ``AbstractUser``,
887 you'll need to run :djadmin:`makemigrations` and generate a migration for your
888 app that contains that model. Also, if wish to set ``last_login`` to ``NULL``
889 for users who haven't logged in, you can run this query::
890
891 from django.db import models
892 from django.contrib.auth import get_user_model
893 from django.contrib.auth.models import AbstractBaseUser
894
895 UserModel = get_user_model()
896 if issubclass(UserModel, AbstractBaseUser):
897 UserModel._default_manager.filter(last_login=models.F("date_joined")).update(
898 last_login=None
899 )
900
901 :mod:`django.contrib.gis`
902 -------------------------
903
904 * Support for GEOS 3.1 and GDAL 1.6 has been dropped.
905
906 * Support for SpatiaLite < 2.4 has been dropped.
907
908 * GIS-specific lookups have been refactored to use the
909 :class:`django.db.models.Lookup` API.
910
911 * The default ``str`` representation of
912 :class:`~django.contrib.gis.geos.GEOSGeometry` objects has been changed from
913 WKT to EWKT format (including the SRID). As this representation is used in
914 the serialization framework, that means that ``dumpdata`` output will now
915 contain the SRID value of geometry objects.
916
917 Priority of context processors for ``TemplateResponse`` brought in line with ``render``
918 ---------------------------------------------------------------------------------------
919
920 The :class:`~django.template.response.TemplateResponse` constructor is designed to be a
921 drop-in replacement for the :func:`~django.shortcuts.render` function. However,
922 it had a slight incompatibility, in that for ``TemplateResponse``, context data
923 from the passed in context dictionary could be shadowed by context data returned
924 from context processors, whereas for ``render`` it was the other way
925 around. This was a bug, and the behavior of ``render`` is more appropriate,
926 since it allows the globally defined context processors to be overridden locally
927 in the view. If you were relying on the fact context data in a
928 ``TemplateResponse`` could be overridden using a context processor, you will
929 need to change your code.
930
931 Overriding ``setUpClass`` / ``tearDownClass`` in test cases
932 -----------------------------------------------------------
933
934 The decorators :func:`~django.test.override_settings` and
935 :func:`~django.test.modify_settings` now act at the class level when used as
936 class decorators. As a consequence, when overriding ``setUpClass()`` or
937 ``tearDownClass()``, the ``super`` implementation should always be called.
938
939 Removal of ``django.contrib.formtools``
940 ---------------------------------------
941
942 The formtools contrib app has been moved to a separate package and the
943 relevant documentation pages have been updated or removed.
944
945 The new package is available `on GitHub`_ and on PyPI.
946
947 .. _on GitHub: https://github.com/jazzband/django-formtools/
948
949 Database connection reloading between tests
950 -------------------------------------------
951
952 Django previously closed database connections between each test within a
953 ``TestCase``. This is no longer the case as Django now wraps the whole
954 ``TestCase`` within a transaction. If some of your tests relied on the old
955 behavior, you should have them inherit from ``TransactionTestCase`` instead.
956
957 Cleanup of the ``django.template`` namespace
958 --------------------------------------------
959
960 If you've been relying on private APIs exposed in the ``django.template``
961 module, you may have to import them from ``django.template.base`` instead.
962
963 Also private APIs ``django.template.base.compile_string()``,
964 ``django.template.loader.find_template()``, and
965 ``django.template.loader.get_template_from_string()`` were removed.
966
967 ``model`` attribute on private model relations
968 ----------------------------------------------
969
970 In earlier versions of Django, on a model with a reverse foreign key
971 relationship (for example), ``model._meta.get_all_related_objects()`` returned
972 the relationship as a ``django.db.models.related.RelatedObject`` with the
973 ``model`` attribute set to the source of the relationship. Now, this method
974 returns the relationship as ``django.db.models.fields.related.ManyToOneRel``
975 (private API ``RelatedObject`` has been removed), and the ``model`` attribute
976 is set to the target of the relationship instead of the source. The source
977 model is accessible on the ``related_model`` attribute instead.
978
979 Consider this example from the tutorial in Django 1.8:
980
981 .. code-block:: pycon
982
983 >>> p = Poll.objects.get(pk=1)
984 >>> p._meta.get_all_related_objects()
985 [<ManyToOneRel: polls.choice>]
986 >>> p._meta.get_all_related_objects()[0].model
987 <class 'polls.models.Poll'>
988 >>> p._meta.get_all_related_objects()[0].related_model
989 <class 'polls.models.Choice'>
990
991 and compare it to the behavior on older versions:
992
993 .. code-block:: pycon
994
995 >>> p._meta.get_all_related_objects()
996 [<RelatedObject: polls:choice related to poll>]
997 >>> p._meta.get_all_related_objects()[0].model
998 <class 'polls.models.Choice'>
999
1000 To access the source model, you can use a pattern like this to write code that
1001 will work with both Django 1.8 and older versions::
1002
1003 for relation in opts.get_all_related_objects():
1004 to_model = getattr(relation, "related_model", relation.model)
1005
1006 Also note that ``get_all_related_objects()`` is deprecated in 1.8.
1007
1008 Database backend API
1009 --------------------
1010
1011 The following changes to the database backend API are documented to assist
1012 those writing third-party backends in updating their code:
1013
1014 * ``BaseDatabaseXXX`` classes have been moved to ``django.db.backends.base``.
1015 Please import them from the new locations::
1016
1017 from django.db.backends.base.base import BaseDatabaseWrapper
1018 from django.db.backends.base.client import BaseDatabaseClient
1019 from django.db.backends.base.creation import BaseDatabaseCreation
1020 from django.db.backends.base.features import BaseDatabaseFeatures
1021 from django.db.backends.base.introspection import BaseDatabaseIntrospection
1022 from django.db.backends.base.introspection import FieldInfo, TableInfo
1023 from django.db.backends.base.operations import BaseDatabaseOperations
1024 from django.db.backends.base.schema import BaseDatabaseSchemaEditor
1025 from django.db.backends.base.validation import BaseDatabaseValidation
1026
1027 * The ``data_types``, ``data_types_suffix``, and
1028 ``data_type_check_constraints`` attributes have moved from the
1029 ``DatabaseCreation`` class to ``DatabaseWrapper``.
1030
1031 * The ``SQLCompiler.as_sql()`` method now takes a ``subquery`` parameter
1032 (:ticket:`24164`).
1033
1034 * The ``BaseDatabaseOperations.date_interval_sql()`` method now only takes a
1035 ``timedelta`` parameter.
1036
1037 :mod:`django.contrib.admin`
1038 ---------------------------
1039
1040 * ``AdminSite`` no longer takes an ``app_name`` argument and its ``app_name``
1041 attribute has been removed. The application name is always ``admin`` (as
1042 opposed to the instance name which you can still customize using
1043 ``AdminSite(name="...")``.
1044
1045 * The ``ModelAdmin.get_object()`` method (private API) now takes a third
1046 argument named ``from_field`` in order to specify which field should match
1047 the provided ``object_id``.
1048
1049 * The :meth:`ModelAdmin.response_delete()
1050 <django.contrib.admin.ModelAdmin.response_delete>` method
1051 now takes a second argument named ``obj_id`` which is the serialized
1052 identifier used to retrieve the object before deletion.
1053
1054 Default autoescaping of functions in ``django.template.defaultfilters``
1055 -----------------------------------------------------------------------
1056
1057 In order to make built-in template filters that output HTML "safe by default"
1058 when calling them in Python code, the following functions in
1059 ``django.template.defaultfilters`` have been changed to automatically escape
1060 their input value:
1061
1062 * ``join``
1063 * ``linebreaksbr``
1064 * ``linebreaks_filter``
1065 * ``linenumbers``
1066 * ``unordered_list``
1067 * ``urlize``
1068 * ``urlizetrunc``
1069
1070 You can revert to the old behavior by specifying ``autoescape=False`` if you
1071 are passing trusted content. This change doesn't have any effect when using
1072 the corresponding filters in templates.
1073
1074 Miscellaneous
1075 -------------
1076
1077 * ``connections.queries`` is now a read-only attribute.
1078
1079 * Database connections are considered equal only if they're the same object.
1080 They aren't hashable any more.
1081
1082 * :class:`~django.middleware.gzip.GZipMiddleware` used to disable compression
1083 for some content types when the request is from Internet Explorer, in order
1084 to work around a bug in IE6 and earlier. This behavior could affect
1085 performance on IE7 and later. It was removed.
1086
1087 * ``URLField.to_python`` no longer adds a trailing slash to pathless URLs.
1088
1089 * The :tfilter:`length` template filter now returns ``0`` for an undefined
1090 variable, rather than an empty string.
1091
1092 * ``ForeignKey.default_error_message['invalid']`` has been changed from
1093 ``'%(model)s instance with pk %(pk)r does not exist.'`` to
1094 ``'%(model)s instance with %(field)s %(value)r does not exist.'`` If you are
1095 using this message in your own code, please update the list of interpolated
1096 parameters. Internally, Django will continue to provide the
1097 ``pk`` parameter in ``params`` for backwards compatibility.
1098
1099 * ``UserCreationForm.error_messages['duplicate_username']`` is no longer used.
1100 If you wish to customize that error message, :ref:`override it on the form
1101 <modelforms-overriding-default-fields>` using the ``'unique'`` key in
1102 ``Meta.error_messages['username']`` or, if you have a custom form field for
1103 ``'username'``, using the ``'unique'`` key in its
1104 :attr:`~django.forms.Field.error_messages` argument.
1105
1106 * The block ``usertools`` in the ``base.html`` template of
1107 :mod:`django.contrib.admin` now requires the ``has_permission`` context
1108 variable to be set. If you have any custom admin views that use this
1109 template, update them to pass :meth:`AdminSite.has_permission()
1110 <django.contrib.admin.AdminSite.has_permission>` as this new variable's
1111 value or simply include :meth:`AdminSite.each_context(request)
1112 <django.contrib.admin.AdminSite.each_context>` in the context.
1113
1114 * Internal changes were made to the :class:`~django.forms.ClearableFileInput`
1115 widget to allow more customization. The undocumented ``url_markup_template``
1116 attribute was removed in favor of ``template_with_initial``.
1117
1118 * For consistency with other major vendors, the ``en_GB`` locale now has Monday
1119 as the first day of the week.
1120
1121 * Seconds have been removed from any locales that had them in ``TIME_FORMAT``,
1122 ``DATETIME_FORMAT``, or ``SHORT_DATETIME_FORMAT``.
1123
1124 * The default max size of the Oracle test tablespace has increased from 300M
1125 (or 200M, before 1.7.2) to 500M.
1126
1127 * ``reverse()`` and ``reverse_lazy()`` now return Unicode strings instead of
1128 bytestrings.
1129
1130 * The ``CacheClass`` shim has been removed from all cache backends.
1131 These aliases were provided for backwards compatibility with Django 1.3.
1132 If you are still using them, please update your project to use the real
1133 class name found in the :setting:`BACKEND <CACHES-BACKEND>` key of the
1134 :setting:`CACHES` setting.
1135
1136 * By default, :func:`~django.core.management.call_command` now always skips the
1137 check framework (unless you pass it ``skip_checks=False``).
1138
1139 * When iterating over lines, :class:`~django.core.files.File` now uses
1140 :pep:`universal newlines <278>`. The following are recognized as ending a
1141 line: the Unix end-of-line convention ``'\n'``, the Windows convention
1142 ``'\r\n'``, and the old Macintosh convention ``'\r'``.
1143
1144 * The Memcached cache backends ``MemcachedCache`` and ``PyLibMCCache`` will
1145 delete a key if ``set()`` fails. This is necessary to ensure the ``cache_db``
1146 session store always fetches the most current session data.
1147
1148 * Private APIs ``override_template_loaders`` and ``override_with_test_loader``
1149 in ``django.test.utils`` were removed. Override ``TEMPLATES`` with
1150 ``override_settings`` instead.
1151
1152 * Warnings from the MySQL database backend are no longer converted to
1153 exceptions when :setting:`DEBUG` is ``True``.
1154
1155 * :class:`~django.http.HttpRequest` now has a simplified ``repr`` (e.g.
1156 ``<WSGIRequest: GET '/somepath/'>``). This won't change the behavior of
1157 the :class:`~django.views.debug.SafeExceptionReporterFilter` class.
1158
1159 * Class-based views that use :class:`~django.views.generic.edit.ModelFormMixin`
1160 will raise an :exc:`~django.core.exceptions.ImproperlyConfigured` exception
1161 when both the ``fields`` and ``form_class`` attributes are specified.
1162 Previously, ``fields`` was silently ignored.
1163
1164 * When following redirects, the test client now raises
1165 :exc:`~django.test.client.RedirectCycleError` if it detects a loop or hits a
1166 maximum redirect limit (rather than passing silently).
1167
1168 * Translatable strings set as the ``default`` parameter of the field are cast
1169 to concrete strings later, so the return type of ``Field.get_default()`` is
1170 different in some cases. There is no change to default values which are the
1171 result of a callable.
1172
1173 * ``GenericIPAddressField.empty_strings_allowed`` is now ``False``. Database
1174 backends that interpret empty strings as null (only Oracle among the backends
1175 that Django includes) will no longer convert null values back to an empty
1176 string. This is consistent with other backends.
1177
1178 * When the ``BaseCommand.leave_locale_alone``
1179 attribute is ``False``, translations are now deactivated instead of forcing
1180 the "en-us" locale. In the case your models contained non-English strings and
1181 you counted on English translations to be activated in management commands,
1182 this will not happen any longer. It might be that new database migrations are
1183 generated (once) after migrating to 1.8.
1184
1185 * :func:`django.utils.translation.get_language()` now returns ``None`` instead
1186 of :setting:`LANGUAGE_CODE` when translations are temporarily deactivated.
1187
1188 * When a translation doesn't exist for a specific literal, the fallback is now
1189 taken from the :setting:`LANGUAGE_CODE` language (instead of from the
1190 untranslated ``msgid`` message).
1191
1192 * The ``name`` field of :class:`django.contrib.contenttypes.models.ContentType`
1193 has been removed by a migration and replaced by a property. That means it's
1194 not possible to query or filter a ``ContentType`` by this field any longer.
1195
1196 Be careful if you upgrade to Django 1.8 and skip Django 1.7. If you run
1197 ``manage.py migrate --fake``, this migration will be skipped and you'll see
1198 a ``RuntimeError: Error creating new content types.`` exception because the
1199 ``name`` column won't be dropped from the database. Use ``manage.py migrate
1200 --fake-initial`` to fake only the initial migration instead.
1201
1202 * The new :option:`migrate --fake-initial` option allows faking initial
1203 migrations. In 1.7, initial migrations were always automatically faked if all
1204 tables created in an initial migration already existed.
1205
1206 * An app *without* migrations with a ``ForeignKey`` to an app *with* migrations
1207 may now result in a foreign key constraint error when migrating the database
1208 or running tests. In Django 1.7, this could fail silently and result in a
1209 missing constraint. To resolve the error, add migrations to the app without
1210 them.
1211
1212 .. _deprecated-features-1.8:
1213
1214 Features deprecated in 1.8
1215 ==========================
1216
1217 Selected methods in ``django.db.models.options.Options``
1218 --------------------------------------------------------
1219
1220 As part of the formalization of the ``Model._meta`` API (from the
1221 :class:`django.db.models.options.Options` class), a number of methods have been
1222 deprecated and will be removed in Django 1.10:
1223
1224 * ``get_all_field_names()``
1225 * ``get_all_related_objects()``
1226 * ``get_all_related_objects_with_model()``
1227 * ``get_all_related_many_to_many_objects()``
1228 * ``get_all_related_m2m_objects_with_model()``
1229 * ``get_concrete_fields_with_model()``
1230 * ``get_field_by_name()``
1231 * ``get_fields_with_model()``
1232 * ``get_m2m_with_model()``
1233
1234 Loading ``cycle`` and ``firstof`` template tags from ``future`` library
1235 -----------------------------------------------------------------------
1236
1237 Django 1.6 introduced ``{% load cycle from future %}`` and
1238 ``{% load firstof from future %}`` syntax for forward compatibility of the
1239 :ttag:`cycle` and :ttag:`firstof` template tags. This syntax is now deprecated
1240 and will be removed in Django 1.10. You can simply remove the
1241 ``{% load ... from future %}`` tags.
1242
1243 ``django.conf.urls.patterns()``
1244 -------------------------------
1245
1246 In the olden days of Django, it was encouraged to reference views as strings
1247 in ``urlpatterns``::
1248
1249 urlpatterns = patterns(
1250 "",
1251 url("^$", "myapp.views.myview"),
1252 )
1253
1254 and Django would magically import ``myapp.views.myview`` internally and turn
1255 the string into a real function reference. In order to reduce repetition when
1256 referencing many views from the same module, the ``patterns()`` function takes
1257 a required initial ``prefix`` argument which is prepended to all
1258 views-as-strings in that set of ``urlpatterns``::
1259
1260 urlpatterns = patterns(
1261 "myapp.views",
1262 url("^$", "myview"),
1263 url("^other/$", "otherview"),
1264 )
1265
1266 In the modern era, we have updated the tutorial to instead recommend importing
1267 your views module and referencing your view functions (or classes) directly.
1268 This has a number of advantages, all deriving from the fact that we are using
1269 normal Python in place of "Django String Magic": the errors when you mistype a
1270 view name are less obscure, IDEs can help with autocompletion of view names,
1271 etc.
1272
1273 So these days, the above use of the ``prefix`` arg is much more likely to be
1274 written (and is better written) as::
1275
1276 from myapp import views
1277
1278 urlpatterns = patterns(
1279 "",
1280 url("^$", views.myview),
1281 url("^other/$", views.otherview),
1282 )
1283
1284 Thus ``patterns()`` serves little purpose and is a burden when teaching new users
1285 (answering the newbie's question "why do I need this empty string as the first
1286 argument to ``patterns()``?"). For these reasons, we are deprecating it.
1287 Updating your code is as simple as ensuring that ``urlpatterns`` is a list of
1288 ``django.conf.urls.url()`` instances. For example::
1289
1290 from django.conf.urls import url
1291 from myapp import views
1292
1293 urlpatterns = [
1294 url("^$", views.myview),
1295 url("^other/$", views.otherview),
1296 ]
1297
1298 Passing a string as ``view`` to ``django.conf.urls.url()``
1299 ----------------------------------------------------------
1300
1301 Related to the previous item, referencing views as strings in the ``url()``
1302 function is deprecated. Pass the callable view as described in the previous
1303 section instead.
1304
1305 Template-related settings
1306 -------------------------
1307
1308 As a consequence of the multiple template engines refactor, several settings
1309 are deprecated in favor of :setting:`TEMPLATES`:
1310
1311 * ``ALLOWED_INCLUDE_ROOTS``
1312 * ``TEMPLATE_CONTEXT_PROCESSORS``
1313 * ``TEMPLATE_DEBUG``
1314 * ``TEMPLATE_DIRS``
1315 * ``TEMPLATE_LOADERS``
1316 * ``TEMPLATE_STRING_IF_INVALID``
1317
1318 ``django.core.context_processors``
1319 ----------------------------------
1320
1321 Built-in template context processors have been moved to
1322 ``django.template.context_processors``.
1323
1324 ``django.test.SimpleTestCase.urls``
1325 -----------------------------------
1326
1327 The attribute ``SimpleTestCase.urls`` for specifying URLconf configuration in
1328 tests has been deprecated and will be removed in Django 1.10. Use
1329 :func:`@override_settings(ROOT_URLCONF=...) <django.test.override_settings>`
1330 instead.
1331
1332 ``prefix`` argument to :func:`~django.conf.urls.i18n.i18n_patterns`
1333 -------------------------------------------------------------------
1334
1335 Related to the previous item, the ``prefix`` argument to
1336 :func:`django.conf.urls.i18n.i18n_patterns` has been deprecated. Simply pass a
1337 list of ``django.conf.urls.url()`` instances instead.
1338
1339 Using an incorrect count of unpacked values in the :ttag:`for` template tag
1340 ---------------------------------------------------------------------------
1341
1342 Using an incorrect count of unpacked values in :ttag:`for` tag will raise an
1343 exception rather than fail silently in Django 1.10.
1344
1345 Passing a dotted path to ``reverse()`` and :ttag:`url`
1346 ------------------------------------------------------
1347
1348 Reversing URLs by Python path is an expensive operation as it causes the
1349 path being reversed to be imported. This behavior has also resulted in a
1350 `security issue`_. Use :ref:`named URL patterns <naming-url-patterns>`
1351 for reversing instead.
1352
1353 If you are using :mod:`django.contrib.sitemaps`, add the ``name`` argument to
1354 the ``url`` that references :func:`django.contrib.sitemaps.views.sitemap`::
1355
1356 from django.contrib.sitemaps.views import sitemap
1357
1358 url(
1359 r"^sitemap\.xml$",
1360 sitemap,
1361 {"sitemaps": sitemaps},
1362 name="django.contrib.sitemaps.views.sitemap",
1363 )
1364
1365 to ensure compatibility when reversing by Python path is removed in Django 1.10.
1366
1367 Similarly for GIS sitemaps, add ``name='django.contrib.gis.sitemaps.views.kml'``
1368 or ``name='django.contrib.gis.sitemaps.views.kmz'``.
1369
1370 If you are using a Python path for the :setting:`LOGIN_URL` or
1371 :setting:`LOGIN_REDIRECT_URL` setting, use the name of the ``url()`` instead.
1372
1373 .. _security issue: https://www.djangoproject.com/weblog/2014/apr/21/security/#s-issue-unexpected-code-execution-using-reverse
1374
1375 Aggregate methods and modules
1376 -----------------------------
1377
1378 The ``django.db.models.sql.aggregates`` and
1379 ``django.contrib.gis.db.models.sql.aggregates`` modules (both private API), have
1380 been deprecated as ``django.db.models.aggregates`` and
1381 ``django.contrib.gis.db.models.aggregates`` are now also responsible
1382 for SQL generation. The old modules will be removed in Django 1.10.
1383
1384 If you were using the old modules, see :doc:`Query Expressions
1385 </ref/models/expressions>` for instructions on rewriting custom aggregates
1386 using the new stable API.
1387
1388 The following methods and properties of ``django.db.models.sql.query.Query``
1389 have also been deprecated and the backwards compatibility shims will be removed
1390 in Django 1.10:
1391
1392 * ``Query.aggregates``, replaced by ``annotations``.
1393 * ``Query.aggregate_select``, replaced by ``annotation_select``.
1394 * ``Query.add_aggregate()``, replaced by ``add_annotation()``.
1395 * ``Query.set_aggregate_mask()``, replaced by ``set_annotation_mask()``.
1396 * ``Query.append_aggregate_mask()``, replaced by ``append_annotation_mask()``.
1397
1398 Extending management command arguments through ``Command.option_list``
1399 ----------------------------------------------------------------------
1400
1401 Management commands now use :py:mod:`argparse` instead of :py:mod:`optparse` to
1402 parse command-line arguments passed to commands. This also means that the way
1403 to add custom arguments to commands has changed: instead of extending the
1404 ``option_list`` class list, you should now override the
1405 :meth:`~django.core.management.BaseCommand.add_arguments` method and add
1406 arguments through ``argparse.add_argument()``. See
1407 :ref:`this example <custom-commands-options>` for more details.
1408
1409 ``django.core.management.NoArgsCommand``
1410 ----------------------------------------
1411
1412 The class ``NoArgsCommand`` is now deprecated and will be removed in Django
1413 1.10. Use :class:`~django.core.management.BaseCommand` instead, which takes no
1414 arguments by default.
1415
1416 Listing all migrations in a project
1417 -----------------------------------
1418
1419 The ``--list`` option of the :djadmin:`migrate` management command is
1420 deprecated and will be removed in Django 1.10. Use :djadmin:`showmigrations`
1421 instead.
1422
1423 ``cache_choices`` option of ``ModelChoiceField`` and ``ModelMultipleChoiceField``
1424 ---------------------------------------------------------------------------------
1425
1426 :class:`~django.forms.ModelChoiceField` and
1427 :class:`~django.forms.ModelMultipleChoiceField` took an undocumented, untested
1428 option ``cache_choices``. This cached querysets between multiple renderings of
1429 the same ``Form`` object. This option is subject to an accelerated deprecation
1430 and will be removed in Django 1.9.
1431
1432 ``django.template.resolve_variable()``
1433 --------------------------------------
1434
1435 The function has been informally marked as "Deprecated" for some time. Replace
1436 ``resolve_variable(path, context)`` with
1437 ``django.template.Variable(path).resolve(context)``.
1438
1439 ``django.contrib.webdesign``
1440 ----------------------------
1441
1442 It provided the :ttag:`lorem` template tag which is now included in the
1443 built-in tags. Simply remove ``'django.contrib.webdesign'`` from
1444 :setting:`INSTALLED_APPS` and ``{% load webdesign %}`` from your templates.
1445
1446 ``error_message`` argument to ``django.forms.RegexField``
1447 ---------------------------------------------------------
1448
1449 It provided backwards compatibility for pre-1.0 code, but its functionality is
1450 redundant. Use ``Field.error_messages['invalid']`` instead.
1451
1452 Old :tfilter:`unordered_list` syntax
1453 ------------------------------------
1454
1455 An older (pre-1.0), more restrictive and verbose input format for the
1456 :tfilter:`unordered_list` template filter has been deprecated::
1457
1458 ["States", [["Kansas", [["Lawrence", []], ["Topeka", []]]], ["Illinois", []]]]
1459
1460 Using the new syntax, this becomes::
1461
1462 ["States", ["Kansas", ["Lawrence", "Topeka"], "Illinois"]]
1463
1464 ``django.forms.Field._has_changed()``
1465 -------------------------------------
1466
1467 Rename this method to :meth:`~django.forms.Field.has_changed` by removing the
1468 leading underscore. The old name will still work until Django 1.10.
1469
1470 ``django.utils.html.remove_tags()`` and ``removetags`` template filter
1471 ----------------------------------------------------------------------
1472
1473 ``django.utils.html.remove_tags()`` as well as the template filter
1474 ``removetags`` have been deprecated as they cannot guarantee safe output. Their
1475 existence is likely to lead to their use in security-sensitive contexts where
1476 they are not actually safe.
1477
1478 The unused and undocumented ``django.utils.html.strip_entities()`` function has
1479 also been deprecated.
1480
1481 ``is_admin_site`` argument to ``django.contrib.auth.views.password_reset()``
1482 ----------------------------------------------------------------------------
1483
1484 It's a legacy option that should no longer be necessary.
1485
1486 ``SubfieldBase``
1487 ----------------
1488
1489 ``django.db.models.fields.subclassing.SubfieldBase`` has been deprecated and
1490 will be removed in Django 1.10. Historically, it was used to handle fields where
1491 type conversion was needed when loading from the database, but it was not used
1492 in ``.values()`` calls or in aggregates. It has been replaced with
1493 :meth:`~django.db.models.Field.from_db_value`.
1494
1495 The new approach doesn't call the :meth:`~django.db.models.Field.to_python`
1496 method on assignment as was the case with ``SubfieldBase``. If you need that
1497 behavior, reimplement the ``Creator`` class `from Django's source code
1498 <https://github.com/django/django/blob/stable/1.8.x/django/db/models/fields/subclassing.py#L31-L44>`_
1499 in your project.
1500
1501 ``django.utils.checksums``
1502 --------------------------
1503
1504 The ``django.utils.checksums`` module has been deprecated and will be removed
1505 in Django 1.10. The functionality it provided (validating checksum using the
1506 Luhn algorithm) was undocumented and not used in Django. The module has been
1507 moved to the :pypi:`django-localflavor` package (version 1.1+).
1508
1509 ``InlineAdminForm.original_content_type_id``
1510 --------------------------------------------
1511
1512 The ``original_content_type_id`` attribute on ``InlineAdminForm`` has been
1513 deprecated and will be removed in Django 1.10. Historically, it was used
1514 to construct the "view on site" URL. This URL is now accessible using the
1515 ``absolute_url`` attribute of the form.
1516
1517 ``django.views.generic.edit.FormMixin.get_form()``’s ``form_class`` argument
1518 ----------------------------------------------------------------------------
1519
1520 ``FormMixin`` subclasses that override the ``get_form()`` method should make
1521 sure to provide a default value for the ``form_class`` argument since it's
1522 now optional.
1523
1524 Rendering templates loaded by :func:`~django.template.loader.get_template()` with a :class:`~django.template.Context`
1525 ---------------------------------------------------------------------------------------------------------------------
1526
1527 The return type of :func:`~django.template.loader.get_template()` has changed
1528 in Django 1.8: instead of a :class:`django.template.Template`, it returns a
1529 ``Template`` instance whose exact type depends on which backend loaded it.
1530
1531 Both classes provide a ``render()`` method, however, the former takes a
1532 :class:`django.template.Context` as an argument while the latter expects a
1533 :class:`dict`. This change is enforced through a deprecation path for Django
1534 templates.
1535
1536 All this also applies to :func:`~django.template.loader.select_template()`.
1537
1538 :class:`~django.template.Template` and :class:`~django.template.Context` classes in template responses
1539 ------------------------------------------------------------------------------------------------------
1540
1541 Some methods of :class:`~django.template.response.SimpleTemplateResponse` and
1542 :class:`~django.template.response.TemplateResponse` accepted
1543 :class:`django.template.Context` and :class:`django.template.Template` objects
1544 as arguments. They should now receive :class:`dict` and backend-dependent
1545 template objects respectively.
1546
1547 This also applies to the return types if you have subclassed either template
1548 response class.
1549
1550 Check the :doc:`template response API documentation </ref/template-response>`
1551 for details.
1552
1553 ``current_app`` argument of template-related APIs
1554 -------------------------------------------------
1555
1556 The following functions and classes will no longer accept a ``current_app``
1557 parameter to set an URL namespace in Django 1.10:
1558
1559 * ``django.shortcuts.render()``
1560 * ``django.template.Context()``
1561 * ``django.template.RequestContext()``
1562 * ``django.template.response.TemplateResponse()``
1563
1564 Set ``request.current_app`` instead, where ``request`` is the first argument
1565 to these functions or classes. If you're using a plain ``Context``, use a
1566 ``RequestContext`` instead.
1567
1568 ``dictionary`` and ``context_instance`` arguments of rendering functions
1569 ------------------------------------------------------------------------
1570
1571 The following functions will no longer accept the ``dictionary`` and
1572 ``context_instance`` parameters in Django 1.10:
1573
1574 * ``django.shortcuts.render()``
1575 * ``django.shortcuts.render_to_response()``
1576 * ``django.template.loader.render_to_string()``
1577
1578 Use the ``context`` parameter instead. When ``dictionary`` is passed as a
1579 positional argument, which is the most common idiom, no changes are needed.
1580
1581 If you're passing a :class:`~django.template.Context` in ``context_instance``,
1582 pass a :class:`dict` in the ``context`` parameter instead. If you're passing a
1583 :class:`~django.template.RequestContext`, pass the request separately in the
1584 ``request`` parameter.
1585
1586 ``dirs`` argument of template-finding functions
1587 -----------------------------------------------
1588
1589 The following functions will no longer accept a ``dirs`` parameter to override
1590 ``TEMPLATE_DIRS`` in Django 1.10:
1591
1592 * :func:`django.template.loader.get_template()`
1593 * :func:`django.template.loader.select_template()`
1594 * :func:`django.shortcuts.render()`
1595 * ``django.shortcuts.render_to_response()``
1596
1597 The parameter didn't work consistently across different template loaders and
1598 didn't work for included templates.
1599
1600 ``django.template.loader.BaseLoader``
1601 -------------------------------------
1602
1603 ``django.template.loader.BaseLoader`` was renamed to
1604 ``django.template.loaders.base.Loader``. If you've written a custom template
1605 loader that inherits ``BaseLoader``, you must inherit ``Loader`` instead.
1606
1607 ``django.test.utils.TestTemplateLoader``
1608 ----------------------------------------
1609
1610 Private API ``django.test.utils.TestTemplateLoader`` is deprecated in favor of
1611 ``django.template.loaders.locmem.Loader`` and will be removed in Django 1.9.
1612
1613 .. _storage-max-length-update:
1614
1615 Support for the ``max_length`` argument on custom ``Storage`` classes
1616 ---------------------------------------------------------------------
1617
1618 ``Storage`` subclasses should add ``max_length=None`` as a parameter to
1619 :meth:`~django.core.files.storage.Storage.get_available_name` and/or
1620 :meth:`~django.core.files.storage.Storage.save` if they override either method.
1621 Support for storages that do not accept this argument will be removed in
1622 Django 1.10.
1623
1624 ``qn`` replaced by ``compiler``
1625 -------------------------------
1626
1627 In previous Django versions, various internal ORM methods (mostly ``as_sql``
1628 methods) accepted a ``qn`` (for "quote name") argument, which was a reference
1629 to a function that quoted identifiers for sending to the database. In Django
1630 1.8, that argument has been renamed to ``compiler`` and is now a full
1631 ``SQLCompiler`` instance. For backwards-compatibility, calling a
1632 ``SQLCompiler`` instance performs the same name-quoting that the ``qn``
1633 function used to. However, this backwards-compatibility shim is immediately
1634 deprecated: you should rename your ``qn`` arguments to ``compiler``, and call
1635 ``compiler.quote_name_unless_alias(...)`` where you previously called
1636 ``qn(...)``.
1637
1638 Default value of ``RedirectView.permanent``
1639 -------------------------------------------
1640
1641 The default value of the
1642 :attr:`RedirectView.permanent <django.views.generic.base.RedirectView.permanent>`
1643 attribute will change from ``True`` to ``False`` in Django 1.9.
1644
1645 Using ``AuthenticationMiddleware`` without ``SessionAuthenticationMiddleware``
1646 ------------------------------------------------------------------------------
1647
1648 ``django.contrib.auth.middleware.SessionAuthenticationMiddleware`` was
1649 added in Django 1.7. In Django 1.7.2, its functionality was moved to
1650 ``auth.get_user()`` and, for backwards compatibility, enabled only if
1651 ``'django.contrib.auth.middleware.SessionAuthenticationMiddleware'`` appears in
1652 ``MIDDLEWARE_CLASSES``.
1653
1654 In Django 1.10, session verification will be enabled regardless of whether or not
1655 ``SessionAuthenticationMiddleware`` is enabled (at which point
1656 ``SessionAuthenticationMiddleware`` will have no significance). You can add it
1657 to your ``MIDDLEWARE_CLASSES`` sometime before then to opt-in. Please read the
1658 :ref:`upgrade considerations <session-invalidation-on-password-change>` first.
1659
1660 ``django.contrib.sitemaps.FlatPageSitemap``
1661 -------------------------------------------
1662
1663 ``django.contrib.sitemaps.FlatPageSitemap`` has moved to
1664 ``django.contrib.flatpages.sitemaps.FlatPageSitemap``. The old import location
1665 is deprecated and will be removed in Django 1.9.
1666
1667 Model ``Field.related``
1668 -----------------------
1669
1670 Private attribute ``django.db.models.Field.related`` is deprecated in favor
1671 of ``Field.rel``. The latter is an instance of
1672 ``django.db.models.fields.related.ForeignObjectRel`` which replaces
1673 ``django.db.models.related.RelatedObject``. The ``django.db.models.related``
1674 module has been removed and the ``Field.related`` attribute will be removed in
1675 Django 1.10.
1676
1677 ``ssi`` template tag
1678 --------------------
1679
1680 The ``ssi`` template tag allows files to be included in a template by
1681 absolute path. This is of limited use in most deployment situations, and
1682 the :ttag:`include` tag often makes more sense. This tag is now deprecated and
1683 will be removed in Django 1.10.
1684
1685 ``=`` as comparison operator in ``if`` template tag
1686 ---------------------------------------------------
1687
1688 Using a single equals sign with the ``{% if %}`` template tag for equality
1689 testing was undocumented and untested. It's now deprecated in favor of ``==``.
1690
1691 ``%(<foo>)s`` syntax in ``ModelFormMixin.success_url``
1692 ------------------------------------------------------
1693
1694 The legacy ``%(<foo>)s`` syntax in :attr:`ModelFormMixin.success_url
1695 <django.views.generic.edit.ModelFormMixin.success_url>` is deprecated and
1696 will be removed in Django 1.10.
1697
1698 ``GeoQuerySet`` aggregate methods
1699 ---------------------------------
1700
1701 The ``collect()``, ``extent()``, ``extent3d()``, ``make_line()``, and
1702 ``unionagg()`` aggregate methods are deprecated and should be replaced by their
1703 function-based aggregate equivalents (``Collect``, ``Extent``, ``Extent3D``,
1704 ``MakeLine``, and ``Union``).
1705
1706 .. _deprecated-signature-of-allow-migrate:
1707
1708 Signature of the ``allow_migrate`` router method
1709 ------------------------------------------------
1710
1711 The signature of the :meth:`allow_migrate` method of database routers has
1712 changed from ``allow_migrate(db, model)`` to
1713 ``allow_migrate(db, app_label, model_name=None, **hints)``.
1714
1715 When ``model_name`` is set, the value that was previously given through the
1716 ``model`` positional argument may now be found inside the ``hints`` dictionary
1717 under the key ``'model'``.
1718
1719 After switching to the new signature the router will also be called by the
1720 :class:`~django.db.migrations.operations.RunPython` and
1721 :class:`~django.db.migrations.operations.RunSQL` operations.
1722
1723 .. _removed-features-1.8:
1724
1725 Features removed in 1.8
1726 =======================
1727
1728 These features have reached the end of their deprecation cycle and are removed
1729 in Django 1.8. See :ref:`deprecated-features-1.6` for details, including how to
1730 remove usage of these features.
1731
1732 * ``django.contrib.comments`` is removed.
1733
1734 * The following transaction management APIs are removed:
1735
1736 - ``TransactionMiddleware``
1737 - the decorators and context managers ``autocommit``, ``commit_on_success``,
1738 and ``commit_manually``, defined in ``django.db.transaction``
1739 - the functions ``commit_unless_managed`` and ``rollback_unless_managed``,
1740 also defined in ``django.db.transaction``
1741 - the ``TRANSACTIONS_MANAGED`` setting
1742
1743 * The :ttag:`cycle` and :ttag:`firstof` template tags auto-escape their
1744 arguments.
1745
1746 * The ``SEND_BROKEN_LINK_EMAILS`` setting is removed.
1747
1748 * ``django.middleware.doc.XViewMiddleware`` is removed.
1749
1750 * The ``Model._meta.module_name`` alias is removed.
1751
1752 * The backward compatible shims introduced to rename ``get_query_set``
1753 and similar queryset methods are removed. This affects the following classes:
1754 ``BaseModelAdmin``, ``ChangeList``, ``BaseCommentNode``,
1755 ``GenericForeignKey``, ``Manager``, ``SingleRelatedObjectDescriptor`` and
1756 ``ReverseSingleRelatedObjectDescriptor``.
1757
1758 * The backward compatible shims introduced to rename the attributes
1759 ``ChangeList.root_query_set`` and ``ChangeList.query_set`` are removed.
1760
1761 * ``django.views.defaults.shortcut`` and ``django.conf.urls.shortcut`` are
1762 removed.
1763
1764 * Support for the Python Imaging Library (PIL) module is removed.
1765
1766 * The following private APIs are removed:
1767
1768 - ``django.db.backend``
1769 - ``django.db.close_connection()``
1770 - ``django.db.backends.creation.BaseDatabaseCreation.set_autocommit()``
1771 - ``django.db.transaction.is_managed()``
1772 - ``django.db.transaction.managed()``
1773
1774 * ``django.forms.widgets.RadioInput`` is removed.
1775
1776 * The module ``django.test.simple`` and the class
1777 ``django.test.simple.DjangoTestSuiteRunner`` are removed.
1778
1779 * The module ``django.test._doctest`` is removed.
1780
1781 * The ``CACHE_MIDDLEWARE_ANONYMOUS_ONLY`` setting is removed. This change
1782 affects both ``django.middleware.cache.CacheMiddleware`` and
1783 ``django.middleware.cache.UpdateCacheMiddleware`` despite the lack of a
1784 deprecation warning in the latter class.
1785
1786 * Usage of the hard-coded *Hold down "Control", or "Command" on a Mac, to select
1787 more than one.* string to override or append to user-provided ``help_text`` in
1788 forms for ``ManyToMany`` model fields is not performed by Django anymore
1789 either at the model or forms layer.
1790
1791 * The ``Model._meta.get_(add|change|delete)_permission`` methods are removed.
1792
1793 * The session key ``django_language`` is no longer read for backwards
1794 compatibility.
1795
1796 * Geographic Sitemaps are removed
1797 (``django.contrib.gis.sitemaps.views.index`` and
1798 ``django.contrib.gis.sitemaps.views.sitemap``).
1799
1800 * ``django.utils.html.fix_ampersands``, the ``fix_ampersands`` template filter,
1801 and ``django.utils.html.clean_html`` are removed.