Notes de publication de Django 5.2¶
April 2, 2025
Bienvenue dans Django 5.2 !
Ces notes de publications couvrent les nouvelles fonctionnalités, ainsi que certaines modifications non rétrocompatibles dont il faut être au courant lors de la mise à jour depuis Django 5.1 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.
Django 5.2 a été désigné comme une version prise en charge à long terme (LTS). Elle recevra des mises à jour de sécurité pour au moins 3 ans après sa publication initiale. La prise en charge de la version LTS précédente, Django 4.2, se terminera en avril 2026.
Compatibilité Python¶
Django 5.2 requiert Python 3.10, 3.11, 3.12 ou 3.13. Nous recommandons vivement et nous ne prenons officiellement en charge que la dernière publication de chaque série.
Quoi de neuf dans Django 5.2¶
Importation automatique des modèles dans le shell¶
La commande d’administration shell importe dorénavant automatiquement les modèles de toutes les applications installées. Il est possible d’afficher plus de détails sur les objets importés en définissant l’option --verbosity à 2 ou plus :
$ python -Wall manage.py shell --verbosity=2
6 objects imported automatically, including:
from django.contrib.admin.models import LogEntry
from django.contrib.auth.models import Group, Permission, User
from django.contrib.contenttypes.models import ContentType
from django.contrib.sessions.models import Session
...\> py -Wall manage.py shell --verbosity=2
6 objects imported automatically, including:
from django.contrib.admin.models import LogEntry
from django.contrib.auth.models import Group, Permission, User
from django.contrib.contenttypes.models import ContentType
from django.contrib.sessions.models import Session
Ce comportement peut être personnalisé pour ajouter ou enlever certaines importations automatiques.
Clés primaires composites¶
Le nouveau champ django.db.models.CompositePrimaryKey permet de créer des tables avec une clé primaire formée de plusieurs champs.
Pour utiliser une clé primaire composite lors de la définition d’un modèle, définissez l’attribut pk à une clé CompositePrimaryKey:
from django.db import models
class Release(models.Model):
pk = models.CompositePrimaryKey("version", "name")
version = models.IntegerField()
name = models.CharField(max_length=20)
Voir Clés primaires composites pour plus de détails.
Surcharge simplifiée de BoundField¶
Prior to version 5.2, overriding Field.get_bound_field() was the only
option to use a custom BoundField. Django now supports
specifying the following attributes to customize form rendering:
BaseRenderer.bound_field_classat the project level,Form.bound_field_classat the form level, andField.bound_field_classat the field level.
For example, to customize the BoundField of a Form class:
from django import forms
class CustomBoundField(forms.BoundField):
custom_class = "custom"
def css_classes(self, extra_classes=None):
result = super().css_classes(extra_classes)
if self.custom_class not in result:
result += f" {self.custom_class}"
return result.strip()
class CustomForm(forms.Form):
bound_field_class = CustomBoundField
name = forms.CharField(
label="Your Name",
max_length=100,
required=False,
widget=forms.TextInput(attrs={"class": "name-input-class"}),
)
email = forms.EmailField(label="Your Email")
When rendering a CustomForm instance, the following HTML is included:
<div class="custom">
<label for="id_name">Your Name:</label>
<input type="text" name="name" class="name-input-class" maxlength="100" id="id_name">
</div>
<div class="custom">
<label for="id_email">Your Email:</label>
<input type="email" name="email" maxlength="320" required="" id="id_email">
</div>
See Personnalisation de BoundField for more details about this feature.
Fonctionnalités mineures¶
django.contrib.admin¶
django.contrib.admindocs¶
Links to components in docstrings now supports custom link text, using the format
:role:`link text <link>`. See documentation helpers for more details.The model pages are now restricted to users with the corresponding view or change permissions.
django.contrib.auth¶
The default iteration count for the PBKDF2 password hasher is increased from 870,000 to 1,000,000.
The following new asynchronous methods are now provided, using an
aprefix:Auth backends can now provide async implementations which are used when calling async auth functions (e.g.
aauthenticate()) to reduce context-switching which improves performance. See adding an async interface for more details.The password validator classes now have a new method
get_error_message(), which can be overridden in subclasses to customize the error messages.
django.contrib.gis¶
GDAL now supports curved geometries
CurvePolygon,CompoundCurve,CircularString,MultiSurface, andMultiCurvevia the newOGRGeometry.has_curveproperty, and theOGRGeometry.get_linear_geometry()andOGRGeometry.get_curve_geometry()methods.
Moteurs de base de données¶
MySQL connections now default to using the
utf8mb4character set, instead ofutf8, which is an alias for the deprecated character setutf8mb3.Oracle backends now support connection pools, by setting
"pool"in theOPTIONSpart of your database configuration.
Décorateurs¶
method_decorator()now supports wrapping asynchronous view methods.
Email¶
Tuple items of
EmailMessage.attachmentsandEmailMultiAlternatives.attachmentsare now named tuples, as opposed to regular tuples.EmailMultiAlternatives.alternativesis now a list of named tuples, as opposed to regular tuples.The new
body_contains()method returns a boolean indicating whether a provided text is contained in the emailbodyand in all attached MIME typetext/*alternatives.
Signalement d’erreurs¶
The attribute
SafeExceptionReporterFilter.hidden_settingsnow treats values as sensitive if their name includesAUTH.
Formulaires¶
The new
ColorInputform widget is for entering a color inrrggbbhexadecimal format and renders as<input type="color" ...>. Some browsers support a visual color picker interface for this input type.The new
SearchInputform widget is for entering search queries and renders as<input type="search" ...>.The new
TelInputform widget is for entering telephone numbers and renders as<input type="tel" ...>.The new
field_idargument forErrorListallows an HTMLidattribute to be added in the error template. SeeErrorList.field_idfor details.An
aria_describedbyproperty is added toBoundFieldto ease use of this HTML attribute in templates.To improve accessibility for screen reader users
aria-describedbyis used to associate form fields with their error messages. See how form errors are displayed for details.The new asset object
Scriptis available for adding custom HTML-attributes to JavaScript in form media. See paths as objects for more details.
Commandes d’administration¶
A new warning is displayed when running
runserver, indicating that it is unsuitable for production. This warning can be suppressed by setting theDJANGO_RUNSERVER_HIDE_WARNINGenvironment variable to"true".The
makemigrationsandmigratecommands have a newCommand.autodetectorattribute for subclasses to override in order to use a custom autodetector class.The new
BaseCommand.get_check_kwargs()method can be overridden in custom commands to control the running of system checks, e.g. to opt into database-dependent checks.
Migrations¶
The new operation
AlterConstraintis a no-op operation that alters constraints without dropping and recreating constraints in the database.
Modèles¶
The
SELECTclause generated when usingQuerySet.values()andQuerySet.values_list()now matches the specified order of the referenced expressions. Previously, the order was based on a set of counterintuitive rules which made query combination through methods such asQuerySet.union()unpredictable.Added support for validation of model constraints which use a
GeneratedField.The new
Expression.set_returningattribute specifies that the expression contains a set-returning function, enforcing subquery evaluation. This is necessary for many Postgres set-returning functions.CharField.max_lengthis no longer required to be set on SQLite, which supports unlimitedVARCHARcolumns.QuerySet.explain()now supports thememoryandserializeoptions on PostgreSQL 17+.The new
JSONArraydatabase function accepts a list of field names or expressions and returns a JSON array containing those values.The new
Expression.allows_composite_expressionsattribute specifies that the expression allows composite expressions, for example, to support composite primary keys.
Requêtes et réponses¶
The new
HttpResponse.textproperty provides the string representation ofHttpResponse.content.The new
HttpRequest.get_preferred_type()method can be used to query the preferred media type the client accepts.The new
preserve_requestargument forHttpResponseRedirectandHttpResponsePermanentRedirectdetermines whether the HTTP status codes 302/307 or 301/308 are used, respectively.The new
preserve_requestargument forredirect()allows to instruct the user agent to reuse the HTTP method and body during redirection using specific status codes.
Sérialisation¶
Each serialization format now defines a
Deserializerclass, rather than a function, to improve extensibility when defining a custom serialization format.
Gabarits¶
The new
simple_block_tag()decorator enables the creation of simple block tags, which can accept and use a section of the template.
Tests¶
Stack frames from Django’s custom assertions are now hidden. This makes test failures easier to read and enables
test --pdbto directly enter into the failing test method.Data loaded from
fixturesand from migrations enabled with serialized_rollback=True are now available duringTransactionTestCase.setUpClass().
URL¶
reverse()andreverse_lazy()now acceptqueryandfragmentkeyword arguments, allowing the addition of a query string and/or fragment identifier in the generated URL, respectively.
Utilitaires¶
SafeStringnow returnsNotImplementedin__add__for non-string right-hand side values. This aligns with thestraddition behavior and allows__radd__to be used if available.format_html_join()now supports taking an iterable of mappings, passing their contents as keyword arguments toformat_html().
Backwards incompatible changes in 5.2¶
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.
The new
Model._is_pk_set()method allows checking if a Model instance’s primary key is defined.BaseDatabaseOperations.adapt_decimalfield_value()is now a no-op, simply returning the given value.
django.contrib.gis¶
Support for PostGIS 3.0 is removed.
Support for GDAL 3.0 is removed.
Dropped support for PostgreSQL 13¶
Upstream support for PostgreSQL 13 ends in November 2025. Django 5.2 supports PostgreSQL 14 and higher.
Changed MySQL connection character set default¶
MySQL connections now default to using the utf8mb4 character set, instead
of utf8, which is an alias for the deprecated character set utf8mb3.
utf8mb3 can be specified in the OPTIONS part of the DATABASES
setting, if needed for legacy databases.
Divers¶
Adding
EmailMultiAlternatives.alternativesis now only supported via theattach_alternative()method.The minimum supported version of
gettextis increased from 0.15 to 0.19.HttpRequest.accepted_typesis now sorted by the client’s preference, based on the request’sAcceptheader.The attributes
UniqueConstraint.violation_error_codeandUniqueConstraint.violation_error_messageare now always used when provided. Previously, they were ignored ifUniqueConstraint.fieldswas set without aUniqueConstraint.condition.The
debug()context processor is no longer included in the default project template.The following methods now have
alters_data=Trueset to prevent side effects when rendering a template context:The minimum supported version of
oracledbis increased from 1.3.2 to 2.3.0.Built-in aggregate functions accepting only one argument (
Avg,Count,Max,Min,StdDev,Sum, andVariance) now raiseTypeErrorwhen called with an incorrect number of arguments.
Features deprecated in 5.2¶
Divers¶
The
allargument for thedjango.contrib.staticfiles.finders.find()function is deprecated in favor of thefind_allargument.Fallbacks to
request.userandrequest.auser()whenuserisNoneindjango.contrib.auth.login()anddjango.contrib.auth.alogin(), respectively, are deprecated.The
orderingkeyword argument of the PostgreSQL specific aggregation functionsdjango.contrib.postgres.aggregates.ArrayAgg,django.contrib.postgres.aggregates.JSONBAgg, anddjango.contrib.postgres.aggregates.StringAggis deprecated in favor of theorder_byargument.Support for subclasses of
RemoteUserMiddlewarethat overrideprocess_request()without overridingaprocess_request()is deprecated.
