Debian Codegraph @

docs/releases/1.11.txt

raw
1 =========================
2 Django 1.11 release notes
3 =========================
4
5 *April 4, 2017*
6
7 Welcome to Django 1.11!
8
9 These release notes cover the :ref:`new features <whats-new-1.11>`, as well as
10 some :ref:`backwards incompatible changes <backwards-incompatible-1.11>` you'll
11 want to be aware of when upgrading from Django 1.10 or older versions. We've
12 :ref:`begun the deprecation process for some features
13 <deprecated-features-1.11>`.
14
15 See the :doc:`/howto/upgrade-version` guide if you're updating an existing
16 project.
17
18 Django 1.11 is designated as a :term:`long-term support release
19 <Long-term support release>`. It will receive security updates for at least
20 three years after its release. Support for the previous LTS, Django 1.8, will
21 end in April 2018.
22
23 Python compatibility
24 ====================
25
26 Django 1.11 requires Python 2.7, 3.4, 3.5, 3.6, or 3.7 (as of 1.11.17). We
27 **highly recommend** and only officially support the latest release of each
28 series.
29
30 The Django 1.11.x series is the last to support Python 2. The next major
31 release, Django 2.0, will only support Python 3.4+.
32
33 Deprecating warnings are no longer loud by default
34 ==================================================
35
36 Unlike older versions of Django, Django's own deprecation warnings are no
37 longer displayed by default. This is consistent with Python's default behavior.
38
39 This change allows third-party apps to support both Django 1.11 LTS and Django
40 1.8 LTS without having to add code to avoid deprecation warnings.
41
42 Following the release of Django 2.0, we suggest that third-party app authors
43 drop support for all versions of Django prior to 1.11. At that time, you should
44 be able run your package's tests using ``python -Wd`` so that deprecation
45 warnings do appear. After making the deprecation warning fixes, your app should
46 be compatible with Django 2.0.
47
48 .. _whats-new-1.11:
49
50 What's new in Django 1.11
51 =========================
52
53 Class-based model indexes
54 -------------------------
55
56 The new :mod:`django.db.models.indexes` module contains classes which ease
57 creating database indexes. Indexes are added to models using the
58 :attr:`Meta.indexes <django.db.models.Options.indexes>` option.
59
60 The :class:`~django.db.models.Index` class creates a b-tree index, as if you
61 used :attr:`~django.db.models.Field.db_index` on the model field or
62 ``index_together`` on the model ``Meta`` class. It can be subclassed to support
63 different index types, such as
64 :class:`~django.contrib.postgres.indexes.GinIndex`. It also allows defining the
65 order (ASC/DESC) for the columns of the index.
66
67 Template-based widget rendering
68 -------------------------------
69
70 To ease customizing widgets, form widget rendering is now done using the
71 template system rather than in Python. See :doc:`/ref/forms/renderers`.
72
73 You may need to adjust any custom widgets that you've written for a few
74 :ref:`backwards incompatible changes <template-widget-incompatibilities-1-11>`.
75
76 ``Subquery`` expressions
77 ------------------------
78
79 The new :class:`~django.db.models.Subquery` and
80 :class:`~django.db.models.Exists` database expressions allow creating
81 explicit subqueries. Subqueries may refer to fields from the outer queryset
82 using the :class:`~django.db.models.OuterRef` class.
83
84 Minor features
85 --------------
86
87 :mod:`django.contrib.admin`
88 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
89
90 * :attr:`.ModelAdmin.date_hierarchy` can now reference fields across relations.
91
92 * The new :meth:`ModelAdmin.get_exclude()
93 <django.contrib.admin.ModelAdmin.get_exclude>` hook allows specifying the
94 exclude fields based on the request or model instance.
95
96 * The ``popup_response.html`` template can now be overridden per app, per
97 model, or by setting the :attr:`.ModelAdmin.popup_response_template`
98 attribute.
99
100 :mod:`django.contrib.auth`
101 ~~~~~~~~~~~~~~~~~~~~~~~~~~
102
103 * The default iteration count for the PBKDF2 password hasher is increased by
104 20%.
105
106 * The :class:`~django.contrib.auth.views.LoginView` and
107 :class:`~django.contrib.auth.views.LogoutView` class-based views supersede the
108 deprecated ``login()`` and ``logout()`` function-based views.
109
110 * The :class:`~django.contrib.auth.views.PasswordChangeView`,
111 :class:`~django.contrib.auth.views.PasswordChangeDoneView`,
112 :class:`~django.contrib.auth.views.PasswordResetView`,
113 :class:`~django.contrib.auth.views.PasswordResetDoneView`,
114 :class:`~django.contrib.auth.views.PasswordResetConfirmView`, and
115 :class:`~django.contrib.auth.views.PasswordResetCompleteView` class-based
116 views supersede the deprecated ``password_change()``,
117 ``password_change_done()``, ``password_reset()``, ``password_reset_done()``,
118 ``password_reset_confirm()``, and ``password_reset_complete()`` function-based
119 views.
120
121 * The new ``post_reset_login`` attribute for
122 :class:`~django.contrib.auth.views.PasswordResetConfirmView` allows
123 automatically logging in a user after a successful password reset.
124 If you have multiple ``AUTHENTICATION_BACKENDS`` configured, use the
125 ``post_reset_login_backend`` attribute to choose which one to use.
126
127 * To avoid the possibility of leaking a password reset token via the HTTP
128 Referer header (for example, if the reset page includes a reference to CSS or
129 JavaScript hosted on another domain), the
130 :class:`~django.contrib.auth.views.PasswordResetConfirmView` (but not the
131 deprecated ``password_reset_confirm()`` function-based view) stores the token
132 in a session and redirects to itself to present the password change form to
133 the user without the token in the URL.
134
135 * :func:`~django.contrib.auth.update_session_auth_hash` now rotates the session
136 key to allow a password change to invalidate stolen session cookies.
137
138 * The new ``success_url_allowed_hosts`` attribute for
139 :class:`~django.contrib.auth.views.LoginView` and
140 :class:`~django.contrib.auth.views.LogoutView` allows specifying a set of
141 hosts that are safe for redirecting after login and logout.
142
143 * Added password validators ``help_text`` to
144 :class:`~django.contrib.auth.forms.UserCreationForm`.
145
146 * The ``HttpRequest`` is now passed to :func:`~django.contrib.auth.authenticate`
147 which in turn passes it to the authentication backend if it accepts a
148 ``request`` argument.
149
150 * The :func:`~django.contrib.auth.signals.user_login_failed` signal now
151 receives a ``request`` argument.
152
153 * :class:`~django.contrib.auth.forms.PasswordResetForm` supports custom user
154 models that use an email field named something other than ``'email'``.
155 Set :attr:`CustomUser.EMAIL_FIELD
156 <django.contrib.auth.models.CustomUser.EMAIL_FIELD>` to the name of the field.
157
158 * :func:`~django.contrib.auth.get_user_model` can now be called at import time,
159 even in modules that define models.
160
161 :mod:`django.contrib.contenttypes`
162 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
163
164 * When stale content types are detected in the
165 :djadmin:`remove_stale_contenttypes` command, there's now a list of related
166 objects such as ``auth.Permission``\s that will also be deleted. Previously,
167 only the content types were listed (and this prompt was after ``migrate``
168 rather than in a separate command).
169
170 :mod:`django.contrib.gis`
171 ~~~~~~~~~~~~~~~~~~~~~~~~~
172
173 * The new :meth:`.GEOSGeometry.from_gml` and :meth:`.OGRGeometry.from_gml`
174 methods allow creating geometries from GML.
175
176 * Added support for the :lookup:`dwithin` lookup on SpatiaLite.
177
178 * The :class:`~django.contrib.gis.db.models.functions.Area` function,
179 :class:`~django.contrib.gis.db.models.functions.Distance` function, and
180 distance lookups now work with geodetic coordinates on SpatiaLite.
181
182 * The OpenLayers-based form widgets now use ``OpenLayers.js`` from
183 ``https://cdnjs.cloudflare.com`` which is more suitable for production use
184 than the old ``https://openlayers.org/`` source. They are also updated to use
185 OpenLayers 3.
186
187 * PostGIS migrations can now change field dimensions.
188
189 * Added the ability to pass the ``size``, ``shape``, and ``offset`` parameters
190 when creating :class:`~django.contrib.gis.gdal.GDALRaster` objects.
191
192 * Added SpatiaLite support for the
193 :class:`~django.contrib.gis.db.models.functions.IsValid` function,
194 :class:`~django.contrib.gis.db.models.functions.MakeValid` function, and
195 :lookup:`isvalid` lookup.
196
197 * Added Oracle support for the
198 :class:`~django.contrib.gis.db.models.functions.AsGML` function,
199 :class:`~django.contrib.gis.db.models.functions.BoundingCircle` function,
200 :class:`~django.contrib.gis.db.models.functions.IsValid` function, and
201 :lookup:`isvalid` lookup.
202
203 :mod:`django.contrib.postgres`
204 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
205
206 * The new ``distinct`` argument for
207 :class:`~django.contrib.postgres.aggregates.StringAgg` determines if
208 concatenated values will be distinct.
209
210 * The new :class:`~django.contrib.postgres.indexes.GinIndex` and
211 :class:`~django.contrib.postgres.indexes.BrinIndex` classes allow
212 creating ``GIN`` and ``BRIN`` indexes in the database.
213
214 * ``django.contrib.postgres.fields.JSONField`` accepts a new ``encoder``
215 parameter to specify a custom class to encode data types not supported by the
216 standard encoder.
217
218 * The new ``CIText`` mixin and
219 :class:`~django.contrib.postgres.operations.CITextExtension` migration
220 operation allow using PostgreSQL's ``citext`` extension for case-insensitive
221 lookups. Three fields are provided: ``CICharField``, ``CIEmailField``, and
222 ``CITextField``.
223
224 * The new :class:`~django.contrib.postgres.aggregates.JSONBAgg` allows
225 aggregating values as a JSON array.
226
227 * The :class:`~django.contrib.postgres.fields.HStoreField` (model field) and
228 :class:`~django.contrib.postgres.forms.HStoreField` (form field) allow
229 storing null values.
230
231 Cache
232 ~~~~~
233
234 * Memcached backends now pass the contents of :setting:`OPTIONS <CACHES-OPTIONS>`
235 as keyword arguments to the client constructors, allowing for more advanced
236 control of client behavior. See the :ref:`cache arguments <cache_arguments>`
237 documentation for examples.
238
239 * Memcached backends now allow defining multiple servers as a comma-delimited
240 string in :setting:`LOCATION <CACHES-LOCATION>`, for convenience with
241 third-party services that use such strings in environment variables.
242
243 CSRF
244 ~~~~
245
246 * Added the :setting:`CSRF_USE_SESSIONS` setting to allow storing the CSRF
247 token in the user's session rather than in a cookie.
248
249 Database backends
250 ~~~~~~~~~~~~~~~~~
251
252 * Added the ``skip_locked`` argument to :meth:`.QuerySet.select_for_update()`
253 on PostgreSQL 9.5+ and Oracle to execute queries with
254 ``FOR UPDATE SKIP LOCKED``.
255
256 * Added the :setting:`TEST['TEMPLATE'] <TEST_TEMPLATE>` setting to let
257 PostgreSQL users specify a template for creating the test database.
258
259 * :meth:`.QuerySet.iterator()` now uses `server-side cursors`_ on PostgreSQL.
260 This feature transfers some of the worker memory load (used to hold query
261 results) to the database and might increase database memory usage.
262
263 .. _server-side cursors: https://www.psycopg.org/docs/usage.html#server-side-cursors
264
265 * Added MySQL support for the ``'isolation_level'`` option in
266 :setting:`OPTIONS` to allow specifying the :ref:`transaction isolation level
267 <mysql-isolation-level>`. To avoid possible data loss, it's recommended to
268 switch from MySQL's default level, repeatable read, to read committed.
269
270 * Added support for ``cx_Oracle`` 5.3.
271
272 Email
273 ~~~~~
274
275 * Added the :setting:`EMAIL_USE_LOCALTIME` setting to allow sending SMTP date
276 headers in the local time zone rather than in UTC.
277
278 * ``EmailMessage.attach()`` and ``attach_file()`` now fall back to MIME type
279 :mimetype:`application/octet-stream` when binary content that can't be
280 decoded as UTF-8 is specified for a :mimetype:`text/*` attachment.
281
282 File Storage
283 ~~~~~~~~~~~~
284
285 * To make it wrappable by :class:`io.TextIOWrapper`,
286 :class:`~django.core.files.File` now has the ``readable()``, ``writable()``,
287 and ``seekable()`` methods.
288
289 Forms
290 ~~~~~
291
292 * The new ``empty_value`` attribute on :class:`~django.forms.CharField`,
293 :class:`~django.forms.EmailField`, :class:`~django.forms.RegexField`,
294 :class:`~django.forms.SlugField`, and :class:`~django.forms.URLField` allows
295 specifying the Python value to use to represent "empty".
296
297 * The new :meth:`Form.get_initial_for_field()
298 <django.forms.Form.get_initial_for_field>` method returns initial data for a
299 form field.
300
301 Internationalization
302 ~~~~~~~~~~~~~~~~~~~~
303
304 * Number formatting and the :setting:`NUMBER_GROUPING` setting support
305 non-uniform digit grouping.
306
307 Management Commands
308 ~~~~~~~~~~~~~~~~~~~
309
310 * The new :option:`loaddata --exclude` option allows excluding models and apps
311 while loading data from fixtures.
312
313 * The new :option:`diffsettings --default` option allows specifying a settings
314 module other than Django's default settings to compare against.
315
316 * ``app_label``\s arguments now limit the :option:`showmigrations --plan`
317 output.
318
319 Migrations
320 ~~~~~~~~~~
321
322 * Added support for serialization of ``uuid.UUID`` objects.
323
324 Models
325 ~~~~~~
326
327 * Added support for callable values in the ``defaults`` argument of
328 :meth:`QuerySet.update_or_create()
329 <django.db.models.query.QuerySet.update_or_create>` and
330 :meth:`~django.db.models.query.QuerySet.get_or_create`.
331
332 * :class:`~django.db.models.ImageField` now has a default
333 :data:`~django.core.validators.validate_image_file_extension` validator.
334 (This validator moved to the form field in :doc:`Django 1.11.2 <1.11.2>`.)
335
336 * Added support for time truncation to
337 :class:`~django.db.models.functions.Trunc` functions.
338
339 * Added the :class:`~django.db.models.functions.ExtractWeek` function to
340 extract the week from :class:`~django.db.models.DateField` and
341 :class:`~django.db.models.DateTimeField` and exposed it through the
342 :lookup:`week` lookup.
343
344 * Added the :class:`~django.db.models.functions.TruncTime` function to truncate
345 :class:`~django.db.models.DateTimeField` to its time component and exposed it
346 through the :lookup:`time` lookup.
347
348 * Added support for expressions in :meth:`.QuerySet.values` and
349 :meth:`~.QuerySet.values_list`.
350
351 * Added support for query expressions on lookups that take multiple arguments,
352 such as ``range``.
353
354 * You can now use the ``unique=True`` option with
355 :class:`~django.db.models.FileField`.
356
357 * Added the ``nulls_first`` and ``nulls_last`` parameters to
358 :class:`Expression.asc() <django.db.models.Expression.asc>` and
359 :meth:`~django.db.models.Expression.desc` to control
360 the ordering of null values.
361
362 * The new ``F`` expression ``bitleftshift()`` and ``bitrightshift()`` methods
363 allow :ref:`bitwise shift operations <using-f-expressions-in-filters>`.
364
365 * Added :meth:`.QuerySet.union`, :meth:`~.QuerySet.intersection`, and
366 :meth:`~.QuerySet.difference`.
367
368 Requests and Responses
369 ~~~~~~~~~~~~~~~~~~~~~~
370
371 * Added :meth:`QueryDict.fromkeys() <django.http.QueryDict.fromkeys>`.
372
373 * :class:`~django.middleware.common.CommonMiddleware` now sets the
374 ``Content-Length`` response header for non-streaming responses.
375
376 * Added the :setting:`SECURE_HSTS_PRELOAD` setting to allow appending the
377 ``preload`` directive to the ``Strict-Transport-Security`` header.
378
379 * :class:`~django.middleware.http.ConditionalGetMiddleware` now adds the
380 ``ETag`` header to responses.
381
382 Serialization
383 ~~~~~~~~~~~~~
384
385 * The new ``django.core.serializers.base.Serializer.stream_class`` attribute
386 allows subclasses to customize the default stream.
387
388 * The encoder used by the :ref:`JSON serializer <serialization-formats-json>`
389 can now be customized by passing a ``cls`` keyword argument to the
390 ``serializers.serialize()`` function.
391
392 * :class:`~django.core.serializers.json.DjangoJSONEncoder` now serializes
393 :class:`~datetime.timedelta` objects (used by
394 :class:`~django.db.models.DurationField`).
395
396 Templates
397 ~~~~~~~~~
398
399 * :meth:`~django.utils.safestring.mark_safe` can now be used as a decorator.
400
401 * The :class:`~django.template.backends.jinja2.Jinja2` template backend now
402 supports context processors by setting the ``'context_processors'`` option in
403 :setting:`OPTIONS <TEMPLATES-OPTIONS>`.
404
405 * The :ttag:`regroup` tag now returns ``namedtuple``\s instead of dictionaries
406 so you can unpack the group object directly in a loop, e.g.
407 ``{% for grouper, list in regrouped %}``.
408
409 * Added a :ttag:`resetcycle` template tag to allow resetting the sequence of
410 the :ttag:`cycle` template tag.
411
412 * You can now specify specific directories for a particular
413 :class:`filesystem.Loader <django.template.loaders.filesystem.Loader>`.
414
415 Tests
416 ~~~~~
417
418 * Added :meth:`.DiscoverRunner.get_test_runner_kwargs` to allow customizing the
419 keyword arguments passed to the test runner.
420
421 * Added the :option:`test --debug-mode` option to help troubleshoot test
422 failures by setting the :setting:`DEBUG` setting to ``True``.
423
424 * The new :func:`django.test.utils.setup_databases` (moved from
425 ``django.test.runner``) and :func:`~django.test.utils.teardown_databases`
426 functions make it easier to build custom test runners.
427
428 * Added support for :meth:`python:unittest.TestCase.subTest`’s when using the
429 :option:`test --parallel` option.
430
431 * ``DiscoverRunner`` now runs the system checks at the start of a test run.
432 Override the :meth:`.DiscoverRunner.run_checks` method if you want to disable
433 that.
434
435 Validators
436 ~~~~~~~~~~
437
438 * Added :class:`~django.core.validators.FileExtensionValidator` to validate
439 file extensions and
440 :data:`~django.core.validators.validate_image_file_extension` to validate
441 image files.
442
443 .. _backwards-incompatible-1.11:
444
445 Backwards incompatible changes in 1.11
446 ======================================
447
448 :mod:`django.contrib.gis`
449 -------------------------
450
451 * To simplify the codebase and because it's easier to install than when
452 ``contrib.gis`` was first released, :ref:`gdalbuild` is now a required
453 dependency for GeoDjango. In older versions, it's only required for SQLite.
454
455 * ``contrib.gis.maps`` is removed as it interfaces with a retired version of
456 the Google Maps API and seems to be unmaintained. If you're using it,
457 :ticket:`let us know <14284>`.
458
459 * The ``GEOSGeometry`` equality operator now also compares SRID.
460
461 * The OpenLayers-based form widgets now use OpenLayers 3, and the
462 ``gis/openlayers.html`` and ``gis/openlayers-osm.html`` templates have been
463 updated. Check your project if you subclass these widgets or extend the
464 templates. Also, the new widgets work a bit differently than the old ones.
465 Instead of using a toolbar in the widget, you click to draw, click and drag
466 to move the map, and click and drag a point/vertex/corner to move it.
467
468 * Support for SpatiaLite < 4.0 is dropped.
469
470 * Support for GDAL 1.7 and 1.8 is dropped.
471
472 * The widgets in ``contrib.gis.forms.widgets`` and the admin's
473 ``OpenLayersWidget`` use the :doc:`form rendering API </ref/forms/renderers>`
474 rather than ``loader.render_to_string()``. If you're using a custom widget
475 template, you'll need to be sure your form renderer can locate it. For
476 example, you could use the :class:`~django.forms.renderers.TemplatesSetting`
477 renderer.
478
479 :mod:`django.contrib.staticfiles`
480 ---------------------------------
481
482 * ``collectstatic`` may now fail during post-processing when using a hashed
483 static files storage if a reference loop exists (e.g. ``'foo.css'``
484 references ``'bar.css'`` which itself references ``'foo.css'``) or if the
485 chain of files referencing other files is too deep to resolve in several
486 passes. In the latter case, increase the number of passes using
487 :attr:`.ManifestStaticFilesStorage.max_post_process_passes`.
488
489 * When using ``ManifestStaticFilesStorage``, static files not found in the
490 manifest at runtime now raise a ``ValueError`` instead of returning an
491 unchanged path. You can revert to the old behavior by setting
492 :attr:`.ManifestStaticFilesStorage.manifest_strict` to ``False``.
493
494 Database backend API
495 --------------------
496
497 This section describes changes that may be needed in third-party database
498 backends.
499
500 * The ``DatabaseOperations.time_trunc_sql()`` method is added to support
501 ``TimeField`` truncation. It accepts a ``lookup_type`` and ``field_name``
502 arguments and returns the appropriate SQL to truncate the given time field
503 ``field_name`` to a time object with only the given specificity. The
504 ``lookup_type`` argument can be either ``'hour'``, ``'minute'``, or
505 ``'second'``.
506
507 * The ``DatabaseOperations.datetime_cast_time_sql()`` method is added to
508 support the :lookup:`time` lookup. It accepts a ``field_name`` and ``tzname``
509 arguments and returns the SQL necessary to cast a datetime value to time value.
510
511 * To enable ``FOR UPDATE SKIP LOCKED`` support, set
512 ``DatabaseFeatures.has_select_for_update_skip_locked = True``.
513
514 * The new ``DatabaseFeatures.supports_index_column_ordering`` attribute
515 specifies if a database allows defining ordering for columns in indexes. The
516 default value is ``True`` and the ``DatabaseIntrospection.get_constraints()``
517 method should include an ``'orders'`` key in each of the returned
518 dictionaries with a list of ``'ASC'`` and/or ``'DESC'`` values corresponding
519 to the ordering of each column in the index.
520
521 * :djadmin:`inspectdb` no longer calls ``DatabaseIntrospection.get_indexes()``
522 which is deprecated. Custom database backends should ensure all types of
523 indexes are returned by ``DatabaseIntrospection.get_constraints()``.
524
525 * Renamed the ``ignores_quoted_identifier_case`` feature to
526 ``ignores_table_name_case`` to more accurately reflect how it is used.
527
528 * The ``name`` keyword argument is added to the
529 ``DatabaseWrapper.create_cursor(self, name=None)`` method to allow usage of
530 server-side cursors on backends that support it.
531
532 Dropped support for PostgreSQL 9.2 and PostGIS 2.0
533 --------------------------------------------------
534
535 Upstream support for PostgreSQL 9.2 ends in September 2017. As a consequence,
536 Django 1.11 sets PostgreSQL 9.3 as the minimum version it officially supports.
537
538 Support for PostGIS 2.0 is also removed as PostgreSQL 9.2 is the last version
539 to support it.
540
541 Also, the minimum supported version of psycopg2 is increased from 2.4.5 to
542 2.5.4.
543
544 .. _liveservertestcase-port-zero-change:
545
546 ``LiveServerTestCase`` binds to port zero
547 -----------------------------------------
548
549 Rather than taking a port range and iterating to find a free port,
550 ``LiveServerTestCase`` binds to port zero and relies on the operating system
551 to assign a free port. The ``DJANGO_LIVE_TEST_SERVER_ADDRESS`` environment
552 variable is no longer used, and as it's also no longer used, the
553 ``manage.py test --liveserver`` option is removed.
554
555 If you need to bind ``LiveServerTestCase`` to a specific port, use the ``port``
556 attribute added in Django 1.11.2.
557
558 Protection against insecure redirects in :mod:`django.contrib.auth` and ``i18n`` views
559 --------------------------------------------------------------------------------------
560
561 ``LoginView``, ``LogoutView`` (and the deprecated function-based equivalents),
562 and :func:`~django.views.i18n.set_language` protect users from being redirected
563 to non-HTTPS ``next`` URLs when the app is running over HTTPS.
564
565 ``QuerySet.get_or_create()`` and ``update_or_create()`` validate arguments
566 --------------------------------------------------------------------------
567
568 To prevent typos from passing silently,
569 :meth:`~django.db.models.query.QuerySet.get_or_create` and
570 :meth:`~django.db.models.query.QuerySet.update_or_create` check that their
571 arguments are model fields. This should be backwards-incompatible only in the
572 fact that it might expose a bug in your project.
573
574 ``pytz`` is a required dependency and support for ``settings.TIME_ZONE = None`` is removed
575 ------------------------------------------------------------------------------------------
576
577 To simplify Django's timezone handling, ``pytz`` is now a required dependency.
578 It's automatically installed along with Django.
579
580 Support for ``settings.TIME_ZONE = None`` is removed as the behavior isn't
581 commonly used and is questionably useful. If you want to automatically detect
582 the timezone based on the system timezone, you can use :pypi:`tzlocal`::
583
584 from tzlocal import get_localzone
585
586 TIME_ZONE = get_localzone().zone
587
588 This works similar to ``settings.TIME_ZONE = None`` except that it also sets
589 ``os.environ['TZ']``. `Let us know
590 <https://groups.google.com/g/django-developers/c/OAV3FChfuPM/discussion>`__
591 if there's a use case where you find you can't adapt your code to set a
592 ``TIME_ZONE``.
593
594 HTML changes in admin templates
595 -------------------------------
596
597 ``<p class="help">`` is replaced with a ``<div>`` tag to allow including lists
598 inside help text.
599
600 Read-only fields are wrapped in ``<div class="readonly">...</div>`` instead of
601 ``<p>...</p>`` to allow any kind of HTML as the field's content.
602
603 .. _template-widget-incompatibilities-1-11:
604
605 Changes due to the introduction of template-based widget rendering
606 ------------------------------------------------------------------
607
608 Some undocumented classes in ``django.forms.widgets`` are removed:
609
610 * ``SubWidget``
611 * ``RendererMixin``, ``ChoiceFieldRenderer``, ``RadioFieldRenderer``,
612 ``CheckboxFieldRenderer``
613 * ``ChoiceInput``, ``RadioChoiceInput``, ``CheckboxChoiceInput``
614
615 The undocumented ``Select.render_option()`` method is removed.
616
617 The ``Widget.format_output()`` method is removed. Use a custom widget template
618 instead.
619
620 Some widget values, such as ``<select>`` options, are now localized if
621 ``settings.USE_L10N=True``. You could revert to the old behavior with custom
622 widget templates that uses the :ttag:`localize` template tag to turn off
623 localization.
624
625 ``django.template.backends.django.Template.render()`` prohibits non-dict context
626 --------------------------------------------------------------------------------
627
628 For compatibility with multiple template engines,
629 ``django.template.backends.django.Template.render()`` (returned from high-level
630 template loader APIs such as ``loader.get_template()``) must receive a
631 dictionary of context rather than ``Context`` or ``RequestContext``. If you
632 were passing either of the two classes, pass a dictionary instead -- doing so
633 is backwards-compatible with older versions of Django.
634
635 Model state changes in migration operations
636 -------------------------------------------
637
638 To improve the speed of applying migrations, rendering of related models is
639 delayed until an operation that needs them (e.g. ``RunPython``). If you have a
640 custom operation that works with model classes or model instances from the
641 ``from_state`` argument in ``database_forwards()`` or ``database_backwards()``,
642 you must render model states using the ``clear_delayed_apps_cache()`` method as
643 described in :ref:`writing your own migration operation
644 <writing-your-own-migration-operation>`.
645
646 Server-side cursors on PostgreSQL
647 ---------------------------------
648
649 The change to make :meth:`.QuerySet.iterator()` use server-side cursors on
650 PostgreSQL prevents running Django with PgBouncer in transaction pooling mode.
651 To reallow that, use the :setting:`DISABLE_SERVER_SIDE_CURSORS
652 <DATABASE-DISABLE_SERVER_SIDE_CURSORS>` setting (added in Django 1.11.1) in
653 :setting:`DATABASES`.
654
655 See :ref:`transaction-pooling-server-side-cursors` for more discussion.
656
657 Miscellaneous
658 -------------
659
660 * If no items in the feed have a ``pubdate`` or ``updateddate`` attribute,
661 :meth:`SyndicationFeed.latest_post_date()
662 <django.utils.feedgenerator.SyndicationFeed.latest_post_date>` now returns
663 the current UTC date/time, instead of a datetime without any timezone
664 information.
665
666 * CSRF failures are logged to the ``django.security.csrf`` logger instead of
667 ``django.request``.
668
669 * :setting:`ALLOWED_HOSTS` validation is no longer disabled when running tests.
670 If your application includes tests with custom host names, you must include
671 those host names in :setting:`ALLOWED_HOSTS`. See
672 :ref:`topics-testing-advanced-multiple-hosts`.
673
674 * Using a foreign key's id (e.g. ``'field_id'``) in ``ModelAdmin.list_display``
675 displays the related object's ID. Remove the ``_id`` suffix if you want the
676 old behavior of the string representation of the object.
677
678 * In model forms, :class:`~django.db.models.CharField` with ``null=True`` now
679 saves ``NULL`` for blank values instead of empty strings.
680
681 * On Oracle, :meth:`Model.validate_unique()
682 <django.db.models.Model.validate_unique>` no longer checks empty strings for
683 uniqueness as the database interprets the value as ``NULL``.
684
685 * If you subclass :class:`.AbstractUser` and override ``clean()``, be sure it
686 calls ``super()``. :meth:`.BaseUserManager.normalize_email` is called in a
687 new :meth:`.AbstractUser.clean` method so that normalization is applied in
688 cases like model form validation.
689
690 * ``EmailField`` and ``URLField`` no longer accept the ``strip`` keyword
691 argument. Remove it because it doesn't have an effect in older versions of
692 Django as these fields always strip whitespace.
693
694 * The ``checked`` and ``selected`` attribute rendered by form widgets now uses
695 HTML5 boolean syntax rather than XHTML's ``checked='checked'`` and
696 ``selected='selected'``.
697
698 * :meth:`RelatedManager.add()
699 <django.db.models.fields.related.RelatedManager.add>`,
700 :meth:`~django.db.models.fields.related.RelatedManager.remove`,
701 :meth:`~django.db.models.fields.related.RelatedManager.clear`, and
702 :meth:`~django.db.models.fields.related.RelatedManager.set` now
703 clear the ``prefetch_related()`` cache.
704
705 * To prevent possible loss of saved settings,
706 :func:`~django.test.utils.setup_test_environment` now raises an exception if
707 called a second time before calling
708 :func:`~django.test.utils.teardown_test_environment`.
709
710 * The undocumented ``DateTimeAwareJSONEncoder`` alias for
711 :class:`~django.core.serializers.json.DjangoJSONEncoder` (renamed in Django
712 1.0) is removed.
713
714 * The :class:`cached template loader <django.template.loaders.cached.Loader>`
715 is now enabled if :setting:`OPTIONS['loaders'] <TEMPLATES-OPTIONS>` isn't
716 specified and :setting:`OPTIONS['debug'] <TEMPLATES-OPTIONS>` is ``False``
717 (the latter option defaults to the value of :setting:`DEBUG`). This could
718 be backwards-incompatible if you have some :ref:`template tags that aren't
719 thread safe <template_tag_thread_safety>`.
720
721 * The prompt for stale content type deletion no longer occurs after running the
722 ``migrate`` command. Use the new :djadmin:`remove_stale_contenttypes` command
723 instead.
724
725 * The admin's widget for ``IntegerField`` uses ``type="number"`` rather than
726 ``type="text"``.
727
728 * Conditional HTTP headers are now parsed and compared according to the
729 :rfc:`7232` Conditional Requests specification rather than the older
730 :rfc:`2616`.
731
732 * :func:`~django.utils.cache.patch_response_headers` no longer adds a
733 ``Last-Modified`` header. According to the :rfc:`7234#section-4.2.2`, this
734 header is useless alongside other caching headers that provide an explicit
735 expiration time, e.g. ``Expires`` or ``Cache-Control``.
736 :class:`~django.middleware.cache.UpdateCacheMiddleware` and
737 :func:`~django.utils.cache.add_never_cache_headers` call
738 ``patch_response_headers()`` and therefore are also affected by this change.
739
740 * In the admin templates, ``<p class="help">`` is replaced with a ``<div>`` tag
741 to allow including lists inside help text.
742
743 * :class:`~django.middleware.http.ConditionalGetMiddleware` no longer sets the
744 ``Date`` header as web servers set that header. It also no longer sets the
745 ``Content-Length`` header as this is now done by
746 :class:`~django.middleware.common.CommonMiddleware`.
747
748 If you have a middleware that modifies a response's content and appears
749 before ``CommonMiddleware`` in the ``MIDDLEWARE`` or ``MIDDLEWARE_CLASSES``
750 settings, you must reorder your middleware so that responses aren't modified
751 after ``Content-Length`` is set, or have the response modifying middleware
752 reset the ``Content-Length`` header.
753
754 * :meth:`~django.apps.AppConfig.get_model` and
755 :meth:`~django.apps.AppConfig.get_models` now raise
756 :exc:`~django.core.exceptions.AppRegistryNotReady` if they're called before
757 models of all applications have been loaded. Previously they only required
758 the target application's models to be loaded and thus could return models
759 without all their relations set up. If you need the old behavior of
760 ``get_model()``, set the ``require_ready`` argument to ``False``.
761
762 * The unused ``BaseCommand.can_import_settings`` attribute is removed.
763
764 * The undocumented ``django.utils.functional.lazy_property`` is removed.
765
766 * For consistency with non-multipart requests, ``MultiPartParser.parse()`` now
767 leaves ``request.POST`` immutable. If you're modifying that ``QueryDict``,
768 you must now first copy it, e.g. ``request.POST.copy()``.
769
770 * Support for ``cx_Oracle`` < 5.2 is removed.
771
772 * Support for IPython < 1.0 is removed from the ``shell`` command.
773
774 * The signature of private API ``Widget.build_attrs()`` changed from
775 ``extra_attrs=None, **kwargs`` to ``base_attrs, extra_attrs=None``.
776
777 * File-like objects (e.g., :class:`~io.StringIO` and :class:`~io.BytesIO`)
778 uploaded to an :class:`~django.db.models.ImageField` using the test client
779 now require a ``name`` attribute with a value that passes the
780 :data:`~django.core.validators.validate_image_file_extension` validator.
781 See the note in :meth:`.Client.post`.
782
783 * :class:`~django.db.models.FileField` now moves rather than copies the file
784 it receives. With the default file upload settings, files larger than
785 :setting:`FILE_UPLOAD_MAX_MEMORY_SIZE` now have the same permissions as
786 temporary files (often ``0o600``) rather than the system's standard umask
787 (often ``0o6644``). Set the :setting:`FILE_UPLOAD_PERMISSIONS` if you need
788 the same permission regardless of file size.
789
790 .. _deprecated-features-1.11:
791
792 Features deprecated in 1.11
793 ===========================
794
795 ``models.permalink()`` decorator
796 --------------------------------
797
798 Use :func:`django.urls.reverse` instead. For example::
799
800 from django.db import models
801
802
803 class MyModel(models.Model):
804 ...
805
806 @models.permalink
807 def url(self):
808 return ("guitarist_detail", [self.slug])
809
810 becomes::
811
812 from django.db import models
813 from django.urls import reverse
814
815
816 class MyModel(models.Model):
817 ...
818
819 def url(self):
820 return reverse("guitarist_detail", args=[self.slug])
821
822 Miscellaneous
823 -------------
824
825 * ``contrib.auth``’s ``login()`` and ``logout()`` function-based views are
826 deprecated in favor of new class-based views
827 :class:`~django.contrib.auth.views.LoginView` and
828 :class:`~django.contrib.auth.views.LogoutView`.
829
830 * The unused ``extra_context`` parameter of
831 ``contrib.auth.views.logout_then_login()`` is deprecated.
832
833 * ``contrib.auth``’s ``password_change()``, ``password_change_done()``,
834 ``password_reset()``, ``password_reset_done()``, ``password_reset_confirm()``,
835 and ``password_reset_complete()`` function-based views are deprecated in favor
836 of new class-based views
837 :class:`~django.contrib.auth.views.PasswordChangeView`,
838 :class:`~django.contrib.auth.views.PasswordChangeDoneView`,
839 :class:`~django.contrib.auth.views.PasswordResetView`,
840 :class:`~django.contrib.auth.views.PasswordResetDoneView`,
841 :class:`~django.contrib.auth.views.PasswordResetConfirmView`, and
842 :class:`~django.contrib.auth.views.PasswordResetCompleteView`.
843
844 * ``django.test.runner.setup_databases()`` is moved to
845 :func:`django.test.utils.setup_databases`. The old location is deprecated.
846
847 * ``django.utils.translation.string_concat()`` is deprecated in
848 favor of :func:`django.utils.text.format_lazy`. ``string_concat(*strings)``
849 can be replaced by ``format_lazy('{}' * len(strings), *strings)``.
850
851 * For the ``PyLibMCCache`` cache backend, passing ``pylibmc`` behavior settings
852 as top-level attributes of ``OPTIONS`` is deprecated. Set them under a
853 ``behaviors`` key within ``OPTIONS`` instead.
854
855 * The ``host`` parameter of ``django.utils.http.is_safe_url()`` is deprecated
856 in favor of the new ``allowed_hosts`` parameter.
857
858 * Silencing exceptions raised while rendering the
859 :ttag:`{% include %} <include>` template tag is deprecated as the behavior is
860 often more confusing than helpful. In Django 2.1, the exception will be
861 raised.
862
863 * ``DatabaseIntrospection.get_indexes()`` is deprecated in favor of
864 ``DatabaseIntrospection.get_constraints()``.
865
866 * :func:`~django.contrib.auth.authenticate` now passes a ``request`` argument
867 to the ``authenticate()`` method of authentication backends. Support for
868 methods that don't accept ``request`` as the first positional argument will
869 be removed in Django 2.1.
870
871 * The ``USE_ETAGS`` setting is deprecated in favor of
872 :class:`~django.middleware.http.ConditionalGetMiddleware` which now adds the
873 ``ETag`` header to responses regardless of the setting. ``CommonMiddleware``
874 and ``django.utils.cache.patch_response_headers()`` will no longer set ETags
875 when the deprecation ends.
876
877 * ``Model._meta.has_auto_field`` is deprecated in favor of checking if
878 ``Model._meta.auto_field is not None``.
879
880 * Using regular expression groups with ``iLmsu#`` in ``url()`` is deprecated.
881 The only group that's useful is ``(?i)`` for case-insensitive URLs, however,
882 case-insensitive URLs aren't a good practice because they create multiple
883 entries for search engines, for example. An alternative solution could be to
884 create a :data:`~django.conf.urls.handler404` that looks for uppercase
885 characters in the URL and redirects to a lowercase equivalent.
886
887 * The ``renderer`` argument is added to the :meth:`Widget.render()
888 <django.forms.Widget.render>` method. Methods that don't accept that argument
889 will work through a deprecation period.