| 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. |