Debian Codegraph @

docs/releases/4.0.txt

raw
1 ========================
2 Django 4.0 release notes
3 ========================
4
5 *December 7, 2021*
6
7 Welcome to Django 4.0!
8
9 These release notes cover the :ref:`new features <whats-new-4.0>`, as well as
10 some :ref:`backwards incompatible changes <backwards-incompatible-4.0>` you'll
11 want to be aware of when upgrading from Django 3.2 or earlier. We've
12 :ref:`begun the deprecation process for some features
13 <deprecated-features-4.0>`.
14
15 See the :doc:`/howto/upgrade-version` guide if you're updating an existing
16 project.
17
18 Python compatibility
19 ====================
20
21 Django 4.0 supports Python 3.8, 3.9, and 3.10. We **highly recommend** and only
22 officially support the latest release of each series.
23
24 The Django 3.2.x series is the last to support Python 3.6 and 3.7.
25
26 .. _whats-new-4.0:
27
28 What's new in Django 4.0
29 ========================
30
31 ``zoneinfo`` default timezone implementation
32 --------------------------------------------
33
34 The Python standard library's :mod:`zoneinfo` is now the default timezone
35 implementation in Django.
36
37 This is the next step in the migration from using ``pytz`` to using
38 :mod:`zoneinfo`. Django 3.2 allowed the use of non-``pytz`` time zones. Django
39 4.0 makes ``zoneinfo`` the default implementation. Support for ``pytz`` is now
40 deprecated and will be removed in Django 5.0.
41
42 :mod:`zoneinfo` is part of the Python standard library from Python 3.9. The
43 ``backports.zoneinfo`` package is automatically installed alongside Django if
44 you are using Python 3.8.
45
46 The move to ``zoneinfo`` should be largely transparent. Selection of the
47 current timezone, conversion of datetime instances to the current timezone in
48 forms and templates, as well as operations on aware datetimes in UTC are
49 unaffected.
50
51 However, if you are working with non-UTC time zones, and using the ``pytz``
52 ``normalize()`` and ``localize()`` APIs, possibly with the :setting:`TIME_ZONE
53 <DATABASE-TIME_ZONE>` setting, you will need to audit your code, since ``pytz``
54 and ``zoneinfo`` are not entirely equivalent.
55
56 To give time for such an audit, the transitional ``USE_DEPRECATED_PYTZ``
57 setting allows continued use of ``pytz`` during the 4.x release cycle. This
58 setting will be removed in Django 5.0.
59
60 In addition, a `pytz_deprecation_shim`_ package, created by the ``zoneinfo``
61 author, can be used to assist with the migration from ``pytz``. This package
62 provides shims to help you safely remove ``pytz``, and has a detailed
63 `migration guide`_ showing how to move to the new ``zoneinfo`` APIs.
64
65 Using `pytz_deprecation_shim`_ and the ``USE_DEPRECATED_PYTZ``
66 transitional setting is recommended if you need a gradual update path.
67
68 .. _pytz_deprecation_shim: https://pytz-deprecation-shim.readthedocs.io/en/latest/index.html
69 .. _migration guide: https://pytz-deprecation-shim.readthedocs.io/en/latest/migration.html
70
71 Functional unique constraints
72 -----------------------------
73
74 The new :attr:`*expressions <django.db.models.UniqueConstraint.expressions>`
75 positional argument of
76 :class:`UniqueConstraint() <django.db.models.UniqueConstraint>` enables
77 creating functional unique constraints on expressions and database functions.
78 For example::
79
80 from django.db import models
81 from django.db.models import UniqueConstraint
82 from django.db.models.functions import Lower
83
84
85 class MyModel(models.Model):
86 first_name = models.CharField(max_length=255)
87 last_name = models.CharField(max_length=255)
88
89 class Meta:
90 constraints = [
91 UniqueConstraint(
92 Lower("first_name"),
93 Lower("last_name").desc(),
94 name="first_last_name_unique",
95 ),
96 ]
97
98 Functional unique constraints are added to models using the
99 :attr:`Meta.constraints <django.db.models.Options.constraints>` option.
100
101 ``scrypt`` password hasher
102 --------------------------
103
104 The new :ref:`scrypt password hasher <scrypt-usage>` is more secure and
105 recommended over PBKDF2. However, it's not the default as it requires OpenSSL
106 1.1+ and more memory.
107
108 Redis cache backend
109 -------------------
110
111 The new ``django.core.cache.backends.redis.RedisCache`` cache backend provides
112 built-in support for caching with Redis. :pypi:`redis-py <redis>` 3.0.0 or
113 higher is required. For more details, see the :ref:`documentation on caching
114 with Redis in Django <redis>`.
115
116 Template based form rendering
117 -----------------------------
118
119 :class:`Forms <django.forms.Form>`, :doc:`Formsets </topics/forms/formsets>`,
120 and :class:`~django.forms.ErrorList` are now rendered using the template engine
121 to enhance customization. See the new :meth:`~django.forms.Form.render`,
122 :meth:`~django.forms.Form.get_context`, and
123 :attr:`~django.forms.Form.template_name` for ``Form`` and
124 :ref:`formset rendering <formset-rendering>` for ``Formset``.
125
126 Minor features
127 --------------
128
129 :mod:`django.contrib.admin`
130 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
131
132 * The ``admin/base.html`` template now has a new block ``header`` which
133 contains the admin site header.
134
135 * The new :meth:`.ModelAdmin.get_formset_kwargs` method allows customizing the
136 keyword arguments passed to the constructor of a formset.
137
138 * The navigation sidebar now has a quick filter toolbar.
139
140 * The new context variable ``model`` which contains the model class for each
141 model is added to the :meth:`.AdminSite.each_context` method.
142
143 * The new :attr:`.ModelAdmin.search_help_text` attribute allows specifying a
144 descriptive text for the search box.
145
146 * The :attr:`.InlineModelAdmin.verbose_name_plural` attribute now fallbacks to
147 the :attr:`.InlineModelAdmin.verbose_name` + ``'s'``.
148
149 * jQuery is upgraded from version 3.5.1 to 3.6.0.
150
151 :mod:`django.contrib.admindocs`
152 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
153
154 * The admindocs now allows esoteric setups where :setting:`ROOT_URLCONF` is not
155 a string.
156
157 * The model section of the ``admindocs`` now shows cached properties.
158
159 :mod:`django.contrib.auth`
160 ~~~~~~~~~~~~~~~~~~~~~~~~~~
161
162 * The default iteration count for the PBKDF2 password hasher is increased from
163 260,000 to 320,000.
164
165 * The new
166 :attr:`LoginView.next_page <django.contrib.auth.views.LoginView.next_page>`
167 attribute and
168 :meth:`~django.contrib.auth.views.LoginView.get_default_redirect_url` method
169 allow customizing the redirect after login.
170
171 :mod:`django.contrib.gis`
172 ~~~~~~~~~~~~~~~~~~~~~~~~~
173
174 * Added support for SpatiaLite 5.
175
176 * :class:`~django.contrib.gis.gdal.GDALRaster` now allows creating rasters in
177 any GDAL virtual filesystem.
178
179 * The new :class:`~django.contrib.gis.admin.GISModelAdmin` class allows
180 customizing the widget used for ``GeometryField``. This is encouraged instead
181 of deprecated ``GeoModelAdmin`` and ``OSMGeoAdmin``.
182
183 :mod:`django.contrib.postgres`
184 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
185
186 * The PostgreSQL backend now supports connecting by a service name. See
187 :ref:`postgresql-connection-settings` for more details.
188
189 * The new :class:`~django.contrib.postgres.operations.AddConstraintNotValid`
190 operation allows creating check constraints on PostgreSQL without verifying
191 that all existing rows satisfy the new constraint.
192
193 * The new :class:`~django.contrib.postgres.operations.ValidateConstraint`
194 operation allows validating check constraints which were created using
195 :class:`~django.contrib.postgres.operations.AddConstraintNotValid` on
196 PostgreSQL.
197
198 * The new
199 :class:`ArraySubquery() <django.contrib.postgres.expressions.ArraySubquery>`
200 expression allows using subqueries to construct lists of values on
201 PostgreSQL.
202
203 * The new :lookup:`trigram_word_similar` lookup, and the
204 :class:`TrigramWordDistance()
205 <django.contrib.postgres.search.TrigramWordDistance>` and
206 :class:`TrigramWordSimilarity()
207 <django.contrib.postgres.search.TrigramWordSimilarity>` expressions allow
208 using trigram word similarity.
209
210 :mod:`django.contrib.staticfiles`
211 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
212
213 * :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage` now
214 replaces paths to JavaScript source map references with their hashed
215 counterparts.
216
217 * The new ``manifest_storage`` argument of
218 :class:`~django.contrib.staticfiles.storage.ManifestFilesMixin` and
219 :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage`
220 allows customizing the manifest file storage.
221
222 Cache
223 ~~~~~
224
225 * The new async API for ``django.core.cache.backends.base.BaseCache`` begins
226 the process of making cache backends async-compatible. The new async methods
227 all have ``a`` prefixed names, e.g. ``aadd()``, ``aget()``, ``aset()``,
228 ``aget_or_set()``, or ``adelete_many()``.
229
230 Going forward, the ``a`` prefix will be used for async variants of methods
231 generally.
232
233 CSRF
234 ~~~~
235
236 * CSRF protection now consults the ``Origin`` header, if present. To facilitate
237 this, :ref:`some changes <csrf-trusted-origins-changes-4.0>` to the
238 :setting:`CSRF_TRUSTED_ORIGINS` setting are required.
239
240 Forms
241 ~~~~~
242
243 * :class:`~django.forms.ModelChoiceField` now includes the provided value in
244 the ``params`` argument of a raised
245 :exc:`~django.core.exceptions.ValidationError` for the ``invalid_choice``
246 error message. This allows custom error messages to use the ``%(value)s``
247 placeholder.
248
249 * :class:`~django.forms.formsets.BaseFormSet` now renders non-form errors with
250 an additional class of ``nonform`` to help distinguish them from
251 form-specific errors.
252
253 * :class:`~django.forms.formsets.BaseFormSet` now allows customizing the widget
254 used when deleting forms via
255 :attr:`~django.forms.formsets.BaseFormSet.can_delete` by setting the
256 :attr:`~django.forms.formsets.BaseFormSet.deletion_widget` attribute or
257 overriding :meth:`~django.forms.formsets.BaseFormSet.get_deletion_widget`
258 method.
259
260 Internationalization
261 ~~~~~~~~~~~~~~~~~~~~
262
263 * Added support and translations for the Malay language.
264
265 Generic Views
266 ~~~~~~~~~~~~~
267
268 * :class:`~django.views.generic.edit.DeleteView` now uses
269 :class:`~django.views.generic.edit.FormMixin`, allowing you to provide a
270 :class:`~django.forms.Form` subclass, with a checkbox for example, to confirm
271 deletion. In addition, this allows ``DeleteView`` to function with
272 :class:`django.contrib.messages.views.SuccessMessageMixin`.
273
274 In accordance with ``FormMixin``, object deletion for POST requests is
275 handled in ``form_valid()``. Custom delete logic in ``delete()`` handlers
276 should be moved to ``form_valid()``, or a shared helper method, as needed.
277
278 Logging
279 ~~~~~~~
280
281 * The alias of the database used in an SQL call is now passed as extra context
282 along with each message to the :ref:`django-db-logger` logger.
283
284 Management Commands
285 ~~~~~~~~~~~~~~~~~~~
286
287 * The :djadmin:`runserver` management command now supports the
288 :option:`--skip-checks` option.
289
290 * On PostgreSQL, :djadmin:`dbshell` now supports specifying a password file.
291
292 * The :djadmin:`shell` command now respects :py:data:`sys.__interactivehook__`
293 at startup. This allows loading shell history between interactive sessions.
294 As a consequence, ``readline`` is no longer loaded if running in *isolated*
295 mode.
296
297 * The new :attr:`BaseCommand.suppressed_base_arguments
298 <django.core.management.BaseCommand.suppressed_base_arguments>` attribute
299 allows suppressing unsupported default command options in the help output.
300
301 * The new :option:`startapp --exclude` and :option:`startproject --exclude`
302 options allow excluding directories from the template.
303
304 Models
305 ~~~~~~
306
307 * New :meth:`QuerySet.contains(obj) <.QuerySet.contains>` method returns
308 whether the queryset contains the given object. This tries to perform the
309 query in the simplest and fastest way possible.
310
311 * The new ``precision`` argument of the
312 :class:`Round() <django.db.models.functions.Round>` database function allows
313 specifying the number of decimal places after rounding.
314
315 * :meth:`.QuerySet.bulk_create` now sets the primary key on objects when using
316 SQLite 3.35+.
317
318 * :class:`~django.db.models.DurationField` now supports multiplying and
319 dividing by scalar values on SQLite.
320
321 * :meth:`.QuerySet.bulk_update` now returns the number of objects updated.
322
323 * The new :attr:`.Expression.empty_result_set_value` attribute allows
324 specifying a value to return when the function is used over an empty result
325 set.
326
327 * The ``skip_locked`` argument of :meth:`.QuerySet.select_for_update()` is now
328 allowed on MariaDB 10.6+.
329
330 * :class:`~django.db.models.Lookup` expressions may now be used in ``QuerySet``
331 annotations, aggregations, and directly in filters.
332
333 * The new :ref:`default <aggregate-default>` argument for built-in aggregates
334 allows specifying a value to be returned when the queryset (or grouping)
335 contains no entries, rather than ``None``.
336
337 Requests and Responses
338 ~~~~~~~~~~~~~~~~~~~~~~
339
340 * The :class:`~django.middleware.security.SecurityMiddleware` now adds the
341 :ref:`Cross-Origin Opener Policy <cross-origin-opener-policy>` header with a
342 value of ``'same-origin'`` to prevent cross-origin popups from sharing the
343 same browsing context. You can prevent this header from being added by
344 setting the :setting:`SECURE_CROSS_ORIGIN_OPENER_POLICY` setting to ``None``.
345
346 Signals
347 ~~~~~~~
348
349 * The new ``stdout`` argument for :func:`~django.db.models.signals.pre_migrate`
350 and :func:`~django.db.models.signals.post_migrate` signals allows redirecting
351 output to a stream-like object. It should be preferred over
352 :py:data:`sys.stdout` and :py:func:`print` when emitting verbose output in
353 order to allow proper capture when testing.
354
355 Templates
356 ~~~~~~~~~
357
358 * :tfilter:`floatformat` template filter now allows using the ``u`` suffix to
359 force disabling localization.
360
361 Tests
362 ~~~~~
363
364 * The new ``serialized_aliases`` argument of
365 :func:`django.test.utils.setup_databases` determines which
366 :setting:`DATABASES` aliases test databases should have their state
367 serialized to allow usage of the
368 :ref:`serialized_rollback <test-case-serialized-rollback>` feature.
369
370 * The :option:`test --buffer` option now supports parallel tests.
371
372 * The new ``logger`` argument to :class:`~django.test.runner.DiscoverRunner`
373 allows a Python :py:ref:`logger <logger>` to be used for logging.
374
375 * The new :meth:`.DiscoverRunner.log` method provides a way to log messages
376 that uses the ``DiscoverRunner.logger``, or prints to the console if not set.
377
378 * :class:`~django.test.runner.DiscoverRunner` can now execute tests in a random
379 order using the :option:`test --shuffle` option.
380
381 * The :option:`test --parallel` option now supports the value ``auto`` to run
382 one test process for each processor core.
383
384 * :meth:`.TestCase.captureOnCommitCallbacks` now captures new callbacks added
385 while executing :func:`.transaction.on_commit` callbacks.
386
387 .. _backwards-incompatible-4.0:
388
389 Backwards incompatible changes in 4.0
390 =====================================
391
392 Database backend API
393 --------------------
394
395 This section describes changes that may be needed in third-party database
396 backends.
397
398 * ``DatabaseOperations.year_lookup_bounds_for_date_field()`` and
399 ``year_lookup_bounds_for_datetime_field()`` methods now take the optional
400 ``iso_year`` argument in order to support bounds for ISO-8601 week-numbering
401 years.
402
403 * The second argument of ``DatabaseSchemaEditor._unique_sql()`` and
404 ``_create_unique_sql()`` methods is now ``fields`` instead of ``columns``.
405
406 :mod:`django.contrib.gis`
407 -------------------------
408
409 * Support for PostGIS 2.3 is removed.
410
411 * Support for GDAL 2.0 and GEOS 3.5 is removed.
412
413 Dropped support for PostgreSQL 9.6
414 ----------------------------------
415
416 Upstream support for PostgreSQL 9.6 ends in November 2021. Django 4.0 supports
417 PostgreSQL 10 and higher.
418
419 Also, the minimum supported version of ``psycopg2`` is increased from 2.5.4 to
420 2.8.4, as ``psycopg2`` 2.8.4 is the first release to support Python 3.8.
421
422 Dropped support for Oracle 12.2 and 18c
423 ---------------------------------------
424
425 Upstream support for Oracle 12.2 ends in March 2022 and for Oracle 18c it ends
426 in June 2021. Django 3.2 will be supported until April 2024. Django 4.0
427 officially supports Oracle 19c.
428
429 .. _csrf-trusted-origins-changes-4.0:
430
431 ``CSRF_TRUSTED_ORIGINS`` changes
432 --------------------------------
433
434 Format change
435 ~~~~~~~~~~~~~
436
437 Values in the :setting:`CSRF_TRUSTED_ORIGINS` setting must include the scheme
438 (e.g. ``'http://'`` or ``'https://'``) instead of only the hostname.
439
440 Also, values that started with a dot, must now also include an asterisk before
441 the dot. For example, change ``'.example.com'`` to ``'https://*.example.com'``.
442
443 A system check detects any required changes.
444
445 Configuring it may now be required
446 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
447
448 As CSRF protection now consults the ``Origin`` header, you may need to set
449 :setting:`CSRF_TRUSTED_ORIGINS`, particularly if you allow requests from
450 subdomains by setting :setting:`CSRF_COOKIE_DOMAIN` (or
451 :setting:`SESSION_COOKIE_DOMAIN` if :setting:`CSRF_USE_SESSIONS` is enabled) to
452 a value starting with a dot.
453
454 ``SecurityMiddleware`` no longer sets the ``X-XSS-Protection`` header
455 ---------------------------------------------------------------------
456
457 The :class:`~django.middleware.security.SecurityMiddleware` no longer sets the
458 ``X-XSS-Protection`` header if the ``SECURE_BROWSER_XSS_FILTER`` setting is
459 ``True``. The setting is removed.
460
461 Most modern browsers don't honor the ``X-XSS-Protection`` HTTP header. You can
462 use Content-Security-Policy_ without allowing ``'unsafe-inline'`` scripts
463 instead.
464
465 If you want to support legacy browsers and set the header, use this line in a
466 custom middleware::
467
468 response.headers.setdefault("X-XSS-Protection", "1; mode=block")
469
470 .. _Content-Security-Policy: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy
471
472 Migrations autodetector changes
473 -------------------------------
474
475 The migrations autodetector now uses model states instead of model classes.
476 Also, migration operations for ``ForeignKey`` and ``ManyToManyField`` fields no
477 longer specify attributes which were not passed to the fields during
478 initialization.
479
480 As a side-effect, running ``makemigrations`` might generate no-op
481 ``AlterField`` operations for ``ManyToManyField`` and ``ForeignKey`` fields in
482 some cases.
483
484 ``DeleteView`` changes
485 ----------------------
486
487 :class:`~django.views.generic.edit.DeleteView` now uses
488 :class:`~django.views.generic.edit.FormMixin` to handle POST requests. As a
489 consequence, any custom deletion logic in ``delete()`` handlers should be
490 moved to ``form_valid()``, or a shared helper method, if required.
491
492 Table and column naming scheme changes on Oracle
493 ------------------------------------------------
494
495 Django 4.0 inadvertently changed the table and column naming scheme on Oracle.
496 This causes errors for models and fields with names longer than 30 characters.
497 Unfortunately, renaming some Oracle tables and columns is required. Use the
498 upgrade script in :ticket:`33789 <33789#comment:15>` to generate ``RENAME``
499 statements to change naming scheme.
500
501 Miscellaneous
502 -------------
503
504 * Support for ``cx_Oracle`` < 7.0 is removed.
505
506 * To allow serving a Django site on a subpath without changing the value of
507 :setting:`STATIC_URL`, the leading slash is removed from that setting (now
508 ``'static/'``) in the default :djadmin:`startproject` template.
509
510 * The :class:`~django.contrib.admin.AdminSite` method for the admin ``index``
511 view is no longer decorated with ``never_cache`` when accessed directly,
512 rather than via the recommended ``AdminSite.urls`` property, or
513 ``AdminSite.get_urls()`` method.
514
515 * Unsupported operations on a sliced queryset now raise ``TypeError`` instead
516 of ``AssertionError``.
517
518 * The undocumented ``django.test.runner.reorder_suite()`` function is renamed
519 to ``reorder_tests()``. It now accepts an iterable of tests rather than a
520 test suite, and returns an iterator of tests.
521
522 * Calling ``FileSystemStorage.delete()`` with an empty ``name`` now raises
523 ``ValueError`` instead of ``AssertionError``.
524
525 * Calling ``EmailMultiAlternatives.attach_alternative()`` or
526 ``EmailMessage.attach()`` with an invalid ``content`` or ``mimetype``
527 arguments now raise ``ValueError`` instead of ``AssertionError``.
528
529 * :meth:`~django.test.SimpleTestCase.assertHTMLEqual` no longer considers a
530 non-boolean attribute without a value equal to an attribute with the same
531 name and value.
532
533 * Tests that fail to load, for example due to syntax errors, now always match
534 when using :option:`test --tag`.
535
536 * The undocumented ``django.contrib.admin.utils.lookup_needs_distinct()``
537 function is renamed to ``lookup_spawns_duplicates()``.
538
539 * The undocumented ``HttpRequest.get_raw_uri()`` method is removed. The
540 :meth:`.HttpRequest.build_absolute_uri` method may be a suitable alternative.
541
542 * The ``object`` argument of undocumented ``ModelAdmin.log_addition()``,
543 ``log_change()``, and ``log_deletion()`` methods is renamed to ``obj``.
544
545 * :class:`~django.utils.feedgenerator.RssFeed`,
546 :class:`~django.utils.feedgenerator.Atom1Feed`, and their subclasses now emit
547 elements with no content as self-closing tags.
548
549 * ``NodeList.render()`` no longer casts the output of ``render()`` method for
550 individual nodes to a string. ``Node.render()`` should always return a string
551 as documented.
552
553 * The ``where_class`` property of ``django.db.models.sql.query.Query`` and the
554 ``where_class`` argument to the private ``get_extra_restriction()`` method of
555 ``ForeignObject`` and ``ForeignObjectRel`` are removed. If needed, initialize
556 ``django.db.models.sql.where.WhereNode`` instead.
557
558 * The ``filter_clause`` argument of the undocumented ``Query.add_filter()``
559 method is replaced by two positional arguments ``filter_lhs`` and
560 ``filter_rhs``.
561
562 * :class:`~django.middleware.csrf.CsrfViewMiddleware` now uses
563 ``request.META['CSRF_COOKIE_NEEDS_UPDATE']`` in place of
564 ``request.META['CSRF_COOKIE_USED']``, ``request.csrf_cookie_needs_reset``,
565 and ``response.csrf_cookie_set`` to track whether the CSRF cookie should be
566 sent. This is an undocumented, private API.
567
568 * The undocumented ``TRANSLATOR_COMMENT_MARK`` constant is moved from
569 ``django.template.base`` to ``django.utils.translation.template``.
570
571 * The ``real_apps`` argument of the undocumented
572 ``django.db.migrations.state.ProjectState.__init__()`` method must now be a
573 set if provided.
574
575 * :class:`~django.forms.RadioSelect` and
576 :class:`~django.forms.CheckboxSelectMultiple` widgets are now rendered in
577 ``<div>`` tags so they are announced more concisely by screen readers. If you
578 need the previous behavior, :ref:`override the widget template
579 <overriding-built-in-widget-templates>` with the appropriate template from
580 Django 3.2.
581
582 * The :tfilter:`floatformat` template filter no longer depends on the
583 ``USE_L10N`` setting and always returns localized output. Use the ``u``
584 suffix to disable localization.
585
586 * The default value of the ``USE_L10N`` setting is changed to ``True``. See the
587 :ref:`Localization section <use_l10n_deprecation>` above for more details.
588
589 * As part of the :ref:`move to zoneinfo <whats-new-4.0>`,
590 ``django.utils.timezone.utc`` is changed to alias
591 :attr:`datetime.timezone.utc`.
592
593 * The minimum supported version of ``asgiref`` is increased from 3.3.2 to
594 3.4.1.
595
596 .. _deprecated-features-4.0:
597
598 Features deprecated in 4.0
599 ==========================
600
601 Use of ``pytz`` time zones
602 --------------------------
603
604 As part of the :ref:`move to zoneinfo <whats-new-4.0>`, use of ``pytz`` time
605 zones is deprecated.
606
607 Accordingly, the ``is_dst`` arguments to the following are also deprecated:
608
609 * :meth:`django.db.models.query.QuerySet.datetimes`
610 * :func:`django.db.models.functions.Trunc`
611 * :func:`django.db.models.functions.TruncSecond`
612 * :func:`django.db.models.functions.TruncMinute`
613 * :func:`django.db.models.functions.TruncHour`
614 * :func:`django.db.models.functions.TruncDay`
615 * :func:`django.db.models.functions.TruncWeek`
616 * :func:`django.db.models.functions.TruncMonth`
617 * :func:`django.db.models.functions.TruncQuarter`
618 * :func:`django.db.models.functions.TruncYear`
619 * :func:`django.utils.timezone.make_aware`
620
621 Support for use of ``pytz`` will be removed in Django 5.0.
622
623 Time zone support
624 -----------------
625
626 In order to follow good practice, the default value of the :setting:`USE_TZ`
627 setting will change from ``False`` to ``True``, and time zone support will be
628 enabled by default, in Django 5.0.
629
630 Note that the default :file:`settings.py` file created by
631 :djadmin:`django-admin startproject <startproject>` includes
632 :setting:`USE_TZ = True <USE_TZ>` since Django 1.4.
633
634 You can set ``USE_TZ`` to ``False`` in your project settings before then to
635 opt-out.
636
637 .. _use_l10n_deprecation:
638
639 Localization
640 ------------
641
642 In order to follow good practice, the default value of the ``USE_L10N`` setting
643 is changed from ``False`` to ``True``.
644
645 Moreover ``USE_L10N`` is deprecated as of this release. Starting with Django
646 5.0, by default, any date or number displayed by Django will be localized.
647
648 The :ttag:`{% localize %} <localize>` tag and the :tfilter:`localize`/
649 :tfilter:`unlocalize` filters will still be honored by Django.
650
651 Miscellaneous
652 -------------
653
654 * ``SERIALIZE`` test setting is deprecated as it can be inferred from the
655 :attr:`~django.test.TestCase.databases` with the
656 :ref:`serialized_rollback <test-case-serialized-rollback>` option enabled.
657
658 * The undocumented ``django.utils.baseconv`` module is deprecated.
659
660 * The undocumented ``django.utils.datetime_safe`` module is deprecated.
661
662 * The default sitemap protocol for sitemaps built outside the context of a
663 request will change from ``'http'`` to ``'https'`` in Django 5.0.
664
665 * The ``extra_tests`` argument for :meth:`.DiscoverRunner.build_suite` and
666 :meth:`.DiscoverRunner.run_tests` is deprecated.
667
668 * The :class:`~django.contrib.postgres.aggregates.ArrayAgg`,
669 :class:`~django.contrib.postgres.aggregates.JSONBAgg`, and
670 :class:`~django.contrib.postgres.aggregates.StringAgg` aggregates will return
671 ``None`` when there are no rows instead of ``[]``, ``[]``, and ``''``
672 respectively in Django 5.0. If you need the previous behavior, explicitly set
673 ``default`` to ``Value([])``, ``Value('[]')``, or ``Value('')``.
674
675 * The ``django.contrib.gis.admin.GeoModelAdmin`` and ``OSMGeoAdmin`` classes
676 are deprecated. Use :class:`~django.contrib.admin.ModelAdmin` and
677 :class:`~django.contrib.gis.admin.GISModelAdmin` instead.
678
679 * Since form rendering now uses the template engine, the undocumented
680 ``BaseForm._html_output()`` helper method is deprecated.
681
682 * The ability to return a ``str`` from ``ErrorList`` and ``ErrorDict`` is
683 deprecated. It is expected these methods return a ``SafeString``.
684
685 Features removed in 4.0
686 =======================
687
688 These features have reached the end of their deprecation cycle and are removed
689 in Django 4.0.
690
691 See :ref:`deprecated-features-3.0` for details on these changes, including how
692 to remove usage of these features.
693
694 * ``django.utils.http.urlquote()``, ``urlquote_plus()``, ``urlunquote()``, and
695 ``urlunquote_plus()`` are removed.
696
697 * ``django.utils.encoding.force_text()`` and ``smart_text()`` are removed.
698
699 * ``django.utils.translation.ugettext()``, ``ugettext_lazy()``,
700 ``ugettext_noop()``, ``ungettext()``, and ``ungettext_lazy()`` are removed.
701
702 * ``django.views.i18n.set_language()`` doesn't set the user language in
703 ``request.session`` (key ``_language``).
704
705 * ``alias=None`` is required in the signature of
706 ``django.db.models.Expression.get_group_by_cols()`` subclasses.
707
708 * ``django.utils.text.unescape_entities()`` is removed.
709
710 * ``django.utils.http.is_safe_url()`` is removed.
711
712 See :ref:`deprecated-features-3.1` for details on these changes, including how
713 to remove usage of these features.
714
715 * The ``PASSWORD_RESET_TIMEOUT_DAYS`` setting is removed.
716
717 * The :lookup:`isnull` lookup no longer allows using non-boolean values as the
718 right-hand side.
719
720 * The ``django.db.models.query_utils.InvalidQuery`` exception class is removed.
721
722 * The ``django-admin.py`` entry point is removed.
723
724 * The ``HttpRequest.is_ajax()`` method is removed.
725
726 * Support for the pre-Django 3.1 encoding format of cookies values used by
727 ``django.contrib.messages.storage.cookie.CookieStorage`` is removed.
728
729 * Support for the pre-Django 3.1 password reset tokens in the admin site (that
730 use the SHA-1 hashing algorithm) is removed.
731
732 * Support for the pre-Django 3.1 encoding format of sessions is removed.
733
734 * Support for the pre-Django 3.1 ``django.core.signing.Signer`` signatures
735 (encoded with the SHA-1 algorithm) is removed.
736
737 * Support for the pre-Django 3.1 ``django.core.signing.dumps()`` signatures
738 (encoded with the SHA-1 algorithm) in ``django.core.signing.loads()`` is
739 removed.
740
741 * Support for the pre-Django 3.1 user sessions (that use the SHA-1 algorithm)
742 is removed.
743
744 * The ``get_response`` argument for
745 ``django.utils.deprecation.MiddlewareMixin.__init__()`` is required and
746 doesn't accept ``None``.
747
748 * The ``providing_args`` argument for ``django.dispatch.Signal`` is removed.
749
750 * The ``length`` argument for ``django.utils.crypto.get_random_string()`` is
751 required.
752
753 * The ``list`` message for ``ModelMultipleChoiceField`` is removed.
754
755 * Support for passing raw column aliases to ``QuerySet.order_by()`` is removed.
756
757 * The ``NullBooleanField`` model field is removed, except for support in
758 historical migrations.
759
760 * ``django.conf.urls.url()`` is removed.
761
762 * The ``django.contrib.postgres.fields.JSONField`` model field is removed,
763 except for support in historical migrations.
764
765 * ``django.contrib.postgres.fields.jsonb.KeyTransform`` and
766 ``django.contrib.postgres.fields.jsonb.KeyTextTransform`` are removed.
767
768 * ``django.contrib.postgres.forms.JSONField`` is removed.
769
770 * The ``{% ifequal %}`` and ``{% ifnotequal %}`` template tags are removed.
771
772 * The ``DEFAULT_HASHING_ALGORITHM`` transitional setting is removed.