Update django to 4.0.6

[pyup-bot]

This PR updates Django from 1.11.4 to 4.0.6.

Changelog

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 previous behavior, explicitly set
``default`` to ``Value([])``, ``Value('[]')``, or ``Value('')``.

* The ``django.contrib.gis.admin.GeoModelAdmin`` and ``OSMGeoAdmin`` classes
are deprecated. Use :class:`~django.contrib.admin.ModelAdmin` and
:class:`~django.contrib.gis.admin.GISModelAdmin` instead.

* Since form rendering now uses the template engine, the undocumented
``BaseForm._html_output()`` helper method is deprecated.

* The ability to return a ``str`` from ``ErrorList`` and ``ErrorDict`` is
deprecated. It is expected these methods return a ``SafeString``.

Features removed in 4.0
=======================

These features have reached the end of their deprecation cycle and are removed
in Django 4.0.

See :ref:`deprecated-features-3.0` for details on these changes, including how
to remove usage of these features.

* ``django.utils.http.urlquote()``, ``urlquote_plus()``, ``urlunquote()``, and
``urlunquote_plus()`` are removed.

* ``django.utils.encoding.force_text()`` and ``smart_text()`` are removed.

* ``django.utils.translation.ugettext()``, ``ugettext_lazy()``,
``ugettext_noop()``, ``ungettext()``, and ``ungettext_lazy()`` are removed.

* ``django.views.i18n.set_language()`` doesn't set the user language in
``request.session`` (key ``_language``).

* ``alias=None`` is required in the signature of
``django.db.models.Expression.get_group_by_cols()`` subclasses.

* ``django.utils.text.unescape_entities()`` is removed.

* ``django.utils.http.is_safe_url()`` is removed.

See :ref:`deprecated-features-3.1` for details on these changes, including how
to remove usage of these features.

* The ``PASSWORD_RESET_TIMEOUT_DAYS`` setting is removed.

* The :lookup:`isnull` lookup no longer allows using non-boolean values as the
right-hand side.

* The ``django.db.models.query_utils.InvalidQuery`` exception class is removed.

* The ``django-admin.py`` entry point is removed.

* The ``HttpRequest.is_ajax()`` method is removed.

* Support for the pre-Django 3.1 encoding format of cookies values used by
``django.contrib.messages.storage.cookie.CookieStorage`` is removed.

* Support for the pre-Django 3.1 password reset tokens in the admin site (that
use the SHA-1 hashing algorithm) is removed.

* Support for the pre-Django 3.1 encoding format of sessions is removed.

* Support for the pre-Django 3.1 ``django.core.signing.Signer`` signatures
(encoded with the SHA-1 algorithm) is removed.

* Support for the pre-Django 3.1 ``django.core.signing.dumps()`` signatures
(encoded with the SHA-1 algorithm) in ``django.core.signing.loads()`` is
removed.

* Support for the pre-Django 3.1 user sessions (that use the SHA-1 algorithm)
is removed.

* The ``get_response`` argument for
``django.utils.deprecation.MiddlewareMixin.__init__()`` is required and
doesn't accept ``None``.

* The ``providing_args`` argument for ``django.dispatch.Signal`` is removed.

* The ``length`` argument for ``django.utils.crypto.get_random_string()`` is
required.

* The ``list`` message for ``ModelMultipleChoiceField`` is removed.

* Support for passing raw column aliases to ``QuerySet.order_by()`` is removed.

* The ``NullBooleanField`` model field is removed, except for support in
historical migrations.

* ``django.conf.urls.url()`` is removed.

* The ``django.contrib.postgres.fields.JSONField`` model field is removed,
except for support in historical migrations.

* ``django.contrib.postgres.fields.jsonb.KeyTransform`` and
``django.contrib.postgres.fields.jsonb.KeyTextTransform`` are removed.

* ``django.contrib.postgres.forms.JSONField`` is removed.

* The ``{% ifequal %}`` and ``{% ifnotequal %}`` template tags are removed.

* The ``DEFAULT_HASHING_ALGORITHM`` transitional setting is removed.


===========================

3.2.14

===========================

*July 4, 2022*

Django 3.2.14 fixes a security issue with severity "high" in 3.2.13.

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.


===========================

3.2.13

===========================

*April 11, 2022*

Django 3.2.13 fixes two security issues with severity "high" in
3.2.12 and a regression in 3.2.4.

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


===========================

3.2.12

===========================

*February 1, 2022*

Django 3.2.12 fixes two security issues with severity "medium" in 3.2.11.

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.


===========================

3.2.11

===========================

*January 4, 2022*

Django 3.2.11 fixes one security issue with severity "medium" and two security
issues with severity "low" in 3.2.10.

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


===========================

3.2.10

===========================

*December 7, 2021*

Django 3.2.10 fixes a security issue with severity "low" and a bug in 3.2.9.

CVE-2021-44420: Potential bypass of an upstream access control based on URL paths
=================================================================================

HTTP requests for URLs with trailing newlines could bypass an upstream access
control based on URL paths.

Bugfixes
========

* Fixed a regression in Django 3.2 that caused a crash of ``setUpTestData()``
with ``BinaryField`` on PostgreSQL, which is ``memoryview``-backed
(:ticket:`33333`).


==========================

3.2.9

==========================

*November 1, 2021*

Django 3.2.9 fixes a bug in 3.2.8 and adds compatibility with Python 3.10.

Bugfixes
========

* Fixed a bug in Django 3.2 that caused a migration crash on SQLite when
altering a field with a functional index (:ticket:`33194`).


==========================

3.2.8

==========================

*October 5, 2021*

Django 3.2.8 fixes two bugs in 3.2.7.

Bugfixes
========

* Fixed a bug in Django 3.2 that caused incorrect links on read-only fields in
the admin (:ticket:`33077`).

* Fixed a regression in Django 3.2 that caused incorrect selection of items
across all pages when actions were placed both on the top and bottom of the
admin change-list view (:ticket:`33083`).


==========================

3.2.7

==========================

*September 1, 2021*

Django 3.2.7 fixes a bug in 3.2.6.

Bugfixes
========

* Fixed a regression in Django 3.2 that caused the incorrect offset extraction
from fixed offset timezones (:ticket:`32992`).


==========================

3.2.6

==========================

*August 2, 2021*

Django 3.2.6 fixes several bugs in 3.2.5.

Bugfixes
========

* Fixed a regression in Django 3.2 that caused a crash validating ``"NaN"``
input with a ``forms.DecimalField`` when additional constraints, e.g.
``max_value``, were specified (:ticket:`32949`).

* Fixed a bug in Django 3.2 where a system check would crash on a model with a
reverse many-to-many relation inherited from a parent class
(:ticket:`32947`).


==========================

3.2.5

==========================

*July 1, 2021*

Django 3.2.5 fixes a security issue with severity "high" and several bugs in
3.2.4. Also, the latest string translations from Transifex are incorporated.

CVE-2021-35042: Potential SQL injection via unsanitized ``QuerySet.order_by()`` input
=====================================================================================

Unsanitized user input passed to ``QuerySet.order_by()`` could bypass intended
column reference validation in path marked for deprecation resulting in a
potential SQL injection even if a deprecation warning is emitted.

As a mitigation the strict column reference validation was restored for the
duration of the deprecation period. This regression appeared in 3.1 as a side
effect of fixing :ticket:`31426`.

The issue is not present in the main branch as the deprecated path has been
removed.

Bugfixes
========

* Fixed a regression in Django 3.2 that caused a crash of
``QuerySet.values_list(…, named=True)`` after ``prefetch_related()``
(:ticket:`32812`).

* Fixed a bug in Django 3.2 that caused a migration crash on MySQL 8.0.13+ when
altering ``BinaryField``, ``JSONField``, or ``TextField`` to non-nullable
(:ticket:`32503`).

* Fixed a regression in Django 3.2 that caused a migration crash on MySQL
8.0.13+ when adding nullable ``BinaryField``, ``JSONField``, or ``TextField``
with a default value (:ticket:`32832`).

* Fixed a bug in Django 3.2 where a system check would crash on a model with an
invalid ``app_label`` (:ticket:`32863`).


==========================

3.2.4

==========================

*June 2, 2021*

Django 3.2.4 fixes two security issues and several bugs in 3.2.3.

CVE-2021-33203: Potential directory traversal via ``admindocs``
===============================================================

Staff members could use the :mod:`~django.contrib.admindocs`
``TemplateDetailView`` view to check the existence of arbitrary files.
Additionally, if (and only if) the default admindocs templates have been
customized by the developers to also expose the file contents, then not only
the existence but also the file contents would have been exposed.

As a mitigation, path sanitation is now applied and only files within the
template root directories can be loaded.

CVE-2021-33571: Possible indeterminate SSRF, RFI, and LFI attacks since validators accepted leading zeros in IPv4 addresses
===========================================================================================================================

:class:`~django.core.validators.URLValidator`,
:func:`~django.core.validators.validate_ipv4_address`, and
:func:`~django.core.validators.validate_ipv46_address` didn't prohibit leading
zeros in octal literals. If you used such values you could suffer from
indeterminate SSRF, RFI, and LFI attacks.

:func:`~django.core.validators.validate_ipv4_address` and
:func:`~django.core.validators.validate_ipv46_address` validators were not
affected on Python 3.9.5+.

Bugfixes
========

* Fixed a bug in Django 3.2 where a final catch-all view in the admin didn't
respect the server-provided value of ``SCRIPT_NAME`` when redirecting
unauthenticated users to the login page (:ticket:`32754`).

* Fixed a bug in Django 3.2 where a system check would crash on an abstract
model (:ticket:`32733`).

* Prevented unnecessary initialization of unused caches following a regression
in Django 3.2 (:ticket:`32747`).

* Fixed a crash in Django 3.2 that could occur when running ``mod_wsgi`` with
the recommended settings while the Windows ``colorama`` library was installed
(:ticket:`32740`).

* Fixed a bug in Django 3.2 that would trigger the auto-reloader for template
changes when directory paths were specified with strings (:ticket:`32744`).

* Fixed a regression in Django 3.2 that caused a crash of auto-reloader with
``AttributeError``, e.g. inside a ``Conda`` environment (:ticket:`32783`).

* Fixed a regression in Django 3.2 that caused a loss of precision for
operations with ``DecimalField`` on MySQL (:ticket:`32793`).


==========================

3.2.3

==========================

*May 13, 2021*

Django 3.2.3 fixes several bugs in 3.2.2.

Bugfixes
========

* Prepared for ``mysqlclient`` > 2.0.3 support (:ticket:`32732`).

* Fixed a regression in Django 3.2 that caused the incorrect filtering of
querysets combined with the ``|`` operator (:ticket:`32717`).

* Fixed a regression in Django 3.2.1 where saving ``FileField`` would raise a
``SuspiciousFileOperation`` even when a custom
:attr:`~django.db.models.FileField.upload_to` returns a valid file path
(:ticket:`32718`).


==========================

3.2.2

==========================

*May 6, 2021*

Django 3.2.2 fixes a security issue and a bug in 3.2.1.

CVE-2021-32052: Header injection possibility since ``URLValidator`` accepted newlines in input on Python 3.9.5+
===============================================================================================================

On Python 3.9.5+, :class:`~django.core.validators.URLValidator` didn't prohibit
newlines and tabs. If you used values with newlines in HTTP response, you could
suffer from header injection attacks. Django itself wasn't vulnerable because
:class:`~django.http.HttpResponse` prohibits newlines in HTTP headers.

Moreover, the ``URLField`` form field which uses ``URLValidator`` silently
removes newlines and tabs on Python 3.9.5+, so the possibility of newlines
entering your data only existed if you are using this validator outside of the
form fields.

This issue was introduced by the :bpo:`43882` fix.

Bugfixes
========

* Prevented, following a regression in Django 3.2.1, :djadmin:`makemigrations`
from generating infinite migrations for a model with ``Meta.ordering``
contained ``OrderBy`` expressions (:ticket:`32714`).


==========================

3.2.1

==========================

*May 4, 2021*

Django 3.2.1 fixes a security issue and several bugs in 3.2.

CVE-2021-31542: Potential directory-traversal via uploaded files
================================================================

``MultiPartParser``, ``UploadedFile``, and ``FieldFile`` allowed
directory-traversal via uploaded files with suitably crafted file names.

In order to mitigate this risk, stricter basename and path sanitation is now
applied.

Bugfixes
========

* Corrected detection of GDAL 3.2 on Windows (:ticket:`32544`).

* Fixed a bug in Django 3.2 where subclasses of ``BigAutoField`` and
``SmallAutoField`` were not allowed for the :setting:`DEFAULT_AUTO_FIELD`
setting (:ticket:`32620`).

* Fixed a regression in Django 3.2 that caused a crash of
``QuerySet.values()/values_list()`` after ``QuerySet.union()``,
``intersection()``, and ``difference()`` when it was ordered by an
unannotated field (:ticket:`32627`).

* Restored, following a regression in Django 3.2, displaying an exception
message on the technical 404 debug page (:ticket:`32637`).

* Fixed a bug in Django 3.2 where a system check would crash on a reverse
one-to-one relationships in ``CheckConstraint.check`` or
``UniqueConstraint.condition`` (:ticket:`32635`).

* Fixed a regression in Django 3.2 that caused a crash of
:attr:`.ModelAdmin.search_fields` when searching against phrases with
unbalanced quotes (:ticket:`32649`).

* Fixed a bug in Django 3.2 where variable lookup errors were logged rendering
the sitemap template if alternates were not defined (:ticket:`32648`).

* Fixed a regression in Django 3.2 that caused a crash when combining ``Q()``
objects which contains boolean expressions (:ticket:`32548`).

* Fixed a regression in Django 3.2 that caused a crash of ``QuerySet.update()``
on a queryset ordered by inherited or joined fields on MySQL and MariaDB
(:ticket:`32645`).

* Fixed a regression in Django 3.2 that caused a crash when decoding a cookie
value, used by ``django.contrib.messages.storage.cookie.CookieStorage``, in
the pre-Django 3.2 format (:ticket:`32643`).

* Fixed a regression in Django 3.2 that stopped the shift-key modifier
selecting multiple rows in the admin changelist (:ticket:`32647`).

* Fixed a bug in Django 3.2 where a system check would crash on the
:setting:`STATICFILES_DIRS` setting with a list of 2-tuples of
``(prefix, path)`` (:ticket:`32665`).

* Fixed a long standing bug involving queryset bitwise combination when used
with subqueries that began manifesting in Django 3.2, due to a separate fix
using ``Exists`` to ``exclude()`` multi-valued relationships
(:ticket:`32650`).

* Fixed a bug in Django 3.2 where variable lookup errors were logged when
rendering some admin templates (:ticket:`32681`).

* Fixed a bug in Django 3.2 where an admin changelist would crash when deleting
objects filtered against multi-valued relationships (:ticket:`32682`). The
admin changelist now uses ``Exists()`` instead ``QuerySet.distinct()``
because calling ``delete()`` after ``distinct()`` is not allowed in Django
3.2 to address a data loss possibility.

* Fixed a regression in Django 3.2 where the calling process environment would
not be passed to the ``dbshell`` command on PostgreSQL (:ticket:`32687`).

* Fixed a performance regression in Django 3.2 when building complex filters
with subqueries (:ticket:`32632`). As a side-effect the private API to check
``django.db.sql.query.Query`` equality is removed.


========================

3.2

========================

*April 6, 2021*

Welcome to Django 3.2!

These release notes cover the :ref:`new features <whats-new-3.2>`, as well as
some :ref:`backwards incompatible changes <backwards-incompatible-3.2>` you'll
want to be aware of when upgrading from Django 3.1 or earlier. We've
:ref:`begun the deprecation process for some features
<deprecated-features-3.2>`.

See the :doc:`/howto/upgrade-version` guide if you're updating an existing
project.

Django 3.2 is designated as a :term:`long-term support release
<Long-term support release>`. It will receive security updates for at least
three years after its release. Support for the previous LTS, Django 2.2, will
end in April 2022.

Python compatibility
====================

Django 3.2 supports Python 3.6, 3.7, 3.8, 3.9, and 3.10 (as of 3.2.9). We
**highly recommend** and only officially support the latest release of each
series.

.. _whats-new-3.2:

What's new in Django 3.2
========================

Automatic :class:`~django.apps.AppConfig` discovery
---------------------------------------------------

Most pluggable applications define an :class:`~django.apps.AppConfig` subclass
in an ``apps.py`` submodule. Many define a ``default_app_config`` variable
pointing to this class in their ``__init__.py``.

When the ``apps.py`` submodule exists and defines a single
:class:`~django.apps.AppConfig` subclass, Django now uses that configuration
automatically, so you can remove ``default_app_config``.

``default_app_config`` made it possible to declare only the application's path
in :setting:`INSTALLED_APPS` (e.g. ``'django.contrib.admin'``) rather than the
app config's path (e.g. ``'django.contrib.admin.apps.AdminConfig'``). It was
introduced for backwards-compatibility with the former style, with the intent
to switch the ecosystem to the latter, but the switch didn't happen.

With automatic ``AppConfig`` discovery, ``default_app_config`` is no longer
needed. As a consequence, it's deprecated.

See :ref:`configuring-applications-ref` for full details.

Customizing type of auto-created primary keys
---------------------------------------------

When defining a model, if no field in a model is defined with
:attr:`primary_key=True <django.db.models.Field.primary_key>` an implicit
primary key is added. The type of this implicit primary key can now be
controlled via the :setting:`DEFAULT_AUTO_FIELD` setting and
:attr:`AppConfig.default_auto_field <django.apps.AppConfig.default_auto_field>`
attribute. No more needing to override primary keys in all models.

Maintaining the historical behavior, the default value for
:setting:`DEFAULT_AUTO_FIELD` is :class:`~django.db.models.AutoField`. Starting
with 3.2 new projects are generated with :setting:`DEFAULT_AUTO_FIELD` set to
:class:`~django.db.models.BigAutoField`. Also, new apps are generated with
:attr:`AppConfig.default_auto_field <django.apps.AppConfig.default_auto_field>`
set to :class:`~django.db.models.BigAutoField`. In a future Django release the
default value of :setting:`DEFAULT_AUTO_FIELD` will be changed to
:class:`~django.db.models.BigAutoField`.

To avoid unwanted migrations in the future, either explicitly set
:setting:`DEFAULT_AUTO_FIELD` to :class:`~django.db.models.AutoField`::

 DEFAULT_AUTO_FIELD = 'django.db.models.AutoField'

or configure it on a per-app basis::

 from django.apps import AppConfig

 class MyAppConfig(AppConfig):
     default_auto_field = 'django.db.models.AutoField'
     name = 'my_app'

or on a per-model basis::

 from django.db import models

 class MyModel(models.Model):
     id = models.AutoField(primary_key=True)

In anticipation of the changing default, a system check will provide a warning
if you do not have an explicit setting for :setting:`DEFAULT_AUTO_FIELD`.

When changing the value of :setting:`DEFAULT_AUTO_FIELD`, migrations for the
primary key of existing auto-created through tables cannot be generated
currently. See the :setting:`DEFAULT_AUTO_FIELD` docs for details on migrating
such tables.

.. _new_functional_indexes:

Functional indexes
------------------

The new :attr:`*expressions <django.db.models.Index.expressions>` positional
argument of :class:`Index() <django.db.models.Index>` enables creating
functional indexes on expressions and database functions. For example::

 from django.db import models
 from django.db.models import F, Index, Value
 from django.db.models.functions import Lower, Upper


 class MyModel(models.Model):
     first_name = models.CharField(max_length=255)
     last_name = models.CharField(max_length=255)
     height = models.IntegerField()
     weight = models.IntegerField()

     class Meta:
         indexes = [
             Index(
                 Lower('first_name'),
                 Upper('last_name').desc(),
                 name='first_last_name_idx',
             ),
             Index(
                 F('height') / (F('weight') + Value(5)),
                 name='calc_idx',
             ),
         ]

Functional indexes are added to models using the
:attr:`Meta.indexes <django.db.models.Options.indexes>` option.

``pymemcache`` support
----------------------

The new ``django.core.cache.backends.memcached.PyMemcacheCache`` cache backend
allows using the pymemcache_ library for memcached. ``pymemcache`` 3.4.0 or
higher is required. For more details, see the :doc:`documentation on caching in
Django </topics/cache>`.

.. _pymemcache: https://pypi.org/project/pymemcache/

New decorators for the admin site
---------------------------------

The new :func:`~django.contrib.admin.display` decorator allows for easily
adding options to custom display functions that can be used with
:attr:`~django.contrib.admin.ModelAdmin.list_display` or
:attr:`~django.contrib.admin.ModelAdmin.readonly_fields`.

Likewise, the new :func:`~django.contrib.admin.action` decorator allows for
easily adding options to action functions that can be used with
:attr:`~django.contrib.admin.ModelAdmin.actions`.

Using the ``display`` decorator has the advantage that it is now
possible to use the ``property`` decorator when needing to specify attributes
on the custom method. Prior to this it was necessary to use the ``property()``
function instead after assigning the required attributes to the method.

Using decorators has the advantage that these options are more discoverable as
they can be suggested by completion utilities in code editors. They are merely
a convenience and still set the same attributes on the functions under the
hood.

Minor features
--------------

:mod:`django.contrib.admin`
~~~~~~~~~~~~~~~~~~~~~~~~~~~

* :attr:`.ModelAdmin.search_fields` now allows searching against quoted phrases
with spaces.

* Read-only related fields are now rendered as navigable links if target models
are registered in the admin.

* The admin now supports theming, and includes a dark theme that is enabled
according to browser settings. See :ref:`admin-theming` for more details.

* :attr:`.ModelAdmin.autocomplete_fields` now respects
:attr:`ForeignKey.to_field <django.db.models.ForeignKey.to_field>` and
:attr:`ForeignKey.limit_choices_to
<django.db.models.ForeignKey.limit_choices_to>` when searching a related
model.

* The admin now installs a final catch-all view that redirects unauthenticated
users to the login page, regardless of whether the URL is otherwise valid.
This protects against a potential model enumeration privacy issue.

Although not recommended, you may set the new
:attr:`.AdminSite.final_catch_all_view` to ``False`` to disable the
catch-all view.

:mod:`django.contrib.auth`
~~~~~~~~~~~~~~~~~~~~~~~~~~

* The default iteration count for the PBKDF2 password hasher is increased from
216,000 to 260,000.

* The default variant for the Argon2 password hasher is changed to Argon2id.
``memory_cost`` and ``parallelism`` are increased to 102,400 and 8
respectively to match the ``argon2-cffi`` defaults.

Increasing the ``memory_cost`` pushes the required memory from 512 KB to 100
MB. This is still rather conservative but can lead to problems in memory
constrained environments. If this is the case, the existing hasher can be
subclassed to override the defaults.

* The default salt entropy for the Argon2, MD5, PBKDF2, SHA-1 password hashers
is increased from 71 to 128 bits.

:mod:`django.contrib.contenttypes`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* The new ``absolute_max`` argument for
:func:`~django.contrib.contenttypes.forms.generic_inlineformset_factory`
allows customizing the maximum number of forms that can be instantiated when
supplying ``POST`` data. See :ref:`formsets-absolute-max` for more details.

* The new ``can_delete_extra`` argument for
:func:`~django.contrib.contenttypes.forms.generic_inlineformset_factory`
allows removal of the option to delete extra forms. See
:attr:`~.BaseFormSet.can_delete_extra` for more information.

:mod:`django.contrib.gis`
~~~~~~~~~~~~~~~~~~~~~~~~~

* The :meth:`.GDALRaster.transform` method now supports
:class:`~django.contrib.gis.gdal.SpatialReference`.

* The :class:`~django.contrib.gis.gdal.DataSource` class now supports
:class:`pathlib.Path`.

* The :class:`~django.contrib.gis.utils.LayerMapping` class now supports
:cla