Changelog
### 4.1
```
========================
*August 3, 2022*
Welcome to Django 4.1!
These release notes cover the :ref:`new features <whats-new-4.1>`, as well as
some :ref:`backwards incompatible changes <backwards-incompatible-4.1>` you'll
want to be aware of when upgrading from Django 4.0 or earlier. We've
:ref:`begun the deprecation process for some features
<deprecated-features-4.1>`.
See the :doc:`/howto/upgrade-version` guide if you're updating an existing
project.
Python compatibility
====================
Django 4.1 supports Python 3.8, 3.9, and 3.10. We **highly recommend** and only
officially support the latest release of each series.
.. _whats-new-4.1:
What's new in Django 4.1
========================
Asynchronous handlers for class-based views
-------------------------------------------
View subclasses may now define async HTTP method handlers::
import asyncio
from django.http import HttpResponse
from django.views import View
class AsyncView(View):
async def get(self, request, *args, **kwargs):
Perform view logic using await.
await asyncio.sleep(1)
return HttpResponse("Hello async world!")
See :ref:`async-class-based-views` for more details.
Asynchronous ORM interface
--------------------------
``QuerySet`` now provides an asynchronous interface for all data access
operations. These are named as-per the existing synchronous operations but with
an ``a`` prefix, for example ``acreate()``, ``aget()``, and so on.
The new interface allows you to write asynchronous code without needing to wrap
ORM operations in ``sync_to_async()``::
async for author in Author.objects.filter(name__startswith="A"):
book = await author.books.afirst()
Note that, at this stage, the underlying database operations remain
synchronous, with contributions ongoing to push asynchronous support down into
the SQL compiler, and integrate asynchronous database drivers. The new
asynchronous queryset interface currently encapsulates the necessary
``sync_to_async()`` operations for you, and will allow your code to take
advantage of developments in the ORM's asynchronous support as it evolves.
See :ref:`async-queries` for details and limitations.
Validation of Constraints
-------------------------
:class:`Check <django.db.models.CheckConstraint>`,
:class:`unique <django.db.models.UniqueConstraint>`, and :class:`exclusion
<django.contrib.postgres.constraints.ExclusionConstraint>` constraints defined
in the :attr:`Meta.constraints <django.db.models.Options.constraints>` option
are now checked during :ref:`model validation <validating-objects>`.
Form rendering accessibility
----------------------------
In order to aid users with screen readers, and other assistive technology, new
``<div>`` based form templates are available from this release. These provide
more accessible navigation than the older templates, and are able to correctly
group related controls, such as radio-lists, into fieldsets.
The new templates are recommended, and will become the default form rendering
style when outputting a form, like ``{{ form }}`` in a template, from Django
5.0.
In order to ease adopting the new output style, the default form and formset
templates are now configurable at the project level via the
:setting:`FORM_RENDERER` setting.
See :ref:`the Forms section (below)<forms-4.1>` for full details.
.. _csrf-cookie-masked-usage:
``CSRF_COOKIE_MASKED`` setting
------------------------------
The new :setting:`CSRF_COOKIE_MASKED` transitional setting allows specifying
whether to mask the CSRF cookie.
:class:`~django.middleware.csrf.CsrfViewMiddleware` no longer masks the CSRF
cookie like it does the CSRF token in the DOM. If you are upgrading multiple
instances of the same project to Django 4.1, you should set
:setting:`CSRF_COOKIE_MASKED` to ``True`` during the transition, in
order to allow compatibility with the older versions of Django. Once the
transition to 4.1 is complete you can stop overriding
:setting:`CSRF_COOKIE_MASKED`.
This setting is deprecated as of this release and will be removed in Django
5.0.
Minor features
--------------
:mod:`django.contrib.admin`
~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The admin :ref:`dark mode CSS variables <admin-theming>` are now applied in a
separate stylesheet and template block.
* :ref:`modeladmin-list-filters` providing custom ``FieldListFilter``
subclasses can now control the query string value separator when filtering
for multiple values using the ``__in`` lookup.
* The admin :meth:`history view <django.contrib.admin.ModelAdmin.history_view>`
is now paginated.
* Related widget wrappers now have a link to object's change form.
* The :meth:`.AdminSite.get_app_list` method now allows changing the order of
apps and models on the admin index page.
:mod:`django.contrib.auth`
~~~~~~~~~~~~~~~~~~~~~~~~~~
* The default iteration count for the PBKDF2 password hasher is increased from
320,000 to 390,000.
* The :meth:`.RemoteUserBackend.configure_user` method now allows synchronizing
user attributes with attributes in a remote system such as an LDAP directory.
:mod:`django.contrib.gis`
~~~~~~~~~~~~~~~~~~~~~~~~~
* The new :meth:`.GEOSGeometry.make_valid()` method allows converting invalid
geometries to valid ones.
* The new ``clone`` argument for :meth:`.GEOSGeometry.normalize` allows
creating a normalized clone of the geometry.
:mod:`django.contrib.postgres`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The new :class:`BitXor() <django.contrib.postgres.aggregates.BitXor>`
aggregate function returns an ``int`` of the bitwise ``XOR`` of all non-null
input values.
* :class:`~django.contrib.postgres.indexes.SpGistIndex` now supports covering
indexes on PostgreSQL 14+.
* :class:`~django.contrib.postgres.constraints.ExclusionConstraint` now
supports covering exclusion constraints using SP-GiST indexes on PostgreSQL
14+.
* The new ``default_bounds`` attribute of :attr:`DateTimeRangeField
<django.contrib.postgres.fields.DateTimeRangeField.default_bounds>` and
:attr:`DecimalRangeField
<django.contrib.postgres.fields.DecimalRangeField.default_bounds>` allows
specifying bounds for list and tuple inputs.
* :class:`~django.contrib.postgres.constraints.ExclusionConstraint` now allows
specifying operator classes with the
:class:`OpClass() <django.contrib.postgres.indexes.OpClass>` expression.
:mod:`django.contrib.sitemaps`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The default sitemap index template ``<sitemapindex>`` now includes the
``<lastmod>`` timestamp where available, through the new
:meth:`~django.contrib.sitemaps.Sitemap.get_latest_lastmod` method. Custom
sitemap index templates should be updated for the adjusted :ref:`context
variables <sitemap-index-context-variables>`.
:mod:`django.contrib.staticfiles`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage` now
replaces paths to CSS source map references with their hashed counterparts.
Database backends
~~~~~~~~~~~~~~~~~
* Third-party database backends can now specify the minimum required version of
the database using the ``DatabaseFeatures.minimum_database_version``
attribute which is a tuple (e.g. ``(10, 0)`` means "10.0"). If a minimum
version is specified, backends must also implement
``DatabaseWrapper.get_database_version()``, which returns a tuple of the
current database version. The backend's
``DatabaseWrapper.init_connection_state()`` method must call ``super()`` in
order for the check to run.
.. _forms-4.1:
Forms
~~~~~
* The default template used to render forms when cast to a string, e.g. in
templates as ``{{ form }}``, is now configurable at the project-level by
setting :attr:`~django.forms.renderers.BaseRenderer.form_template_name` on
the class provided for :setting:`FORM_RENDERER`.
:attr:`.Form.template_name` is now a property deferring to the renderer, but
may be overridden with a string value to specify the template name per-form
class.
Similarly, the default template used to render formsets can be specified via
the matching
:attr:`~django.forms.renderers.BaseRenderer.formset_template_name` renderer
attribute.
* The new ``div.html`` form template, referencing
:attr:`.Form.template_name_div` attribute, and matching :meth:`.Form.as_div`
method, render forms using HTML ``<div>`` elements.
This new output style is recommended over the existing
:meth:`~.Form.as_table`, :meth:`~.Form.as_p` and :meth:`~.Form.as_ul` styles,
as the template implements ``<fieldset>`` and ``<legend>`` to group related
inputs and is easier for screen reader users to navigate.
The div-based output will become the default rendering style from Django 5.0.
* In order to smooth adoption of the new ``<div>`` output style, two
transitional form renderer classes are available:
:class:`django.forms.renderers.DjangoDivFormRenderer` and
:class:`django.forms.renderers.Jinja2DivFormRenderer`, for the Django and
Jinja2 template backends respectively.
You can apply one of these via the :setting:`FORM_RENDERER` setting. For
example::
FORM_RENDERER = "django.forms.renderers.DjangoDivFormRenderer"
Once the ``<div>`` output style is the default, from Django 5.0, these
transitional renderers will be deprecated, for removal in Django 6.0. The
``FORM_RENDERER`` declaration can be removed at that time.
* If the new ``<div>`` output style is not appropriate for your project, you should
define a renderer subclass specifying
:attr:`~django.forms.renderers.BaseRenderer.form_template_name` and
:attr:`~django.forms.renderers.BaseRenderer.formset_template_name` for your
required style, and set :setting:`FORM_RENDERER` accordingly.
For example, for the ``<p>`` output style used by :meth:`~.Form.as_p`, you
would define a form renderer setting ``form_template_name`` to
``"django/forms/p.html"`` and ``formset_template_name`` to
``"django/forms/formsets/p.html"``.
* The new :meth:`~django.forms.BoundField.legend_tag` allows rendering field
labels in ``<legend>`` tags via the new ``tag`` argument of
:meth:`~django.forms.BoundField.label_tag`.
* The new ``edit_only`` argument for :func:`.modelformset_factory` and
:func:`.inlineformset_factory` allows preventing new objects creation.
* The ``js`` and ``css`` class attributes of :doc:`Media </topics/forms/media>`
now allow using hashable objects, not only path strings, as long as those
objects implement the ``__html__()`` method (typically when decorated with
the :func:`~django.utils.html.html_safe` decorator).
* The new :attr:`.BoundField.use_fieldset` and :attr:`.Widget.use_fieldset`
attributes help to identify widgets where its inputs should be grouped in a
``<fieldset>`` with a ``<legend>``.
* The :ref:`formsets-error-messages` argument for
:class:`~django.forms.formsets.BaseFormSet` now allows customizing
error messages for invalid number of forms by passing ``'too_few_forms'``
and ``'too_many_forms'`` keys.
* :class:`~django.forms.IntegerField`, :class:`~django.forms.FloatField`, and
:class:`~django.forms.DecimalField` now optionally accept a ``step_size``
argument. This is used to set the ``step`` HTML attribute, and is validated
on form submission.
Internationalization
~~~~~~~~~~~~~~~~~~~~
* The :func:`~django.conf.urls.i18n.i18n_patterns` function now supports
languages with both scripts and regions.
Management Commands
~~~~~~~~~~~~~~~~~~~
* :option:`makemigrations --no-input` now logs default answers and reasons why
migrations cannot be created.
* The new :option:`makemigrations --scriptable` option diverts log output and
input prompts to ``stderr``, writing only paths of generated migration files
to ``stdout``.
* The new :option:`migrate --prune` option allows deleting nonexistent
migrations from the ``django_migrations`` table.
* Python files created by :djadmin:`startproject`, :djadmin:`startapp`,
:djadmin:`optimizemigration`, :djadmin:`makemigrations`, and
:djadmin:`squashmigrations` are now formatted using the ``black`` command if
it is present on your ``PATH``.
* The new :djadmin:`optimizemigration` command allows optimizing operations for
a migration.
Migrations
~~~~~~~~~~
* The new :class:`~django.db.migrations.operations.RenameIndex` operation
allows renaming indexes defined in the
:attr:`Meta.indexes <django.db.models.Options.indexes>` or
:attr:`~django.db.models.Options.index_together` options.
* The migrations autodetector now generates
:class:`~django.db.migrations.operations.RenameIndex` operations instead of
``RemoveIndex`` and ``AddIndex``, when renaming indexes defined in the
:attr:`Meta.indexes <django.db.models.Options.indexes>`.
* The migrations autodetector now generates
:class:`~django.db.migrations.operations.RenameIndex` operations instead of
``AlterIndexTogether`` and ``AddIndex``, when moving indexes defined in the
:attr:`Meta.index_together <django.db.models.Options.index_together>` to the
:attr:`Meta.indexes <django.db.models.Options.indexes>`.
Models
~~~~~~
* The ``order_by`` argument of the
:class:`~django.db.models.expressions.Window` expression now accepts string
references to fields and transforms.
* The new :setting:`CONN_HEALTH_CHECKS` setting allows enabling health checks
for :ref:`persistent database connections <persistent-database-connections>`
in order to reduce the number of failed requests, e.g. after database server
restart.
* :meth:`.QuerySet.bulk_create` now supports updating fields when a row
insertion fails uniqueness constraints. This is supported on MariaDB, MySQL,
PostgreSQL, and SQLite 3.24+.
* :meth:`.QuerySet.iterator` now supports prefetching related objects as long
as the ``chunk_size`` argument is provided. In older versions, no prefetching
was done.
* :class:`~django.db.models.Q` objects and querysets can now be combined using
``^`` as the exclusive or (``XOR``) operator. ``XOR`` is natively supported
on MariaDB and MySQL. For databases that do not support ``XOR``, the query
will be converted to an equivalent using ``AND``, ``OR``, and ``NOT``.
* The new :ref:`Field.non_db_attrs <custom-field-non_db_attrs>` attribute
allows customizing attributes of fields that don't affect a column
definition.
* On PostgreSQL, ``AutoField``, ``BigAutoField``, and ``SmallAutoField`` are
now created as identity columns rather than serial columns with sequences.
Requests and Responses
~~~~~~~~~~~~~~~~~~~~~~
* :meth:`.HttpResponse.set_cookie` now supports :class:`~datetime.timedelta`
objects for the ``max_age`` argument.
Security
~~~~~~~~
* The new :setting:`SECRET_KEY_FALLBACKS` setting allows providing a list of
values for secret key rotation.
* The :setting:`SECURE_PROXY_SSL_HEADER` setting now supports a comma-separated
list of protocols in the header value.
Signals
~~~~~~~
* The :data:`~django.db.models.signals.pre_delete` and
:data:`~django.db.models.signals.post_delete` signals now dispatch the
``origin`` of the deletion.
.. _templates-4.1:
Templates
~~~~~~~~~
* The HTML ``<script>`` element ``id`` attribute is no longer required when
wrapping the :tfilter:`json_script` template filter.
* The :class:`cached template loader <django.template.loaders.cached.Loader>`
is now enabled in development, when :setting:`DEBUG` is ``True``, and
:setting:`OPTIONS['loaders'] <TEMPLATES-OPTIONS>` isn't specified. You may
specify ``OPTIONS['loaders']`` to override this, if necessary.
Tests
~~~~~
* The :class:`.DiscoverRunner` now supports running tests in parallel on
macOS, Windows, and any other systems where the default
:mod:`multiprocessing` start method is ``spawn``.
* A nested atomic block marked as durable in :class:`django.test.TestCase` now
raises a ``RuntimeError``, the same as outside of tests.
* :meth:`.SimpleTestCase.assertFormError` and
:meth:`~.SimpleTestCase.assertFormsetError` now support passing a
form/formset object directly.
URLs
~~~~
* The new :attr:`.ResolverMatch.captured_kwargs` attribute stores the captured
keyword arguments, as parsed from the URL.
* The new :attr:`.ResolverMatch.extra_kwargs` attribute stores the additional
keyword arguments passed to the view function.
Utilities
~~~~~~~~~
* ``SimpleLazyObject`` now supports addition operations.
* :func:`~django.utils.safestring.mark_safe` now preserves lazy objects.
Validators
~~~~~~~~~~
* The new :class:`~django.core.validators.StepValueValidator` checks if a value
is an integral multiple of a given step size. This new validator is used for
the new ``step_size`` argument added to form fields representing numeric
values.
.. _backwards-incompatible-4.1:
Backwards incompatible changes in 4.1
=====================================
Database backend API
--------------------
This section describes changes that may be needed in third-party database
backends.
* ``BaseDatabaseFeatures.has_case_insensitive_like`` is changed from ``True``
to ``False`` to reflect the behavior of most databases.
* ``DatabaseIntrospection.get_key_columns()`` is removed. Use
``DatabaseIntrospection.get_relations()`` instead.
* ``DatabaseOperations.ignore_conflicts_suffix_sql()`` method is replaced by
``DatabaseOperations.on_conflict_suffix_sql()`` that accepts the ``fields``,
``on_conflict``, ``update_fields``, and ``unique_fields`` arguments.
* The ``ignore_conflicts`` argument of the
``DatabaseOperations.insert_statement()`` method is replaced by
``on_conflict`` that accepts ``django.db.models.constants.OnConflict``.
* ``DatabaseOperations._convert_field_to_tz()`` is replaced by
``DatabaseOperations._convert_sql_to_tz()`` that accepts the ``sql``,
``params``, and ``tzname`` arguments.
* Several date and time methods on ``DatabaseOperations`` now take ``sql`` and
``params`` arguments instead of ``field_name`` and return 2-tuple containing
some SQL and the parameters to be interpolated into that SQL. The changed
methods have these new signatures:
* ``DatabaseOperations.date_extract_sql(lookup_type, sql, params)``
* ``DatabaseOperations.datetime_extract_sql(lookup_type, sql, params, tzname)``
* ``DatabaseOperations.time_extract_sql(lookup_type, sql, params)``
* ``DatabaseOperations.date_trunc_sql(lookup_type, sql, params, tzname=None)``
* ``DatabaseOperations.datetime_trunc_sql(self, lookup_type, sql, params, tzname)``
* ``DatabaseOperations.time_trunc_sql(lookup_type, sql, params, tzname=None)``
* ``DatabaseOperations.datetime_cast_date_sql(sql, params, tzname)``
* ``DatabaseOperations.datetime_cast_time_sql(sql, params, tzname)``
:mod:`django.contrib.gis`
-------------------------
* Support for GDAL 2.1 is removed.
* Support for PostGIS 2.4 is removed.
Dropped support for PostgreSQL 10
---------------------------------
Upstream support for PostgreSQL 10 ends in November 2022. Django 4.1 supports
PostgreSQL 11 and higher.
Dropped support for MariaDB 10.2
--------------------------------
Upstream support for MariaDB 10.2 ends in May 2022. Django 4.1 supports MariaDB
10.3 and higher.
Admin changelist searches spanning multi-valued relationships changes
---------------------------------------------------------------------
Admin changelist searches using multiple search terms are now applied in a
single call to ``filter()``, rather than in sequential ``filter()`` calls.
For multi-valued relationships, this means that rows from the related model
must match all terms rather than any term. For example, if ``search_fields``
is set to ``['child__name', 'child__age']``, and a user searches for
``'Jamal 17'``, parent rows will be returned only if there is a relationship to
some 17-year-old child named Jamal, rather than also returning parents who
merely have a younger or older child named Jamal in addition to some other
17-year-old.
See the :ref:`spanning-multi-valued-relationships` topic for more discussion of
this difference. In Django 4.0 and earlier,
:meth:`~django.contrib.admin.ModelAdmin.get_search_results` followed the
second example query, but this undocumented behavior led to queries with
excessive joins.
Reverse foreign key changes for unsaved model instances
-------------------------------------------------------
In order to unify the behavior with many-to-many relations for unsaved model
instances, a reverse foreign key now raises ``ValueError`` when calling
:class:`related managers <django.db.models.fields.related.RelatedManager>` for
unsaved objects.
Miscellaneous
-------------
* Related managers for :class:`~django.db.models.ForeignKey`,
:class:`~django.db.models.ManyToManyField`, and
:class:`~django.contrib.contenttypes.fields.GenericRelation` are now cached
on the :class:`~django.db.models.Model` instance to which they belong.
* The Django test runner now returns a non-zero error code for unexpected
successes from tests marked with :py:func:`unittest.expectedFailure`.
* :class:`~django.middleware.csrf.CsrfViewMiddleware` no longer masks the CSRF
cookie like it does the CSRF token in the DOM.
* :class:`~django.middleware.csrf.CsrfViewMiddleware` now uses
``request.META['CSRF_COOKIE']`` for storing the unmasked CSRF secret rather
than a masked version. This is an undocumented, private API.
* The :attr:`.ModelAdmin.actions` and
:attr:`~django.contrib.admin.ModelAdmin.inlines` attributes now default to an
empty tuple rather than an empty list to discourage unintended mutation.
* The ``type="text/css"`` attribute is no longer included in ``<link>`` tags
for CSS :doc:`form media </topics/forms/media>`.
* ``formset:added`` and ``formset:removed`` JavaScript events are now pure
JavaScript events and don't depend on jQuery. See
:ref:`admin-javascript-inline-form-events` for more details on the change.
* The ``exc_info`` argument of the undocumented
``django.utils.log.log_response()`` function is replaced by ``exception``.
* The ``size`` argument of the undocumented
``django.views.static.was_modified_since()`` function is removed.
* The admin log out UI now uses ``POST`` requests.
* The undocumented ``InlineAdminFormSet.non_form_errors`` property is replaced
by the ``non_form_errors()`` method. This is consistent with ``BaseFormSet``.
* As per :ref:`above<templates-4.1>`, the cached template loader is now
enabled in development. You may specify ``OPTIONS['loaders']`` to override
this, if necessary.
* The undocumented ``django.contrib.auth.views.SuccessURLAllowedHostsMixin``
mixin is replaced by ``RedirectURLMixin``.
* :class:`~django.db.models.BaseConstraint` subclasses must implement
:meth:`~django.db.models.BaseConstraint.validate` method to allow those
constraints to be used for validation.
* The undocumented ``URLResolver._is_callback()``,
``URLResolver._callback_strs``, and ``URLPattern.lookup_str()`` are
moved to ``django.contrib.admindocs.utils``.
* The :meth:`.Model.full_clean` method now converts an ``exclude`` value to a
``set``. It’s also preferable to pass an ``exclude`` value as a ``set`` to
the :meth:`.Model.clean_fields`, :meth:`.Model.full_clean`,
:meth:`.Model.validate_unique`, and :meth:`.Model.validate_constraints`
methods.
* The minimum supported version of ``asgiref`` is increased from 3.4.1 to
3.5.2.
.. _deprecated-features-4.1:
Features deprecated in 4.1
==========================
Log out via GET
---------------
Logging out via ``GET`` requests to the :py:class:`built-in logout view
<django.contrib.auth.views.LogoutView>` is deprecated. Use ``POST`` requests
instead.
If you want to retain the user experience of an HTML link, you can use a form
that is styled to appear as a link:
.. code-block:: html
<form id="logout-form" method="post" action="{% url 'admin:logout' %}">
{% csrf_token %}
<button type="submit">{% translate "Log out" %}</button>
</form>
.. code-block:: css
logout-form {
display: inline;
}
logout-form button {
background: none;
border: none;
cursor: pointer;
padding: 0;
text-decoration: underline;
}
Miscellaneous
-------------
* The context for sitemap index templates of a flat list of URLs is deprecated.
Custom sitemap index templates should be updated for the adjusted
:ref:`context variables <sitemap-index-context-variables>`, expecting a list
of objects with ``location`` and optional ``lastmod`` attributes.
* ``CSRF_COOKIE_MASKED`` transitional setting is deprecated.
* The ``name`` argument of :func:`django.utils.functional.cached_property` is
deprecated as it's unnecessary as of Python 3.6.
* The ``opclasses`` argument of
``django.contrib.postgres.constraints.ExclusionConstraint`` is deprecated in
favor of using :class:`OpClass() <django.contrib.postgres.indexes.OpClass>`
in :attr:`.ExclusionConstraint.expressions`. To use it, you need to add
``'django.contrib.postgres'`` in your :setting:`INSTALLED_APPS`.
After making this change, :djadmin:`makemigrations` will generate a new
migration with two operations: ``RemoveConstraint`` and ``AddConstraint``.
Since this change has no effect on the database schema,
the :class:`~django.db.migrations.operations.SeparateDatabaseAndState`
operation can be used to only update the migration state without running any
SQL. Move the generated operations into the ``state_operations`` argument of
:class:`~django.db.migrations.operations.SeparateDatabaseAndState`. For
example::
class Migration(migrations.Migration):
...
operations = [
migrations.SeparateDatabaseAndState(
database_operations=[],
state_operations=[
migrations.RemoveConstraint(
...
),
migrations.AddConstraint(
...
),
],
),
]
* The undocumented ability to pass ``errors=None`` to
:meth:`.SimpleTestCase.assertFormError` and
:meth:`~.SimpleTestCase.assertFormsetError` is deprecated. Use ``errors=[]``
instead.
* ``django.contrib.sessions.serializers.PickleSerializer`` is deprecated due to
the risk of remote code execution.
* The usage of ``QuerySet.iterator()`` on a queryset that prefetches related
objects without providing the ``chunk_size`` argument is deprecated. In older
versions, no prefetching was done. Providing a value for ``chunk_size``
signifies that the additional query per chunk needed to prefetch is desired.
* Passing unsaved model instances to related filters is deprecated. In Django
5.0, the exception will be raised.
* ``created=True`` is added to the signature of
:meth:`.RemoteUserBackend.configure_user`. Support for ``RemoteUserBackend``
subclasses that do not accept this argument is deprecated.
* The :data:`django.utils.timezone.utc` alias to :attr:`datetime.timezone.utc`
is deprecated. Use :attr:`datetime.timezone.utc` directly.
* Passing a response object and a form/formset name to
``SimpleTestCase.assertFormError()`` and ``assertFormsetError()`` is
deprecated. Use::
assertFormError(response.context['form_name'], …)
assertFormsetError(response.context['formset_name'], …)
or pass the form/formset object directly instead.
* The undocumented ``django.contrib.gis.admin.OpenLayersWidget`` is deprecated.
* ``django.contrib.auth.hashers.CryptPasswordHasher`` is deprecated.
* The ability to pass ``nulls_first=False`` or ``nulls_last=False`` to
``Expression.asc()`` and ``Expression.desc()`` methods, and the ``OrderBy``
expression is deprecated. Use ``None`` instead.
* The ``"django/forms/default.html"`` and
``"django/forms/formsets/default.html"`` templates which are a proxy to the
table-based templates are deprecated. Use the specific template instead.
Features removed in 4.1
=======================
These features have reached the end of their deprecation cycle and are removed
in Django 4.1.
See :ref:`deprecated-features-3.2` for details on these changes, including how
to remove usage of these features.
* Support for assigning objects which don't support creating deep copies with
``copy.deepcopy()`` to class attributes in ``TestCase.setUpTestData()`` is
removed.
* Support for using a boolean value in
:attr:`.BaseCommand.requires_system_checks` is removed.
* The ``whitelist`` argument and ``domain_whitelist`` attribute of
``django.core.validators.EmailValidator`` are removed.
* The ``default_app_config`` application configuration variable is removed.
* ``TransactionTestCase.assertQuerysetEqual()`` no longer calls ``repr()`` on a
queryset when compared to string values.
* The ``django.core.cache.backends.memcached.MemcachedCache`` backend is
removed.
* Support for the pre-Django 3.2 format of messages used by
``django.contrib.messages.storage.cookie.CookieStorage`` is removed.
==========================
```
### 4.0.7
```
==========================
*August 3, 2022*
Django 4.0.7 fixes a security issue with severity "high" in 4.0.6.
CVE-2022-36359: Potential reflected file download vulnerability in ``FileResponse``
===================================================================================
An application may have been vulnerable to a reflected file download (RFD)
attack that sets the Content-Disposition header of a
:class:`~django.http.FileResponse` when the ``filename`` was derived from
user-supplied input. The ``filename`` is now escaped to avoid this possibility.
==========================
```
### 4.0.6
```
==========================
*July 4, 2022*
Django 4.0.6 fixes a security issue with severity "high" in 4.0.5.
CVE-2022-34265: Potential SQL injection via ``Trunc(kind)`` and ``Extract(lookup_name)`` arguments
==================================================================================================
:class:`Trunc() <django.db.models.functions.Trunc>` and
:class:`Extract() <django.db.models.functions.Extract>` database functions were
subject to SQL injection if untrusted data was used as a
``kind``/``lookup_name`` value.
Applications that constrain the lookup name and kind choice to a known safe
list are unaffected.
==========================
```
### 4.0.5
```
==========================
*June 1, 2022*
Django 4.0.5 fixes several bugs in 4.0.4.
Bugfixes
========
* Fixed a bug in Django 4.0 where not all :setting:`OPTIONS <CACHES-OPTIONS>`
were passed to a Redis client (:ticket:`33681`).
* Fixed a bug in Django 4.0 that caused a crash of ``QuerySet.filter()`` on
``IsNull()`` expressions (:ticket:`33705`).
* Fixed a bug in Django 4.0 where a hidden quick filter toolbar in the admin's
navigation sidebar was focusable (:ticket:`33725`).
==========================
```
### 4.0.4
```
==========================
*April 11, 2022*
Django 4.0.4 fixes two security issues with severity "high" and two bugs in
4.0.3.
CVE-2022-28346: Potential SQL injection in ``QuerySet.annotate()``, ``aggregate()``, and ``extra()``
====================================================================================================
:meth:`.QuerySet.annotate`, :meth:`~.QuerySet.aggregate`, and
:meth:`~.QuerySet.extra` methods were subject to SQL injection in column
aliases, using a suitably crafted dictionary, with dictionary expansion, as the
``**kwargs`` passed to these methods.
CVE-2022-28347: Potential SQL injection via ``QuerySet.explain(**options)`` on PostgreSQL
=========================================================================================
:meth:`.QuerySet.explain` method was subject to SQL injection in option names,
using a suitably crafted dictionary, with dictionary expansion, as the
``**options`` argument.
Bugfixes
========
* Fixed a regression in Django 4.0 that caused ignoring multiple
``FilteredRelation()`` relationships to the same field (:ticket:`33598`).
* Fixed a regression in Django 3.2.4 that caused the auto-reloader to no longer
detect changes when the ``DIRS`` option of the ``TEMPLATES`` setting
contained an empty string (:ticket:`33628`).
==========================
```
### 4.0.3
```
==========================
*March 1, 2022*
Django 4.0.3 fixes several bugs in 4.0.2. Also, all Python code in Django is
reformatted with `black`_.
.. _black: https://pypi.org/project/black/
Bugfixes
========
* Prevented, following a regression in Django 4.0.1, :djadmin:`makemigrations`
from generating infinite migrations for a model with ``ManyToManyField`` to
a lowercased swappable model such as ``'auth.user'`` (:ticket:`33515`).
* Fixed a regression in Django 4.0 that caused a crash when rendering invalid
inlines with :attr:`~django.contrib.admin.ModelAdmin.readonly_fields` in the
admin (:ticket:`33547`).
==========================
```
### 4.0.2
```
==========================
*February 1, 2022*
Django 4.0.2 fixes two security issues with severity "medium" and several bugs
in 4.0.1. Also, the latest string translations from Transifex are incorporated,
with a special mention for Bulgarian (fully translated).
CVE-2022-22818: Possible XSS via ``{% debug %}`` template tag
=============================================================
The ``{% debug %}`` template tag didn't properly encode the current context,
posing an XSS attack vector.
In order to avoid this vulnerability, ``{% debug %}`` no longer outputs
information when the ``DEBUG`` setting is ``False``, and it ensures all context
variables are correctly escaped when the ``DEBUG`` setting is ``True``.
CVE-2022-23833: Denial-of-service possibility in file uploads
=============================================================
Passing certain inputs to multipart forms could result in an infinite loop when
parsing files.
Bugfixes
========
* Fixed a bug in Django 4.0 where ``TestCase.captureOnCommitCallbacks()`` could
execute callbacks multiple times (:ticket:`33410`).
* Fixed a regression in Django 4.0 where ``help_text`` was HTML-escaped in
automatically-generated forms (:ticket:`33419`).
* Fixed a regression in Django 4.0 that caused displaying an incorrect name for
class-based views on the technical 404 debug page (:ticket:`33425`).
* Fixed a regression in Django 4.0 that caused an incorrect ``repr`` of
``ResolverMatch`` for class-based views (:ticket:`33426`).
* Fixed a regression in Django 4.0 that caused a crash of ``makemigrations`` on
models without ``Meta.order_with_respect_to`` but with a field named
``_order`` (:ticket:`33449`).
* Fixed a regression in Django 4.0 that caused incorrect
:attr:`.ModelAdmin.radio_fields` layout in the admin (:ticket:`33407`).
* Fixed a duplicate operation regression in Django 4.0 that caused a migration
crash when altering a primary key type for a concrete parent model referenced
by a foreign key (:ticket:`33462`).
* Fixed a bug in Django 4.0 that caused a crash of ``QuerySet.aggregate()``
after ``annotate()`` on an aggregate function with a
:ref:`default <aggregate-default>` (:ticket:`33468`).
* Fixed a regression in Django 4.0 that caused a crash of ``makemigrations``
when renaming a field of a renamed model (:ticket:`33480`).
==========================
```
### 4.0.1
```
==========================
*January 4, 2022*
Django 4.0.1 fixes one security issue with severity "medium", two security
issues with severity "low", and several bugs in 4.0.
CVE-2021-45115: Denial-of-service possibility in ``UserAttributeSimilarityValidator``
=====================================================================================
:class:`.UserAttributeSimilarityValidator` incurred significant overhead
evaluating submitted password that were artificially large in relative to the
comparison values. On the assumption that access to user registration was
unrestricted this provided a potential vector for a denial-of-service attack.
In order to mitigate this issue, relatively long values are now ignored by
``UserAttributeSimilarityValidator``.
This issue has severity "medium" according to the :ref:`Django security policy
<security-disclosure>`.
CVE-2021-45116: Potential information disclosure in ``dictsort`` template filter
================================================================================
Due to leveraging the Django Template Language's variable resolution logic, the
:tfilter:`dictsort` template filter was potentially vulnerable to information
disclosure or unintended method calls, if passed a suitably crafted key.
In order to avoid this possibility, ``dictsort`` now works with a restricted
resolution logic, that will not call methods, nor allow indexing on
dictionaries.
As a reminder, all untrusted user input should be validated before use.
This issue has severity "low" according to the :ref:`Django security policy
<security-disclosure>`.
CVE-2021-45452: Potential directory-traversal via ``Storage.save()``
====================================================================
``Storage.save()`` allowed directory-traversal if directly passed suitably
crafted file names.
This issue has severity "low" according to the :ref:`Django security policy
<security-disclosure>`.
Bugfixes
========
* Fixed a regression in Django 4.0 that caused a crash of
:meth:`~django.test.SimpleTestCase.assertFormsetError` on a formset named
``form`` (:ticket:`33346`).
* Fixed a bug in Django 4.0 that caused a crash on booleans with the
``RedisCache`` backend (:ticket:`33361`).
* Relaxed the check added in Django 4.0 to reallow use of a duck-typed
``HttpRequest`` in ``django.views.decorators.cache.cache_control()`` and
``never_cache()`` decorators (:ticket:`33350`).
* Fixed a regression in Django 4.0 that caused creating bogus migrations for
models that reference swappable models such as ``auth.User``
(:ticket:`33366`).
* Fixed a long standing bug in :ref:`geos-geometry-collections` and
:class:`~django.contrib.gis.geos.Polygon` that caused a crash on some
platforms (reported on macOS based on the ``ARM64`` architecture)
(:ticket:`32600`).
========================
```
### 4.0
```
========================
*December 7, 2021*
Welcome to Django 4.0!
These release notes cover the :ref:`new features <whats-new-4.0>`, as well as
some :ref:`backwards incompatible changes <backwards-incompatible-4.0>` you'll
want to be aware of when upgrading from Django 3.2 or earlier. We've
:ref:`begun the deprecation process for some features
<deprecated-features-4.0>`.
See the :doc:`/howto/upgrade-version` guide if you're updating an existing
project.
Python compatibility
====================
Django 4.0 supports Python 3.8, 3.9, and 3.10. We **highly recommend** and only
officially support the latest release of each series.
The Django 3.2.x series is the last to support Python 3.6 and 3.7.
.. _whats-new-4.0:
What's new in Django 4.0
========================
``zoneinfo`` default timezone implementation
--------------------------------------------
The Python standard library's :mod:`zoneinfo` is now the default timezone
implementation in Django.
This is the next step in the migration from using ``pytz`` to using
:mod:`zoneinfo`. Django 3.2 allowed the use of non-``pytz`` time zones. Django
4.0 makes ``zoneinfo`` the default implementation. Support for ``pytz`` is now
deprecated and will be removed in Django 5.0.
:mod:`zoneinfo` is part of the Python standard library from Python 3.9. The
``backports.zoneinfo`` package is automatically installed alongside Django if
you are using Python 3.8.
The move to ``zoneinfo`` should be largely transparent. Selection of the
current timezone, conversion of datetime instances to the current timezone in
forms and templates, as well as operations on aware datetimes in UTC are
unaffected.
However, if you are working with non-UTC time zones, and using the ``pytz``
``normalize()`` and ``localize()`` APIs, possibly with the :setting:`TIME_ZONE
<DATABASE-TIME_ZONE>` setting, you will need to audit your code, since ``pytz``
and ``zoneinfo`` are not entirely equivalent.
To give time for such an audit, the transitional :setting:`USE_DEPRECATED_PYTZ`
setting allows continued use of ``pytz`` during the 4.x release cycle. This
setting will be removed in Django 5.0.
In addition, a `pytz_deprecation_shim`_ package, created by the ``zoneinfo``
author, can be used to assist with the migration from ``pytz``. This package
provides shims to help you safely remove ``pytz``, and has a detailed
`migration guide`_ showing how to move to the new ``zoneinfo`` APIs.
Using `pytz_deprecation_shim`_ and the :setting:`USE_DEPRECATED_PYTZ`
transitional setting is recommended if you need a gradual update path.
.. _pytz_deprecation_shim: https://pytz-deprecation-shim.readthedocs.io/en/latest/index.html
.. _migration guide: https://pytz-deprecation-shim.readthedocs.io/en/latest/migration.html
Functional unique constraints
-----------------------------
The new :attr:`*expressions <django.db.models.UniqueConstraint.expressions>`
positional argument of
:class:`UniqueConstraint() <django.db.models.UniqueConstraint>` enables
creating functional unique constraints on expressions and database functions.
For example::
from django.db import models
from django.db.models import UniqueConstraint
from django.db.models.functions import Lower
class MyModel(models.Model):
first_name = models.CharField(max_length=255)
last_name = models.CharField(max_length=255)
class Meta:
constraints = [
UniqueConstraint(
Lower('first_name'),
Lower('last_name').desc(),
name='first_last_name_unique',
),
]
Functional unique constraints are added to models using the
:attr:`Meta.constraints <django.db.models.Options.constraints>` option.
``scrypt`` password hasher
--------------------------
The new :ref:`scrypt password hasher <scrypt-usage>` is more secure and
recommended over PBKDF2. However, it's not the default as it requires OpenSSL
1.1+ and more memory.
Redis cache backend
-------------------
The new ``django.core.cache.backends.redis.RedisCache`` cache backend provides
built-in support for caching with Redis. `redis-py`_ 3.0.0 or higher is
required. For more details, see the :ref:`documentation on caching with Redis
in Django <redis>`.
.. _`redis-py`: https://pypi.org/project/redis/
Template based form rendering
-----------------------------
:class:`Forms <django.forms.Form>`, :doc:`Formsets </topics/forms/formsets>`,
and :class:`~django.forms.ErrorList` are now rendered using the template engine
to enhance customization. See the new :meth:`~django.forms.Form.render`,
:meth:`~django.forms.Form.get_context`, and
:attr:`~django.forms.Form.template_name` for ``Form`` and
:ref:`formset rendering <formset-rendering>` for ``Formset``.
Minor features
--------------
:mod:`django.contrib.admin`
~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The ``admin/base.html`` template now has a new block ``header`` which
contains the admin site header.
* The new :meth:`.ModelAdmin.get_formset_kwargs` method allows customizing the
keyword arguments passed to the constructor of a formset.
* The navigation sidebar now has a quick filter toolbar.
* The new context variable ``model`` which contains the model class for each
model is added to the :meth:`.AdminSite.each_context` method.
* The new :attr:`.ModelAdmin.search_help_text` attribute allows specifying a
descriptive text for the search box.
* The :attr:`.InlineModelAdmin.verbose_name_plural` attribute now fallbacks to
the :attr:`.InlineModelAdmin.verbose_name` + ``'s'``.
* jQuery is upgraded from version 3.5.1 to 3.6.0.
:mod:`django.contrib.admindocs`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The admindocs now allows esoteric setups where :setting:`ROOT_URLCONF` is not
a string.
* The model section of the ``admindocs`` now shows cached properties.
:mod:`django.contrib.auth`
~~~~~~~~~~~~~~~~~~~~~~~~~~
* The default iteration count for the PBKDF2 password hasher is increased from
260,000 to 320,000.
* The new
:attr:`LoginView.next_page <django.contrib.auth.views.LoginView.next_page>`
attribute and
:meth:`~django.contrib.auth.views.LoginView.get_default_redirect_url` method
allow customizing the redirect after login.
:mod:`django.contrib.gis`
~~~~~~~~~~~~~~~~~~~~~~~~~
* Added support for SpatiaLite 5.
* :class:`~django.contrib.gis.gdal.GDALRaster` now allows creating rasters in
any GDAL virtual filesystem.
* The new :class:`~django.contrib.gis.admin.GISModelAdmin` class allows
customizing the widget used for ``GeometryField``. This is encouraged instead
of deprecated ``GeoModelAdmin`` and ``OSMGeoAdmin``.
:mod:`django.contrib.postgres`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The PostgreSQL backend now supports connecting by a service name. See
:ref:`postgresql-connection-settings` for more details.
* The new :class:`~django.contrib.postgres.operations.AddConstraintNotValid`
operation allows creating check constraints on PostgreSQL without verifying
that all existing rows satisfy the new constraint.
* The new :class:`~django.contrib.postgres.operations.ValidateConstraint`
operation allows validating check constraints which were created using
:class:`~django.contrib.postgres.operations.AddConstraintNotValid` on
PostgreSQL.
* The new
:class:`ArraySubquery() <django.contrib.postgres.expressions.ArraySubquery>`
expression allows using subqueries to construct lists of values on
PostgreSQL.
* The new :lookup:`trigram_word_similar` lookup, and the
:class:`TrigramWordDistance()
<django.contrib.postgres.search.TrigramWordDistance>` and
:class:`TrigramWordSimilarity()
<django.contrib.postgres.search.TrigramWordSimilarity>` expressions allow
using trigram word similarity.
:mod:`django.contrib.staticfiles`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage` now
replaces paths to JavaScript source map references with their hashed
counterparts.
* The new ``manifest_storage`` argument of
:class:`~django.contrib.staticfiles.storage.ManifestFilesMixin` and
:class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage`
allows customizing the manifest file storage.
Cache
~~~~~
* The new async API for ``django.core.cache.backends.base.BaseCache`` begins
the process of making cache backends async-compatible. The new async methods
all have ``a`` prefixed names, e.g. ``aadd()``, ``aget()``, ``aset()``,
``aget_or_set()``, or ``adelete_many()``.
Going forward, the ``a`` prefix will be used for async variants of methods
generally.
CSRF
~~~~
* CSRF protection now consults the ``Origin`` header, if present. To facilitate
this, :ref:`some changes <csrf-trusted-origins-changes-4.0>` to the
:setting:`CSRF_TRUSTED_ORIGINS` setting are required.
Forms
~~~~~
* :class:`~django.forms.ModelChoiceField` now includes the provided value in
the ``params`` argument of a raised
:exc:`~django.core.exceptions.ValidationError` for the ``invalid_choice``
error message. This allows custom error messages to use the ``%(value)s``
placeholder.
* :class:`~django.forms.formsets.BaseFormSet` now renders non-form errors with
an additional class of ``nonform`` to help distinguish them from
form-specific errors.
* :class:`~django.forms.formsets.BaseFormSet` now allows customizing the widget
used when deleting forms via
:attr:`~django.forms.formsets.BaseFormSet.can_delete` by setting the
:attr:`~django.forms.formsets.BaseFormSet.deletion_widget` attribute or
overriding :meth:`~django.forms.formsets.BaseFormSet.get_deletion_widget`
method.
Internationalization
~~~~~~~~~~~~~~~~~~~~
* Added support and translations for the Malay language.
Generic Views
~~~~~~~~~~~~~
* :class:`~django.views.generic.edit.DeleteView` now uses
:class:`~django.views.generic.edit.FormMixin`, allowing you to provide a
:class:`~django.forms.Form` subclass, with a checkbox for example, to confirm
deletion. In addition, this allows ``DeleteView`` to function with
:class:`django.contrib.messages.views.SuccessMessageMixin`.
In accordance with ``FormMixin``, object deletion for POST requests is
handled in ``form_valid()``. Custom delete logic in ``delete()`` handlers
should be moved to ``form_valid()``, or a shared helper method, as needed.
Logging
~~~~~~~
* The alias of the database used in an SQL call is now passed as extra context
along with each message to the :ref:`django-db-logger` logger.
Management Commands
~~~~~~~~~~~~~~~~~~~
* The :djadmin:`runserver` management command now supports the
:option:`--skip-checks` option.
* On PostgreSQL, :djadmin:`dbshell` now supports specifying a password file.
* The :djadmin:`shell` command now respects :py:data:`sys.__interactivehook__`
at startup. This allows loading shell history between interactive sessions.
As a consequence, ``readline`` is no longer loaded if running in *isolated*
mode.
* The new :attr:`BaseCommand.suppressed_base_arguments
<django.core.management.BaseCommand.suppressed_base_arguments>` attribute
allows suppressing unsupported default command options in the help output.
* The new :option:`startapp --exclude` and :option:`startproject --exclude`
options allow excluding directories from the template.
Models
~~~~~~
* New :meth:`QuerySet.contains(obj) <.QuerySet.contains>` method returns
whether the queryset contains the given object. This tries to perform the
query in the simplest and fastest way possible.
* The new ``precision`` argument of the
:class:`Round() <django.db.models.functions.Round>` database function allows
specifying the number of decimal places after rounding.
* :meth:`.QuerySet.bulk_create` now sets the primary key on objects when using
SQLite 3.35+.
* :class:`~django.db.models.DurationField` now supports multiplying and
dividing by scalar values on SQLite.
* :meth:`.QuerySet.bulk_update` now returns the number of objects updated.
* The new :attr:`.Expression.empty_result_set_value` attribute allows
specifying a value to return when the function is used over an empty result
set.
* The ``skip_locked`` argument of :meth:`.QuerySet.select_for_update()` is now
allowed on MariaDB 10.6+.
* :class:`~django.db.models.Lookup` expressions may now be used in ``QuerySet``
annotations, aggregations, and directly in filters.
* The new :ref:`default <aggregate-default>` argument for built-in aggregates
allows specifying a value to be returned when the queryset (or grouping)
contains no entries, rather than ``None``.
Requests and Responses
~~~~~~~~~~~~~~~~~~~~~~
* The :class:`~django.middleware.security.SecurityMiddleware` now adds the
:ref:`Cross-Origin Opener Policy <cross-origin-opener-policy>` header with a
value of ``'same-origin'`` to prevent cross-origin popups from sharing the
same browsing context. You can prevent this header from being added by
setting the :setting:`SECURE_CROSS_ORIGIN_OPENER_POLICY` setting to ``None``.
Signals
~~~~~~~
* The new ``stdout`` argument for :func:`~django.db.models.signals.pre_migrate`
and :func:`~django.db.models.signals.post_migrate` signals allows redirecting
output to a stream-like object. It should be preferred over
:py:data:`sys.stdout` and :py:func:`print` when emitting verbose output in
order to allow proper capture when testing.
Templates
~~~~~~~~~
* :tfilter:`floatformat` template filter now allows using the ``u`` suffix to
force disabling localization.
Tests
~~~~~
* The new ``serialized_aliases`` argument of
:func:`django.test.utils.setup_databases` determines which
:setting:`DATABASES` aliases test databases should have their state
serialized to allow usage of the
:ref:`serialized_rollback <test-case-serialized-rollback>` feature.
* Django test runner now supports a :option:`--buffer <test --buffer>` option
with parallel tests.
* The new ``logger`` argument to :class:`~django.test.runner.DiscoverRunner`
allows a Python :py:ref:`logger <logger>` to be used for logging.
* The new :meth:`.DiscoverRunner.log` method provides a way to log messages
that uses the ``DiscoverRunner.logger``, or prints to the console if not set.
* Django test runner now supports a :option:`--shuffle <test --shuffle>` option
to execute tests in a random order.
* The :option:`test --parallel` option now supports the value ``auto`` to run
one test process for each processor core.
* :meth:`.TestCase.captureOnCommitCallbacks` now captures new callbacks added
while executing :func:`.transaction.on_commit` callbacks.
.. _backwards-incompatible-4.0:
Backwards incompatible changes in 4.0
=====================================
Database backend API
--------------------
This section describes changes that may be needed in third-party database
backends.
* ``DatabaseOperations.year_lookup_bounds_for_date_field()`` and
``year_lookup_bounds_for_datetime_field()`` methods now take the optional
``iso_year`` argument in order to support bounds for ISO-8601 week-numbering
years.
* The second argument of ``DatabaseSchemaEditor._unique_sql()`` and
``_create_unique_sql()`` methods is now ``fields`` instead of ``columns``.
:mod:`django.contrib.gis`
-------------------------
* Support for PostGIS 2.3 is removed.
* Support for GDAL 2.0 and GEOS 3.5 is removed.
Dropped support for PostgreSQL 9.6
----------------------------------
Upstream support for PostgreSQL 9.6 ends in November 2021. Django 4.0 supports
PostgreSQL 10 and higher.
Also, the minimum supported version of ``psycopg2`` is increased from 2.5.4 to
2.8.4, as ``psycopg2`` 2.8.4 is the first release to support Python 3.8.
Dropped support for Oracle 12.2 and 18c
---------------------------------------
Upstream support for Oracle 12.2 ends in March 2022 and for Oracle 18c it ends
in June 2021. Django 3.2 will be supported until April 2024. Django 4.0
officially supports Oracle 19c.
.. _csrf-trusted-origins-changes-4.0:
``CSRF_TRUSTED_ORIGINS`` changes
--------------------------------
Format change
~~~~~~~~~~~~~
Values in the :setting:`CSRF_TRUSTED_ORIGINS` setting must include the scheme
(e.g. ``'http://'`` or ``'https://'``) instead of only the hostname.
Also, values that started with a dot, must now also include an asterisk before
the dot. For example, change ``'.example.com'`` to ``'https://*.example.com'``.
A system check detects any required changes.
Configuring it may now be required
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As CSRF protection now consults the ``Origin`` header, you may need to set
:setting:`CSRF_TRUSTED_ORIGINS`, particularly if you allow requests from
subdomains by setting :setting:`CSRF_COOKIE_DOMAIN` (or
:setting:`SESSION_COOKIE_DOMAIN` if :setting:`CSRF_USE_SESSIONS` is enabled) to
a value starting with a dot.
``SecurityMiddleware`` no longer sets the ``X-XSS-Protection`` header
---------------------------------------------------------------------
The :class:`~django.middleware.security.SecurityMiddleware` no longer sets the
``X-XSS-Protection`` header if the ``SECURE_BROWSER_XSS_FILTER`` setting is
``True``. The setting is removed.
Most modern browsers don't honor the ``X-XSS-Protection`` HTTP header. You can
use Content-Security-Policy_ without allowing ``'unsafe-inline'`` scripts
instead.
If you want to support legacy browsers and set the header, use this line in a
custom middleware::
response.headers.setdefault('X-XSS-Protection', '1; mode=block')
.. _Content-Security-Policy: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy
Migrations autodetector changes
-------------------------------
The migrations autodetector now uses model states instead of model classes.
Also, migration operations for ``ForeignKey`` and ``ManyToManyField`` fields no
longer specify attributes which were not passed to the fields during
initialization.
As a side-effect, running ``makemigrations`` might generate no-op
``AlterField`` operations for ``ManyToManyField`` and ``ForeignKey`` fields in
some cases.
``DeleteView`` changes
----------------------
:class:`~django.views.generic.edit.DeleteView` now uses
:class:`~django.views.generic.edit.FormMixin` to handle POST requests. As a
consequence, any custom deletion logic in ``delete()`` handlers should be
moved to ``form_valid()``, or a shared helper method, if required.
Table and column naming scheme changes on Oracle
------------------------------------------------
Django 4.0 inadvertently changed the table and column naming scheme on Oracle.
This causes errors for models and fields with names longer than 30 characters.
Unfortunately, renaming some Oracle tables and columns is required. Use the
upgrade script in :ticket:`33789 <33789comment:15>` to generate ``RENAME``
statements to change naming scheme.
Miscellaneous
-------------
* Support for ``cx_Oracle`` < 7.0 is removed.
* To allow serving a Django site on a subpath without changing the value of
:setting:`STATIC_URL`, the leading slash is removed from that setting (now
``'static/'``) in the default :djadmin:`startproject` template.
* The :class:`~django.contrib.admin.AdminSite` method for the admin ``index``
view is no longer decorated with ``never_cache`` when accessed directly,
rather than via the recommended ``AdminSite.urls`` property, or
``AdminSite.get_urls()`` method.
* Unsupported operations on a sliced queryset now raise ``TypeError`` instead
of ``AssertionError``.
* The undocumented ``django.test.runner.reorder_suite()`` function is renamed
to ``reorder_tests()``. It now accepts an iterable of tests rather than a
test suite, and returns an iterator of tests.
* Calling ``FileSystemStorage.delete()`` with an empty ``name`` now raises
``ValueError`` instead of ``AssertionError``.
* Calling ``EmailMultiAlternatives.attach_alternative()`` or
``EmailMessage.attach()`` with an invalid ``content`` or ``mimetype``
arguments now raise ``ValueError`` instead of ``AssertionError``.
* :meth:`~django.test.SimpleTestCase.assertHTMLEqual` no longer considers a
non-boolean attribute without a value equal to an attribute with the same
name and value.
* Tests that fail to load, for example due to syntax errors, now always match
when using :option:`test --tag`.
* The undocumented ``django.contrib.admin.utils.lookup_needs_distinct()``
function is renamed to ``lookup_spawns_duplicates()``.
* The undocumented ``HttpRequest.get_raw_uri()`` method is removed. The
:meth:`.HttpRequest.build_absolute_uri` method may be a suitable alternative.
* The ``object`` argument of undocumented ``ModelAdmin.log_addition()``,
``log_change()``, and ``log_deletion()`` methods is renamed to ``obj``.
* :class:`~django.utils.feedgenerator.RssFeed`,
:class:`~django.utils.feedgenerator.Atom1Feed`, and their subclasses now emit
elements with no content as self-closing tags.
* ``NodeList.render()`` no longer casts the output of ``render()`` method for
individual nodes to a string. ``Node.render()`` should always return a string
as documented.
* The ``where_class`` property of ``django.db.models.sql.query.Query`` and the
``where_class`` argument to the private ``get_extra_restriction()`` method of
``ForeignObject`` and ``ForeignObjectRel`` are removed. If needed, initialize
``django.db.models.sql.where.WhereNode`` instead.
* The ``filter_clause`` argument of the undocumented ``Query.add_filter()``
method is replaced by two positional arguments ``filter_lhs`` and
``filter_rhs``.
* :class:`~django.middleware.csrf.CsrfViewMiddleware` now uses
``request.META['CSRF_COOKIE_NEEDS_UPDATE']`` in place of
``request.META['CSRF_COOKIE_USED']``, ``request.csrf_cookie_needs_reset``,
and ``response.csrf_cookie_set`` to track whether the CSRF cookie should be
sent. This is an undocumented, private API.
* The undocumented ``TRANSLATOR_COMMENT_MARK`` constant is moved from
``django.template.base`` to ``django.utils.translation.template``.
* The ``real_apps`` argument of the undocumented
``django.db.migrations.state.ProjectState.__init__()`` method must now be a
set if provided.
* :class:`~django.forms.RadioSelect` and
:class:`~django.forms.CheckboxSelectMultiple` widgets are now rendered in
``<div>`` tags so they are announced more concisely by screen readers. If you
need the previous behavior, :ref:`override the widget template
<overriding-built-in-widget-templates>` with the appropriate template from
Django 3.2.
* The :tfilter:`floatformat` template filter no longer depends on the
``USE_L10N`` setting and always returns localized output. Use the ``u``
suffix to disable localization.
* The default value of the ``USE_L10N`` setting is changed to ``True``. See the
:ref:`Localization section <use_l10n_deprecation>` above for more details.
* As part of the :ref:`move to zoneinfo <whats-new-4.0>`,
:attr:`django.utils.timezone.utc` is changed to alias
:attr:`datetime.timezone.utc`.
* The minimum supported version of ``asgiref`` is increased from 3.3.2 to
3.4.1.
.. _deprecated-features-4.0:
Features deprecated in 4.0
==========================
Use of ``pytz`` time zones
--------------------------
As part of the :ref:`move to zoneinfo <whats-new-4.0>`, use of ``pytz`` time
zones is deprecated.
Accordingly, the ``is_dst`` arguments to the following are also deprecated:
* :meth:`django.db.models.query.QuerySet.datetimes`
* :func:`django.db.models.functions.Trunc`
* :func:`django.db.models.functions.TruncSecond`
* :func:`django.db.models.functions.TruncMinute`
* :func:`django.db.models.functions.TruncHour`
* :func:`django.db.models.functions.TruncDay`
* :func:`django.db.models.functions.TruncWeek`
* :func:`django.db.models.functions.TruncMonth`
* :func:`django.db.models.functions.TruncQuarter`
* :func:`django.db.models.functions.TruncYear`
* :func:`django.utils.timezone.make_aware`
Support for use of ``pytz`` will be removed in Django 5.0.
Time zone support
-----------------
In order to follow good practice, the default value of the :setting:`USE_TZ`
setting will change from ``False`` to ``True``, and time zone support will be
enabled by default, in Django 5.0.
Note that the default :file:`settings.py` file created by
:djadmin:`django-admin startproject <startproject>` includes
:setting:`USE_TZ = True <USE_TZ>` since Django 1.4.
You can set ``USE_TZ`` to ``False`` in your project settings before then to
opt-out.
.. _use_l10n_deprecation:
Localization
------------
In order to follow good practice, the default value of the ``USE_L10N`` setting
is changed from ``False`` to ``True``.
Moreover ``USE_L10N`` is deprecated as of this release. Starting with Django
5.0, by default, any date or number displayed by Django will be localized.
The :ttag:`{% localize %} <localize>` tag and the :tfilter:`localize`/
:tfilter:`unlocalize` filters will still be honored by Django.
Miscellaneous
-------------
* ``SERIALIZE`` test setting is deprecated as it can be inferred from the
:attr:`~django.test.TestCase.databases` with the
:ref:`serialized_rollback <test-case-serialized-rollback>` option enabled.
* The undocumented ``django.utils.baseconv`` module is deprecated.
* The undocumented ``django.utils.datetime_safe`` module is deprecated.
* The default sitemap protocol for sitemaps built outside the context of a
request will change from ``'http'`` to ``'https'`` in Django 5.0.
* The ``extra_tests`` argument for :meth:`.DiscoverRunner.build_suite` and
:meth:`.DiscoverRunner.run_tests` is deprecated.
* The :class:`~django.contrib.postgres.aggregates.ArrayAgg`,
:class:`~django.contrib.postgres.aggregates.JSONBAgg`, and
:class:`~django.contrib.postgres.aggregates.StringAgg` aggregates will return
``None`` when there are no rows instead of ``[]``, ``[]``, and ``''``
respectively in Django 5.0. If you need the
This PR pins django to the latest release 4.1.
Changelog
### 4.1 ``` ======================== *August 3, 2022* Welcome to Django 4.1! These release notes cover the :ref:`new features <whats-new-4.1>`, as well as some :ref:`backwards incompatible changes <backwards-incompatible-4.1>` you'll want to be aware of when upgrading from Django 4.0 or earlier. We've :ref:`begun the deprecation process for some features <deprecated-features-4.1>`. See the :doc:`/howto/upgrade-version` guide if you're updating an existing project. Python compatibility ==================== Django 4.1 supports Python 3.8, 3.9, and 3.10. We **highly recommend** and only officially support the latest release of each series. .. _whats-new-4.1: What's new in Django 4.1 ======================== Asynchronous handlers for class-based views ------------------------------------------- View subclasses may now define async HTTP method handlers:: import asyncio from django.http import HttpResponse from django.views import View class AsyncView(View): async def get(self, request, *args, **kwargs): Perform view logic using await. await asyncio.sleep(1) return HttpResponse("Hello async world!") See :ref:`async-class-based-views` for more details. Asynchronous ORM interface -------------------------- ``QuerySet`` now provides an asynchronous interface for all data access operations. These are named as-per the existing synchronous operations but with an ``a`` prefix, for example ``acreate()``, ``aget()``, and so on. The new interface allows you to write asynchronous code without needing to wrap ORM operations in ``sync_to_async()``:: async for author in Author.objects.filter(name__startswith="A"): book = await author.books.afirst() Note that, at this stage, the underlying database operations remain synchronous, with contributions ongoing to push asynchronous support down into the SQL compiler, and integrate asynchronous database drivers. The new asynchronous queryset interface currently encapsulates the necessary ``sync_to_async()`` operations for you, and will allow your code to take advantage of developments in the ORM's asynchronous support as it evolves. See :ref:`async-queries` for details and limitations. Validation of Constraints ------------------------- :class:`Check <django.db.models.CheckConstraint>`, :class:`unique <django.db.models.UniqueConstraint>`, and :class:`exclusion <django.contrib.postgres.constraints.ExclusionConstraint>` constraints defined in the :attr:`Meta.constraints <django.db.models.Options.constraints>` option are now checked during :ref:`model validation <validating-objects>`. Form rendering accessibility ---------------------------- In order to aid users with screen readers, and other assistive technology, new ``<div>`` based form templates are available from this release. These provide more accessible navigation than the older templates, and are able to correctly group related controls, such as radio-lists, into fieldsets. The new templates are recommended, and will become the default form rendering style when outputting a form, like ``{{ form }}`` in a template, from Django 5.0. In order to ease adopting the new output style, the default form and formset templates are now configurable at the project level via the :setting:`FORM_RENDERER` setting. See :ref:`the Forms section (below)<forms-4.1>` for full details. .. _csrf-cookie-masked-usage: ``CSRF_COOKIE_MASKED`` setting ------------------------------ The new :setting:`CSRF_COOKIE_MASKED` transitional setting allows specifying whether to mask the CSRF cookie. :class:`~django.middleware.csrf.CsrfViewMiddleware` no longer masks the CSRF cookie like it does the CSRF token in the DOM. If you are upgrading multiple instances of the same project to Django 4.1, you should set :setting:`CSRF_COOKIE_MASKED` to ``True`` during the transition, in order to allow compatibility with the older versions of Django. Once the transition to 4.1 is complete you can stop overriding :setting:`CSRF_COOKIE_MASKED`. This setting is deprecated as of this release and will be removed in Django 5.0. Minor features -------------- :mod:`django.contrib.admin` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ * The admin :ref:`dark mode CSS variables <admin-theming>` are now applied in a separate stylesheet and template block. * :ref:`modeladmin-list-filters` providing custom ``FieldListFilter`` subclasses can now control the query string value separator when filtering for multiple values using the ``__in`` lookup. * The admin :meth:`history view <django.contrib.admin.ModelAdmin.history_view>` is now paginated. * Related widget wrappers now have a link to object's change form. * The :meth:`.AdminSite.get_app_list` method now allows changing the order of apps and models on the admin index page. :mod:`django.contrib.auth` ~~~~~~~~~~~~~~~~~~~~~~~~~~ * The default iteration count for the PBKDF2 password hasher is increased from 320,000 to 390,000. * The :meth:`.RemoteUserBackend.configure_user` method now allows synchronizing user attributes with attributes in a remote system such as an LDAP directory. :mod:`django.contrib.gis` ~~~~~~~~~~~~~~~~~~~~~~~~~ * The new :meth:`.GEOSGeometry.make_valid()` method allows converting invalid geometries to valid ones. * The new ``clone`` argument for :meth:`.GEOSGeometry.normalize` allows creating a normalized clone of the geometry. :mod:`django.contrib.postgres` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * The new :class:`BitXor() <django.contrib.postgres.aggregates.BitXor>` aggregate function returns an ``int`` of the bitwise ``XOR`` of all non-null input values. * :class:`~django.contrib.postgres.indexes.SpGistIndex` now supports covering indexes on PostgreSQL 14+. * :class:`~django.contrib.postgres.constraints.ExclusionConstraint` now supports covering exclusion constraints using SP-GiST indexes on PostgreSQL 14+. * The new ``default_bounds`` attribute of :attr:`DateTimeRangeField <django.contrib.postgres.fields.DateTimeRangeField.default_bounds>` and :attr:`DecimalRangeField <django.contrib.postgres.fields.DecimalRangeField.default_bounds>` allows specifying bounds for list and tuple inputs. * :class:`~django.contrib.postgres.constraints.ExclusionConstraint` now allows specifying operator classes with the :class:`OpClass() <django.contrib.postgres.indexes.OpClass>` expression. :mod:`django.contrib.sitemaps` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * The default sitemap index template ``<sitemapindex>`` now includes the ``<lastmod>`` timestamp where available, through the new :meth:`~django.contrib.sitemaps.Sitemap.get_latest_lastmod` method. Custom sitemap index templates should be updated for the adjusted :ref:`context variables <sitemap-index-context-variables>`. :mod:`django.contrib.staticfiles` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage` now replaces paths to CSS source map references with their hashed counterparts. Database backends ~~~~~~~~~~~~~~~~~ * Third-party database backends can now specify the minimum required version of the database using the ``DatabaseFeatures.minimum_database_version`` attribute which is a tuple (e.g. ``(10, 0)`` means "10.0"). If a minimum version is specified, backends must also implement ``DatabaseWrapper.get_database_version()``, which returns a tuple of the current database version. The backend's ``DatabaseWrapper.init_connection_state()`` method must call ``super()`` in order for the check to run. .. _forms-4.1: Forms ~~~~~ * The default template used to render forms when cast to a string, e.g. in templates as ``{{ form }}``, is now configurable at the project-level by setting :attr:`~django.forms.renderers.BaseRenderer.form_template_name` on the class provided for :setting:`FORM_RENDERER`. :attr:`.Form.template_name` is now a property deferring to the renderer, but may be overridden with a string value to specify the template name per-form class. Similarly, the default template used to render formsets can be specified via the matching :attr:`~django.forms.renderers.BaseRenderer.formset_template_name` renderer attribute. * The new ``div.html`` form template, referencing :attr:`.Form.template_name_div` attribute, and matching :meth:`.Form.as_div` method, render forms using HTML ``<div>`` elements. This new output style is recommended over the existing :meth:`~.Form.as_table`, :meth:`~.Form.as_p` and :meth:`~.Form.as_ul` styles, as the template implements ``<fieldset>`` and ``<legend>`` to group related inputs and is easier for screen reader users to navigate. The div-based output will become the default rendering style from Django 5.0. * In order to smooth adoption of the new ``<div>`` output style, two transitional form renderer classes are available: :class:`django.forms.renderers.DjangoDivFormRenderer` and :class:`django.forms.renderers.Jinja2DivFormRenderer`, for the Django and Jinja2 template backends respectively. You can apply one of these via the :setting:`FORM_RENDERER` setting. For example:: FORM_RENDERER = "django.forms.renderers.DjangoDivFormRenderer" Once the ``<div>`` output style is the default, from Django 5.0, these transitional renderers will be deprecated, for removal in Django 6.0. The ``FORM_RENDERER`` declaration can be removed at that time. * If the new ``<div>`` output style is not appropriate for your project, you should define a renderer subclass specifying :attr:`~django.forms.renderers.BaseRenderer.form_template_name` and :attr:`~django.forms.renderers.BaseRenderer.formset_template_name` for your required style, and set :setting:`FORM_RENDERER` accordingly. For example, for the ``<p>`` output style used by :meth:`~.Form.as_p`, you would define a form renderer setting ``form_template_name`` to ``"django/forms/p.html"`` and ``formset_template_name`` to ``"django/forms/formsets/p.html"``. * The new :meth:`~django.forms.BoundField.legend_tag` allows rendering field labels in ``<legend>`` tags via the new ``tag`` argument of :meth:`~django.forms.BoundField.label_tag`. * The new ``edit_only`` argument for :func:`.modelformset_factory` and :func:`.inlineformset_factory` allows preventing new objects creation. * The ``js`` and ``css`` class attributes of :doc:`Media </topics/forms/media>` now allow using hashable objects, not only path strings, as long as those objects implement the ``__html__()`` method (typically when decorated with the :func:`~django.utils.html.html_safe` decorator). * The new :attr:`.BoundField.use_fieldset` and :attr:`.Widget.use_fieldset` attributes help to identify widgets where its inputs should be grouped in a ``<fieldset>`` with a ``<legend>``. * The :ref:`formsets-error-messages` argument for :class:`~django.forms.formsets.BaseFormSet` now allows customizing error messages for invalid number of forms by passing ``'too_few_forms'`` and ``'too_many_forms'`` keys. * :class:`~django.forms.IntegerField`, :class:`~django.forms.FloatField`, and :class:`~django.forms.DecimalField` now optionally accept a ``step_size`` argument. This is used to set the ``step`` HTML attribute, and is validated on form submission. Internationalization ~~~~~~~~~~~~~~~~~~~~ * The :func:`~django.conf.urls.i18n.i18n_patterns` function now supports languages with both scripts and regions. Management Commands ~~~~~~~~~~~~~~~~~~~ * :option:`makemigrations --no-input` now logs default answers and reasons why migrations cannot be created. * The new :option:`makemigrations --scriptable` option diverts log output and input prompts to ``stderr``, writing only paths of generated migration files to ``stdout``. * The new :option:`migrate --prune` option allows deleting nonexistent migrations from the ``django_migrations`` table. * Python files created by :djadmin:`startproject`, :djadmin:`startapp`, :djadmin:`optimizemigration`, :djadmin:`makemigrations`, and :djadmin:`squashmigrations` are now formatted using the ``black`` command if it is present on your ``PATH``. * The new :djadmin:`optimizemigration` command allows optimizing operations for a migration. Migrations ~~~~~~~~~~ * The new :class:`~django.db.migrations.operations.RenameIndex` operation allows renaming indexes defined in the :attr:`Meta.indexes <django.db.models.Options.indexes>` or :attr:`~django.db.models.Options.index_together` options. * The migrations autodetector now generates :class:`~django.db.migrations.operations.RenameIndex` operations instead of ``RemoveIndex`` and ``AddIndex``, when renaming indexes defined in the :attr:`Meta.indexes <django.db.models.Options.indexes>`. * The migrations autodetector now generates :class:`~django.db.migrations.operations.RenameIndex` operations instead of ``AlterIndexTogether`` and ``AddIndex``, when moving indexes defined in the :attr:`Meta.index_together <django.db.models.Options.index_together>` to the :attr:`Meta.indexes <django.db.models.Options.indexes>`. Models ~~~~~~ * The ``order_by`` argument of the :class:`~django.db.models.expressions.Window` expression now accepts string references to fields and transforms. * The new :setting:`CONN_HEALTH_CHECKS` setting allows enabling health checks for :ref:`persistent database connections <persistent-database-connections>` in order to reduce the number of failed requests, e.g. after database server restart. * :meth:`.QuerySet.bulk_create` now supports updating fields when a row insertion fails uniqueness constraints. This is supported on MariaDB, MySQL, PostgreSQL, and SQLite 3.24+. * :meth:`.QuerySet.iterator` now supports prefetching related objects as long as the ``chunk_size`` argument is provided. In older versions, no prefetching was done. * :class:`~django.db.models.Q` objects and querysets can now be combined using ``^`` as the exclusive or (``XOR``) operator. ``XOR`` is natively supported on MariaDB and MySQL. For databases that do not support ``XOR``, the query will be converted to an equivalent using ``AND``, ``OR``, and ``NOT``. * The new :ref:`Field.non_db_attrs <custom-field-non_db_attrs>` attribute allows customizing attributes of fields that don't affect a column definition. * On PostgreSQL, ``AutoField``, ``BigAutoField``, and ``SmallAutoField`` are now created as identity columns rather than serial columns with sequences. Requests and Responses ~~~~~~~~~~~~~~~~~~~~~~ * :meth:`.HttpResponse.set_cookie` now supports :class:`~datetime.timedelta` objects for the ``max_age`` argument. Security ~~~~~~~~ * The new :setting:`SECRET_KEY_FALLBACKS` setting allows providing a list of values for secret key rotation. * The :setting:`SECURE_PROXY_SSL_HEADER` setting now supports a comma-separated list of protocols in the header value. Signals ~~~~~~~ * The :data:`~django.db.models.signals.pre_delete` and :data:`~django.db.models.signals.post_delete` signals now dispatch the ``origin`` of the deletion. .. _templates-4.1: Templates ~~~~~~~~~ * The HTML ``<script>`` element ``id`` attribute is no longer required when wrapping the :tfilter:`json_script` template filter. * The :class:`cached template loader <django.template.loaders.cached.Loader>` is now enabled in development, when :setting:`DEBUG` is ``True``, and :setting:`OPTIONS['loaders'] <TEMPLATES-OPTIONS>` isn't specified. You may specify ``OPTIONS['loaders']`` to override this, if necessary. Tests ~~~~~ * The :class:`.DiscoverRunner` now supports running tests in parallel on macOS, Windows, and any other systems where the default :mod:`multiprocessing` start method is ``spawn``. * A nested atomic block marked as durable in :class:`django.test.TestCase` now raises a ``RuntimeError``, the same as outside of tests. * :meth:`.SimpleTestCase.assertFormError` and :meth:`~.SimpleTestCase.assertFormsetError` now support passing a form/formset object directly. URLs ~~~~ * The new :attr:`.ResolverMatch.captured_kwargs` attribute stores the captured keyword arguments, as parsed from the URL. * The new :attr:`.ResolverMatch.extra_kwargs` attribute stores the additional keyword arguments passed to the view function. Utilities ~~~~~~~~~ * ``SimpleLazyObject`` now supports addition operations. * :func:`~django.utils.safestring.mark_safe` now preserves lazy objects. Validators ~~~~~~~~~~ * The new :class:`~django.core.validators.StepValueValidator` checks if a value is an integral multiple of a given step size. This new validator is used for the new ``step_size`` argument added to form fields representing numeric values. .. _backwards-incompatible-4.1: Backwards incompatible changes in 4.1 ===================================== Database backend API -------------------- This section describes changes that may be needed in third-party database backends. * ``BaseDatabaseFeatures.has_case_insensitive_like`` is changed from ``True`` to ``False`` to reflect the behavior of most databases. * ``DatabaseIntrospection.get_key_columns()`` is removed. Use ``DatabaseIntrospection.get_relations()`` instead. * ``DatabaseOperations.ignore_conflicts_suffix_sql()`` method is replaced by ``DatabaseOperations.on_conflict_suffix_sql()`` that accepts the ``fields``, ``on_conflict``, ``update_fields``, and ``unique_fields`` arguments. * The ``ignore_conflicts`` argument of the ``DatabaseOperations.insert_statement()`` method is replaced by ``on_conflict`` that accepts ``django.db.models.constants.OnConflict``. * ``DatabaseOperations._convert_field_to_tz()`` is replaced by ``DatabaseOperations._convert_sql_to_tz()`` that accepts the ``sql``, ``params``, and ``tzname`` arguments. * Several date and time methods on ``DatabaseOperations`` now take ``sql`` and ``params`` arguments instead of ``field_name`` and return 2-tuple containing some SQL and the parameters to be interpolated into that SQL. The changed methods have these new signatures: * ``DatabaseOperations.date_extract_sql(lookup_type, sql, params)`` * ``DatabaseOperations.datetime_extract_sql(lookup_type, sql, params, tzname)`` * ``DatabaseOperations.time_extract_sql(lookup_type, sql, params)`` * ``DatabaseOperations.date_trunc_sql(lookup_type, sql, params, tzname=None)`` * ``DatabaseOperations.datetime_trunc_sql(self, lookup_type, sql, params, tzname)`` * ``DatabaseOperations.time_trunc_sql(lookup_type, sql, params, tzname=None)`` * ``DatabaseOperations.datetime_cast_date_sql(sql, params, tzname)`` * ``DatabaseOperations.datetime_cast_time_sql(sql, params, tzname)`` :mod:`django.contrib.gis` ------------------------- * Support for GDAL 2.1 is removed. * Support for PostGIS 2.4 is removed. Dropped support for PostgreSQL 10 --------------------------------- Upstream support for PostgreSQL 10 ends in November 2022. Django 4.1 supports PostgreSQL 11 and higher. Dropped support for MariaDB 10.2 -------------------------------- Upstream support for MariaDB 10.2 ends in May 2022. Django 4.1 supports MariaDB 10.3 and higher. Admin changelist searches spanning multi-valued relationships changes --------------------------------------------------------------------- Admin changelist searches using multiple search terms are now applied in a single call to ``filter()``, rather than in sequential ``filter()`` calls. For multi-valued relationships, this means that rows from the related model must match all terms rather than any term. For example, if ``search_fields`` is set to ``['child__name', 'child__age']``, and a user searches for ``'Jamal 17'``, parent rows will be returned only if there is a relationship to some 17-year-old child named Jamal, rather than also returning parents who merely have a younger or older child named Jamal in addition to some other 17-year-old. See the :ref:`spanning-multi-valued-relationships` topic for more discussion of this difference. In Django 4.0 and earlier, :meth:`~django.contrib.admin.ModelAdmin.get_search_results` followed the second example query, but this undocumented behavior led to queries with excessive joins. Reverse foreign key changes for unsaved model instances ------------------------------------------------------- In order to unify the behavior with many-to-many relations for unsaved model instances, a reverse foreign key now raises ``ValueError`` when calling :class:`related managers <django.db.models.fields.related.RelatedManager>` for unsaved objects. Miscellaneous ------------- * Related managers for :class:`~django.db.models.ForeignKey`, :class:`~django.db.models.ManyToManyField`, and :class:`~django.contrib.contenttypes.fields.GenericRelation` are now cached on the :class:`~django.db.models.Model` instance to which they belong. * The Django test runner now returns a non-zero error code for unexpected successes from tests marked with :py:func:`unittest.expectedFailure`. * :class:`~django.middleware.csrf.CsrfViewMiddleware` no longer masks the CSRF cookie like it does the CSRF token in the DOM. * :class:`~django.middleware.csrf.CsrfViewMiddleware` now uses ``request.META['CSRF_COOKIE']`` for storing the unmasked CSRF secret rather than a masked version. This is an undocumented, private API. * The :attr:`.ModelAdmin.actions` and :attr:`~django.contrib.admin.ModelAdmin.inlines` attributes now default to an empty tuple rather than an empty list to discourage unintended mutation. * The ``type="text/css"`` attribute is no longer included in ``<link>`` tags for CSS :doc:`form media </topics/forms/media>`. * ``formset:added`` and ``formset:removed`` JavaScript events are now pure JavaScript events and don't depend on jQuery. See :ref:`admin-javascript-inline-form-events` for more details on the change. * The ``exc_info`` argument of the undocumented ``django.utils.log.log_response()`` function is replaced by ``exception``. * The ``size`` argument of the undocumented ``django.views.static.was_modified_since()`` function is removed. * The admin log out UI now uses ``POST`` requests. * The undocumented ``InlineAdminFormSet.non_form_errors`` property is replaced by the ``non_form_errors()`` method. This is consistent with ``BaseFormSet``. * As per :ref:`above<templates-4.1>`, the cached template loader is now enabled in development. You may specify ``OPTIONS['loaders']`` to override this, if necessary. * The undocumented ``django.contrib.auth.views.SuccessURLAllowedHostsMixin`` mixin is replaced by ``RedirectURLMixin``. * :class:`~django.db.models.BaseConstraint` subclasses must implement :meth:`~django.db.models.BaseConstraint.validate` method to allow those constraints to be used for validation. * The undocumented ``URLResolver._is_callback()``, ``URLResolver._callback_strs``, and ``URLPattern.lookup_str()`` are moved to ``django.contrib.admindocs.utils``. * The :meth:`.Model.full_clean` method now converts an ``exclude`` value to a ``set``. It’s also preferable to pass an ``exclude`` value as a ``set`` to the :meth:`.Model.clean_fields`, :meth:`.Model.full_clean`, :meth:`.Model.validate_unique`, and :meth:`.Model.validate_constraints` methods. * The minimum supported version of ``asgiref`` is increased from 3.4.1 to 3.5.2. .. _deprecated-features-4.1: Features deprecated in 4.1 ========================== Log out via GET --------------- Logging out via ``GET`` requests to the :py:class:`built-in logout view <django.contrib.auth.views.LogoutView>` is deprecated. Use ``POST`` requests instead. If you want to retain the user experience of an HTML link, you can use a form that is styled to appear as a link: .. code-block:: html <form id="logout-form" method="post" action="{% url 'admin:logout' %}"> {% csrf_token %} <button type="submit">{% translate "Log out" %}</button> </form> .. code-block:: css logout-form { display: inline; } logout-form button { background: none; border: none; cursor: pointer; padding: 0; text-decoration: underline; } Miscellaneous ------------- * The context for sitemap index templates of a flat list of URLs is deprecated. Custom sitemap index templates should be updated for the adjusted :ref:`context variables <sitemap-index-context-variables>`, expecting a list of objects with ``location`` and optional ``lastmod`` attributes. * ``CSRF_COOKIE_MASKED`` transitional setting is deprecated. * The ``name`` argument of :func:`django.utils.functional.cached_property` is deprecated as it's unnecessary as of Python 3.6. * The ``opclasses`` argument of ``django.contrib.postgres.constraints.ExclusionConstraint`` is deprecated in favor of using :class:`OpClass() <django.contrib.postgres.indexes.OpClass>` in :attr:`.ExclusionConstraint.expressions`. To use it, you need to add ``'django.contrib.postgres'`` in your :setting:`INSTALLED_APPS`. After making this change, :djadmin:`makemigrations` will generate a new migration with two operations: ``RemoveConstraint`` and ``AddConstraint``. Since this change has no effect on the database schema, the :class:`~django.db.migrations.operations.SeparateDatabaseAndState` operation can be used to only update the migration state without running any SQL. Move the generated operations into the ``state_operations`` argument of :class:`~django.db.migrations.operations.SeparateDatabaseAndState`. For example:: class Migration(migrations.Migration): ... operations = [ migrations.SeparateDatabaseAndState( database_operations=[], state_operations=[ migrations.RemoveConstraint( ... ), migrations.AddConstraint( ... ), ], ), ] * The undocumented ability to pass ``errors=None`` to :meth:`.SimpleTestCase.assertFormError` and :meth:`~.SimpleTestCase.assertFormsetError` is deprecated. Use ``errors=[]`` instead. * ``django.contrib.sessions.serializers.PickleSerializer`` is deprecated due to the risk of remote code execution. * The usage of ``QuerySet.iterator()`` on a queryset that prefetches related objects without providing the ``chunk_size`` argument is deprecated. In older versions, no prefetching was done. Providing a value for ``chunk_size`` signifies that the additional query per chunk needed to prefetch is desired. * Passing unsaved model instances to related filters is deprecated. In Django 5.0, the exception will be raised. * ``created=True`` is added to the signature of :meth:`.RemoteUserBackend.configure_user`. Support for ``RemoteUserBackend`` subclasses that do not accept this argument is deprecated. * The :data:`django.utils.timezone.utc` alias to :attr:`datetime.timezone.utc` is deprecated. Use :attr:`datetime.timezone.utc` directly. * Passing a response object and a form/formset name to ``SimpleTestCase.assertFormError()`` and ``assertFormsetError()`` is deprecated. Use:: assertFormError(response.context['form_name'], …) assertFormsetError(response.context['formset_name'], …) or pass the form/formset object directly instead. * The undocumented ``django.contrib.gis.admin.OpenLayersWidget`` is deprecated. * ``django.contrib.auth.hashers.CryptPasswordHasher`` is deprecated. * The ability to pass ``nulls_first=False`` or ``nulls_last=False`` to ``Expression.asc()`` and ``Expression.desc()`` methods, and the ``OrderBy`` expression is deprecated. Use ``None`` instead. * The ``"django/forms/default.html"`` and ``"django/forms/formsets/default.html"`` templates which are a proxy to the table-based templates are deprecated. Use the specific template instead. Features removed in 4.1 ======================= These features have reached the end of their deprecation cycle and are removed in Django 4.1. See :ref:`deprecated-features-3.2` for details on these changes, including how to remove usage of these features. * Support for assigning objects which don't support creating deep copies with ``copy.deepcopy()`` to class attributes in ``TestCase.setUpTestData()`` is removed. * Support for using a boolean value in :attr:`.BaseCommand.requires_system_checks` is removed. * The ``whitelist`` argument and ``domain_whitelist`` attribute of ``django.core.validators.EmailValidator`` are removed. * The ``default_app_config`` application configuration variable is removed. * ``TransactionTestCase.assertQuerysetEqual()`` no longer calls ``repr()`` on a queryset when compared to string values. * The ``django.core.cache.backends.memcached.MemcachedCache`` backend is removed. * Support for the pre-Django 3.2 format of messages used by ``django.contrib.messages.storage.cookie.CookieStorage`` is removed. ========================== ``` ### 4.0.7 ``` ========================== *August 3, 2022* Django 4.0.7 fixes a security issue with severity "high" in 4.0.6. CVE-2022-36359: Potential reflected file download vulnerability in ``FileResponse`` =================================================================================== An application may have been vulnerable to a reflected file download (RFD) attack that sets the Content-Disposition header of a :class:`~django.http.FileResponse` when the ``filename`` was derived from user-supplied input. The ``filename`` is now escaped to avoid this possibility. ========================== ``` ### 4.0.6 ``` ========================== *July 4, 2022* Django 4.0.6 fixes a security issue with severity "high" in 4.0.5. CVE-2022-34265: Potential SQL injection via ``Trunc(kind)`` and ``Extract(lookup_name)`` arguments ================================================================================================== :class:`Trunc() <django.db.models.functions.Trunc>` and :class:`Extract() <django.db.models.functions.Extract>` database functions were subject to SQL injection if untrusted data was used as a ``kind``/``lookup_name`` value. Applications that constrain the lookup name and kind choice to a known safe list are unaffected. ========================== ``` ### 4.0.5 ``` ========================== *June 1, 2022* Django 4.0.5 fixes several bugs in 4.0.4. Bugfixes ======== * Fixed a bug in Django 4.0 where not all :setting:`OPTIONS <CACHES-OPTIONS>` were passed to a Redis client (:ticket:`33681`). * Fixed a bug in Django 4.0 that caused a crash of ``QuerySet.filter()`` on ``IsNull()`` expressions (:ticket:`33705`). * Fixed a bug in Django 4.0 where a hidden quick filter toolbar in the admin's navigation sidebar was focusable (:ticket:`33725`). ========================== ``` ### 4.0.4 ``` ========================== *April 11, 2022* Django 4.0.4 fixes two security issues with severity "high" and two bugs in 4.0.3. CVE-2022-28346: Potential SQL injection in ``QuerySet.annotate()``, ``aggregate()``, and ``extra()`` ==================================================================================================== :meth:`.QuerySet.annotate`, :meth:`~.QuerySet.aggregate`, and :meth:`~.QuerySet.extra` methods were subject to SQL injection in column aliases, using a suitably crafted dictionary, with dictionary expansion, as the ``**kwargs`` passed to these methods. CVE-2022-28347: Potential SQL injection via ``QuerySet.explain(**options)`` on PostgreSQL ========================================================================================= :meth:`.QuerySet.explain` method was subject to SQL injection in option names, using a suitably crafted dictionary, with dictionary expansion, as the ``**options`` argument. Bugfixes ======== * Fixed a regression in Django 4.0 that caused ignoring multiple ``FilteredRelation()`` relationships to the same field (:ticket:`33598`). * Fixed a regression in Django 3.2.4 that caused the auto-reloader to no longer detect changes when the ``DIRS`` option of the ``TEMPLATES`` setting contained an empty string (:ticket:`33628`). ========================== ``` ### 4.0.3 ``` ========================== *March 1, 2022* Django 4.0.3 fixes several bugs in 4.0.2. Also, all Python code in Django is reformatted with `black`_. .. _black: https://pypi.org/project/black/ Bugfixes ======== * Prevented, following a regression in Django 4.0.1, :djadmin:`makemigrations` from generating infinite migrations for a model with ``ManyToManyField`` to a lowercased swappable model such as ``'auth.user'`` (:ticket:`33515`). * Fixed a regression in Django 4.0 that caused a crash when rendering invalid inlines with :attr:`~django.contrib.admin.ModelAdmin.readonly_fields` in the admin (:ticket:`33547`). ========================== ``` ### 4.0.2 ``` ========================== *February 1, 2022* Django 4.0.2 fixes two security issues with severity "medium" and several bugs in 4.0.1. Also, the latest string translations from Transifex are incorporated, with a special mention for Bulgarian (fully translated). CVE-2022-22818: Possible XSS via ``{% debug %}`` template tag ============================================================= The ``{% debug %}`` template tag didn't properly encode the current context, posing an XSS attack vector. In order to avoid this vulnerability, ``{% debug %}`` no longer outputs information when the ``DEBUG`` setting is ``False``, and it ensures all context variables are correctly escaped when the ``DEBUG`` setting is ``True``. CVE-2022-23833: Denial-of-service possibility in file uploads ============================================================= Passing certain inputs to multipart forms could result in an infinite loop when parsing files. Bugfixes ======== * Fixed a bug in Django 4.0 where ``TestCase.captureOnCommitCallbacks()`` could execute callbacks multiple times (:ticket:`33410`). * Fixed a regression in Django 4.0 where ``help_text`` was HTML-escaped in automatically-generated forms (:ticket:`33419`). * Fixed a regression in Django 4.0 that caused displaying an incorrect name for class-based views on the technical 404 debug page (:ticket:`33425`). * Fixed a regression in Django 4.0 that caused an incorrect ``repr`` of ``ResolverMatch`` for class-based views (:ticket:`33426`). * Fixed a regression in Django 4.0 that caused a crash of ``makemigrations`` on models without ``Meta.order_with_respect_to`` but with a field named ``_order`` (:ticket:`33449`). * Fixed a regression in Django 4.0 that caused incorrect :attr:`.ModelAdmin.radio_fields` layout in the admin (:ticket:`33407`). * Fixed a duplicate operation regression in Django 4.0 that caused a migration crash when altering a primary key type for a concrete parent model referenced by a foreign key (:ticket:`33462`). * Fixed a bug in Django 4.0 that caused a crash of ``QuerySet.aggregate()`` after ``annotate()`` on an aggregate function with a :ref:`default <aggregate-default>` (:ticket:`33468`). * Fixed a regression in Django 4.0 that caused a crash of ``makemigrations`` when renaming a field of a renamed model (:ticket:`33480`). ========================== ``` ### 4.0.1 ``` ========================== *January 4, 2022* Django 4.0.1 fixes one security issue with severity "medium", two security issues with severity "low", and several bugs in 4.0. CVE-2021-45115: Denial-of-service possibility in ``UserAttributeSimilarityValidator`` ===================================================================================== :class:`.UserAttributeSimilarityValidator` incurred significant overhead evaluating submitted password that were artificially large in relative to the comparison values. On the assumption that access to user registration was unrestricted this provided a potential vector for a denial-of-service attack. In order to mitigate this issue, relatively long values are now ignored by ``UserAttributeSimilarityValidator``. This issue has severity "medium" according to the :ref:`Django security policy <security-disclosure>`. CVE-2021-45116: Potential information disclosure in ``dictsort`` template filter ================================================================================ Due to leveraging the Django Template Language's variable resolution logic, the :tfilter:`dictsort` template filter was potentially vulnerable to information disclosure or unintended method calls, if passed a suitably crafted key. In order to avoid this possibility, ``dictsort`` now works with a restricted resolution logic, that will not call methods, nor allow indexing on dictionaries. As a reminder, all untrusted user input should be validated before use. This issue has severity "low" according to the :ref:`Django security policy <security-disclosure>`. CVE-2021-45452: Potential directory-traversal via ``Storage.save()`` ==================================================================== ``Storage.save()`` allowed directory-traversal if directly passed suitably crafted file names. This issue has severity "low" according to the :ref:`Django security policy <security-disclosure>`. Bugfixes ======== * Fixed a regression in Django 4.0 that caused a crash of :meth:`~django.test.SimpleTestCase.assertFormsetError` on a formset named ``form`` (:ticket:`33346`). * Fixed a bug in Django 4.0 that caused a crash on booleans with the ``RedisCache`` backend (:ticket:`33361`). * Relaxed the check added in Django 4.0 to reallow use of a duck-typed ``HttpRequest`` in ``django.views.decorators.cache.cache_control()`` and ``never_cache()`` decorators (:ticket:`33350`). * Fixed a regression in Django 4.0 that caused creating bogus migrations for models that reference swappable models such as ``auth.User`` (:ticket:`33366`). * Fixed a long standing bug in :ref:`geos-geometry-collections` and :class:`~django.contrib.gis.geos.Polygon` that caused a crash on some platforms (reported on macOS based on the ``ARM64`` architecture) (:ticket:`32600`). ======================== ``` ### 4.0 ``` ======================== *December 7, 2021* Welcome to Django 4.0! These release notes cover the :ref:`new features <whats-new-4.0>`, as well as some :ref:`backwards incompatible changes <backwards-incompatible-4.0>` you'll want to be aware of when upgrading from Django 3.2 or earlier. We've :ref:`begun the deprecation process for some features <deprecated-features-4.0>`. See the :doc:`/howto/upgrade-version` guide if you're updating an existing project. Python compatibility ==================== Django 4.0 supports Python 3.8, 3.9, and 3.10. We **highly recommend** and only officially support the latest release of each series. The Django 3.2.x series is the last to support Python 3.6 and 3.7. .. _whats-new-4.0: What's new in Django 4.0 ======================== ``zoneinfo`` default timezone implementation -------------------------------------------- The Python standard library's :mod:`zoneinfo` is now the default timezone implementation in Django. This is the next step in the migration from using ``pytz`` to using :mod:`zoneinfo`. Django 3.2 allowed the use of non-``pytz`` time zones. Django 4.0 makes ``zoneinfo`` the default implementation. Support for ``pytz`` is now deprecated and will be removed in Django 5.0. :mod:`zoneinfo` is part of the Python standard library from Python 3.9. The ``backports.zoneinfo`` package is automatically installed alongside Django if you are using Python 3.8. The move to ``zoneinfo`` should be largely transparent. Selection of the current timezone, conversion of datetime instances to the current timezone in forms and templates, as well as operations on aware datetimes in UTC are unaffected. However, if you are working with non-UTC time zones, and using the ``pytz`` ``normalize()`` and ``localize()`` APIs, possibly with the :setting:`TIME_ZONE <DATABASE-TIME_ZONE>` setting, you will need to audit your code, since ``pytz`` and ``zoneinfo`` are not entirely equivalent. To give time for such an audit, the transitional :setting:`USE_DEPRECATED_PYTZ` setting allows continued use of ``pytz`` during the 4.x release cycle. This setting will be removed in Django 5.0. In addition, a `pytz_deprecation_shim`_ package, created by the ``zoneinfo`` author, can be used to assist with the migration from ``pytz``. This package provides shims to help you safely remove ``pytz``, and has a detailed `migration guide`_ showing how to move to the new ``zoneinfo`` APIs. Using `pytz_deprecation_shim`_ and the :setting:`USE_DEPRECATED_PYTZ` transitional setting is recommended if you need a gradual update path. .. _pytz_deprecation_shim: https://pytz-deprecation-shim.readthedocs.io/en/latest/index.html .. _migration guide: https://pytz-deprecation-shim.readthedocs.io/en/latest/migration.html Functional unique constraints ----------------------------- The new :attr:`*expressions <django.db.models.UniqueConstraint.expressions>` positional argument of :class:`UniqueConstraint() <django.db.models.UniqueConstraint>` enables creating functional unique constraints on expressions and database functions. For example:: from django.db import models from django.db.models import UniqueConstraint from django.db.models.functions import Lower class MyModel(models.Model): first_name = models.CharField(max_length=255) last_name = models.CharField(max_length=255) class Meta: constraints = [ UniqueConstraint( Lower('first_name'), Lower('last_name').desc(), name='first_last_name_unique', ), ] Functional unique constraints are added to models using the :attr:`Meta.constraints <django.db.models.Options.constraints>` option. ``scrypt`` password hasher -------------------------- The new :ref:`scrypt password hasher <scrypt-usage>` is more secure and recommended over PBKDF2. However, it's not the default as it requires OpenSSL 1.1+ and more memory. Redis cache backend ------------------- The new ``django.core.cache.backends.redis.RedisCache`` cache backend provides built-in support for caching with Redis. `redis-py`_ 3.0.0 or higher is required. For more details, see the :ref:`documentation on caching with Redis in Django <redis>`. .. _`redis-py`: https://pypi.org/project/redis/ Template based form rendering ----------------------------- :class:`Forms <django.forms.Form>`, :doc:`Formsets </topics/forms/formsets>`, and :class:`~django.forms.ErrorList` are now rendered using the template engine to enhance customization. See the new :meth:`~django.forms.Form.render`, :meth:`~django.forms.Form.get_context`, and :attr:`~django.forms.Form.template_name` for ``Form`` and :ref:`formset rendering <formset-rendering>` for ``Formset``. Minor features -------------- :mod:`django.contrib.admin` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ * The ``admin/base.html`` template now has a new block ``header`` which contains the admin site header. * The new :meth:`.ModelAdmin.get_formset_kwargs` method allows customizing the keyword arguments passed to the constructor of a formset. * The navigation sidebar now has a quick filter toolbar. * The new context variable ``model`` which contains the model class for each model is added to the :meth:`.AdminSite.each_context` method. * The new :attr:`.ModelAdmin.search_help_text` attribute allows specifying a descriptive text for the search box. * The :attr:`.InlineModelAdmin.verbose_name_plural` attribute now fallbacks to the :attr:`.InlineModelAdmin.verbose_name` + ``'s'``. * jQuery is upgraded from version 3.5.1 to 3.6.0. :mod:`django.contrib.admindocs` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * The admindocs now allows esoteric setups where :setting:`ROOT_URLCONF` is not a string. * The model section of the ``admindocs`` now shows cached properties. :mod:`django.contrib.auth` ~~~~~~~~~~~~~~~~~~~~~~~~~~ * The default iteration count for the PBKDF2 password hasher is increased from 260,000 to 320,000. * The new :attr:`LoginView.next_page <django.contrib.auth.views.LoginView.next_page>` attribute and :meth:`~django.contrib.auth.views.LoginView.get_default_redirect_url` method allow customizing the redirect after login. :mod:`django.contrib.gis` ~~~~~~~~~~~~~~~~~~~~~~~~~ * Added support for SpatiaLite 5. * :class:`~django.contrib.gis.gdal.GDALRaster` now allows creating rasters in any GDAL virtual filesystem. * The new :class:`~django.contrib.gis.admin.GISModelAdmin` class allows customizing the widget used for ``GeometryField``. This is encouraged instead of deprecated ``GeoModelAdmin`` and ``OSMGeoAdmin``. :mod:`django.contrib.postgres` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * The PostgreSQL backend now supports connecting by a service name. See :ref:`postgresql-connection-settings` for more details. * The new :class:`~django.contrib.postgres.operations.AddConstraintNotValid` operation allows creating check constraints on PostgreSQL without verifying that all existing rows satisfy the new constraint. * The new :class:`~django.contrib.postgres.operations.ValidateConstraint` operation allows validating check constraints which were created using :class:`~django.contrib.postgres.operations.AddConstraintNotValid` on PostgreSQL. * The new :class:`ArraySubquery() <django.contrib.postgres.expressions.ArraySubquery>` expression allows using subqueries to construct lists of values on PostgreSQL. * The new :lookup:`trigram_word_similar` lookup, and the :class:`TrigramWordDistance() <django.contrib.postgres.search.TrigramWordDistance>` and :class:`TrigramWordSimilarity() <django.contrib.postgres.search.TrigramWordSimilarity>` expressions allow using trigram word similarity. :mod:`django.contrib.staticfiles` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage` now replaces paths to JavaScript source map references with their hashed counterparts. * The new ``manifest_storage`` argument of :class:`~django.contrib.staticfiles.storage.ManifestFilesMixin` and :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage` allows customizing the manifest file storage. Cache ~~~~~ * The new async API for ``django.core.cache.backends.base.BaseCache`` begins the process of making cache backends async-compatible. The new async methods all have ``a`` prefixed names, e.g. ``aadd()``, ``aget()``, ``aset()``, ``aget_or_set()``, or ``adelete_many()``. Going forward, the ``a`` prefix will be used for async variants of methods generally. CSRF ~~~~ * CSRF protection now consults the ``Origin`` header, if present. To facilitate this, :ref:`some changes <csrf-trusted-origins-changes-4.0>` to the :setting:`CSRF_TRUSTED_ORIGINS` setting are required. Forms ~~~~~ * :class:`~django.forms.ModelChoiceField` now includes the provided value in the ``params`` argument of a raised :exc:`~django.core.exceptions.ValidationError` for the ``invalid_choice`` error message. This allows custom error messages to use the ``%(value)s`` placeholder. * :class:`~django.forms.formsets.BaseFormSet` now renders non-form errors with an additional class of ``nonform`` to help distinguish them from form-specific errors. * :class:`~django.forms.formsets.BaseFormSet` now allows customizing the widget used when deleting forms via :attr:`~django.forms.formsets.BaseFormSet.can_delete` by setting the :attr:`~django.forms.formsets.BaseFormSet.deletion_widget` attribute or overriding :meth:`~django.forms.formsets.BaseFormSet.get_deletion_widget` method. Internationalization ~~~~~~~~~~~~~~~~~~~~ * Added support and translations for the Malay language. Generic Views ~~~~~~~~~~~~~ * :class:`~django.views.generic.edit.DeleteView` now uses :class:`~django.views.generic.edit.FormMixin`, allowing you to provide a :class:`~django.forms.Form` subclass, with a checkbox for example, to confirm deletion. In addition, this allows ``DeleteView`` to function with :class:`django.contrib.messages.views.SuccessMessageMixin`. In accordance with ``FormMixin``, object deletion for POST requests is handled in ``form_valid()``. Custom delete logic in ``delete()`` handlers should be moved to ``form_valid()``, or a shared helper method, as needed. Logging ~~~~~~~ * The alias of the database used in an SQL call is now passed as extra context along with each message to the :ref:`django-db-logger` logger. Management Commands ~~~~~~~~~~~~~~~~~~~ * The :djadmin:`runserver` management command now supports the :option:`--skip-checks` option. * On PostgreSQL, :djadmin:`dbshell` now supports specifying a password file. * The :djadmin:`shell` command now respects :py:data:`sys.__interactivehook__` at startup. This allows loading shell history between interactive sessions. As a consequence, ``readline`` is no longer loaded if running in *isolated* mode. * The new :attr:`BaseCommand.suppressed_base_arguments <django.core.management.BaseCommand.suppressed_base_arguments>` attribute allows suppressing unsupported default command options in the help output. * The new :option:`startapp --exclude` and :option:`startproject --exclude` options allow excluding directories from the template. Models ~~~~~~ * New :meth:`QuerySet.contains(obj) <.QuerySet.contains>` method returns whether the queryset contains the given object. This tries to perform the query in the simplest and fastest way possible. * The new ``precision`` argument of the :class:`Round() <django.db.models.functions.Round>` database function allows specifying the number of decimal places after rounding. * :meth:`.QuerySet.bulk_create` now sets the primary key on objects when using SQLite 3.35+. * :class:`~django.db.models.DurationField` now supports multiplying and dividing by scalar values on SQLite. * :meth:`.QuerySet.bulk_update` now returns the number of objects updated. * The new :attr:`.Expression.empty_result_set_value` attribute allows specifying a value to return when the function is used over an empty result set. * The ``skip_locked`` argument of :meth:`.QuerySet.select_for_update()` is now allowed on MariaDB 10.6+. * :class:`~django.db.models.Lookup` expressions may now be used in ``QuerySet`` annotations, aggregations, and directly in filters. * The new :ref:`default <aggregate-default>` argument for built-in aggregates allows specifying a value to be returned when the queryset (or grouping) contains no entries, rather than ``None``. Requests and Responses ~~~~~~~~~~~~~~~~~~~~~~ * The :class:`~django.middleware.security.SecurityMiddleware` now adds the :ref:`Cross-Origin Opener Policy <cross-origin-opener-policy>` header with a value of ``'same-origin'`` to prevent cross-origin popups from sharing the same browsing context. You can prevent this header from being added by setting the :setting:`SECURE_CROSS_ORIGIN_OPENER_POLICY` setting to ``None``. Signals ~~~~~~~ * The new ``stdout`` argument for :func:`~django.db.models.signals.pre_migrate` and :func:`~django.db.models.signals.post_migrate` signals allows redirecting output to a stream-like object. It should be preferred over :py:data:`sys.stdout` and :py:func:`print` when emitting verbose output in order to allow proper capture when testing. Templates ~~~~~~~~~ * :tfilter:`floatformat` template filter now allows using the ``u`` suffix to force disabling localization. Tests ~~~~~ * The new ``serialized_aliases`` argument of :func:`django.test.utils.setup_databases` determines which :setting:`DATABASES` aliases test databases should have their state serialized to allow usage of the :ref:`serialized_rollback <test-case-serialized-rollback>` feature. * Django test runner now supports a :option:`--buffer <test --buffer>` option with parallel tests. * The new ``logger`` argument to :class:`~django.test.runner.DiscoverRunner` allows a Python :py:ref:`logger <logger>` to be used for logging. * The new :meth:`.DiscoverRunner.log` method provides a way to log messages that uses the ``DiscoverRunner.logger``, or prints to the console if not set. * Django test runner now supports a :option:`--shuffle <test --shuffle>` option to execute tests in a random order. * The :option:`test --parallel` option now supports the value ``auto`` to run one test process for each processor core. * :meth:`.TestCase.captureOnCommitCallbacks` now captures new callbacks added while executing :func:`.transaction.on_commit` callbacks. .. _backwards-incompatible-4.0: Backwards incompatible changes in 4.0 ===================================== Database backend API -------------------- This section describes changes that may be needed in third-party database backends. * ``DatabaseOperations.year_lookup_bounds_for_date_field()`` and ``year_lookup_bounds_for_datetime_field()`` methods now take the optional ``iso_year`` argument in order to support bounds for ISO-8601 week-numbering years. * The second argument of ``DatabaseSchemaEditor._unique_sql()`` and ``_create_unique_sql()`` methods is now ``fields`` instead of ``columns``. :mod:`django.contrib.gis` ------------------------- * Support for PostGIS 2.3 is removed. * Support for GDAL 2.0 and GEOS 3.5 is removed. Dropped support for PostgreSQL 9.6 ---------------------------------- Upstream support for PostgreSQL 9.6 ends in November 2021. Django 4.0 supports PostgreSQL 10 and higher. Also, the minimum supported version of ``psycopg2`` is increased from 2.5.4 to 2.8.4, as ``psycopg2`` 2.8.4 is the first release to support Python 3.8. Dropped support for Oracle 12.2 and 18c --------------------------------------- Upstream support for Oracle 12.2 ends in March 2022 and for Oracle 18c it ends in June 2021. Django 3.2 will be supported until April 2024. Django 4.0 officially supports Oracle 19c. .. _csrf-trusted-origins-changes-4.0: ``CSRF_TRUSTED_ORIGINS`` changes -------------------------------- Format change ~~~~~~~~~~~~~ Values in the :setting:`CSRF_TRUSTED_ORIGINS` setting must include the scheme (e.g. ``'http://'`` or ``'https://'``) instead of only the hostname. Also, values that started with a dot, must now also include an asterisk before the dot. For example, change ``'.example.com'`` to ``'https://*.example.com'``. A system check detects any required changes. Configuring it may now be required ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ As CSRF protection now consults the ``Origin`` header, you may need to set :setting:`CSRF_TRUSTED_ORIGINS`, particularly if you allow requests from subdomains by setting :setting:`CSRF_COOKIE_DOMAIN` (or :setting:`SESSION_COOKIE_DOMAIN` if :setting:`CSRF_USE_SESSIONS` is enabled) to a value starting with a dot. ``SecurityMiddleware`` no longer sets the ``X-XSS-Protection`` header --------------------------------------------------------------------- The :class:`~django.middleware.security.SecurityMiddleware` no longer sets the ``X-XSS-Protection`` header if the ``SECURE_BROWSER_XSS_FILTER`` setting is ``True``. The setting is removed. Most modern browsers don't honor the ``X-XSS-Protection`` HTTP header. You can use Content-Security-Policy_ without allowing ``'unsafe-inline'`` scripts instead. If you want to support legacy browsers and set the header, use this line in a custom middleware:: response.headers.setdefault('X-XSS-Protection', '1; mode=block') .. _Content-Security-Policy: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy Migrations autodetector changes ------------------------------- The migrations autodetector now uses model states instead of model classes. Also, migration operations for ``ForeignKey`` and ``ManyToManyField`` fields no longer specify attributes which were not passed to the fields during initialization. As a side-effect, running ``makemigrations`` might generate no-op ``AlterField`` operations for ``ManyToManyField`` and ``ForeignKey`` fields in some cases. ``DeleteView`` changes ---------------------- :class:`~django.views.generic.edit.DeleteView` now uses :class:`~django.views.generic.edit.FormMixin` to handle POST requests. As a consequence, any custom deletion logic in ``delete()`` handlers should be moved to ``form_valid()``, or a shared helper method, if required. Table and column naming scheme changes on Oracle ------------------------------------------------ Django 4.0 inadvertently changed the table and column naming scheme on Oracle. This causes errors for models and fields with names longer than 30 characters. Unfortunately, renaming some Oracle tables and columns is required. Use the upgrade script in :ticket:`33789 <33789comment:15>` to generate ``RENAME`` statements to change naming scheme. Miscellaneous ------------- * Support for ``cx_Oracle`` < 7.0 is removed. * To allow serving a Django site on a subpath without changing the value of :setting:`STATIC_URL`, the leading slash is removed from that setting (now ``'static/'``) in the default :djadmin:`startproject` template. * The :class:`~django.contrib.admin.AdminSite` method for the admin ``index`` view is no longer decorated with ``never_cache`` when accessed directly, rather than via the recommended ``AdminSite.urls`` property, or ``AdminSite.get_urls()`` method. * Unsupported operations on a sliced queryset now raise ``TypeError`` instead of ``AssertionError``. * The undocumented ``django.test.runner.reorder_suite()`` function is renamed to ``reorder_tests()``. It now accepts an iterable of tests rather than a test suite, and returns an iterator of tests. * Calling ``FileSystemStorage.delete()`` with an empty ``name`` now raises ``ValueError`` instead of ``AssertionError``. * Calling ``EmailMultiAlternatives.attach_alternative()`` or ``EmailMessage.attach()`` with an invalid ``content`` or ``mimetype`` arguments now raise ``ValueError`` instead of ``AssertionError``. * :meth:`~django.test.SimpleTestCase.assertHTMLEqual` no longer considers a non-boolean attribute without a value equal to an attribute with the same name and value. * Tests that fail to load, for example due to syntax errors, now always match when using :option:`test --tag`. * The undocumented ``django.contrib.admin.utils.lookup_needs_distinct()`` function is renamed to ``lookup_spawns_duplicates()``. * The undocumented ``HttpRequest.get_raw_uri()`` method is removed. The :meth:`.HttpRequest.build_absolute_uri` method may be a suitable alternative. * The ``object`` argument of undocumented ``ModelAdmin.log_addition()``, ``log_change()``, and ``log_deletion()`` methods is renamed to ``obj``. * :class:`~django.utils.feedgenerator.RssFeed`, :class:`~django.utils.feedgenerator.Atom1Feed`, and their subclasses now emit elements with no content as self-closing tags. * ``NodeList.render()`` no longer casts the output of ``render()`` method for individual nodes to a string. ``Node.render()`` should always return a string as documented. * The ``where_class`` property of ``django.db.models.sql.query.Query`` and the ``where_class`` argument to the private ``get_extra_restriction()`` method of ``ForeignObject`` and ``ForeignObjectRel`` are removed. If needed, initialize ``django.db.models.sql.where.WhereNode`` instead. * The ``filter_clause`` argument of the undocumented ``Query.add_filter()`` method is replaced by two positional arguments ``filter_lhs`` and ``filter_rhs``. * :class:`~django.middleware.csrf.CsrfViewMiddleware` now uses ``request.META['CSRF_COOKIE_NEEDS_UPDATE']`` in place of ``request.META['CSRF_COOKIE_USED']``, ``request.csrf_cookie_needs_reset``, and ``response.csrf_cookie_set`` to track whether the CSRF cookie should be sent. This is an undocumented, private API. * The undocumented ``TRANSLATOR_COMMENT_MARK`` constant is moved from ``django.template.base`` to ``django.utils.translation.template``. * The ``real_apps`` argument of the undocumented ``django.db.migrations.state.ProjectState.__init__()`` method must now be a set if provided. * :class:`~django.forms.RadioSelect` and :class:`~django.forms.CheckboxSelectMultiple` widgets are now rendered in ``<div>`` tags so they are announced more concisely by screen readers. If you need the previous behavior, :ref:`override the widget template <overriding-built-in-widget-templates>` with the appropriate template from Django 3.2. * The :tfilter:`floatformat` template filter no longer depends on the ``USE_L10N`` setting and always returns localized output. Use the ``u`` suffix to disable localization. * The default value of the ``USE_L10N`` setting is changed to ``True``. See the :ref:`Localization section <use_l10n_deprecation>` above for more details. * As part of the :ref:`move to zoneinfo <whats-new-4.0>`, :attr:`django.utils.timezone.utc` is changed to alias :attr:`datetime.timezone.utc`. * The minimum supported version of ``asgiref`` is increased from 3.3.2 to 3.4.1. .. _deprecated-features-4.0: Features deprecated in 4.0 ========================== Use of ``pytz`` time zones -------------------------- As part of the :ref:`move to zoneinfo <whats-new-4.0>`, use of ``pytz`` time zones is deprecated. Accordingly, the ``is_dst`` arguments to the following are also deprecated: * :meth:`django.db.models.query.QuerySet.datetimes` * :func:`django.db.models.functions.Trunc` * :func:`django.db.models.functions.TruncSecond` * :func:`django.db.models.functions.TruncMinute` * :func:`django.db.models.functions.TruncHour` * :func:`django.db.models.functions.TruncDay` * :func:`django.db.models.functions.TruncWeek` * :func:`django.db.models.functions.TruncMonth` * :func:`django.db.models.functions.TruncQuarter` * :func:`django.db.models.functions.TruncYear` * :func:`django.utils.timezone.make_aware` Support for use of ``pytz`` will be removed in Django 5.0. Time zone support ----------------- In order to follow good practice, the default value of the :setting:`USE_TZ` setting will change from ``False`` to ``True``, and time zone support will be enabled by default, in Django 5.0. Note that the default :file:`settings.py` file created by :djadmin:`django-admin startproject <startproject>` includes :setting:`USE_TZ = True <USE_TZ>` since Django 1.4. You can set ``USE_TZ`` to ``False`` in your project settings before then to opt-out. .. _use_l10n_deprecation: Localization ------------ In order to follow good practice, the default value of the ``USE_L10N`` setting is changed from ``False`` to ``True``. Moreover ``USE_L10N`` is deprecated as of this release. Starting with Django 5.0, by default, any date or number displayed by Django will be localized. The :ttag:`{% localize %} <localize>` tag and the :tfilter:`localize`/ :tfilter:`unlocalize` filters will still be honored by Django. Miscellaneous ------------- * ``SERIALIZE`` test setting is deprecated as it can be inferred from the :attr:`~django.test.TestCase.databases` with the :ref:`serialized_rollback <test-case-serialized-rollback>` option enabled. * The undocumented ``django.utils.baseconv`` module is deprecated. * The undocumented ``django.utils.datetime_safe`` module is deprecated. * The default sitemap protocol for sitemaps built outside the context of a request will change from ``'http'`` to ``'https'`` in Django 5.0. * The ``extra_tests`` argument for :meth:`.DiscoverRunner.build_suite` and :meth:`.DiscoverRunner.run_tests` is deprecated. * The :class:`~django.contrib.postgres.aggregates.ArrayAgg`, :class:`~django.contrib.postgres.aggregates.JSONBAgg`, and :class:`~django.contrib.postgres.aggregates.StringAgg` aggregates will return ``None`` when there are no rows instead of ``[]``, ``[]``, and ``''`` respectively in Django 5.0. If you need the