Update django to 5.0.4

[pyup-bot]

This PR updates django from 2.2.2 to 5.0.4.

Changelog

5.0.4

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

*April 3, 2024*

Django 5.0.4 fixes several bugs in 5.0.3.

Bugfixes
========

* Fixed a bug in Django 5.0 that caused a crash of ``Model.full_clean()`` on
fields with expressions in ``db_default``. As a consequence,
``Model.full_clean()`` no longer validates for empty values in fields with
``db_default`` (:ticket:`35223`).

* Fixed a regression in Django 5.0 where the ``AdminFileWidget`` could be
rendered with two ``id`` attributes on the "Clear" checkbox
(:ticket:`35273`).

* Fixed a bug in Django 5.0 that caused a migration crash on PostgreSQL 15+
when adding a partial ``UniqueConstraint`` with ``nulls_distinct``
(:ticket:`35329`).

* Fixed a crash in Django 5.0 when performing queries involving table aliases
and lookups on a ``GeneratedField`` of the aliased table (:ticket:`35344`).

* Fixed a bug in Django 5.0 that caused a migration crash when adding a
``GeneratedField`` relying on the ``__contains`` or ``__icontains``
lookups or using a ``Value`` containing a ``"%"`` (:ticket:`35336`).


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

5.0.3

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

*March 4, 2024*

Django 5.0.3 fixes a security issue with severity "moderate" and several bugs
in 5.0.2.

CVE-2024-27351: Potential regular expression denial-of-service in ``django.utils.text.Truncator.words()``
=========================================================================================================

``django.utils.text.Truncator.words()`` method (with ``html=True``) and
:tfilter:`truncatewords_html` template filter were subject to a potential
regular expression denial-of-service attack using a suitably crafted string
(follow up to :cve:`2019-14232` and :cve:`2023-43665`).

Bugfixes
========

* Fixed a regression in Django 5.0.2 where ``intcomma`` template filter could
return a leading comma for string representation of floats (:ticket:`35172`).

* Fixed a bug in Django 5.0 that caused a crash of ``Signal.asend()`` and
``asend_robust()`` when all receivers were asynchronous functions
(:ticket:`35174`).

* Fixed a regression in Django 5.0.1 where :meth:`.ModelAdmin.lookup_allowed`
would prevent filtering against foreign keys using lookups like ``__isnull``
when the field was not included in :attr:`.ModelAdmin.list_filter`
(:ticket:`35173`).

* Fixed a regression in Django 5.0 that caused a crash of
``sensitive_variables`` and ``sensitive_post_parameters`` decorators on
functions loaded from ``.pyc`` files (:ticket:`35187`).

* Fixed a regression in Django 5.0 that caused a crash when reloading a test
database and a base queryset for a base manager used ``prefetch_related()``
(:ticket:`35238`).

* Fixed a bug in Django 5.0 where facet filters in the admin would crash on a
``SimpleListFilter`` using a queryset without primary keys (:ticket:`35198`).


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

5.0.2

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

*February 6, 2024*

Django 5.0.2 fixes a security issue with severity "moderate" and several bugs
in 5.0.1. Also, the latest string translations from Transifex are incorporated.

CVE-2024-24680: Potential denial-of-service in ``intcomma`` template filter
===========================================================================

The ``intcomma`` template filter was subject to a potential denial-of-service
attack when used with very long strings.

Bugfixes
========

* Reallowed, following a regression in Django 5.0.1, filtering against local
foreign keys not included in :attr:`.ModelAdmin.list_filter`
(:ticket:`35087`).

* Fixed a regression in Django 5.0 where links in the admin had an incorrect
color (:ticket:`35121`).

* Fixed a bug in Django 5.0 that caused a crash of ``Model.full_clean()`` on
models with a ``GeneratedField`` (:ticket:`35127`).

* Fixed a regression in Django 5.0 that caused a crash of
``FilteredRelation()`` with querysets as right-hand sides (:ticket:`35135`).
``FilteredRelation()`` now raises a ``ValueError`` on querysets as right-hand
sides.

* Fixed a regression in Django 5.0 that caused a crash of the ``dumpdata``
management command when a base queryset used ``prefetch_related()``
(:ticket:`35159`).

* Fixed a regression in Django 5.0 that caused the ``request_finished`` signal to
sometimes not be fired when running Django through an ASGI server, resulting
in potential resource leaks (:ticket:`35059`).

* Fixed a bug in Django 5.0 that caused a migration crash on MySQL when adding
a ``BinaryField``, ``TextField``, ``JSONField``, or ``GeometryField`` with a
``db_default`` (:ticket:`35162`).

* Fixed a bug in Django 5.0 that caused a migration crash on models with a
literal ``db_default`` of a complex type such as ``dict`` instance of a
``JSONField``. Running ``makemigrations`` might generate no-op ``AlterField``
operations for fields using ``db_default`` (:ticket:`35149`).


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

5.0.1

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

*January 2, 2024*

Django 5.0.1 fixes several bugs in 5.0.

Bugfixes
========

* Reallowed, following a regression in Django 5.0, using a foreign key to a
model with a primary key that is not ``AutoField`` in
:attr:`.ModelAdmin.list_filter` (:ticket:`35020`).

* Fixed a long standing bug in handling the ``RETURNING INTO`` clause that
caused a crash when creating a model instance with a ``GeneratedField`` which
``output_field`` had backend-specific converters (:ticket:`35024`).

* Fixed a regression in Django 5.0 that caused a crash of ``Model.save()`` for
models with both ``GeneratedField`` and ``ForeignKey`` fields
(:ticket:`35019`).

* Fixed a bug in Django 5.0 that caused a migration crash on Oracle < 23c when
adding a ``GeneratedField`` with ``output_field=BooleanField``
(:ticket:`35018`).

* Fixed a regression in Django 5.0 where admin fields on the same line could
overflow the page and become non-interactive (:ticket:`35012`).

* Added compatibility for ``oracledb`` 2.0.0 (:ticket:`35054`).

* Fixed a regression in Django 5.0 where querysets referenced incorrect field
names from ``FilteredRelation()`` (:ticket:`35050`).

* Fixed a regression in Django 5.0 that caused a system check crash when
``ModelAdmin.filter_horizontal`` or ``filter_vertical`` contained a reverse
many-to-many relation with ``related_name`` (:ticket:`35056`).


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

5.0

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

*December 4, 2023*

Welcome to Django 5.0!

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

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

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

Django 5.0 supports Python 3.10, 3.11, and 3.12. We **highly recommend** and
only officially support the latest release of each series.

The Django 4.2.x series is the last to support Python 3.8 and 3.9.

Third-party library support for older version of Django
=======================================================

Following the release of Django 5.0, we suggest that third-party app authors
drop support for all versions of Django prior to 4.2. At that time, you should
be able to run your package's tests using ``python -Wd`` so that deprecation
warnings appear. After making the deprecation warning fixes, your app should be
compatible with Django 5.0.

.. _whats-new-5.0:

What's new in Django 5.0
========================

Facet filters in the admin
--------------------------

Facet counts are now shown for applied filters in the admin changelist when
toggled on via the UI. This behavior can be changed via the new
:attr:`.ModelAdmin.show_facets` attribute. For more information see
:ref:`facet-filters`.

Simplified templates for form field rendering
---------------------------------------------

Django 5.0 introduces the concept of a field group, and field group templates.
This simplifies rendering of the related elements of a Django form field such
as its label, widget, help text, and errors.

For example, the template below:

.. code-block:: html+django

 <form>
 ...
 <div>
   {{ form.name.label_tag }}
   {% if form.name.help_text %}
     <div class="helptext" id="{{ form.name.auto_id }}_helptext">
       {{ form.name.help_text|safe }}
     </div>
   {% endif %}
   {{ form.name.errors }}
   {{ form.name }}
   <div class="row">
     <div class="col">
       {{ form.email.label_tag }}
       {% if form.email.help_text %}
         <div class="helptext" id="{{ form.email.auto_id }}_helptext">
           {{ form.email.help_text|safe }}
         </div>
       {% endif %}
       {{ form.email.errors }}
       {{ form.email }}
     </div>
     <div class="col">
       {{ form.password.label_tag }}
       {% if form.password.help_text %}
         <div class="helptext" id="{{ form.password.auto_id }}_helptext">
           {{ form.password.help_text|safe }}
         </div>
       {% endif %}
       {{ form.password.errors }}
       {{ form.password }}
     </div>
   </div>
 </div>
 ...
 </form>

Can now be simplified to:

.. code-block:: html+django

 <form>
 ...
 <div>
   {{ form.name.as_field_group }}
   <div class="row">
     <div class="col">{{ form.email.as_field_group }}</div>
     <div class="col">{{ form.password.as_field_group }}</div>
   </div>
 </div>
 ...
 </form>

:meth:`~django.forms.BoundField.as_field_group` renders fields with the
``"django/forms/field.html"`` template by default and can be customized on a
per-project, per-field, or per-request basis. See
:ref:`reusable-field-group-templates`.

Database-computed default values
--------------------------------

The new :attr:`Field.db_default <django.db.models.Field.db_default>` parameter
sets a database-computed default value. For example::

 from django.db import models
 from django.db.models.functions import Now, Pi


 class MyModel(models.Model):
     age = models.IntegerField(db_default=18)
     created = models.DateTimeField(db_default=Now())
     circumference = models.FloatField(db_default=2 * Pi())

Database generated model field
------------------------------

The new :class:`~django.db.models.GeneratedField` allows creation of database
generated columns. This field can be used on all supported database backends
to create a field that is always computed from other fields. For example::

 from django.db import models
 from django.db.models import F


 class Square(models.Model):
     side = models.IntegerField()
     area = models.GeneratedField(
         expression=F("side") * F("side"),
         output_field=models.BigIntegerField(),
         db_persist=True,
     )

More options for declaring field choices
----------------------------------------

:attr:`.Field.choices` *(for model fields)* and :attr:`.ChoiceField.choices`
*(for form fields)* allow for more flexibility when declaring their values. In
previous versions of Django, ``choices`` should either be a list of 2-tuples,
or an :ref:`field-choices-enum-types` subclass, but the latter required
accessing the ``.choices`` attribute to provide the values in the expected
form::

 from django.db import models

 Medal = models.TextChoices("Medal", "GOLD SILVER BRONZE")

 SPORT_CHOICES = [
     ("Martial Arts", [("judo", "Judo"), ("karate", "Karate")]),
     ("Racket", [("badminton", "Badminton"), ("tennis", "Tennis")]),
     ("unknown", "Unknown"),
 ]


 class Winner(models.Model):
     name = models.CharField(...)
     medal = models.CharField(..., choices=Medal.choices)
     sport = models.CharField(..., choices=SPORT_CHOICES)

Django 5.0 adds support for accepting a mapping or a callable instead of an
iterable, and also no longer requires ``.choices`` to be used directly to
expand :ref:`enumeration types <field-choices-enum-types>`::

 from django.db import models

 Medal = models.TextChoices("Medal", "GOLD SILVER BRONZE")

 SPORT_CHOICES = {   Using a mapping instead of a list of 2-tuples.
     "Martial Arts": {"judo": "Judo", "karate": "Karate"},
     "Racket": {"badminton": "Badminton", "tennis": "Tennis"},
     "unknown": "Unknown",
 }


 def get_scores():
     return [(i, str(i)) for i in range(10)]


 class Winner(models.Model):
     name = models.CharField(...)
     medal = models.CharField(..., choices=Medal)   Using `.choices` not required.
     sport = models.CharField(..., choices=SPORT_CHOICES)
     score = models.IntegerField(choices=get_scores)   A callable is allowed.

Under the hood the provided ``choices`` are normalized into a list of 2-tuples
as the canonical form whenever the ``choices`` value is updated. For more
information, please check the :ref:`model field reference on choices
<field-choices>`.

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

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

* The new :meth:`.AdminSite.get_log_entries` method allows customizing the
queryset for the site's listed log entries.

* The ``django.contrib.admin.AllValuesFieldListFilter``,
``ChoicesFieldListFilter``, ``RelatedFieldListFilter``, and
``RelatedOnlyFieldListFilter`` admin filters now handle multi-valued query
parameters.

* ``XRegExp`` is upgraded from version 3.2.0 to 5.1.1.

* The new :meth:`.AdminSite.get_model_admin` method returns an admin class for
the given model class.

* Properties in :attr:`.ModelAdmin.list_display` now support ``boolean``
attribute.

* jQuery is upgraded from version 3.6.4 to 3.7.1.


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

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

* The new asynchronous functions are now provided, using an
``a`` prefix: :func:`django.contrib.auth.aauthenticate`,
:func:`~.django.contrib.auth.aget_user`,
:func:`~.django.contrib.auth.alogin`, :func:`~.django.contrib.auth.alogout`,
and :func:`~.django.contrib.auth.aupdate_session_auth_hash`.

* ``AuthenticationMiddleware`` now adds an :meth:`.HttpRequest.auser`
asynchronous method that returns the currently logged-in user.

* The new :func:`django.contrib.auth.hashers.acheck_password` asynchronous
function and :meth:`.AbstractBaseUser.acheck_password` method allow
asynchronous checking of user passwords.

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

* :meth:`.QuerySet.prefetch_related` now supports prefetching
:class:`~django.contrib.contenttypes.fields.GenericForeignKey` with
non-homogeneous set of results.

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

* The new
:class:`ClosestPoint() <django.contrib.gis.db.models.functions.ClosestPoint>`
function returns a 2-dimensional point on the geometry that is closest to
another geometry.

* :ref:`GIS aggregates <gis-aggregation-functions>` now support the ``filter``
argument.

* Support for GDAL 3.7 and GEOS 3.12 is added.

* The new :meth:`.GEOSGeometry.equals_identical` method allows point-wise
equivalence checking of geometries.

:mod:`django.contrib.messages`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* The new :meth:`.MessagesTestMixin.assertMessages` assertion method allows
testing :mod:`~django.contrib.messages` added to a
:class:`response <django.http.HttpResponse>`.

:mod:`django.contrib.postgres`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* The new :attr:`~.ExclusionConstraint.violation_error_code` attribute of
:class:`~django.contrib.postgres.constraints.ExclusionConstraint` allows
customizing the ``code`` of ``ValidationError`` raised during
:ref:`model validation <validating-objects>`.

Asynchronous views
~~~~~~~~~~~~~~~~~~

* Under ASGI, ``http.disconnect`` events are now handled. This allows views to
perform any necessary cleanup if a client disconnects before the response is
generated. See :ref:`async-handling-disconnect` for more details.

Decorators
~~~~~~~~~~

* The following decorators now support wrapping asynchronous view functions:

* :func:`~django.views.decorators.cache.cache_control`
* :func:`~django.views.decorators.cache.never_cache`
* :func:`~django.views.decorators.common.no_append_slash`
* :func:`~django.views.decorators.csrf.csrf_exempt`
* :func:`~django.views.decorators.csrf.csrf_protect`
* :func:`~django.views.decorators.csrf.ensure_csrf_cookie`
* :func:`~django.views.decorators.csrf.requires_csrf_token`
* :func:`~django.views.decorators.debug.sensitive_variables`
* :func:`~django.views.decorators.debug.sensitive_post_parameters`
* :func:`~django.views.decorators.gzip.gzip_page`
* :func:`~django.views.decorators.http.condition`
* ``conditional_page()``
* :func:`~django.views.decorators.http.etag`
* :func:`~django.views.decorators.http.last_modified`
* :func:`~django.views.decorators.http.require_http_methods`
* :func:`~django.views.decorators.http.require_GET`
* :func:`~django.views.decorators.http.require_POST`
* :func:`~django.views.decorators.http.require_safe`
* :func:`~django.views.decorators.vary.vary_on_cookie`
* :func:`~django.views.decorators.vary.vary_on_headers`
* ``xframe_options_deny()``
* ``xframe_options_sameorigin()``
* ``xframe_options_exempt()``

Error Reporting
~~~~~~~~~~~~~~~

* :func:`~django.views.decorators.debug.sensitive_variables` and
:func:`~django.views.decorators.debug.sensitive_post_parameters` can now be
used with asynchronous functions.

File Storage
~~~~~~~~~~~~

* :meth:`.File.open` now passes all positional (``*args``) and keyword
arguments (``**kwargs``) to Python's built-in :func:`python:open`.

Forms
~~~~~

* The new :attr:`~django.forms.URLField.assume_scheme` argument for
:class:`~django.forms.URLField` allows specifying a default URL scheme.

* In order to improve accessibility, the following changes are made:

* Form fields now include the ``aria-describedby`` HTML attribute to enable
 screen readers to associate form fields with their help text.
* Invalid form fields now include the ``aria-invalid="true"`` HTML attribute.

Internationalization
~~~~~~~~~~~~~~~~~~~~

* Support and translations for the Uyghur language are now available.

Migrations
~~~~~~~~~~

* Serialization of functions decorated with :func:`functools.cache` or
:func:`functools.lru_cache` is now supported without the need to write a
custom serializer.

Models
~~~~~~

* The new ``create_defaults`` argument of :meth:`.QuerySet.update_or_create`
and :meth:`.QuerySet.aupdate_or_create` methods allows specifying a different
field values for the create operation.

* The new ``violation_error_code`` attribute of
:class:`~django.db.models.BaseConstraint`,
:class:`~django.db.models.CheckConstraint`, and
:class:`~django.db.models.UniqueConstraint` allows customizing the ``code``
of ``ValidationError`` raised during
:ref:`model validation <validating-objects>`.

* The :ref:`force_insert <ref-models-force-insert>` argument of
:meth:`.Model.save` now allows specifying a tuple of parent classes that must
be forced to be inserted.

* :meth:`.QuerySet.bulk_create` and :meth:`.QuerySet.abulk_create` methods now
set the primary key on each model instance when the ``update_conflicts``
parameter is enabled (if the database supports it).

* The new :attr:`.UniqueConstraint.nulls_distinct` attribute allows customizing
the treatment of ``NULL`` values on PostgreSQL 15+.

* The new :func:`~django.shortcuts.aget_object_or_404` and
:func:`~django.shortcuts.aget_list_or_404` asynchronous shortcuts allow
asynchronous getting objects.

* The new :func:`~django.db.models.aprefetch_related_objects` function allows
asynchronous prefetching of model instances.

* :meth:`.QuerySet.aiterator` now supports previous calls to
``prefetch_related()``.

* On MariaDB 10.7+, ``UUIDField`` is now created as ``UUID`` column rather than
``CHAR(32)`` column. See the migration guide above for more details on
:ref:`migrating-uuidfield`.

* Django now supports `oracledb`_ version 1.3.2 or higher. Support for
``cx_Oracle`` is deprecated as of this release and will be removed in Django
6.0.

Pagination
~~~~~~~~~~

* The new :attr:`django.core.paginator.Paginator.error_messages` argument
allows customizing the error messages raised by :meth:`.Paginator.page`.

Signals
~~~~~~~

* The new :meth:`.Signal.asend` and :meth:`.Signal.asend_robust` methods allow
asynchronous signal dispatch. Signal receivers may be synchronous or
asynchronous, and will be automatically adapted to the correct calling style.

Templates
~~~~~~~~~

* The new :tfilter:`escapeseq` template filter applies :tfilter:`escape` to
each element of a sequence.

Tests
~~~~~

* :class:`~django.test.Client` and :class:`~django.test.AsyncClient` now
provide asynchronous methods, using an ``a`` prefix:
:meth:`~django.test.Client.asession`, :meth:`~django.test.Client.alogin`,
:meth:`~django.test.Client.aforce_login`, and
:meth:`~django.test.Client.alogout`.

* :class:`~django.test.AsyncClient` now supports the ``follow`` parameter.

* :class:`~django.test.runner.DiscoverRunner` now allows showing the duration
of the slowest tests using the :option:`test --durations` option (available
on Python 3.12+).

Validators
~~~~~~~~~~

* The new ``offset`` argument of
:class:`~django.core.validators.StepValueValidator` allows specifying an
offset for valid values.

.. _backwards-incompatible-5.0:

Backwards incompatible changes in 5.0
=====================================

Database backend API
--------------------

This section describes changes that may be needed in third-party database
backends.

* ``DatabaseFeatures.supports_expression_defaults`` should be set to ``False``
if the database doesn't support using database functions as defaults.

* ``DatabaseFeatures.supports_default_keyword_in_insert`` should be set to
``False`` if the database doesn't support the ``DEFAULT`` keyword in
``INSERT`` queries.

* ``DatabaseFeatures.supports_default_keyword_in_bulk_insert`` should be set to
``False`` if the database doesn't support the ``DEFAULT`` keyword in bulk
``INSERT`` queries.

:mod:`django.contrib.gis`
-------------------------

* Support for GDAL 2.2 and 2.3 is removed.

* Support for GEOS 3.6 and 3.7 is removed.

:mod:`django.contrib.sitemaps`
------------------------------

* The ``django.contrib.sitemaps.ping_google()`` function and the
``ping_google`` management command are removed as the Google
Sitemaps ping endpoint is deprecated and will be removed in January 2024.

* The ``django.contrib.sitemaps.SitemapNotFound`` exception class is removed.

Dropped support for MySQL < 8.0.11
----------------------------------

Support for pre-releases of MySQL 8.0.x series is removed. Django 5.0 supports
MySQL 8.0.11 and higher.

Using ``create_defaults__exact`` may now be required with ``QuerySet.update_or_create()``
-----------------------------------------------------------------------------------------

:meth:`.QuerySet.update_or_create` now supports the parameter
``create_defaults``. As a consequence, any models that have a field named
``create_defaults`` that are used with an ``update_or_create()`` should specify
the field in the lookup with ``create_defaults__exact``.

.. _migrating-uuidfield:

Migrating existing ``UUIDField`` on MariaDB 10.7+
-------------------------------------------------

On MariaDB 10.7+, ``UUIDField`` is now created as ``UUID`` column rather than
``CHAR(32)`` column. As a consequence, any ``UUIDField`` created in
Django < 5.0 should be replaced with a ``UUIDField`` subclass backed by
``CHAR(32)``::

 class Char32UUIDField(models.UUIDField):
     def db_type(self, connection):
         return "char(32)"

     def get_db_prep_value(self, value, connection, prepared=False):
         value = super().get_db_prep_value(value, connection, prepared)
         if value is not None:
             value = value.hex
         return value

For example::

 class MyModel(models.Model):
     uuid = models.UUIDField(primary_key=True, default=uuid.uuid4)

Should become::

 class Char32UUIDField(models.UUIDField): ...


 class MyModel(models.Model):
     uuid = Char32UUIDField(primary_key=True, default=uuid.uuid4)

Running the :djadmin:`makemigrations` command will generate a migration
containing a no-op ``AlterField`` operation.

Miscellaneous
-------------

* The ``instance`` argument of the undocumented
``BaseModelFormSet.save_existing()`` method is renamed to ``obj``.

* The undocumented ``django.contrib.admin.helpers.checkbox`` is removed.

* Integer fields are now validated as 64-bit integers on SQLite to match the
behavior of ``sqlite3``.

* The undocumented ``Query.annotation_select_mask`` attribute is changed from a
set of strings to an ordered list of strings.

* ``ImageField.update_dimension_fields()`` is no longer called on the
``post_init`` signal if ``width_field`` and ``height_field`` are not set.

* :class:`~django.db.models.functions.Now` database function now uses
``LOCALTIMESTAMP`` instead of ``CURRENT_TIMESTAMP`` on Oracle.

* :attr:`.AdminSite.site_header` is now rendered in a ``<div>`` tag instead of
``<h1>``. Screen reader users rely on heading elements for navigation within
a page. Having two ``<h1>`` elements was confusing and the site header wasn't
helpful as it is repeated on all pages.

* In order to improve accessibility, the admin's main content area and header
content area are now rendered in a ``<main>`` and ``<header>`` tag instead of
``<div>``.

* On databases without native support for the SQL ``XOR`` operator, ``^`` as
the exclusive or (``XOR``) operator now returns rows that are matched by an
odd number of operands rather than exactly one operand. This is consistent
with the behavior of MySQL, MariaDB, and Python.

* The minimum supported version of ``asgiref`` is increased from 3.6.0 to
3.7.0.

* The minimum supported version of ``selenium`` is increased from 3.8.0 to
4.8.0.

* The ``AlreadyRegistered`` and ``NotRegistered`` exceptions are moved from
``django.contrib.admin.sites`` to ``django.contrib.admin.exceptions``.

* The minimum supported version of SQLite is increased from 3.21.0 to 3.27.0.

* Support for ``cx_Oracle`` < 8.3 is removed.

* Executing SQL queries before the app registry has been fully populated now
raises :exc:`RuntimeWarning`.

* :exc:`~django.core.exceptions.BadRequest` is raised for non-UTF-8 encoded
requests with the :mimetype:`application/x-www-form-urlencoded` content type.
See :rfc:`1866` for more details.

* The minimum supported version of ``colorama`` is increased to 0.4.6.

* The minimum supported version of ``docutils`` is increased to 0.19.

* Filtering querysets against overflowing integer values now always returns an
empty queryset. As a consequence, you may need to use ``ExpressionWrapper()``
to :ref:`explicitly wrap <using-f-with-annotations>` arithmetic against
integer fields in such cases.

.. _deprecated-features-5.0:

Features deprecated in 5.0
==========================

Miscellaneous
-------------

* The ``DjangoDivFormRenderer`` and ``Jinja2DivFormRenderer`` transitional form
renderers are deprecated.

* Passing positional arguments ``name`` and ``violation_error_message`` to
:class:`~django.db.models.BaseConstraint` is deprecated in favor of
keyword-only arguments.

* ``request`` is added to the signature of :meth:`.ModelAdmin.lookup_allowed`.
Support for ``ModelAdmin`` subclasses that do not accept this argument is
deprecated.

* The ``get_joining_columns()`` method of ``ForeignObject`` and
``ForeignObjectRel`` is deprecated. Starting with Django 6.0,
``django.db.models.sql.datastructures.Join`` will no longer fallback to
``get_joining_columns()``. Subclasses should implement
``get_joining_fields()`` instead.

* The ``ForeignObject.get_reverse_joining_columns()`` method is deprecated.

* The default scheme for ``forms.URLField`` will change from ``"http"`` to
``"https"`` in Django 6.0. Set :setting:`FORMS_URLFIELD_ASSUME_HTTPS`
transitional setting to ``True`` to opt into assuming ``"https"`` during the
Django 5.x release cycle.

* ``FORMS_URLFIELD_ASSUME_HTTPS`` transitional setting is deprecated.

* Support for calling ``format_html()`` without passing args or kwargs will be
removed.

* Support for ``cx_Oracle`` is deprecated in favor of `oracledb`_ 1.3.2+ Python
driver.

* ``DatabaseOperations.field_cast_sql()`` is deprecated in favor of
``DatabaseOperations.lookup_cast()``. Starting with Django 6.0,
``BuiltinLookup.process_lhs()`` will no longer call ``field_cast_sql()``.
Third-party database backends should implement ``lookup_cast()`` instead.

* The ``django.db.models.enums.ChoicesMeta`` metaclass is renamed to
``ChoicesType``.

* The ``Prefetch.get_current_queryset()`` method is deprecated.

* The ``get_prefetch_queryset()`` method of related managers and descriptors
is deprecated. Starting with Django 6.0, ``get_prefetcher()`` and
``prefetch_related_objects()`` will no longer fallback to
``get_prefetch_queryset()``. Subclasses should implement
``get_prefetch_querysets()`` instead.

.. _`oracledb`: https://oracle.github.io/python-oracledb/

Features removed in 5.0
=======================

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

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

* The ``SERIALIZE`` test setting is removed.

* The undocumented ``django.utils.baseconv`` module is removed.

* The undocumented ``django.utils.datetime_safe`` module is removed.

* The default value of the ``USE_TZ`` setting is changed from ``False`` to
``True``.

* The default sitemap protocol for sitemaps built outside the context of a
request is changed from ``'http'`` to ``'https'``.

* The ``extra_tests`` argument for ``DiscoverRunner.build_suite()`` and
``DiscoverRunner.run_tests()`` is removed.

* The ``django.contrib.postgres.aggregates.ArrayAgg``, ``JSONBAgg``, and
``StringAgg`` aggregates no longer return ``[]``, ``[]``, and ``''``,
respectively, when there are no rows.

* The ``USE_L10N`` setting is removed.

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

* Support for ``pytz`` timezones is removed.

* The ``is_dst`` argument is removed from:

* ``QuerySet.datetimes()``
* ``django.utils.timezone.make_aware()``
* ``django.db.models.functions.Trunc()``
* ``django.db.models.functions.TruncSecond()``
* ``django.db.models.functions.TruncMinute()``
* ``django.db.models.functions.TruncHour()``
* ``django.db.models.functions.TruncDay()``
* ``django.db.models.functions.TruncWeek()``
* ``django.db.models.functions.TruncMonth()``
* ``django.db.models.functions.TruncQuarter()``
* ``django.db.models.functions.TruncYear()``

* The ``django.contrib.gis.admin.GeoModelAdmin`` and ``OSMGeoAdmin`` classes
are removed.

* The undocumented ``BaseForm._html_output()`` method is removed.

* The ability to return a ``str``, rather than a ``SafeString``, when rendering
an ``ErrorDict`` and ``ErrorList`` is removed.

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

* The ``SitemapIndexItem.__str__()`` method is removed.

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

* The ``name`` argument of ``django.utils.functional.cached_property()`` is
removed.

* The ``opclasses`` argument of
``django.contrib.postgres.constraints.ExclusionConstraint`` is removed.

* The undocumented ability to pass ``errors=None`` to
``SimpleTestCase.assertFormError()`` and ``assertFormsetError()`` is removed.

* ``django.contrib.sessions.serializers.PickleSerializer`` is removed.

* The usage of ``QuerySet.iterator()`` on a queryset that prefetches related
objects without providing the ``chunk_size`` argument is no longer allowed.

* Passing unsaved model instances to related filters is no longer allowed.

* ``created=True`` is required in the signature of
``RemoteUserBackend.configure_user()`` subclasses.

* Support for logging out via ``GET`` requests in the
``django.contrib.auth.views.LogoutView`` and
``django.contrib.auth.views.logout_then_login()`` is removed.

* The ``django.utils.timezone.utc`` alias to ``datetime.timezone.utc`` is
removed.

* Passing a response object and a form/formset name to
``SimpleTestCase.assertFormError()`` and ``assertFormSetError()`` is no
longer allowed.

* The ``django.contrib.gis.admin.OpenLayersWidget`` is removed.

+ The ``django.contrib.auth.hashers.CryptPasswordHasher`` is removed.

* The ``"django/forms/default.html"`` and
``"django/forms/formsets/default.html"`` templates are removed.

* The default form and formset rendering style is changed to the div-based.

* Passing ``nulls_first=False`` or ``nulls_last=False`` to ``Expression.asc()``
and ``Expression.desc()`` methods, and the ``OrderBy`` expression is no
longer allowed.








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

4.2.11

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

*March 4, 2024*

Django 4.2.11 fixes a security issue with severity "moderate" and a regression
in 4.2.10.

CVE-2024-27351: Potential regular expression denial-of-service in ``django.utils.text.Truncator.words()``
=========================================================================================================

``django.utils.text.Truncator.words()`` method (with ``html=True``) and
:tfilter:`truncatewords_html` template filter were subject to a potential
regular expression denial-of-service attack using a suitably crafted string
(follow up to :cve:`2019-14232` and :cve:`2023-43665`).

Bugfixes
========

* Fixed a regression in Django 4.2.10 where ``intcomma`` template filter could
return a leading comma for string representation of floats (:ticket:`35172`).


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

4.2.10

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

*February 6, 2024*

Django 4.2.10 fixes a security issue with severity "moderate" in 4.2.9.

CVE-2024-24680: Potential denial-of-service in ``intcomma`` template filter
===========================================================================

The ``intcomma`` template filter was subject to a potential denial-of-service
attack when used with very long strings.


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

4.2.9

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

*January 2, 2024*

Django 4.2.9 fixes a bug in 4.2.8.

Bugfixes
========

* Fixed a regression in Django 4.2.8 where admin fields on the same line could
overflow the page and become non-interactive (:ticket:`35012`).


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

4.2.8

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

*December 4, 2023*

Django 4.2.8 fixes several bugs in 4.2.7 and adds compatibility with Python
3.12.

Bugfixes
========

* Fixed a regression in Django 4.2 that caused :option:`makemigrations --check`
to stop displaying pending migrations (:ticket:`34457`).

* Fixed a regression in Django 4.2 that caused a crash of
``QuerySet.aggregate()`` with aggregates referencing other aggregates or
window functions through conditional expressions (:ticket:`34975`).

* Fixed a regression in Django 4.2 that caused a crash when annotating a
``QuerySet`` with a ``Window`` expressions composed of a ``partition_by``
clause mixing field types and aggregation expressions (:ticket:`34987`).

* Fixed a regression in Django 4.2 where the admin's change list page had
misaligned pagination links and inputs when using ``list_editable``
(:ticket:`34991`).

* Fixed a regression in Django 4.2 where checkboxes in the admin would be
centered on narrower screen widths (:ticket:`34994`).

* Fixed a regression in Django 4.2 that caused a crash of querysets with
aggregations on MariaDB when the ``ONLY_FULL_GROUP_BY`` SQL mode was enabled
(:ticket:`34992`).

* Fixed a regression in Django 4.2 where the admin's read-only password widget
and some help texts were incorrectly aligned at tablet widths
(:ticket:`34982`).

* Fixed a regression in Django 4.2 that caused a migration crash on SQLite when
altering unsupported ``Meta.db_table_comment`` (:ticket:`35006`).


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

4.2.7

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

*November 1, 2023*

Django 4.2.7 fixes a security issue with severity "moderate" and several bugs
in 4.2.6.

CVE-2023-46695: Potential denial of service vulnerability in ``UsernameField`` on Windows
=========================================================================================

The :func:`NFKC normalization <python:unicodedata.normalize>` is slow on
Windows. As a consequence, ``django.contrib.auth.forms.UsernameField`` was
subject to a potential denial of service attack via certain inputs with a very
large number of Unicode characters.

In order to avoid the vulnerability, invalid values longer than
``UsernameField.max_length`` are no longer normalized, since they cannot pass
validation anyway.

Bugfixes
========

* Fixed a regression in Django 4.2 that caused a crash of
``QuerySet.aggregate()`` with aggregates referencing expressions containing
subqueries (:ticket:`34798`).

* Restored, following a regression in Django 4.2, creating
``varchar/text_pattern_ops`` indexes on ``CharField`` and ``TextField`` with
deterministic collations on PostgreSQL (:ticket:`34932`).


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

4.2.6

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

*October 4, 2023*

Django 4.2.6 fixes a security issue with severity "moderate" and several bugs
in 4.2.5.

CVE-2023-43665: Denial-of-service possibility in ``django.utils.text.Truncator``
================================================================================

Following the fix for :cve:`2019-14232`, the regular expressions used in the
implementation of ``django.utils.text.Truncator``'s ``chars()`` and ``words()``
methods (with ``html=True``) were revised and improved. However, these regular
expressions still exhibited linear backtracking complexity, so when given a
very long, potentially malformed HTML input, the evaluation would still be
slow, leading to a potential denial of service vulnerability.

The ``chars()`` and ``words()`` methods are used to implement the
:tfilter:`truncatechars_html` and :tfilter:`truncatewords_html` template
filters, which were thus also vulnerable.

The input processed by ``Truncator``, when operating in HTML mode, has been
limited to the first five million characters in order to avoid potential
performance and memory issues.

Bugfixes
========

* Fixed a regression in Django 4.2.5 where overriding the deprecated
``DEFAULT_FILE_STORAGE`` and ``STATICFILES_STORAGE`` settings in tests caused
the main ``STORAGES`` to mutate (:ticket:`34821`).

* Fixed a regression in Django 4.2 that caused unnecessary casting of string
based fields (``CharField``, ``EmailField``, ``TextField``, ``CICharField``,
``CIEmailField``, and ``CITextField``) used with the ``__isnull`` lookup on
PostgreSQL. As a consequence, indexes using an ``__isnull`` expression or
condition created before Django 4.2 wouldn't be used by the query planner,
leading to a performance regression (:ticket:`34840`).

You may need to recreate such indexes created in your database with Django
4.2 to 4.2.5, as they contain unnecessary ``::text`` casting. Find candidate
indexes with this query:

.. code-block:: sql

     SELECT indexname, indexdef
     FROM pg_indexes
     WHERE indexdef LIKE '%::text IS %NULL';


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

4.2.5

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

*September 4, 2023*

Django 4.2.5 fixes a security issue with severity "moderate" and several bugs
in 4.2.4.

CVE-2023-41164: Potential denial of service vulnerability in ``django.utils.encoding.uri_to_iri()``
===================================================================================================

``django.utils.encoding.uri_to_iri()`` was subject to potential denial of
service attack via certain inputs with a very large number of Unicode
characters.

Bugfixes
========

* Fixed a regression in Django 4.2 that caused an incorrect validation of
``CheckConstraints`` on ``__isnull`` lookups against ``JSONField``
(:ticket:`34754`).

* Fixed a bug in Django 4.2 where the deprecated ``DEFAULT_FILE_STORAGE`` and
``STATICFILES_STORAGE`` settings were not synced with ``STORAGES``
(:ticket:`34773`).

* Fixed a regression in Django 4.2.2 that caused an unnecessary selection of a
non-nullable ``ManyToManyField`` without a natural key during serialization
(:ticket:`34779`).

* Fixed a regression in Django 4.2 that caused a crash of a queryset when
filtering against deeply nested ``OuterRef()`` annotations (:ticket:`34803`).


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

4.2.4

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

*August 1, 2023*

Django 4.2.4 fixes several bugs in 4.2.3.

Bugfixes
========

* Fixed a regression in Django 4.2 that caused a crash of
``QuerySet.aggregate()`` with aggregates referencing window functions
(:ticket:`34717`).

* Fixed a regression in Django 4.2 that caused a crash when grouping by a
reference in a subquery (:ticket:`34748`).

* Fixed a regression in Django 4.2 that caused aggregation over query that
uses explicit grouping by multi-valued annotations to group against the wrong
columns (:ticket:`34750`).


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

4.2.3

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

*July 3, 2023*

Django 4.2.3 fixes a security issue with severity "moderate" and several bugs
in 4.2.2.

CVE-2023-36053: Potential regular expression denial of service vulnerability in ``EmailValidator``/``URLValidator``
===================================================================================================================

``EmailValidator`` and ``URLValidator`` were subject to potential regular
expression denial of service attack via a very large number of domain name
labels of emails and URLs.

Bugfixes
========

* Fixed a regression in Django 4.2 that caused incorrect alignment of timezone
warnings for ``DateField`` and ``TimeField`` in the admin (:ticket:`34645`).

* Fixed a regression in Django 4.2 that caused incorrect highlighting of rows
in the admin changelist view when ``ModelAdmin.list_editable`` contained a
``BooleanField`` (:ticket:`34638`).


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

4.2.2

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

*June 5, 2023*

Django 4.2.2 fixes several bugs in 4.2.1.

Bugfixes
========

* Fixed a regression in Django 4.2 that caused an unnecessary
``DBMS_LOB.SUBSTR()`` wrapping in the ``__isnull`` and ``__exact=None``
lookups for ``TextField()``/``BinaryField()`` on Oracle (:ticket:`34544`).

* Restored, following a regression in Django 4.2, ``get_prep_value()`` call in
``JSONField`` subclasses (:ticket:`34539`).

* Fixed a regression in Django 4.2 that caused a crash of ``QuerySet.defer()``
when passing a ``ManyToManyField`` or ``GenericForeignKey`` reference. While
doing so is a no-op, it was allowed in older version (:ticket:`34570`).

* Fixed a regression in Django 4.2 that caused a crash of ``QuerySet.only()``
when passing a reverse ``OneToOneField`` reference (:ticket:`34612`).

* Fixed a bug in Django 4.2 where :option:`makemigrations --update` didn't
respect the ``--name`` option (:ticket:`34568`).

* Fixed a performance regression in Django 4.2 when compiling queries without
ordering (:ticket:`34580`).

* Fixed a regression in Django 4.2 where nonexistent stylesheet was linked on a
“Congratulations!” page (:ticket:`34588`).

* Fixed a regression in Django 4.2 that caused a crash of
``QuerySet.aggregate()`` with expressions referencing other aggregates
(:ticket:`34551`).

* Fixed a regression in Django 4.2 that caused a crash of
``QuerySet.aggregate()`` with aggregates referencing subqueries
(:ticket:`34551`).

* Fixed a regression in Django 4.2 that caused a crash of querysets on SQLite
when filtering on ``DecimalField`` against values outside of the defined
range (:ticket:`34590`).

* Fixed a regression in Django 4.2 that caused a serialization crash on a
``ManyToManyField`` without a natural key when its ``Manager``’s base
``QuerySet`` used ``select_related()`` (:ticket:`34620`).


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

4.2.1

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

*May 3, 2023*

Django 4.2.1 fixes a security issue with severity "low" and several bugs in
4.2.

CVE-2023-31047: Potential bypass of validation when uploading multiple files using one form field
=================================================================================================

Uploading multiple files using one form field has never been supported by
:class:`.forms.FileField` or :class:`.forms.ImageField` as only the last
uploaded file was validated. Unfortunately, :ref:`uploading_multiple_files`
topic suggested otherwise.

In order to avoid the vulnerability, :class:`~django.forms.ClearableFileInput`
and :class:`~django.forms.FileInput` form widgets now raise ``ValueError`` when
the ``multiple`` HTML attribute is set on them. To prevent the exception and
keep the old behavior, set ``allow_multiple_selected`` to ``True``.

For more details on using the new attribute and handling of multiple files
through a single field, see :ref:`uploading_multiple_files`.

Bugfixes
========

* Fixed a regression in Django 4.2 that caused a crash of ``QuerySet.defer()``
when deferring fields by attribute names (:ticket:`34458`).

* Fixed a regression in Django 4.2 that caused a crash of
:class:`~django.contrib.postgres.search.SearchVector` function with ``%``
characters (:ticket:`34459`).

* Fixed a regression in Django 4.2 that caused aggregation over query that
uses explicit grouping to group against the wrong columns (:ticket:`34464`).

* Reallowed, following a regression in Django 4.2, setting the
``"cursor_factory"`` option in :setting:`OPTIONS` on PostgreSQL
(:ticket:`34466`).

* Enforced UTF-8 client encoding on PostgreSQL, following a regression in
Django 4.2 (:ticket:`34470`).

* Fixed a regression in Django 4.2 where ``i18n_patterns()`` didn't respect the
``prefix_default_language`` argument when a fallback language of the default
language was used (:ticket:`34455`).

* Fixed a regression in Django 4.2 where translated URLs of the default
language from ``i18n_patterns()`` with ``prefix_default_language`` set to
``False`` raised 404 errors for a request with a different language
(:ticket:`34515`).

* Fixed a regression in Django 4.2 where creating copies and deep copies of
``HttpRequest``, ``HttpResponse``, and their subclasses didn't always work
correctly (:ticket:`34482`, :ticket:`34484`).

* Fixed a regression in Django 4.2 where ``timesince`` and ``timeuntil``
template filters returned incorrect results for a datetime with a non-UTC
timezone when a time difference is less than 1 day (:ticket:`34483`).

* Fixed a regression in Django 4.2 that caused a crash of
:class:`~django.contrib.postgres.search.SearchHeadline` function with
``psycopg`` 3 (:ticket:`34486`).

* Fixed a regression in Django 4.2 that caused incorrect ``ClearableFileInput``
margins in the admin (:ticket:`34506`).

* Fixed a regression in Django 4.2 where breadcrumbs didn't appear on admin
site app index views (:ticket:`34512`).

* Made squashing migrations reduce ``AddIndex``, ``RemoveIndex``,
``RenameIndex``, and ``CreateModel`` operations which allows removing a
deprecated ``Meta.index_together`` option from historical migrations and use
``Meta.indexes`` instead (:ticket:`34525`).


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

4.2

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

*April 3, 2023*

Welcome to Django 4.2!

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

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

Django 4.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 3.2, will
end in April 2024.

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

Django 4.2 supports Python 3.8, 3.9, 3.10, 3.11, and 3.12 (as of 4.2.8). We
**highly recommend** and only officially support the latest release of each
series.

.. _whats-new-4.2:

What's new in Django 4.2
========================

Psycopg 3 support
-----------------

Django now supports `psycopg`_ version 3.1.8 or higher. To update your code,
install the :pypi:`psycopg library <psycopg>`, you don't need to change the
:setting:`ENGINE <DATABASE-ENGINE>` as ``django.db.backends.postgresql``
supports both libraries.

Support for ``psycopg2`` is likely to be deprecated and removed at some point
in the future.

Be aware that ``psycopg`` 3 introduces some breaking changes over ``psycopg2``.
As a consequence, you may need to make some changes to account for
`differences from psycopg2`_.

.. _psycopg: https://www.psycopg.org/psycopg3/
.. _differences from psycopg2: https://www.psycopg.org/psycopg3/docs/basic/from_pg2.html

Comments on columns and tables
------------------------------

The new :attr:`Field.db_comment <django.db.models.Field.db_comment>` and
:attr:`Meta.db_table_comment <django.db.models.Options.db_table_comment>`
options allow creating comments on columns and tables, respectively. For
example::

 from django.db import models


 class Question(models.Model):
     text = models.TextField(db_comment="Poll question")
     pub_date = models.DateTimeField(
         db_comment="Date and time when the question was published",
     )

     class Meta:
         db_table_comment = "Poll questions"


 class Answer(models.Model):
     question = models.ForeignKey(
         Question,
         on_delete=models.CASCADE,
         db_comment="Reference to a question",
     )
     answer = models.TextField(db_comment="Question answer")

     class Meta:
         db_table_comment = "Question answers"

Also, the new :class:`~django.db.migrations.operations.AlterModelTableComment`
operation allows changing table comments defined in the
:attr:`Meta.db_table_comment <django.db.models.Options.db_table_comment>`.

Mitigation for the BREACH attack
--------------------------------

:class:`~django.middleware.gzip.GZipMiddleware` now includes a mitigation for
the BREACH attack. It will add up to 100 random bytes to gzip responses to make
BREACH attacks harder. Read more about the mitigation technique in the `Heal
The Breach (HTB) paper`_.

.. _Heal The Breach (HTB) paper: https://ieeexplore.ieee.org/document/9754554

In-memory file storage
----------------------

The new :class:`django.core.files.storage.InMemoryStorage` class provides a
non-persistent storage useful for speeding up tests by avoiding disk access.

Custom file storages
--------------------

The new :setting:`STORAGES` setting allows configuring multiple custom file
storage backends. It also controls storage engines for managing
:doc:`files </topics/files>` (the ``"default"`` key) and :doc:`static files
</ref/contrib/staticfiles>` (the ``"staticfiles"`` key).

The old ``DEFAULT_FILE_STORAGE`` and ``STATICFILES_STORAGE`` settings are
deprecated as of this release.

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

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

* The light or dark color theme of the admin can now be toggled in the UI, as
well as being set to follow the system setting.

* The admin's font stack now prefers system UI fonts and no longer requires
downloading fonts. Additionally, CSS variables are available to more easily
override the default font families.

* The :source:`admin/delete_confirmation.html
<django/contrib/admin/templates/admin/delete_confirmation.html>` template now
has some additional blocks and scripting hooks to ease customization.

* The chosen options of
:attr:`~django.contrib.admin.ModelAdmin.filter_horizontal` and
:attr:`~django.contrib.admin.ModelAdmin.filter_vertical` widgets are now
filterable.

* The ``admin/base.html`` template now has a new block ``nav-breadcrumbs``
which contains the navigation landmark and the ``breadcrumbs`` block.

* :attr:`.ModelAdmin.list_editable` now uses atomic transactions when making
edits.

* jQuery is upgraded from version 3.6.0 to 3.6.4.

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

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

* :class:`~django.contrib.auth.forms.UserCreationForm` now saves many-to-many
form fields for a custom user model.

* The new :class:`~django.contrib.auth.forms.BaseUserCreationForm` is now the
recommended base class for customizing the user creation form.

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

* The :doc:`GeoJSON serializer </ref/contrib/gis/serializers>` now outputs the
``id`` key for serialized features, which defaults to the primary key of
objects.

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

* The :class:`~django.contrib.gis.geoip2.GeoIP2` class now supports  ``.mmdb``
files downloaded from DB-IP.

* The OpenLayers template widget no longer includes inline CSS (which also
removes the former ``map_css`` block) to better comply with a strict Content
Security Policy.

* :class:`~django.contrib.gis.forms.widgets.OpenLayersWidget` is now based on
OpenLayers 7.2.2 (previously 4.6.5).

* The new :lookup:`isempty` lookup and
:class:`IsEmpty() <django.contrib.gis.db.models.functions.IsEmpty>`
expression allow filtering empty geometries on PostGIS.

* The new :class:`FromWKB() <django.contrib.gis.db.models.functions.FromWKB>`
and :class:`FromWKT() <django.contrib.gis.db.models.functions.FromWKT>`
functions allow creating geometries from Well-known binary (WKB) and
Well-known text (WKT) representations.

:mod:`django.contrib.postgres`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* The new :lookup:`trigram_strict_word_similar` lookup, and the
:class:`TrigramStrictWordSimilarity()
<django.contrib.postgres.search.TrigramStrictWordSimilarity>` and
:class:`TrigramStrictWordDistance()
<django.contrib.postgres.search.TrigramStrictWordDistance>` expressions allow
using trigram strict word similarity.

* The :lookup:`arrayfield.overlap` lookup now supports ``QuerySet.values()``
and ``values_list()`` as a right-hand side.

:mod:`django.contrib.sitemaps`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* The new :meth:`.Sitemap.get_languages_for_item` method allows customizing the
list of languages for which the item is displayed.

:mod:`django.contrib.staticfiles`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage` now
has experimental support for replacing paths to JavaScript modules in
``import`` and ``export`` statements with their hashed counterparts. If you
want to try it, subclass ``ManifestStaticFilesStorage`` and set the
``support_js_module_import_aggregation`` attribute to ``True``.

* The new :attr:`.ManifestStaticFilesStorage.manifest_hash` attribute provides
a hash over all files in the manifest and changes whenever one of the files
changes.

Database backends
~~~~~~~~~~~~~~~~~

* The new ``"assume_role"`` option is now supported in :setting:`OPTIONS` on
PostgreSQL to allow specifying the :ref:`session role <database-role>`.

* The new ``"server_side_binding"`` option is now supported in
:setting:`OPTIONS` on PostgreSQL with ``psycopg`` 3.1.8+ to allow using
:ref:`server-side binding cursors <database-server-side-parameters-binding>`.

Error Reporting
~~~~~~~~~~~~~~~

* The debug page now shows :pep:`exception notes <678>` and
:pep:`fine-grained error locations <657>` on Python 3.11+.

* Session cookies are now treated as credentials and therefore hidden and
replaced with stars (``**********``) in error reports.

Forms
~~~~~

* :class:`~django.forms.ModelForm` now accepts the new ``Meta`` option
``formfield_callback`` to customize form fields.

* :func:`~django.forms.models.modelform_factory` now respects the
``formfield_callback`` attribute of the ``form``’s ``Meta``.

Internationalization
~~~~~~~~~~~~~~~~~~~~

* Added support and translations for the Central Kurdish (Sorani) language.

Logging
~~~~~~~

* The :ref:`django-db-logger` logger now logs transaction management queries
(``BEGIN``, ``COMMIT``, and ``ROLLBACK``) at the ``DEBUG`` level.

Management Commands
~~~~~~~~~~~~~~~~~~~

* :djadmin:`makemessages` command now supports locales with private sub-tags
such as ``nl_NL-x-informal``.

* The new :option:`makemigrations --update` option merges model changes into
the latest migration and optimizes the resulting operations.

Migrations
~~~~~~~~~~

* Migrations now support serialization of ``enum.Flag`` objects.

Models
~~~~~~

* ``QuerySet`` now extensively supports filtering against
:ref:`window-functions` with the exception of disjunctive filter lookups
against window functions when performing aggregation.

* :meth:`~.QuerySet.prefetch_related` now supports
:class:`~django.db.models.Prefetch` objects with sliced querysets.

* :ref:`Registering lookups <lookup-registration-api>` on
:class:`~django.db.models.Field` instances is now supported.

* The new ``robust`` argument for :func:`~django.db.transaction.on_commit`
allows performing actions that can fail after a database transaction is
successfully committed.

* The new :class:`KT() <django.db.models.fields.json.KT>` expression represents
the text value of a key, index, or path transform of
:class:`~django.db.models.JSONField`.

* :class:`~django.db.models.functions.Now` now supports microsecond precision
on MySQL and millisecond precision on SQLite.

* :class:`F() <django.db.models.F>` expressions that output ``BooleanField``
can now be negated using ``~F()`` (inversion operator).

* ``Model`` now provides asynchronous versions of some methods that use the
database, using an ``a`` prefix: :meth:`~.Model.adelete`,
:meth:`~.Model.arefresh_from_db`, and :meth:`~.Model.asave`.

* Related managers now provide asynchronous versions of methods that change a
set of related objects, using an ``a`` prefix: :meth:`~.RelatedManager.aadd`,
:meth:`~.RelatedManager.aclear`, :meth:`~.RelatedManager.aremove`, and
:meth:`~.RelatedManager.aset`.

* :attr:`CharField.max_length <django.db.models.CharField.max_length>` is no
longer required to be set on PostgreSQL, which supports unlimited ``VARCHAR``
columns.

Requests and Responses
~~~~~~~~~~~~~~~~~~~~~~

* :class:`~django.http.StreamingHttpResponse` now supports async iterators
when Django is served via ASGI.

Tests
~~~~~

* The :option:`test --debug-sql` option now formats SQL queries with
``sqlparse``.

* The :class:`~django.test.RequestFactory`,
:class:`~django.test.AsyncRequestFactory`, :class:`~django.test.Client`, and
:class:`~django.test.AsyncClient` classes now support the ``headers``
parameter, which accepts a dictionary of header names and values. This allows
a more natural syntax for declaring headers.

.. code-block:: python

   Before:
  self.client.get("/home/", HTTP_ACCEPT_LANGUAGE="fr")
  await self.async_client.get("/home/", ACCEPT_LANGUAGE="fr")

   After:
  self.client.get("/home/", headers={"accept-language": "fr"})
  await self.async_client.get("/home/", headers={"accept-language": "fr"})

Utilities
~~~~~~~~~

* The new ``encoder`` parameter for :meth:`django.utils.html.json_script`
function allows customizing a JSON encoder class.

* The private internal vendored copy of ``urllib.parse.urlsplit()`` now strips
``'\r'``, ``'\n'``, and ``'\t'`` (see :cve:`2022-0391` and :bpo:`43882`).
This is to protect projects that may be incorrectly using the internal
``url_has_allowed_host_and_scheme()`` function, instead of using one of the
documented functions for handling URL redirects. The Django functions were
not affected.

* The new :func:`django.utils.http.content_disposition_header` function returns
a ``Content-Disposition`` HTTP header value as specified by :rfc:`6266`.

Validators
~~~~~~~~~~

* The list of common passwords used by ``CommonPasswordValidator`` is updated
to the most recent version.

.. _backwards-incompatible-4.2:

Backwards incompatible changes in 4.2
=====================================

Database backend API
--------------------

This section describes changes that may be needed in third-party database
backends.

* ``DatabaseFeatures.allows_group_by_pk`` is removed as it only remained to
accommodate a MySQL extension that has been supplanted by proper functional
dependency detection in MySQL 5.7.15. Note that
``DatabaseFeatures.allows_group_by_selected_pks`` is still supported and
should be enabled if your backend supports functional dependency detection in
``GROUP BY`` clauses as specified by the ``SQL:1999`` standard.

* :djadmin:`inspectdb` now uses ``display_size`` from
``DatabaseIntrospection.get_table_description()`` rather than
``internal_size`` for ``CharField``.

Dropped support for MariaDB 10.3
--------------------------------

Upstream support for MariaDB 10.3 ends in May 2023. Django 4.2 supports MariaDB
10.4 and higher.

Dropped support for MySQL 5.7
-----------------------------

Upstream support for MySQL 5.7 ends in October 2023. Django 4.2 supports MySQL
8 and higher.

Dropped support for PostgreSQL 11
---------------------------------

Upstream support for PostgreSQL 11 ends in November 2023. Django 4.2 supports
PostgreSQL 12 and higher.

Setting ``update_fields`` in ``Model.save()`` may now be required
-----------------------------------------------------------------

In order to avoid updating unnecessary columns,
:meth:`.QuerySet.update_or_create` now passes ``update_fields`` to the
:meth:`Model.save() <django.db.models.Model.save>` calls. As a consequence, any
fields modified in the custom ``save()`` methods should be added to the
``update_fields`` keyword argument before calling ``super()``. See
:ref:`overriding-model-methods` for more details.

Dropped support for raw aggregations on MySQL
---------------------------------------------

MySQL 8+ allows functional dependencies on ``GROUP BY`` columns, so the
pre-Django 4.2 workaround of grouping by primary keys of the main table is
removed. As a consequence, using ``RawSQL()`` aggregations is no longer
supported on MySQL as there is no way to determine if such aggregations are
needed or valid in the ``GROUP BY`` clause. Use :ref:`aggregation-functions`
instead.

Miscellaneous
-------------

* The undocumented ``django.http.multipartparser.parse_header()`` function is
removed. Use ``django.utils.http.parse_header_parameters()`` instead.

* :ttag:`{% blocktranslate asvar … %}<blocktranslate>` result is now marked as
safe for (HTML) output purposes.

* The ``autofocus`` HTML attribute in the admin search box is removed as it can
be confusing for screen readers.

* The :option:`makemigrations --check` option n