Debian Codegraph @

docs/releases/2.1.txt

raw
1 ========================
2 Django 2.1 release notes
3 ========================
4
5 *August 1, 2018*
6
7 Welcome to Django 2.1!
8
9 These release notes cover the :ref:`new features <whats-new-2.1>`, as well as
10 some :ref:`backwards incompatible changes <backwards-incompatible-2.1>` you'll
11 want to be aware of when upgrading from Django 2.0 or earlier. We've
12 :ref:`dropped some features<removed-features-2.1>` that have reached the end of
13 their deprecation cycle, and we've :ref:`begun the deprecation process for some
14 features <deprecated-features-2.1>`.
15
16 See the :doc:`/howto/upgrade-version` guide if you're updating an existing
17 project.
18
19 Python compatibility
20 ====================
21
22 Django 2.1 supports Python 3.5, 3.6, and 3.7. Django 2.0 is the last version to
23 support Python 3.4. We **highly recommend** and only officially support the
24 latest release of each series.
25
26 .. _whats-new-2.1:
27
28 What's new in Django 2.1
29 ========================
30
31 Model "view" permission
32 -----------------------
33
34 A "view" permission is added to the model :attr:`Meta.default_permissions
35 <django.db.models.Options.default_permissions>`. The new permissions will be
36 created automatically when running :djadmin:`migrate`.
37
38 This allows giving users read-only access to models in the admin.
39 :meth:`.ModelAdmin.has_view_permission` is new. The implementation is backwards
40 compatible in that there isn't a need to assign the "view" permission to allow
41 users who have the "change" permission to edit objects.
42
43 There are a couple of :ref:`backwards incompatible considerations
44 <view_permission_backwards_incompatible>`.
45
46 Minor features
47 --------------
48
49 :mod:`django.contrib.admin`
50 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
51
52 * :attr:`.ModelAdmin.search_fields` now accepts any lookup such as
53 ``field__exact``.
54
55 * jQuery is upgraded from version 2.2.3 to 3.3.1.
56
57 * The new :meth:`.ModelAdmin.delete_queryset` method allows customizing the
58 deletion process of the "delete selected objects" action.
59
60 * You can now :ref:`override the default admin site
61 <overriding-default-admin-site>`.
62
63 * The new :attr:`.ModelAdmin.sortable_by` attribute and
64 :meth:`.ModelAdmin.get_sortable_by` method allow limiting the columns that
65 can be sorted in the change list page.
66
67 * The ``admin_order_field`` attribute for elements in
68 :attr:`.ModelAdmin.list_display` may now be a query expression.
69
70 * The new :meth:`.ModelAdmin.get_deleted_objects()` method allows customizing
71 the deletion process of the delete view and the "delete selected" action.
72
73 * The ``actions.html``, ``change_list_results.html``, ``date_hierarchy.html``,
74 ``pagination.html``, ``prepopulated_fields_js.html``, ``search_form.html``,
75 and ``submit_line.html`` templates can now be :ref:`overridden per app or
76 per model <admin-templates-overridden-per-app-or-model>` (besides overridden
77 globally).
78
79 * The admin change list and change form object tools can now be :ref:`overridden
80 per app, per model, or globally <admin-templates-overridden-per-app-or-model>`
81 with ``change_list_object_tools.html`` and
82 ``change_form_object_tools.html`` templates.
83
84 * :meth:`.InlineModelAdmin.has_add_permission` is now passed the parent object
85 as the second positional argument, ``obj``.
86
87 * Admin actions may now :ref:`specify permissions <admin-action-permissions>`
88 to limit their availability to certain users.
89
90 :mod:`django.contrib.auth`
91 ~~~~~~~~~~~~~~~~~~~~~~~~~~
92
93 * :djadmin:`createsuperuser` now gives a prompt to allow bypassing the
94 :setting:`AUTH_PASSWORD_VALIDATORS` checks.
95
96 :mod:`django.contrib.gis`
97 ~~~~~~~~~~~~~~~~~~~~~~~~~
98
99 * The new :meth:`.GEOSGeometry.buffer_with_style` method is a version of
100 :meth:`~.GEOSGeometry.buffer` that allows customizing the style of the
101 buffer.
102
103 * :class:`~django.contrib.gis.forms.widgets.OpenLayersWidget` is now based on
104 OpenLayers 4.6.5 (previously 3.20.1).
105
106 :mod:`django.contrib.sessions`
107 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
108
109 * Added the :setting:`SESSION_COOKIE_SAMESITE` setting to set the ``SameSite``
110 cookie flag on session cookies.
111
112 Cache
113 ~~~~~
114
115 * The :ref:`local-memory cache backend <local-memory-caching>` now uses a
116 least-recently-used (LRU) culling strategy rather than a pseudo-random one.
117
118 * The new :meth:`~django.core.cache.cache.touch` method of the :ref:`low-level
119 cache API <low-level-cache-api>` updates the timeout of cache keys.
120
121 CSRF
122 ~~~~
123
124 * Added the :setting:`CSRF_COOKIE_SAMESITE` setting to set the ``SameSite``
125 cookie flag on CSRF cookies.
126
127 Forms
128 ~~~~~
129
130 * The widget for ``ImageField`` now renders with the HTML attribute
131 ``accept="image/*"``.
132
133 Internationalization
134 ~~~~~~~~~~~~~~~~~~~~
135
136 * Added the :meth:`~django.utils.translation.get_supported_language_variant`
137 function.
138
139 * Untranslated strings for territorial language variants now use the
140 translations of the generic language. For example, untranslated ``pt_BR``
141 strings use ``pt`` translations.
142
143 Management Commands
144 ~~~~~~~~~~~~~~~~~~~
145
146 * The new :option:`inspectdb --include-views` option allows creating models
147 for database views.
148
149 * The :class:`~django.core.management.BaseCommand` class now uses a custom help
150 formatter so that the standard options like ``--verbosity`` or ``--settings``
151 appear last in the help output, giving a more prominent position to subclassed
152 command's options.
153
154 Migrations
155 ~~~~~~~~~~
156
157 * Added support for serialization of ``functools.partialmethod`` objects.
158
159 * To support frozen environments, migrations may be loaded from ``.pyc`` files.
160
161 Models
162 ~~~~~~
163
164 * Models can now use ``__init_subclass__()`` from :pep:`487`.
165
166 * A ``BinaryField`` may now be set to ``editable=True`` if you wish to include
167 it in model forms.
168
169 * A number of new text database functions are added:
170 :class:`~django.db.models.functions.Chr`,
171 :class:`~django.db.models.functions.Left`,
172 :class:`~django.db.models.functions.LPad`,
173 :class:`~django.db.models.functions.LTrim`,
174 :class:`~django.db.models.functions.Ord`,
175 :class:`~django.db.models.functions.Repeat`,
176 :class:`~django.db.models.functions.Replace`,
177 :class:`~django.db.models.functions.Right`,
178 :class:`~django.db.models.functions.RPad`,
179 :class:`~django.db.models.functions.RTrim`, and
180 :class:`~django.db.models.functions.Trim`.
181
182 * The new :class:`~django.db.models.functions.TruncWeek` function truncates
183 :class:`~django.db.models.DateField` and
184 :class:`~django.db.models.DateTimeField` to the Monday of a week.
185
186 * Query expressions can now be negated using a minus sign.
187
188 * :meth:`.QuerySet.order_by` and :meth:`distinct(*fields) <.QuerySet.distinct>`
189 now support using field transforms.
190
191 * :class:`~django.db.models.BooleanField` can now be ``null=True``. This is
192 encouraged instead of ``NullBooleanField``, which will likely be deprecated
193 in the future.
194
195 * The new :meth:`.QuerySet.explain` method displays the database's execution
196 plan of a queryset's query.
197
198 * :meth:`.QuerySet.raw` now supports :meth:`~.QuerySet.prefetch_related`.
199
200 Requests and Responses
201 ~~~~~~~~~~~~~~~~~~~~~~
202
203 * Added :meth:`.HttpRequest.get_full_path_info`.
204
205 * Added the ``samesite`` argument to :meth:`.HttpResponse.set_cookie` to allow
206 setting the ``SameSite`` cookie flag.
207
208 * The new ``as_attachment`` argument for :class:`~django.http.FileResponse`
209 sets the ``Content-Disposition`` header to make the browser ask if the user
210 wants to download the file. ``FileResponse`` also tries to set the
211 ``Content-Type`` and ``Content-Length`` headers where appropriate.
212
213 Templates
214 ~~~~~~~~~
215
216 * The new :tfilter:`json_script` filter safely outputs a Python object as JSON,
217 wrapped in a ``<script>`` tag, ready for use with JavaScript.
218
219 Tests
220 ~~~~~
221
222 * Added test :class:`~django.test.Client` support for 307 and 308 redirects.
223
224 * The test :class:`~django.test.Client` now serializes a request data
225 dictionary as JSON if ``content_type='application/json'``. You can customize
226 the JSON encoder with test client's ``json_encoder`` parameter.
227
228 * The new :meth:`.SimpleTestCase.assertWarnsMessage` method is a simpler
229 version of :meth:`~unittest.TestCase.assertWarnsRegex`.
230
231 .. _backwards-incompatible-2.1:
232
233 Backwards incompatible changes in 2.1
234 =====================================
235
236 Database backend API
237 --------------------
238
239 This section describes changes that may be needed in third-party database
240 backends.
241
242 * To adhere to :pep:`249`, exceptions where a database doesn't support a
243 feature are changed from :exc:`NotImplementedError` to
244 :exc:`django.db.NotSupportedError`.
245
246 * Renamed the ``allow_sliced_subqueries`` database feature flag to
247 ``allow_sliced_subqueries_with_in``.
248
249 * ``DatabaseOperations.distinct_sql()`` now requires an additional ``params``
250 argument and returns a tuple of SQL and parameters instead of an SQL string.
251
252 * ``DatabaseFeatures.introspected_boolean_field_type`` is changed from a method
253 to a property.
254
255 :mod:`django.contrib.gis`
256 -------------------------
257
258 * Support for SpatiaLite 4.0 is removed.
259
260 Dropped support for MySQL 5.5
261 -----------------------------
262
263 The end of upstream support for MySQL 5.5 is December 2018. Django 2.1 supports
264 MySQL 5.6 and higher.
265
266 Dropped support for PostgreSQL 9.3
267 ----------------------------------
268
269 The end of upstream support for PostgreSQL 9.3 is September 2018. Django 2.1
270 supports PostgreSQL 9.4 and higher.
271
272 Removed ``BCryptPasswordHasher`` from the default ``PASSWORD_HASHERS`` setting
273 ------------------------------------------------------------------------------
274
275 If you used bcrypt with Django 1.4 or 1.5 (before ``BCryptSHA256PasswordHasher``
276 was added in Django 1.6), you might have some passwords that use the
277 ``BCryptPasswordHasher`` hasher.
278
279 You can check if that's the case like this::
280
281 from django.contrib.auth import get_user_model
282
283 User = get_user_model()
284 User.objects.filter(password__startswith="bcrypt$$")
285
286 If you want to continue to allow those passwords to be used, you'll
287 have to define the :setting:`PASSWORD_HASHERS` setting (if you don't already)
288 and include ``'django.contrib.auth.hashers.BCryptPasswordHasher'``.
289
290 Moved ``wrap_label`` widget template context variable
291 -----------------------------------------------------
292
293 To fix the lack of ``<label>`` when using ``RadioSelect`` and
294 ``CheckboxSelectMultiple`` with ``MultiWidget``, the ``wrap_label`` context
295 variable now appears as an attribute of each option. For example, in a custom
296 ``input_option.html`` template, change ``{% if wrap_label %}`` to
297 ``{% if widget.wrap_label %}``.
298
299 ``SameSite`` cookies
300 --------------------
301
302 The cookies used for ``django.contrib.sessions``, ``django.contrib.messages``,
303 and Django's CSRF protection now set the ``SameSite`` flag to ``Lax`` by
304 default. Browsers that respect this flag won't send these cookies on
305 cross-origin requests. If you rely on the old behavior, set the
306 :setting:`SESSION_COOKIE_SAMESITE` and/or :setting:`CSRF_COOKIE_SAMESITE`
307 setting to ``None``.
308
309 .. _view_permission_backwards_incompatible:
310
311 Considerations for the new model "view" permission
312 --------------------------------------------------
313
314 Custom admin forms need to take the view-only case into account
315 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
316
317 With the new "view" permission, existing custom admin forms may raise errors
318 when a user doesn't have the change permission because the form might access
319 nonexistent fields. Fix this by overriding :meth:`.ModelAdmin.get_form` and
320 checking if the user has the "change" permissions and returning the default
321 form if not::
322
323 class MyAdmin(admin.ModelAdmin):
324 def get_form(self, request, obj=None, **kwargs):
325 if not self.has_change_permission(request, obj):
326 return super().get_form(request, obj, **kwargs)
327 return CustomForm
328
329 New default view permission could allow unwanted access to admin views
330 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
331
332 If you have a custom permission with a codename of the form
333 ``view_<modelname>``, the new view permission handling in the admin will allow
334 view access to the changelist and detail pages for those models. If this is
335 unwanted, you must change your custom permission codename.
336
337 Miscellaneous
338 -------------
339
340 * The minimum supported version of ``mysqlclient`` is increased from 1.3.3 to
341 1.3.7.
342
343 * Support for SQLite < 3.7.15 is removed.
344
345 * The date format of ``Set-Cookie``'s ``Expires`` directive is changed to
346 follow :rfc:`7231#section-7.1.1.1` instead of Netscape's cookie standard.
347 Hyphens present in dates like ``Tue, 25-Dec-2018 22:26:13 GMT`` are removed.
348 This change should be merely cosmetic except perhaps for antiquated browsers
349 that don't parse the new format.
350
351 * ``allowed_hosts`` is now a required argument of private API
352 ``django.utils.http.is_safe_url()``.
353
354 * The ``multiple`` attribute rendered by the
355 :class:`~django.forms.SelectMultiple` widget now uses HTML5 boolean syntax
356 rather than XHTML's ``multiple="multiple"``.
357
358 * HTML rendered by form widgets no longer includes a closing slash on void
359 elements, e.g. ``<br>``. This is incompatible within XHTML, although some
360 widgets already used aspects of HTML5 such as boolean attributes.
361
362 * The value of :class:`~django.forms.SelectDateWidget`'s empty options is
363 changed from 0 to an empty string, which mainly may require some adjustments
364 in tests that compare HTML.
365
366 * :meth:`.User.has_usable_password` and the
367 :func:`~django.contrib.auth.hashers.is_password_usable` function no longer
368 return ``False`` if the password is ``None`` or an empty string, or if the
369 password uses a hasher that's not in the :setting:`PASSWORD_HASHERS` setting.
370 This undocumented behavior was a regression in Django 1.6 and prevented users
371 with such passwords from requesting a password reset. Audit your code to
372 confirm that your usage of these APIs don't rely on the old behavior.
373
374 * Since migrations are now loaded from ``.pyc`` files, you might need to delete
375 them if you're working in a mixed Python 2 and Python 3 environment.
376
377 * Using ``None`` as a ``django.contrib.postgres.fields.JSONField`` lookup
378 value now matches objects that have the specified key and a null value rather
379 than objects that don't have the key.
380
381 * The admin CSS class ``field-box`` is renamed to ``fieldBox`` to prevent
382 conflicts with the class given to model fields named "box".
383
384 * Since the admin's ``actions.html``, ``change_list_results.html``,
385 ``date_hierarchy.html``, ``pagination.html``, ``prepopulated_fields_js.html``,
386 ``search_form.html``, and ``submit_line.html`` templates can now be
387 overridden per app or per model, you may need to rename existing templates
388 with those names that were written for a different purpose.
389
390 * ``QuerySet.raw()`` now caches its results like regular querysets. Use
391 ``iterator()`` if you don't want caching.
392
393 * The database router :meth:`allow_relation` method is called in more cases.
394 Improperly written routers may need to be updated accordingly.
395
396 * Translations are no longer deactivated before running management commands.
397 If your custom command requires translations to be deactivated (for example,
398 to insert untranslated content into the database), use the new
399 :ref:`@no_translations decorator <management-commands-and-locales>`.
400
401 * Management commands no longer allow the abbreviated forms of the
402 ``--settings`` and ``--pythonpath`` arguments.
403
404 * The private ``django.db.models.sql.constants.QUERY_TERMS`` constant is
405 removed. The :meth:`~.RegisterLookupMixin.get_lookup`
406 and :meth:`~.RegisterLookupMixin.get_lookups` methods
407 of the :ref:`Lookup Registration API <lookup-registration-api>` may be
408 suitable alternatives. Compared to the ``QUERY_TERMS`` constant, they allow
409 your code to also account for any custom lookups that have been registered.
410
411 * Compatibility with ``py-bcrypt`` is removed as it's unmaintained. Use
412 :pypi:`bcrypt` instead.
413
414 .. _deprecated-features-2.1:
415
416 Features deprecated in 2.1
417 ==========================
418
419 Miscellaneous
420 -------------
421
422 * The ``ForceRHR`` GIS function is deprecated in favor of the new
423 :class:`~django.contrib.gis.db.models.functions.ForcePolygonCW` function.
424
425 * ``django.utils.http.cookie_date()`` is deprecated in favor of
426 :func:`~django.utils.http.http_date`, which follows the format of the latest
427 RFC.
428
429 * ``{% load staticfiles %}`` and ``{% load admin_static %}`` are deprecated
430 in favor of ``{% load static %}``, which works the same.
431
432 * ``django.contrib.staticfiles.templatetags.static()`` is deprecated in favor
433 of ``django.templatetags.static.static()``.
434
435 * Support for :meth:`.InlineModelAdmin.has_add_permission` methods that don't
436 accept ``obj`` as the second positional argument will be removed in Django
437 3.0.
438
439 .. _removed-features-2.1:
440
441 Features removed in 2.1
442 =======================
443
444 These features have reached the end of their deprecation cycle and are removed
445 in Django 2.1. See :ref:`deprecated-features-1.11` for details, including how
446 to remove usage of these features.
447
448 * ``contrib.auth.views.login()``, ``logout()``, ``password_change()``,
449 ``password_change_done()``, ``password_reset()``, ``password_reset_done()``,
450 ``password_reset_confirm()``, and ``password_reset_complete()`` are removed.
451
452 * The ``extra_context`` parameter of ``contrib.auth.views.logout_then_login()``
453 is removed.
454
455 * ``django.test.runner.setup_databases()`` is removed.
456
457 * ``django.utils.translation.string_concat()`` is removed.
458
459 * ``django.core.cache.backends.memcached.PyLibMCCache`` no longer supports
460 passing ``pylibmc`` behavior settings as top-level attributes of ``OPTIONS``.
461
462 * The ``host`` parameter of ``django.utils.http.is_safe_url()`` is removed.
463
464 * Silencing of exceptions raised while rendering the ``{% include %}`` template
465 tag is removed.
466
467 * ``DatabaseIntrospection.get_indexes()`` is removed.
468
469 * The ``authenticate()`` method of authentication backends requires ``request``
470 as the first positional argument.
471
472 * The ``django.db.models.permalink()`` decorator is removed.
473
474 * The ``USE_ETAGS`` setting is removed. ``CommonMiddleware`` and
475 ``django.utils.cache.patch_response_headers()`` no longer set ETags.
476
477 * The ``Model._meta.has_auto_field`` attribute is removed.
478
479 * ``url()``'s support for inline flags in regular expression groups (``(?i)``,
480 ``(?L)``, ``(?m)``, ``(?s)``, and ``(?u)``) is removed.
481
482 * Support for ``Widget.render()`` methods without the ``renderer`` argument
483 is removed.