Pin django to latest version 5.0.1

[pyup-bot]

This PR pins django to the latest release 5.0.1.

Changelog

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.

* The new :option:`test --durations` option allows showing the duration of the
slowest tests 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.

.. _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.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 no longer creates missing
migration files.

* The ``alias`` argument for :meth:`.Expression.get_group_by_cols` is removed.

* The minimum supported version of ``sqlparse`` is increased from 0.2.2 to
0.3.1.

* The undocumented ``negated`` parameter of the
:class:`~django.db.models.Exists` expression is removed.

* The ``is_summary`` argument of the undocumented ``Query.add_annotation()``
method is removed.

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

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

* :class:`~django.contrib.auth.forms.UserCreationForm` now rejects usernames
that differ only in case. If you need the previous behavior, use
:class:`~django.contrib.auth.forms.BaseUserCreationForm` instead.

* The minimum supported version of ``mysqlclient`` is increased from 1.4.0 to
1.4.3.

* The minimum supported version of ``argon2-cffi`` is increased  from 19.1.0 to
19.2.0.

* The minimum supported version of ``Pillow`` is increased from 6.2.0 to 6.2.1.

* The minimum supported version of ``jinja2`` is increased from 2.9.2 to
2.11.0.

* The minimum supported version of :pypi:`redis-py <redis>` is increased from
3.0.0 to 3.4.0.

* Manually instantiated ``WSGIRequest`` objects must be provided a file-like
object for ``wsgi.input``. Previously, Django was more lax than the expected
behavior as specified by the WSGI specification.

* Support for ``PROJ`` < 5 is removed.

* :class:`~django.core.mail.backends.smtp.EmailBackend` now verifies a
:py:attr:`hostname <ssl.SSLContext.check_hostname>` and
:py:attr:`certificates <ssl.SSLContext.verify_mode>`. If you need the
previous behavior that is less restrictive and not recommended, subclass
``EmailBackend`` and override the ``ssl_context`` property.

.. _deprecated-features-4.2:

Features deprecated in 4.2
==========================

``index_together`` option is deprecated in favor of ``indexes``
---------------------------------------------------------------

The ``Meta.index_together`` option is deprecated in favor of the
:attr:`~django.db.models.Options.indexes` option.

Migrating existing ``index_together`` should be handled as a migration. For
example::

 class Author(models.Model):
     rank = models.IntegerField()
     name = models.CharField(max_length=30)

     class Meta:
         index_together = [["rank", "name"]]

Should become::

 class Author(models.Model):
     rank = models.IntegerField()
     name = models.CharField(max_length=30)

     class Meta:
         indexes = [models.Index(fields=["rank", "name"])]

Running the :djadmin:`makemigrations` command will generate a migration
containing a :class:`~django.db.migrations.operations.RenameIndex` operation
which will rename the existing index. Next, consider squashing migrations to
remove ``index_together`` from historical migrations.

The ``AlterIndexTogether`` migration operation is now officially supported only
for pre-Django 4.2 migration files. For backward compatibility reasons, it's
still part of the public API, and there's no plan to deprecate or remove it,
but it should not be used for new migrations. Use
:class:`~django.db.migrations.operations.AddIndex` and
:class:`~django.db.migrations.operations.RemoveIndex` operations instead.

Passing encoded JSON string literals to ``JSONField`` is deprecated
-------------------------------------------------------------------

``JSONField`` and its associated lookups and aggregates used to allow passing
JSON encoded string literals which caused ambiguity on whether string literals
were already encoded from database backend's perspective.

During the deprecation period string literals will be attempted to be JSON
decoded and a warning will be emitted on success that points at passing
non-encoded forms instead.

Code that used to pass JSON encoded string literals::

 Document.objects.bulk_create(
     Document(data=Value("null")),
     Document(data=Value("[]")),
     Document(data=Value('"foo-bar"')),
 )
 Document.objects.annotate(
     JSONBAgg("field", default=Value("[]")),
 )

Should become::

 Document.objects.bulk_create(
     Document(data=Value(None, JSONField())),
     Document(data=[]),
     Document(data="foo-bar"),
 )
 Document.objects.annotate(
     JSONBAgg("field", default=[]),
 )

From Django 5.1+ string literals will be implicitly interpreted as JSON string
literals.

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

* The ``BaseUserManager.make_random_password()`` method is deprecated. See
`recipes and best practices
<https://docs.python.org/3/library/secrets.html#recipes-and-best-practices>`_
for using Python's :py:mod:`secrets` module to generate passwords.

* The ``length_is`` template filter is deprecated in favor of :tfilter:`length`
and the ``==`` operator within an :ttag:`{% if %}<if>` tag. For example

.. code-block:: html+django

 {% if value|length == 4 %}…{% endif %}
 {% if value|length == 4 %}True{% else %}False{% endif %}

instead of:

.. code-block:: html+django

 {% if value|length_is:4 %}…{% endif %}
 {{ value|length_is:4 }}

* ``django.contrib.auth.hashers.SHA1PasswordHasher``,
``django.contrib.auth.hashers.UnsaltedSHA1PasswordHasher``, and
``django.contrib.auth.hashers.UnsaltedMD5PasswordHasher`` are deprecated.

* ``django.contrib.postgres.fields.CICharField`` is deprecated in favor of
``CharField(db_collation="…")`` with a case-insensitive non-deterministic
collation.

* ``django.contrib.postgres.fields.CIEmailField`` is deprecated in favor of
``EmailField(db_collation="…")`` with a case-insensitive non-deterministic
collation.

* ``django.contrib.postgres.fields.CITextField`` is deprecated in favor of
``TextField(db_collation="…")`` with a case-insensitive non-deterministic
collation.

* ``django.contrib.postgres.fields.CIText`` mixin is deprecated.

* The ``map_height`` and ``map_width`` attributes of ``BaseGeometryWidget`` are
deprecated, use CSS to size map widgets instead.

* ``SimpleTestCase.assertFormsetError()`` is deprecated in favor of
``assertFormSetError()``.

* ``TransactionTestCase.assertQuerysetEqual()`` is deprecated in favor of
``assertQuerySetEqual()``.

* Passing positional arguments to ``Signer`` and ``TimestampSigner`` is
deprecated in favor of keyword-only arguments.

* The ``DEFAULT_FILE_STORAGE`` setting is deprecated in favor of
``STORAGES["default"]``.

* The ``STATICFIL