2023-01-06 06:31:13 +00:00
|
|
|
============================================
|
|
|
|
Django 5.0 release notes - UNDER DEVELOPMENT
|
|
|
|
============================================
|
|
|
|
|
|
|
|
*Expected December 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.
|
|
|
|
|
2023-01-18 08:46:01 +00:00
|
|
|
The Django 4.2.x series is the last to support Python 3.8 and 3.9.
|
|
|
|
|
2023-01-06 06:31:13 +00:00
|
|
|
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
|
|
|
|
========================
|
|
|
|
|
2023-02-16 12:23:24 +00:00
|
|
|
Facet filters in the admin
|
|
|
|
--------------------------
|
|
|
|
|
2023-03-05 13:01:19 +00:00
|
|
|
Facet counts are now shown for applied filters in the admin changelist when
|
2023-02-16 12:23:24 +00:00
|
|
|
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`.
|
|
|
|
|
2022-11-02 20:13:16 +00:00
|
|
|
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>
|
2023-06-01 10:19:11 +00:00
|
|
|
{{ form.name.label_tag }}
|
2022-11-02 20:13:16 +00:00
|
|
|
{% if form.name.help_text %}
|
2023-06-01 14:44:57 +00:00
|
|
|
<div class="helptext" id="{{ form.name.id_for_label }}_helptext">
|
|
|
|
{{ form.name.help_text|safe }}
|
|
|
|
</div>
|
2022-11-02 20:13:16 +00:00
|
|
|
{% endif %}
|
|
|
|
{{ form.name.errors }}
|
|
|
|
{{ form.name }}
|
|
|
|
<div class="row">
|
|
|
|
<div class="col">
|
2023-06-01 10:19:11 +00:00
|
|
|
{{ form.email.label_tag }}
|
2022-11-02 20:13:16 +00:00
|
|
|
{% if form.email.help_text %}
|
2023-06-01 14:44:57 +00:00
|
|
|
<div class="helptext" id="{{ form.email.id_for_label }}_helptext">
|
|
|
|
{{ form.email.help_text|safe }}
|
|
|
|
</div>
|
2022-11-02 20:13:16 +00:00
|
|
|
{% endif %}
|
|
|
|
{{ form.email.errors }}
|
|
|
|
{{ form.email }}
|
|
|
|
</div>
|
|
|
|
<div class="col">
|
2023-06-01 10:19:11 +00:00
|
|
|
{{ form.password.label_tag }}
|
2022-11-02 20:13:16 +00:00
|
|
|
{% if form.password.help_text %}
|
2023-06-01 14:44:57 +00:00
|
|
|
<div class="helptext" id="{{ form.password.id_for_label }}_helptext">
|
|
|
|
{{ form.password.help_text|safe }}
|
|
|
|
</div>
|
2022-11-02 20:13:16 +00:00
|
|
|
{% 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`.
|
|
|
|
|
2020-11-22 22:27:57 +00:00
|
|
|
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())
|
|
|
|
|
2023-07-07 02:36:48 +00:00
|
|
|
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
|
2023-09-20 07:00:30 +00:00
|
|
|
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"), db_persist=True)
|
2023-07-07 02:36:48 +00:00
|
|
|
|
2023-08-31 01:57:40 +00:00
|
|
|
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"),
|
|
|
|
]
|
|
|
|
|
|
|
|
|
2023-08-31 12:09:30 +00:00
|
|
|
class Winner(models.Model):
|
2023-08-31 01:57:40 +00:00
|
|
|
name = models.CharField(...)
|
|
|
|
medal = models.CharField(..., choices=Medal.choices)
|
|
|
|
sport = models.CharField(..., choices=SPORT_CHOICES)
|
|
|
|
|
2023-08-31 12:09:30 +00:00
|
|
|
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>`::
|
2023-08-31 01:57:40 +00:00
|
|
|
|
|
|
|
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",
|
|
|
|
}
|
|
|
|
|
|
|
|
|
2023-08-31 12:09:30 +00:00
|
|
|
def get_scores():
|
|
|
|
return [(i, str(i)) for i in range(10)]
|
|
|
|
|
|
|
|
|
|
|
|
class Winner(models.Model):
|
2023-08-31 01:57:40 +00:00
|
|
|
name = models.CharField(...)
|
|
|
|
medal = models.CharField(..., choices=Medal) # Using `.choices` not required.
|
|
|
|
sport = models.CharField(..., choices=SPORT_CHOICES)
|
2023-08-31 12:09:30 +00:00
|
|
|
score = models.IntegerField(choices=get_scores) # A callable is allowed.
|
2023-08-31 01:57:40 +00:00
|
|
|
|
|
|
|
Under the hood the provided ``choices`` are normalized into a list of 2-tuples
|
2023-08-31 12:09:30 +00:00
|
|
|
as the canonical form whenever the ``choices`` value is updated. For more
|
|
|
|
information, please check the :ref:`model field reference on choices
|
|
|
|
<field-choices>`.
|
2023-08-31 01:57:40 +00:00
|
|
|
|
2023-01-06 06:31:13 +00:00
|
|
|
Minor features
|
|
|
|
--------------
|
|
|
|
|
|
|
|
:mod:`django.contrib.admin`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2023-02-08 17:37:32 +00:00
|
|
|
* The new :meth:`.AdminSite.get_log_entries` method allows customizing the
|
|
|
|
queryset for the site's listed log entries.
|
2023-01-06 06:31:13 +00:00
|
|
|
|
2023-03-06 14:24:39 +00:00
|
|
|
* The ``django.contrib.admin.AllValuesFieldListFilter``,
|
|
|
|
``ChoicesFieldListFilter``, ``RelatedFieldListFilter``, and
|
|
|
|
``RelatedOnlyFieldListFilter`` admin filters now handle multi-valued query
|
|
|
|
parameters.
|
|
|
|
|
2023-04-18 14:11:40 +00:00
|
|
|
* ``XRegExp`` is upgraded from version 3.2.0 to 5.1.1.
|
|
|
|
|
2023-07-07 06:06:01 +00:00
|
|
|
* The new :meth:`.AdminSite.get_model_admin` method returns an admin class for
|
|
|
|
the given model class.
|
|
|
|
|
2023-09-14 12:10:20 +00:00
|
|
|
* Properties in :attr:`.ModelAdmin.list_display` now support ``boolean``
|
|
|
|
attribute.
|
|
|
|
|
2023-09-18 06:54:44 +00:00
|
|
|
* jQuery is upgraded from version 3.6.4 to 3.7.1.
|
|
|
|
|
2023-01-06 06:31:13 +00:00
|
|
|
|
|
|
|
:mod:`django.contrib.auth`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2023-01-25 21:25:29 +00:00
|
|
|
* The default iteration count for the PBKDF2 password hasher is increased from
|
2023-02-04 12:37:44 +00:00
|
|
|
600,000 to 720,000.
|
2023-01-06 06:31:13 +00:00
|
|
|
|
2023-02-11 01:43:26 +00:00
|
|
|
* 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`.
|
|
|
|
|
2023-02-13 23:24:35 +00:00
|
|
|
* ``AuthenticationMiddleware`` now adds an :meth:`.HttpRequest.auser`
|
|
|
|
asynchronous method that returns the currently logged-in user.
|
|
|
|
|
2023-05-14 16:12:22 +00:00
|
|
|
* The new :func:`django.contrib.auth.hashers.acheck_password` asynchronous
|
|
|
|
function and :meth:`.AbstractBaseUser.acheck_password` method allow
|
|
|
|
asynchronous checking of user passwords.
|
|
|
|
|
2023-01-06 06:31:13 +00:00
|
|
|
:mod:`django.contrib.contenttypes`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2023-08-01 21:31:40 +00:00
|
|
|
* :meth:`.QuerySet.prefetch_related` now supports prefetching
|
|
|
|
:class:`~django.contrib.contenttypes.fields.GenericForeignKey` with
|
|
|
|
non-homogeneous set of results.
|
2023-01-06 06:31:13 +00:00
|
|
|
|
|
|
|
:mod:`django.contrib.gis`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2023-01-13 16:48:27 +00:00
|
|
|
* 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.
|
2023-01-06 06:31:13 +00:00
|
|
|
|
2023-06-03 13:54:22 +00:00
|
|
|
* :ref:`GIS aggregates <gis-aggregation-functions>` now support the ``filter``
|
|
|
|
argument.
|
|
|
|
|
2023-09-18 12:06:15 +00:00
|
|
|
* Support for GDAL 3.7 and GEOS 3.12 is added.
|
2023-07-10 15:43:19 +00:00
|
|
|
|
2023-07-26 21:18:29 +00:00
|
|
|
* The new :meth:`.GEOSGeometry.equals_identical` method allows point-wise
|
|
|
|
equivalence checking of geometries.
|
|
|
|
|
2023-01-06 06:31:13 +00:00
|
|
|
:mod:`django.contrib.messages`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2023-06-15 15:16:46 +00:00
|
|
|
* The new :meth:`.MessagesTestMixin.assertMessages` assertion method allows
|
|
|
|
testing :mod:`~django.contrib.messages` added to a
|
|
|
|
:class:`response <django.http.HttpResponse>`.
|
2023-01-06 06:31:13 +00:00
|
|
|
|
|
|
|
:mod:`django.contrib.postgres`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2023-02-14 20:06:45 +00:00
|
|
|
* 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>`.
|
2023-01-06 06:31:13 +00:00
|
|
|
|
2022-12-21 19:25:24 +00:00
|
|
|
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.
|
|
|
|
|
2023-01-06 06:31:13 +00:00
|
|
|
Decorators
|
|
|
|
~~~~~~~~~~
|
|
|
|
|
2023-04-26 06:08:33 +00:00
|
|
|
* The following decorators now support wrapping asynchronous view functions:
|
|
|
|
|
|
|
|
* :func:`~django.views.decorators.cache.cache_control`
|
|
|
|
* :func:`~django.views.decorators.cache.never_cache`
|
2023-05-19 13:14:32 +00:00
|
|
|
* :func:`~django.views.decorators.common.no_append_slash`
|
2023-07-08 20:00:42 +00:00
|
|
|
* :func:`~django.views.decorators.csrf.csrf_exempt`
|
2023-07-08 21:51:19 +00:00
|
|
|
* :func:`~django.views.decorators.csrf.csrf_protect`
|
|
|
|
* :func:`~django.views.decorators.csrf.ensure_csrf_cookie`
|
|
|
|
* :func:`~django.views.decorators.csrf.requires_csrf_token`
|
2023-05-07 03:20:00 +00:00
|
|
|
* :func:`~django.views.decorators.debug.sensitive_variables`
|
|
|
|
* :func:`~django.views.decorators.debug.sensitive_post_parameters`
|
2023-07-08 21:51:19 +00:00
|
|
|
* :func:`~django.views.decorators.gzip.gzip_page`
|
2023-04-11 11:40:55 +00:00
|
|
|
* :func:`~django.views.decorators.http.condition`
|
2023-07-08 21:51:19 +00:00
|
|
|
* ``conditional_page()``
|
2023-04-11 11:40:55 +00:00
|
|
|
* :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`
|
2023-07-08 20:54:37 +00:00
|
|
|
* :func:`~django.views.decorators.vary.vary_on_cookie`
|
|
|
|
* :func:`~django.views.decorators.vary.vary_on_headers`
|
2023-04-26 06:08:33 +00:00
|
|
|
* ``xframe_options_deny()``
|
|
|
|
* ``xframe_options_sameorigin()``
|
|
|
|
* ``xframe_options_exempt()``
|
2023-01-06 06:31:13 +00:00
|
|
|
|
|
|
|
Error Reporting
|
|
|
|
~~~~~~~~~~~~~~~
|
|
|
|
|
2023-05-07 03:20:00 +00:00
|
|
|
* :func:`~django.views.decorators.debug.sensitive_variables` and
|
|
|
|
:func:`~django.views.decorators.debug.sensitive_post_parameters` can now be
|
|
|
|
used with asynchronous functions.
|
2023-01-06 06:31:13 +00:00
|
|
|
|
|
|
|
File Storage
|
|
|
|
~~~~~~~~~~~~
|
|
|
|
|
2023-08-18 16:52:57 +00:00
|
|
|
* :meth:`.File.open` now passes all positional (``*args``) and keyword
|
|
|
|
arguments (``**kwargs``) to Python's built-in :func:`python:open`.
|
2023-01-06 06:31:13 +00:00
|
|
|
|
|
|
|
Forms
|
|
|
|
~~~~~
|
|
|
|
|
2023-03-08 19:12:34 +00:00
|
|
|
* The new ``assume_scheme`` argument for :class:`~django.forms.URLField` allows
|
|
|
|
specifying a default URL scheme.
|
|
|
|
|
2023-09-18 12:06:15 +00:00
|
|
|
* In order to improve accessibility, the following changes are made:
|
2023-06-01 14:44:57 +00:00
|
|
|
|
2023-09-18 12:06:15 +00:00
|
|
|
* 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.
|
2023-06-02 14:27:24 +00:00
|
|
|
|
2023-01-06 06:31:13 +00:00
|
|
|
Internationalization
|
|
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2023-09-18 12:06:15 +00:00
|
|
|
* Support and translations for the Uyghur language are now available.
|
2023-01-06 06:31:13 +00:00
|
|
|
|
|
|
|
Migrations
|
|
|
|
~~~~~~~~~~
|
|
|
|
|
2023-09-13 14:49:10 +00:00
|
|
|
* Serialization of functions decorated with :func:`functools.cache` or
|
|
|
|
:func:`functools.lru_cache` is now supported without the need to write a
|
|
|
|
custom serializer.
|
2023-01-06 06:31:13 +00:00
|
|
|
|
|
|
|
Models
|
|
|
|
~~~~~~
|
|
|
|
|
2023-01-31 02:39:15 +00:00
|
|
|
* 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.
|
2023-01-06 06:31:13 +00:00
|
|
|
|
2023-02-14 20:06:45 +00:00
|
|
|
* 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>`.
|
|
|
|
|
2023-06-22 12:53:11 +00:00
|
|
|
* 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.
|
|
|
|
|
2023-07-07 11:08:17 +00:00
|
|
|
* :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).
|
|
|
|
|
2023-07-07 23:43:51 +00:00
|
|
|
* The new :attr:`.UniqueConstraint.nulls_distinct` attribute allows customizing
|
|
|
|
the treatment of ``NULL`` values on PostgreSQL 15+.
|
|
|
|
|
2023-07-20 15:50:06 +00:00
|
|
|
* The new :func:`~django.shortcuts.aget_object_or_404` and
|
|
|
|
:func:`~django.shortcuts.aget_list_or_404` asynchronous shortcuts allow
|
|
|
|
asynchronous getting objects.
|
|
|
|
|
2023-07-27 21:38:12 +00:00
|
|
|
* 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()``.
|
|
|
|
|
2022-10-19 12:20:48 +00:00
|
|
|
* 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`.
|
|
|
|
|
2022-07-12 06:22:40 +00:00
|
|
|
* 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.
|
|
|
|
|
2023-04-10 01:30:40 +00:00
|
|
|
Pagination
|
|
|
|
~~~~~~~~~~
|
|
|
|
|
|
|
|
* The new :attr:`django.core.paginator.Paginator.error_messages` argument
|
|
|
|
allows customizing the error messages raised by :meth:`.Paginator.page`.
|
|
|
|
|
2023-01-06 06:31:13 +00:00
|
|
|
Signals
|
|
|
|
~~~~~~~
|
|
|
|
|
2020-11-07 10:19:20 +00:00
|
|
|
* 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.
|
2023-01-06 06:31:13 +00:00
|
|
|
|
|
|
|
Templates
|
|
|
|
~~~~~~~~~
|
|
|
|
|
2023-05-19 22:33:51 +00:00
|
|
|
* The new :tfilter:`escapeseq` template filter applies :tfilter:`escape` to
|
|
|
|
each element of a sequence.
|
2023-01-06 06:31:13 +00:00
|
|
|
|
|
|
|
Tests
|
|
|
|
~~~~~
|
|
|
|
|
2023-02-11 01:43:26 +00:00
|
|
|
* :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`.
|
2023-01-06 06:31:13 +00:00
|
|
|
|
2023-08-04 07:14:19 +00:00
|
|
|
* :class:`~django.test.AsyncClient` now supports the ``follow`` parameter.
|
|
|
|
|
2023-06-14 18:22:48 +00:00
|
|
|
* The new :option:`test --durations` option allows showing the duration of the
|
|
|
|
slowest tests on Python 3.12+.
|
|
|
|
|
2023-01-06 06:31:13 +00:00
|
|
|
Validators
|
|
|
|
~~~~~~~~~~
|
|
|
|
|
2023-04-08 20:10:17 +00:00
|
|
|
* The new ``offset`` argument of
|
|
|
|
:class:`~django.core.validators.StepValueValidator` allows specifying an
|
|
|
|
offset for valid values.
|
2023-01-06 06:31:13 +00:00
|
|
|
|
|
|
|
.. _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.
|
|
|
|
|
2020-11-22 22:27:57 +00:00
|
|
|
* ``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.
|
|
|
|
|
2023-09-19 07:27:28 +00:00
|
|
|
* ``DatabaseFeatures.supports_default_keyword_in_bulk_insert`` should be set to
|
2020-11-22 22:27:57 +00:00
|
|
|
``False`` if the database doesn't support the ``DEFAULT`` keyword in bulk
|
|
|
|
``INSERT`` queries.
|
2023-01-06 06:31:13 +00:00
|
|
|
|
2023-06-29 07:11:30 +00:00
|
|
|
:mod:`django.contrib.gis`
|
|
|
|
-------------------------
|
|
|
|
|
|
|
|
* Support for GDAL 2.2 and 2.3 is removed.
|
|
|
|
|
2023-06-29 19:45:36 +00:00
|
|
|
* Support for GEOS 3.6 and 3.7 is removed.
|
|
|
|
|
2023-07-02 20:48:56 +00:00
|
|
|
: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.
|
|
|
|
|
2023-09-18 12:06:15 +00:00
|
|
|
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.
|
|
|
|
|
2023-01-31 02:39:15 +00:00
|
|
|
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``.
|
|
|
|
|
2022-10-19 12:20:48 +00:00
|
|
|
.. _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)"
|
|
|
|
|
|
|
|
For example::
|
|
|
|
|
|
|
|
class MyModel(models.Model):
|
|
|
|
uuid = models.UUIDField(primary_key=True, default=uuid.uuid4)
|
|
|
|
|
|
|
|
Should become::
|
|
|
|
|
|
|
|
class Char32UUIDField(models.UUIDField):
|
|
|
|
def db_type(self, connection):
|
|
|
|
return "char(32)"
|
|
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
2023-01-06 06:31:13 +00:00
|
|
|
Miscellaneous
|
|
|
|
-------------
|
|
|
|
|
2023-02-07 13:18:58 +00:00
|
|
|
* The ``instance`` argument of the undocumented
|
|
|
|
``BaseModelFormSet.save_existing()`` method is renamed to ``obj``.
|
2023-01-06 06:31:13 +00:00
|
|
|
|
2023-01-31 18:05:03 +00:00
|
|
|
* The undocumented ``django.contrib.admin.helpers.checkbox`` is removed.
|
|
|
|
|
2023-03-01 22:13:00 +00:00
|
|
|
* Integer fields are now validated as 64-bit integers on SQLite to match the
|
|
|
|
behavior of ``sqlite3``.
|
|
|
|
|
2023-03-13 14:03:28 +00:00
|
|
|
* The undocumented ``Query.annotation_select_mask`` attribute is changed from a
|
|
|
|
set of strings to an ordered list of strings.
|
|
|
|
|
2023-04-26 07:22:43 +00:00
|
|
|
* ``ImageField.update_dimension_fields()`` is no longer called on the
|
|
|
|
``post_init`` signal if ``width_field`` and ``height_field`` are not set.
|
|
|
|
|
2023-05-11 16:22:55 +00:00
|
|
|
* :class:`~django.db.models.functions.Now` database function now uses
|
|
|
|
``LOCALTIMESTAMP`` instead of ``CURRENT_TIMESTAMP`` on Oracle.
|
|
|
|
|
2023-06-02 10:54:07 +00:00
|
|
|
* :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.
|
|
|
|
|
2023-09-13 19:25:02 +00:00
|
|
|
* 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>``.
|
2023-09-13 22:17:50 +00:00
|
|
|
|
2023-05-30 04:59:22 +00:00
|
|
|
* 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.
|
|
|
|
|
2023-06-23 19:52:04 +00:00
|
|
|
* The minimum supported version of ``asgiref`` is increased from 3.6.0 to
|
|
|
|
3.7.0.
|
|
|
|
|
2023-06-26 12:22:54 +00:00
|
|
|
* The minimum supported version of ``selenium`` is increased from 3.8.0 to
|
|
|
|
4.8.0.
|
|
|
|
|
2023-07-07 11:22:06 +00:00
|
|
|
* The ``AlreadyRegistered`` and ``NotRegistered`` exceptions are moved from
|
|
|
|
``django.contrib.admin.sites`` to ``django.contrib.admin.exceptions``.
|
|
|
|
|
2023-08-04 04:35:13 +00:00
|
|
|
* The minimum supported version of SQLite is increased from 3.21.0 to 3.27.0.
|
|
|
|
|
2023-08-09 10:41:47 +00:00
|
|
|
* Support for ``cx_Oracle`` < 8.3 is removed.
|
|
|
|
|
2023-06-01 14:39:52 +00:00
|
|
|
* Executing SQL queries before the app registry has been fully populated now
|
|
|
|
raises :exc:`RuntimeWarning`.
|
|
|
|
|
2023-08-25 19:27:22 +00:00
|
|
|
* :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.
|
|
|
|
|
2023-08-31 03:03:30 +00:00
|
|
|
* The minimum supported version of ``colorama`` is increased to 0.4.6.
|
|
|
|
|
2023-09-04 16:13:10 +00:00
|
|
|
* The minimum supported version of ``docutils`` is increased to 0.19.
|
|
|
|
|
2023-01-06 06:31:13 +00:00
|
|
|
.. _deprecated-features-5.0:
|
|
|
|
|
|
|
|
Features deprecated in 5.0
|
|
|
|
==========================
|
|
|
|
|
|
|
|
Miscellaneous
|
|
|
|
-------------
|
|
|
|
|
2023-01-18 10:08:39 +00:00
|
|
|
* The ``DjangoDivFormRenderer`` and ``Jinja2DivFormRenderer`` transitional form
|
|
|
|
renderers are deprecated.
|
2023-01-06 06:31:13 +00:00
|
|
|
|
2023-09-18 12:06:15 +00:00
|
|
|
* Passing positional arguments ``name`` and ``violation_error_message`` to
|
2023-02-20 13:28:21 +00:00
|
|
|
:class:`~django.db.models.BaseConstraint` is deprecated in favor of
|
|
|
|
keyword-only arguments.
|
|
|
|
|
2023-04-13 09:46:47 +00:00
|
|
|
* ``request`` is added to the signature of :meth:`.ModelAdmin.lookup_allowed`.
|
|
|
|
Support for ``ModelAdmin`` subclasses that do not accept this argument is
|
|
|
|
deprecated.
|
|
|
|
|
2023-04-18 08:20:32 +00:00
|
|
|
* 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.
|
|
|
|
|
2023-03-08 19:12:34 +00:00
|
|
|
* The default scheme for ``forms.URLField`` will change from ``"http"`` to
|
|
|
|
``"https"`` in Django 6.0.
|
|
|
|
|
2023-06-06 08:56:53 +00:00
|
|
|
* Support for calling ``format_html()`` without passing args or kwargs will be
|
|
|
|
removed.
|
|
|
|
|
2022-07-12 06:22:40 +00:00
|
|
|
* Support for ``cx_Oracle`` is deprecated in favor of `oracledb`_ 1.3.2+ Python
|
|
|
|
driver.
|
|
|
|
|
2023-08-18 13:16:57 +00:00
|
|
|
* ``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.
|
|
|
|
|
2023-08-23 09:04:37 +00:00
|
|
|
* The ``django.db.models.enums.ChoicesMeta`` metaclass is renamed to
|
|
|
|
``ChoicesType``.
|
|
|
|
|
2023-08-01 21:31:40 +00:00
|
|
|
* 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.
|
|
|
|
|
2022-07-12 06:22:40 +00:00
|
|
|
.. _`oracledb`: https://oracle.github.io/python-oracledb/
|
|
|
|
|
2023-01-06 06:31:13 +00:00
|
|
|
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.
|
|
|
|
|
2023-01-06 08:28:25 +00:00
|
|
|
* The ``SERIALIZE`` test setting is removed.
|
2023-01-06 06:31:13 +00:00
|
|
|
|
2023-01-06 08:33:02 +00:00
|
|
|
* The undocumented ``django.utils.baseconv`` module is removed.
|
|
|
|
|
2023-01-06 08:37:41 +00:00
|
|
|
* The undocumented ``django.utils.datetime_safe`` module is removed.
|
|
|
|
|
2023-01-06 11:30:23 +00:00
|
|
|
* The default value of the ``USE_TZ`` setting is changed from ``False`` to
|
|
|
|
``True``.
|
|
|
|
|
2023-01-06 11:55:14 +00:00
|
|
|
* The default sitemap protocol for sitemaps built outside the context of a
|
|
|
|
request is changed from ``'http'`` to ``'https'``.
|
|
|
|
|
2023-01-06 12:12:23 +00:00
|
|
|
* The ``extra_tests`` argument for ``DiscoverRunner.build_suite()`` and
|
|
|
|
``DiscoverRunner.run_tests()`` is removed.
|
|
|
|
|
2023-01-06 12:53:42 +00:00
|
|
|
* The ``django.contrib.postgres.aggregates.ArrayAgg``, ``JSONBAgg``, and
|
|
|
|
``StringAgg`` aggregates no longer return ``[]``, ``[]``, and ``''``,
|
|
|
|
respectively, when there are no rows.
|
|
|
|
|
2023-01-06 13:46:33 +00:00
|
|
|
* The ``USE_L10N`` setting is removed.
|
|
|
|
|
2023-01-09 08:03:38 +00:00
|
|
|
* The ``USE_DEPRECATED_PYTZ`` transitional setting is removed.
|
|
|
|
|
|
|
|
* Support for ``pytz`` timezones is removed.
|
|
|
|
|
2023-01-09 08:52:26 +00:00
|
|
|
* 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()``
|
|
|
|
|
2023-01-10 12:01:14 +00:00
|
|
|
* The ``django.contrib.gis.admin.GeoModelAdmin`` and ``OSMGeoAdmin`` classes
|
|
|
|
are removed.
|
|
|
|
|
2023-01-10 12:43:21 +00:00
|
|
|
* The undocumented ``BaseForm._html_output()`` method is removed.
|
|
|
|
|
2023-01-11 05:07:16 +00:00
|
|
|
* The ability to return a ``str``, rather than a ``SafeString``, when rendering
|
|
|
|
an ``ErrorDict`` and ``ErrorList`` is removed.
|
|
|
|
|
2023-01-06 06:31:13 +00:00
|
|
|
See :ref:`deprecated-features-4.1` for details on these changes, including how
|
|
|
|
to remove usage of these features.
|
|
|
|
|
2023-01-12 11:34:42 +00:00
|
|
|
* The ``SitemapIndexItem.__str__()`` method is removed.
|
2023-01-12 11:47:42 +00:00
|
|
|
|
|
|
|
* The ``CSRF_COOKIE_MASKED`` transitional setting is removed.
|
2023-01-12 12:00:18 +00:00
|
|
|
|
|
|
|
* The ``name`` argument of ``django.utils.functional.cached_property()`` is
|
|
|
|
removed.
|
2023-01-12 12:20:08 +00:00
|
|
|
|
|
|
|
* The ``opclasses`` argument of
|
|
|
|
``django.contrib.postgres.constraints.ExclusionConstraint`` is removed.
|
2023-01-12 13:32:00 +00:00
|
|
|
|
|
|
|
* The undocumented ability to pass ``errors=None`` to
|
|
|
|
``SimpleTestCase.assertFormError()`` and ``assertFormsetError()`` is removed.
|
2023-01-12 13:43:48 +00:00
|
|
|
|
|
|
|
* ``django.contrib.sessions.serializers.PickleSerializer`` is removed.
|
2023-01-12 18:13:22 +00:00
|
|
|
|
|
|
|
* The usage of ``QuerySet.iterator()`` on a queryset that prefetches related
|
|
|
|
objects without providing the ``chunk_size`` argument is no longer allowed.
|
2023-01-12 18:31:49 +00:00
|
|
|
|
|
|
|
* Passing unsaved model instances to related filters is no longer allowed.
|
2023-01-13 04:49:36 +00:00
|
|
|
|
|
|
|
* ``created=True`` is required in the signature of
|
|
|
|
``RemoteUserBackend.configure_user()`` subclasses.
|
2023-01-13 05:03:29 +00:00
|
|
|
|
|
|
|
* Support for logging out via ``GET`` requests in the
|
|
|
|
``django.contrib.auth.views.LogoutView`` and
|
|
|
|
``django.contrib.auth.views.logout_then_login()`` is removed.
|
2023-01-13 07:22:41 +00:00
|
|
|
|
|
|
|
* The ``django.utils.timezone.utc`` alias to ``datetime.timezone.utc`` is
|
|
|
|
removed.
|
2023-01-13 07:31:30 +00:00
|
|
|
|
|
|
|
* Passing a response object and a form/formset name to
|
|
|
|
``SimpleTestCase.assertFormError()`` and ``assertFormSetError()`` is no
|
|
|
|
longer allowed.
|
2023-01-13 07:36:50 +00:00
|
|
|
|
|
|
|
* The ``django.contrib.gis.admin.OpenLayersWidget`` is removed.
|
2023-01-13 08:09:58 +00:00
|
|
|
|
|
|
|
+ The ``django.contrib.auth.hashers.CryptPasswordHasher`` is removed.
|
2023-01-13 08:32:35 +00:00
|
|
|
|
|
|
|
* 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.
|
2023-01-13 08:49:28 +00:00
|
|
|
|
|
|
|
* Passing ``nulls_first=False`` or ``nulls_last=False`` to ``Expression.asc()``
|
|
|
|
and ``Expression.desc()`` methods, and the ``OrderBy`` expression is no
|
|
|
|
longer allowed.
|