Debian Codegraph @

docs/releases/4.2.txt

raw
1 ========================
2 Django 4.2 release notes
3 ========================
4
5 *April 3, 2023*
6
7 Welcome to Django 4.2!
8
9 These release notes cover the :ref:`new features <whats-new-4.2>`, as well as
10 some :ref:`backwards incompatible changes <backwards-incompatible-4.2>` you'll
11 want to be aware of when upgrading from Django 4.1 or earlier. We've
12 :ref:`begun the deprecation process for some features
13 <deprecated-features-4.2>`.
14
15 See the :doc:`/howto/upgrade-version` guide if you're updating an existing
16 project.
17
18 Django 4.2 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 3.2, will
21 end in April 2024.
22
23 Python compatibility
24 ====================
25
26 Django 4.2 supports Python 3.8, 3.9, 3.10, 3.11, and 3.12 (as of 4.2.8). We
27 **highly recommend** and only officially support the latest release of each
28 series.
29
30 .. _whats-new-4.2:
31
32 What's new in Django 4.2
33 ========================
34
35 Psycopg 3 support
36 -----------------
37
38 Django now supports `psycopg`_ version 3.1.8 or higher. To update your code,
39 install the :pypi:`psycopg library <psycopg>`, you don't need to change the
40 :setting:`ENGINE <DATABASE-ENGINE>` as ``django.db.backends.postgresql``
41 supports both libraries.
42
43 Support for ``psycopg2`` is likely to be deprecated and removed at some point
44 in the future.
45
46 Be aware that ``psycopg`` 3 introduces some breaking changes over ``psycopg2``.
47 As a consequence, you may need to make some changes to account for
48 `differences from psycopg2`_.
49
50 .. _psycopg: https://www.psycopg.org/psycopg3/
51 .. _differences from psycopg2: https://www.psycopg.org/psycopg3/docs/basic/from_pg2.html
52
53 Comments on columns and tables
54 ------------------------------
55
56 The new :attr:`Field.db_comment <django.db.models.Field.db_comment>` and
57 :attr:`Meta.db_table_comment <django.db.models.Options.db_table_comment>`
58 options allow creating comments on columns and tables, respectively. For
59 example::
60
61 from django.db import models
62
63
64 class Question(models.Model):
65 text = models.TextField(db_comment="Poll question")
66 pub_date = models.DateTimeField(
67 db_comment="Date and time when the question was published",
68 )
69
70 class Meta:
71 db_table_comment = "Poll questions"
72
73
74 class Answer(models.Model):
75 question = models.ForeignKey(
76 Question,
77 on_delete=models.CASCADE,
78 db_comment="Reference to a question",
79 )
80 answer = models.TextField(db_comment="Question answer")
81
82 class Meta:
83 db_table_comment = "Question answers"
84
85 Also, the new :class:`~django.db.migrations.operations.AlterModelTableComment`
86 operation allows changing table comments defined in the
87 :attr:`Meta.db_table_comment <django.db.models.Options.db_table_comment>`.
88
89 Mitigation for the BREACH attack
90 --------------------------------
91
92 :class:`~django.middleware.gzip.GZipMiddleware` now includes a mitigation for
93 the BREACH attack. It will add up to 100 random bytes to gzip responses to make
94 BREACH attacks harder. Read more about the mitigation technique in the `Heal
95 The Breach (HTB) paper`_.
96
97 .. _Heal The Breach (HTB) paper: https://ieeexplore.ieee.org/document/9754554
98
99 In-memory file storage
100 ----------------------
101
102 The new :class:`django.core.files.storage.InMemoryStorage` class provides a
103 non-persistent storage useful for speeding up tests by avoiding disk access.
104
105 Custom file storages
106 --------------------
107
108 The new :setting:`STORAGES` setting allows configuring multiple custom file
109 storage backends. It also controls storage engines for managing
110 :doc:`files </topics/files>` (the ``"default"`` key) and :doc:`static files
111 </ref/contrib/staticfiles>` (the ``"staticfiles"`` key).
112
113 The old ``DEFAULT_FILE_STORAGE`` and ``STATICFILES_STORAGE`` settings are
114 deprecated as of this release.
115
116 Minor features
117 --------------
118
119 :mod:`django.contrib.admin`
120 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
121
122 * The light or dark color theme of the admin can now be toggled in the UI, as
123 well as being set to follow the system setting.
124
125 * The admin's font stack now prefers system UI fonts and no longer requires
126 downloading fonts. Additionally, CSS variables are available to more easily
127 override the default font families.
128
129 * The :source:`admin/delete_confirmation.html
130 <django/contrib/admin/templates/admin/delete_confirmation.html>` template now
131 has some additional blocks and scripting hooks to ease customization.
132
133 * The chosen options of
134 :attr:`~django.contrib.admin.ModelAdmin.filter_horizontal` and
135 :attr:`~django.contrib.admin.ModelAdmin.filter_vertical` widgets are now
136 filterable.
137
138 * The ``admin/base.html`` template now has a new block ``nav-breadcrumbs``
139 which contains the navigation landmark and the ``breadcrumbs`` block.
140
141 * :attr:`.ModelAdmin.list_editable` now uses atomic transactions when making
142 edits.
143
144 * jQuery is upgraded from version 3.6.0 to 3.6.4.
145
146 :mod:`django.contrib.auth`
147 ~~~~~~~~~~~~~~~~~~~~~~~~~~
148
149 * The default iteration count for the PBKDF2 password hasher is increased from
150 390,000 to 600,000.
151
152 * :class:`~django.contrib.auth.forms.UserCreationForm` now saves many-to-many
153 form fields for a custom user model.
154
155 * The new :class:`~django.contrib.auth.forms.BaseUserCreationForm` is now the
156 recommended base class for customizing the user creation form.
157
158 :mod:`django.contrib.gis`
159 ~~~~~~~~~~~~~~~~~~~~~~~~~
160
161 * The :doc:`GeoJSON serializer </ref/contrib/gis/serializers>` now outputs the
162 ``id`` key for serialized features, which defaults to the primary key of
163 objects.
164
165 * The :class:`~django.contrib.gis.gdal.GDALRaster` class now supports
166 :class:`pathlib.Path`.
167
168 * The :class:`~django.contrib.gis.geoip2.GeoIP2` class now supports ``.mmdb``
169 files downloaded from DB-IP.
170
171 * The OpenLayers template widget no longer includes inline CSS (which also
172 removes the former ``map_css`` block) to better comply with a strict Content
173 Security Policy.
174
175 * :class:`~django.contrib.gis.forms.widgets.OpenLayersWidget` is now based on
176 OpenLayers 7.2.2 (previously 4.6.5).
177
178 * The new :lookup:`isempty` lookup and
179 :class:`IsEmpty() <django.contrib.gis.db.models.functions.IsEmpty>`
180 expression allow filtering empty geometries on PostGIS.
181
182 * The new :class:`FromWKB() <django.contrib.gis.db.models.functions.FromWKB>`
183 and :class:`FromWKT() <django.contrib.gis.db.models.functions.FromWKT>`
184 functions allow creating geometries from Well-known binary (WKB) and
185 Well-known text (WKT) representations.
186
187 :mod:`django.contrib.postgres`
188 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
189
190 * The new :lookup:`trigram_strict_word_similar` lookup, and the
191 :class:`TrigramStrictWordSimilarity()
192 <django.contrib.postgres.search.TrigramStrictWordSimilarity>` and
193 :class:`TrigramStrictWordDistance()
194 <django.contrib.postgres.search.TrigramStrictWordDistance>` expressions allow
195 using trigram strict word similarity.
196
197 * The :lookup:`arrayfield.overlap` lookup now supports ``QuerySet.values()``
198 and ``values_list()`` as a right-hand side.
199
200 :mod:`django.contrib.sitemaps`
201 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
202
203 * The new :meth:`.Sitemap.get_languages_for_item` method allows customizing the
204 list of languages for which the item is displayed.
205
206 :mod:`django.contrib.staticfiles`
207 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
208
209 * :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage` now
210 has experimental support for replacing paths to JavaScript modules in
211 ``import`` and ``export`` statements with their hashed counterparts. If you
212 want to try it, subclass ``ManifestStaticFilesStorage`` and set the
213 ``support_js_module_import_aggregation`` attribute to ``True``.
214
215 * The new :attr:`.ManifestStaticFilesStorage.manifest_hash` attribute provides
216 a hash over all files in the manifest and changes whenever one of the files
217 changes.
218
219 Database backends
220 ~~~~~~~~~~~~~~~~~
221
222 * The new ``"assume_role"`` option is now supported in :setting:`OPTIONS` on
223 PostgreSQL to allow specifying the :ref:`session role <database-role>`.
224
225 * The new ``"server_side_binding"`` option is now supported in
226 :setting:`OPTIONS` on PostgreSQL with ``psycopg`` 3.1.8+ to allow using
227 :ref:`server-side binding cursors <database-server-side-parameters-binding>`.
228
229 Error Reporting
230 ~~~~~~~~~~~~~~~
231
232 * The debug page now shows :pep:`exception notes <678>` and
233 :pep:`fine-grained error locations <657>` on Python 3.11+.
234
235 * Session cookies are now treated as credentials and therefore hidden and
236 replaced with stars (``**********``) in error reports.
237
238 Forms
239 ~~~~~
240
241 * :class:`~django.forms.ModelForm` now accepts the new ``Meta`` option
242 ``formfield_callback`` to customize form fields.
243
244 * :func:`~django.forms.models.modelform_factory` now respects the
245 ``formfield_callback`` attribute of the ``form``’s ``Meta``.
246
247 Internationalization
248 ~~~~~~~~~~~~~~~~~~~~
249
250 * Added support and translations for the Central Kurdish (Sorani) language.
251
252 Logging
253 ~~~~~~~
254
255 * The :ref:`django-db-logger` logger now logs transaction management queries
256 (``BEGIN``, ``COMMIT``, and ``ROLLBACK``) at the ``DEBUG`` level.
257
258 Management Commands
259 ~~~~~~~~~~~~~~~~~~~
260
261 * :djadmin:`makemessages` command now supports locales with private sub-tags
262 such as ``nl_NL-x-informal``.
263
264 * The new :option:`makemigrations --update` option merges model changes into
265 the latest migration and optimizes the resulting operations.
266
267 Migrations
268 ~~~~~~~~~~
269
270 * Migrations now support serialization of ``enum.Flag`` objects.
271
272 Models
273 ~~~~~~
274
275 * ``QuerySet`` now extensively supports filtering against
276 :ref:`window-functions` with the exception of disjunctive filter lookups
277 against window functions when performing aggregation.
278
279 * :meth:`~.QuerySet.prefetch_related` now supports
280 :class:`~django.db.models.Prefetch` objects with sliced querysets.
281
282 * :ref:`Registering lookups <lookup-registration-api>` on
283 :class:`~django.db.models.Field` instances is now supported.
284
285 * The new ``robust`` argument for :func:`~django.db.transaction.on_commit`
286 allows performing actions that can fail after a database transaction is
287 successfully committed.
288
289 * The new :class:`KT() <django.db.models.fields.json.KT>` expression represents
290 the text value of a key, index, or path transform of
291 :class:`~django.db.models.JSONField`.
292
293 * :class:`~django.db.models.functions.Now` now supports microsecond precision
294 on MySQL and millisecond precision on SQLite.
295
296 * :class:`F() <django.db.models.F>` expressions that output ``BooleanField``
297 can now be negated using ``~F()`` (inversion operator).
298
299 * ``Model`` now provides asynchronous versions of some methods that use the
300 database, using an ``a`` prefix: :meth:`~.Model.adelete`,
301 :meth:`~.Model.arefresh_from_db`, and :meth:`~.Model.asave`.
302
303 * Related managers now provide asynchronous versions of methods that change a
304 set of related objects, using an ``a`` prefix: :meth:`~.RelatedManager.aadd`,
305 :meth:`~.RelatedManager.aclear`, :meth:`~.RelatedManager.aremove`, and
306 :meth:`~.RelatedManager.aset`.
307
308 * :attr:`CharField.max_length <django.db.models.CharField.max_length>` is no
309 longer required to be set on PostgreSQL, which supports unlimited ``VARCHAR``
310 columns.
311
312 Requests and Responses
313 ~~~~~~~~~~~~~~~~~~~~~~
314
315 * :class:`~django.http.StreamingHttpResponse` now supports async iterators
316 when Django is served via ASGI.
317
318 Tests
319 ~~~~~
320
321 * The :option:`test --debug-sql` option now formats SQL queries with
322 ``sqlparse``.
323
324 * The :class:`~django.test.RequestFactory`,
325 :class:`~django.test.AsyncRequestFactory`, :class:`~django.test.Client`, and
326 :class:`~django.test.AsyncClient` classes now support the ``headers``
327 parameter, which accepts a dictionary of header names and values. This allows
328 a more natural syntax for declaring headers.
329
330 .. code-block:: python
331
332 # Before:
333 self.client.get("/home/", HTTP_ACCEPT_LANGUAGE="fr")
334 await self.async_client.get("/home/", ACCEPT_LANGUAGE="fr")
335
336 # After:
337 self.client.get("/home/", headers={"accept-language": "fr"})
338 await self.async_client.get("/home/", headers={"accept-language": "fr"})
339
340 Utilities
341 ~~~~~~~~~
342
343 * The new ``encoder`` parameter for :meth:`django.utils.html.json_script`
344 function allows customizing a JSON encoder class.
345
346 * The private internal vendored copy of ``urllib.parse.urlsplit()`` now strips
347 ``'\r'``, ``'\n'``, and ``'\t'`` (see :cve:`2022-0391` and :bpo:`43882`).
348 This is to protect projects that may be incorrectly using the internal
349 ``url_has_allowed_host_and_scheme()`` function, instead of using one of the
350 documented functions for handling URL redirects. The Django functions were
351 not affected.
352
353 * The new :func:`django.utils.http.content_disposition_header` function returns
354 a ``Content-Disposition`` HTTP header value as specified by :rfc:`6266`.
355
356 Validators
357 ~~~~~~~~~~
358
359 * The list of common passwords used by ``CommonPasswordValidator`` is updated
360 to the most recent version.
361
362 .. _backwards-incompatible-4.2:
363
364 Backwards incompatible changes in 4.2
365 =====================================
366
367 Database backend API
368 --------------------
369
370 This section describes changes that may be needed in third-party database
371 backends.
372
373 * ``DatabaseFeatures.allows_group_by_pk`` is removed as it only remained to
374 accommodate a MySQL extension that has been supplanted by proper functional
375 dependency detection in MySQL 5.7.15. Note that
376 ``DatabaseFeatures.allows_group_by_selected_pks`` is still supported and
377 should be enabled if your backend supports functional dependency detection in
378 ``GROUP BY`` clauses as specified by the ``SQL:1999`` standard.
379
380 * :djadmin:`inspectdb` now uses ``display_size`` from
381 ``DatabaseIntrospection.get_table_description()`` rather than
382 ``internal_size`` for ``CharField``.
383
384 Dropped support for MariaDB 10.3
385 --------------------------------
386
387 Upstream support for MariaDB 10.3 ends in May 2023. Django 4.2 supports MariaDB
388 10.4 and higher.
389
390 Dropped support for MySQL 5.7
391 -----------------------------
392
393 Upstream support for MySQL 5.7 ends in October 2023. Django 4.2 supports MySQL
394 8 and higher.
395
396 Dropped support for PostgreSQL 11
397 ---------------------------------
398
399 Upstream support for PostgreSQL 11 ends in November 2023. Django 4.2 supports
400 PostgreSQL 12 and higher.
401
402 Setting ``update_fields`` in ``Model.save()`` may now be required
403 -----------------------------------------------------------------
404
405 In order to avoid updating unnecessary columns,
406 :meth:`.QuerySet.update_or_create` now passes ``update_fields`` to the
407 :meth:`Model.save() <django.db.models.Model.save>` calls. As a consequence, any
408 fields modified in the custom ``save()`` methods should be added to the
409 ``update_fields`` keyword argument before calling ``super()``. See
410 :ref:`overriding-model-methods` for more details.
411
412 Dropped support for raw aggregations on MySQL
413 ---------------------------------------------
414
415 MySQL 8+ allows functional dependencies on ``GROUP BY`` columns, so the
416 pre-Django 4.2 workaround of grouping by primary keys of the main table is
417 removed. As a consequence, using ``RawSQL()`` aggregations is no longer
418 supported on MySQL as there is no way to determine if such aggregations are
419 needed or valid in the ``GROUP BY`` clause. Use :ref:`aggregation-functions`
420 instead.
421
422 Miscellaneous
423 -------------
424
425 * The undocumented ``django.http.multipartparser.parse_header()`` function is
426 removed. Use ``django.utils.http.parse_header_parameters()`` instead.
427
428 * :ttag:`{% blocktranslate asvar … %}<blocktranslate>` result is now marked as
429 safe for (HTML) output purposes.
430
431 * The ``autofocus`` HTML attribute in the admin search box is removed as it can
432 be confusing for screen readers.
433
434 * The :option:`makemigrations --check` option no longer creates missing
435 migration files.
436
437 * The ``alias`` argument for :meth:`.Expression.get_group_by_cols` is removed.
438
439 * The minimum supported version of ``sqlparse`` is increased from 0.2.2 to
440 0.3.1.
441
442 * The undocumented ``negated`` parameter of the
443 :class:`~django.db.models.Exists` expression is removed.
444
445 * The ``is_summary`` argument of the undocumented ``Query.add_annotation()``
446 method is removed.
447
448 * The minimum supported version of SQLite is increased from 3.9.0 to 3.21.0.
449
450 * The minimum supported version of ``asgiref`` is increased from 3.5.2 to
451 3.6.0.
452
453 * :class:`~django.contrib.auth.forms.UserCreationForm` now rejects usernames
454 that differ only in case. If you need the previous behavior, use
455 :class:`~django.contrib.auth.forms.BaseUserCreationForm` instead.
456
457 * The minimum supported version of ``mysqlclient`` is increased from 1.4.0 to
458 1.4.3.
459
460 * The minimum supported version of ``argon2-cffi`` is increased from 19.1.0 to
461 19.2.0.
462
463 * The minimum supported version of ``Pillow`` is increased from 6.2.0 to 6.2.1.
464
465 * The minimum supported version of ``jinja2`` is increased from 2.9.2 to
466 2.11.0.
467
468 * The minimum supported version of :pypi:`redis-py <redis>` is increased from
469 3.0.0 to 3.4.0.
470
471 * Manually instantiated ``WSGIRequest`` objects must be provided a file-like
472 object for ``wsgi.input``. Previously, Django was more lax than the expected
473 behavior as specified by the WSGI specification.
474
475 * Support for ``PROJ`` < 5 is removed.
476
477 * :class:`~django.core.mail.backends.smtp.EmailBackend` now verifies a
478 :py:attr:`hostname <ssl.SSLContext.check_hostname>` and
479 :py:attr:`certificates <ssl.SSLContext.verify_mode>`. If you need the
480 previous behavior that is less restrictive and not recommended, subclass
481 ``EmailBackend`` and override the ``ssl_context`` property.
482
483 .. _deprecated-features-4.2:
484
485 Features deprecated in 4.2
486 ==========================
487
488 ``index_together`` option is deprecated in favor of ``indexes``
489 ---------------------------------------------------------------
490
491 The ``Meta.index_together`` option is deprecated in favor of the
492 :attr:`~django.db.models.Options.indexes` option.
493
494 Migrating existing ``index_together`` should be handled as a migration. For
495 example::
496
497 class Author(models.Model):
498 rank = models.IntegerField()
499 name = models.CharField(max_length=30)
500
501 class Meta:
502 index_together = [["rank", "name"]]
503
504 Should become::
505
506 class Author(models.Model):
507 rank = models.IntegerField()
508 name = models.CharField(max_length=30)
509
510 class Meta:
511 indexes = [models.Index(fields=["rank", "name"])]
512
513 Running the :djadmin:`makemigrations` command will generate a migration
514 containing a :class:`~django.db.migrations.operations.RenameIndex` operation
515 which will rename the existing index. Next, consider squashing migrations to
516 remove ``index_together`` from historical migrations.
517
518 The ``AlterIndexTogether`` migration operation is now officially supported only
519 for pre-Django 4.2 migration files. For backward compatibility reasons, it's
520 still part of the public API, and there's no plan to deprecate or remove it,
521 but it should not be used for new migrations. Use
522 :class:`~django.db.migrations.operations.AddIndex` and
523 :class:`~django.db.migrations.operations.RemoveIndex` operations instead.
524
525 Passing encoded JSON string literals to ``JSONField`` is deprecated
526 -------------------------------------------------------------------
527
528 ``JSONField`` and its associated lookups and aggregates used to allow passing
529 JSON encoded string literals which caused ambiguity on whether string literals
530 were already encoded from database backend's perspective.
531
532 During the deprecation period string literals will be attempted to be JSON
533 decoded and a warning will be emitted on success that points at passing
534 non-encoded forms instead.
535
536 Code that used to pass JSON encoded string literals::
537
538 Document.objects.bulk_create(
539 Document(data=Value("null")),
540 Document(data=Value("[]")),
541 Document(data=Value('"foo-bar"')),
542 )
543 Document.objects.annotate(
544 JSONBAgg("field", default=Value("[]")),
545 )
546
547 Should become::
548
549 Document.objects.bulk_create(
550 Document(data=Value(None, JSONField())),
551 Document(data=[]),
552 Document(data="foo-bar"),
553 )
554 Document.objects.annotate(
555 JSONBAgg("field", default=[]),
556 )
557
558 From Django 5.1+ string literals will be implicitly interpreted as JSON string
559 literals.
560
561 Miscellaneous
562 -------------
563
564 * The ``BaseUserManager.make_random_password()`` method is deprecated. See
565 `recipes and best practices
566 <https://docs.python.org/3/library/secrets.html#recipes-and-best-practices>`_
567 for using Python's :py:mod:`secrets` module to generate passwords.
568
569 * The ``length_is`` template filter is deprecated in favor of :tfilter:`length`
570 and the ``==`` operator within an :ttag:`{% if %}<if>` tag. For example
571
572 .. code-block:: html+django
573
574 {% if value|length == 4 %}…{% endif %}
575 {% if value|length == 4 %}True{% else %}False{% endif %}
576
577 instead of:
578
579 .. code-block:: html+django
580
581 {% if value|length_is:4 %}…{% endif %}
582 {{ value|length_is:4 }}
583
584 * ``django.contrib.auth.hashers.SHA1PasswordHasher``,
585 ``django.contrib.auth.hashers.UnsaltedSHA1PasswordHasher``, and
586 ``django.contrib.auth.hashers.UnsaltedMD5PasswordHasher`` are deprecated.
587
588 * ``django.contrib.postgres.fields.CICharField`` is deprecated in favor of
589 ``CharField(db_collation="…")`` with a case-insensitive non-deterministic
590 collation.
591
592 * ``django.contrib.postgres.fields.CIEmailField`` is deprecated in favor of
593 ``EmailField(db_collation="…")`` with a case-insensitive non-deterministic
594 collation.
595
596 * ``django.contrib.postgres.fields.CITextField`` is deprecated in favor of
597 ``TextField(db_collation="…")`` with a case-insensitive non-deterministic
598 collation.
599
600 * ``django.contrib.postgres.fields.CIText`` mixin is deprecated.
601
602 * The ``map_height`` and ``map_width`` attributes of ``BaseGeometryWidget`` are
603 deprecated, use CSS to size map widgets instead.
604
605 * ``SimpleTestCase.assertFormsetError()`` is deprecated in favor of
606 ``assertFormSetError()``.
607
608 * ``TransactionTestCase.assertQuerysetEqual()`` is deprecated in favor of
609 ``assertQuerySetEqual()``.
610
611 * Passing positional arguments to ``Signer`` and ``TimestampSigner`` is
612 deprecated in favor of keyword-only arguments.
613
614 * The ``DEFAULT_FILE_STORAGE`` setting is deprecated in favor of
615 ``STORAGES["default"]``.
616
617 * The ``STATICFILES_STORAGE`` setting is deprecated in favor of
618 ``STORAGES["staticfiles"]``.
619
620 * The ``django.core.files.storage.get_storage_class()`` function is deprecated.