- dev
- Version de la documentation : 5.0
Notes de publication de Django 5.0¶
4 décembre 2023
Bienvenue dans Django 5.0 !
Ces notes de publications couvrent les nouvelles fonctionnalités, ainsi que certaines modifications non rétrocompatibles dont il faut être au courant lors la mise à jour depuis Django 4.2 ou des versions plus anciennes. Nous avons commencé le processus d’obsolescence de certaines fonctionnalités.
Voir le guide Mise à jour de Django à une version plus récente si vous mettez à jour un projet existant.
Compatibilité Python¶
Django 5.0 requiert Python 3.10, 3.11 ou 3.12. Nous recommandons vivement et nous ne prenons officiellement en charge que la dernière publication de chaque série.
La série Django 4.2.x est la dernière à prendre en charge Python 3.8 et 3.9.
Prise en charge des bibliothèques tierces pour les anciennes versions de Django¶
Après la publication de Django 5.0, nous suggérons aux applications tierces de ne plus prendre en charge les versions de Django plus anciennes que 4.2. À ce moment, vous devriez pouvoir exécuter les tests de votre projet en utilisant python -Wd afin de faire apparaître les avertissements d’obsolescence. Après avoir corrigé ceux-ci, votre application devrait être compatible avec Django 5.0.
Quoi de neuf dans Django 5.0¶
Filtres de facettes dans le site d’administration¶
Des nombres de facettes sont maintenant visibles pour les filtres appliqués dans la liste pour modification du site d’administration lorsque les filtres sont activés dans l’interface. Ce comportement peut être modifié au travers du nouvel attribut ModelAdmin.show_facets
. Pour plus d’informations, lisez Facettes.
Gabarits simplifiés pour le rendu des champs de formulaire¶
Django 5.0 introduit le concept d’un groupe de champ et de gabarits de groupes de champs. Cela simplifie le rendu des éléments liés à un champ de formulaire Django, comme son étiquette, son composant, son texte d’aide et ses erreurs.
Par exemple, le gabarit ci-dessous :
<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>
Peut désormais être simplifié en :
<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>
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
Gabarits de groupes de champs réutilisables.
Database-computed default values¶
The new 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 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¶
Field.choices
(for model fields) and 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 Types énumératifs 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 ajoute la prise en charge des dictionnaires ou d’objets exécutables au lieu d’objets itérables et n’exige plus que .choices
soit explicitement mentionné pour étendre les types énumérations:
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 model field reference on choices.
Fonctionnalités mineures¶
django.contrib.admin
¶
- The new
AdminSite.get_log_entries()
method allows customizing the queryset for the site’s listed log entries. - The
django.contrib.admin.AllValuesFieldListFilter
,ChoicesFieldListFilter
,RelatedFieldListFilter
, andRelatedOnlyFieldListFilter
admin filters now handle multi-valued query parameters. XRegExp
is upgraded from version 3.2.0 to 5.1.1.- The new
AdminSite.get_model_admin()
method returns an admin class for the given model class. - Properties in
ModelAdmin.list_display
now supportboolean
attribute. - jQuery is upgraded from version 3.6.4 to 3.7.1.
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:django.contrib.auth.aauthenticate()
,aget_user()
,alogin()
,alogout()
, andaupdate_session_auth_hash()
. AuthenticationMiddleware
now adds anHttpRequest.auser()
asynchronous method that returns the currently logged-in user.- The new
django.contrib.auth.hashers.acheck_password()
asynchronous function andAbstractBaseUser.acheck_password()
method allow asynchronous checking of user passwords.
django.contrib.contenttypes
¶
QuerySet.prefetch_related()
now supports prefetchingGenericForeignKey
with non-homogeneous set of results.
django.contrib.gis
¶
- The new
ClosestPoint()
function returns a 2-dimensional point on the geometry that is closest to another geometry. - GIS aggregates now support the
filter
argument. - Support for GDAL 3.7 and GEOS 3.12 is added.
- The new
GEOSGeometry.equals_identical()
method allows point-wise equivalence checking of geometries.
django.contrib.messages
¶
- The new
MessagesTestMixin.assertMessages()
assertion method allows testingmessages
added to aresponse
.
django.contrib.postgres
¶
- The new
violation_error_code
attribute ofExclusionConstraint
allows customizing thecode
ofValidationError
raised during model validation.
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 Gestion des déconnexions for more details.
Décorateurs¶
- The following decorators now support wrapping asynchronous view functions:
cache_control()
never_cache()
no_append_slash()
csrf_exempt()
csrf_protect()
ensure_csrf_cookie()
requires_csrf_token()
sensitive_variables()
sensitive_post_parameters()
gzip_page()
condition()
conditional_page()
etag()
last_modified()
require_http_methods()
require_GET()
require_POST()
require_safe()
vary_on_cookie()
vary_on_headers()
xframe_options_deny()
xframe_options_sameorigin()
xframe_options_exempt()
Signalement d’erreurs¶
sensitive_variables()
andsensitive_post_parameters()
can now be used with asynchronous functions.
Stockage de fichier¶
File.open()
now passes all positional (*args
) and keyword arguments (**kwargs
) to Python’s built-inopen()
.
Formulaires¶
- The new
assume_scheme
argument forURLField
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.
- Form fields now include the
Internationalisation¶
- Support and translations for the Uyghur language are now available.
Migrations¶
- Serialization of functions decorated with
functools.cache()
orfunctools.lru_cache()
is now supported without the need to write a custom serializer.
Modèles¶
- The new
create_defaults
argument ofQuerySet.update_or_create()
andQuerySet.aupdate_or_create()
methods allows specifying a different field values for the create operation. - The new
violation_error_code
attribute ofBaseConstraint
,CheckConstraint
, andUniqueConstraint
allows customizing thecode
ofValidationError
raised during model validation. - The force_insert argument of
Model.save()
now allows specifying a tuple of parent classes that must be forced to be inserted. QuerySet.bulk_create()
andQuerySet.abulk_create()
methods now set the primary key on each model instance when theupdate_conflicts
parameter is enabled (if the database supports it).- The new
UniqueConstraint.nulls_distinct
attribute allows customizing the treatment ofNULL
values on PostgreSQL 15+. - The new
aget_object_or_404()
andaget_list_or_404()
asynchronous shortcuts allow asynchronous getting objects. - The new
aprefetch_related_objects()
function allows asynchronous prefetching of model instances. QuerySet.aiterator()
now supports previous calls toprefetch_related()
.- On MariaDB 10.7+,
UUIDField
is now created asUUID
column rather thanCHAR(32)
column. See the migration guide above for more details on Migrating existing UUIDField on MariaDB 10.7+. - 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
django.core.paginator.Paginator.error_messages
argument allows customizing the error messages raised byPaginator.page()
.
Signaux¶
- The new
Signal.asend()
andSignal.asend_robust()
methods allow asynchronous signal dispatch. Signal receivers may be synchronous or asynchronous, and will be automatically adapted to the correct calling style.
Tests¶
Client
andAsyncClient
now provide asynchronous methods, using ana
prefix:asession()
,alogin()
,aforce_login()
, andalogout()
.AsyncClient
now supports thefollow
parameter.- The new
test --durations
option allows showing the duration of the slowest tests on Python 3.12+.
Validateurs¶
- The new
offset
argument ofStepValueValidator
allows specifying an offset for valid values.
Changements incompatibles avec les anciennes versions dans Django 5.0¶
API de moteur de base de données¶
Cette section décrit des modifications qui pourraient être nécessaires dans des moteurs de base de données tiers.
DatabaseFeatures.supports_expression_defaults
should be set toFalse
if the database doesn’t support using database functions as defaults.DatabaseFeatures.supports_default_keyword_in_insert
should be set toFalse
if the database doesn’t support theDEFAULT
keyword inINSERT
queries.DatabaseFeatures.supports_default_keyword_in_bulk_insert
should be set toFalse
if the database doesn’t support theDEFAULT
keyword in bulkINSERT
queries.
django.contrib.gis
¶
- Support for GDAL 2.2 and 2.3 is removed.
- Support for GEOS 3.6 and 3.7 is removed.
django.contrib.sitemaps
¶
- The
django.contrib.sitemaps.ping_google()
function and theping_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()
¶
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 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
Par exemple :
class MyModel(models.Model):
uuid = models.UUIDField(primary_key=True, default=uuid.uuid4)
Devrait devenir :
class Char32UUIDField(models.UUIDField): ...
class MyModel(models.Model):
uuid = Char32UUIDField(primary_key=True, default=uuid.uuid4)
Running the makemigrations
command will generate a migration
containing a no-op AlterField
operation.
Divers¶
- The
instance
argument of the undocumentedBaseModelFormSet.save_existing()
method is renamed toobj
. - 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 thepost_init
signal ifwidth_field
andheight_field
are not set.Now
database function now usesLOCALTIMESTAMP
instead ofCURRENT_TIMESTAMP
on Oracle.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
andNotRegistered
exceptions are moved fromdjango.contrib.admin.sites
todjango.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
RuntimeWarning
. BadRequest
is raised for non-UTF-8 encoded requests with the application/x-www-form-urlencoded content type. See RFC 1866 for more details.- The minimum supported version of
colorama
is increased to 0.4.6. - The minimum supported version of
docutils
is increased to 0.19. - Filtering querysets against overflowing integer values now always returns an
empty queryset. As a consequence, you may need to use
ExpressionWrapper()
to explicitly wrap arithmetic against integer fields in such cases.
Fonctionnalités rendues obsolètes dans Django 5.0¶
Divers¶
- The
DjangoDivFormRenderer
andJinja2DivFormRenderer
transitional form renderers are deprecated. - Passing positional arguments
name
andviolation_error_message
toBaseConstraint
is deprecated in favor of keyword-only arguments. request
is added to the signature ofModelAdmin.lookup_allowed()
. Support forModelAdmin
subclasses that do not accept this argument is deprecated.- The
get_joining_columns()
method ofForeignObject
andForeignObjectRel
is deprecated. Starting with Django 6.0,django.db.models.sql.datastructures.Join
will no longer fallback toget_joining_columns()
. Subclasses should implementget_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. SetFORMS_URLFIELD_ASSUME_HTTPS
transitional setting toTrue
to opt into assuming"https"
during the Django 5.x release cycle. FORMS_URLFIELD_ASSUME_HTTPS
transitional setting is deprecated.- La prise en charge de l’appel à
format_html()
sans transmettre d’arguments, nommés ou pas, sera supprimée. - Support for
cx_Oracle
is deprecated in favor of oracledb 1.3.2+ Python driver. DatabaseOperations.field_cast_sql()
is deprecated in favor ofDatabaseOperations.lookup_cast()
. Starting with Django 6.0,BuiltinLookup.process_lhs()
will no longer callfield_cast_sql()
. Third-party database backends should implementlookup_cast()
instead.- The
django.db.models.enums.ChoicesMeta
metaclass is renamed toChoicesType
. - 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()
andprefetch_related_objects()
will no longer fallback toget_prefetch_queryset()
. Subclasses should implementget_prefetch_querysets()
instead.
Fonctionnalités supprimées dans 5.0¶
Ces fonctionnalités ont atteint la fin de leur cycle d’obsolescence et sont supprimées dans Django 5.0.
See Fonctionnalités rendues obsolètes dans Django 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 fromFalse
toTrue
. - The default sitemap protocol for sitemaps built outside the context of a
request is changed from
'http'
to'https'
. - The
extra_tests
argument forDiscoverRunner.build_suite()
andDiscoverRunner.run_tests()
is removed. - The
django.contrib.postgres.aggregates.ArrayAgg
,JSONBAgg
, andStringAgg
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
andOSMGeoAdmin
classes are removed. - The undocumented
BaseForm._html_output()
method is removed. - The ability to return a
str
, rather than aSafeString
, when rendering anErrorDict
andErrorList
is removed.
See Features deprecated in 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 ofdjango.utils.functional.cached_property()
is removed. - The
opclasses
argument ofdjango.contrib.postgres.constraints.ExclusionConstraint
is removed. - The undocumented ability to pass
errors=None
toSimpleTestCase.assertFormError()
andassertFormsetError()
is removed. django.contrib.sessions.serializers.PickleSerializer
is removed.- The usage of
QuerySet.iterator()
on a queryset that prefetches related objects without providing thechunk_size
argument is no longer allowed. - Passing unsaved model instances to related filters is no longer allowed.
created=True
is required in the signature ofRemoteUserBackend.configure_user()
subclasses.- Support for logging out via
GET
requests in thedjango.contrib.auth.views.LogoutView
anddjango.contrib.auth.views.logout_then_login()
is removed. - The
django.utils.timezone.utc
alias todatetime.timezone.utc
is removed. - Passing a response object and a form/formset name to
SimpleTestCase.assertFormError()
andassertFormSetError()
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
ornulls_last=False
toExpression.asc()
andExpression.desc()
methods, and theOrderBy
expression is no longer allowed.