Django 5.2发布说明

April 2, 2025

欢迎来到Django 5.2！

这些发行说明涵盖 new features ，以及一些 backwards incompatible changes 从Django 5.1或更早版本升级时您应该注意这一点。我们 begun the deprecation process for some features 。

见 如何将Django升级到更新版本 如果正在更新现有项目，则提供指南。

Django 5.2被指定为 long-term support release .它将在发布后至少三年内收到安全更新。对之前的RTS Django 4.2的支持将于2026年4月结束。

python兼容性

Django 5.2支持Python 3.10、3.11、3.12和3.13。我们 highly recommend 并且仅官方支持每个系列的最新版本。

Django 5.2中的新内容

自动模型在 shell

的 shell 管理命令现在自动从所有已安装的应用程序导入模型。您可以通过设置 --verbosity 标记为2或更多：

$ 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

这 behavior can be customized 添加或删除自动导入。

复合主键

新 django.db.models.CompositePrimaryKey 允许使用由多个字段组成的公钥创建表。

要使用复合公钥，请在定义模型时设置 pk 属性要成为 CompositePrimaryKey

from django.db import models


class Release(models.Model):
    pk = models.CompositePrimaryKey("version", "name")
    version = models.IntegerField()
    name = models.CharField(max_length=20)

看到 复合主键 了解更多详细信息。

简化覆盖 BoundField

在5.2版本之前，覆盖 Field.get_bound_field() 是使用自定义的唯一选择 BoundField . Django现在支持指定以下属性来自定义表单渲染：

例如，要自定义 BoundField 的 Form 类别：：

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")

当渲染 CustomForm 实例中，包括以下HTML：

<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>

看到 定制 BoundField 有关此功能的更多详细信息。

次要特征

django.contrib.admin

  • 这个 admin/base.html 模板现在有了一个新块 extrabody 用于在收盘前添加自定义代码 </body> 标签。

  • 的价值 URLField 现在渲染为链接。

django.contrib.admindocs

  • 文档字符串中的组件链接现在支持自定义链接文本，格式为 :role:`link text <link> .看到 :ref:`documentation helpers <admindocs-helpers> 了解更多详细信息。

  • 的 model pages 现在仅限于具有相应查看或更改权限的用户。

django.contrib.auth

django.contrib.gis

django.contrib.syndication

  • 全 SyndicationFeed 课程现在支持 stylesheets 属性如果指定，则为 <? xml-stylesheet ?> 处理指令将添加到给定列表中每个样式表的文档顶部。看到 饲料样式表 了解更多详细信息。

数据库后端

  • MySQL连接现在默认使用 utf8mb4 字符集，而不是 utf8 ，这是不推荐的字符集的别名 utf8mb3 .

  • Oracle后台现在支持 connection pools ，通过设置 "pool" 在 OPTIONS 数据库配置的一部分。

装饰者

电子邮件

错误报告

形式

  • 新 ColorInput 表单小部件用于输入颜色 rrggbb 十六进制格式并呈现为 <input type="color" ...> .某些浏览器支持此输入类型的可视颜色选择器界面。

  • 新 SearchInput 表单小部件用于输入搜索查询并呈现为 <input type="search" ...> .

  • 新 TelInput 表单小部件用于输入电话号码并呈现为 <input type="tel" ...> .

  • 新 field_id 论据 ErrorList 允许HTML id 要添加到错误模板中的属性。看到 ErrorList.field_id 有关详细信息

  • 一个 aria_describedby 特性添加到 BoundField 以轻松在模板中使用此HTML属性。

  • 提高屏幕阅读器用户的可访问性 aria-describedby 用于将表单字段与其错误消息关联起来。看到 how form errors are displayed 有关详细信息

  • 新资产对象 Script 可用于将自定义HTML属性添加到表单媒体中的JavaScript。看到 paths as objects 了解更多详细信息。

管理命令

迁徙

  • 新运行 AlterConstraint 是一种无操作操作，可以更改约束，而无需删除和重新创建数据库中的约束。

模型

请求和响应

串行化

  • 每种序列化格式现在定义了 Deserializer 类而不是函数，以提高定义时的可扩展性 custom serialization format .

模板

  • 新 simple_block_tag() 装饰器支持创建简单的块标签，该标签可以接受和使用模板的一部分。

测验

  • Django自定义断言的堆栈框架现在被隐藏。这使得测试失败更容易阅读并使 test --pdb 直接进入失败测试方法。

  • 数据加载自 fixtures 以及通过启用迁移 serialized_rollback=True 现已在期间可用 TransactionTestCase.setUpClass() .

URLs

  • reverse() 和 reverse_lazy() 现在接受 query 和 fragment 关键字参数，允许分别在生成的URL中添加查询字符串和/或片段标识符。

公用事业

5.2中向后不兼容的更改

数据库后端API

本节描述第三方数据库后端可能需要的更改。

  • 新 Model._is_pk_set() 方法允许检查是否定义了Model实例的公钥。

  • BaseDatabaseOperations.adapt_decimalfield_value() 现在是无操作的，只需返回给定的值。

django.contrib.gis

  • 已删除对PostGIS 3.0的支持。

  • 已删除对GDAL 3.0的支持。

放弃对PostgreSQL 13的支持

对PostgreSQL 13的上游支持将于2025年11月结束。Django 5.2支持PostgreSQL 14及更高版本。

更改了默认的SQL连接字符集

MySQL连接现在默认使用 utf8mb4 字符集，而不是 utf8 ，这是不推荐的字符集的别名 utf8mb3 . utf8mb3 可以在 OPTIONS 的一部分 DATABASES 如果遗留数据库需要，则设置。

其他

5.2中废弃的功能

其他

  • 这个 all 的论据 django.contrib.staticfiles.finders.find() 该函数已被弃用，转而采用 find_all 争论。

  • 倒退到 request.user 当 user 是 None 在 django.contrib.auth.login() 和 django.contrib.auth.alogin() 将被移除。

  • 的 ordering PostgreSQL特定聚合函数的关键字参数 django.contrib.postgres.aggregates.ArrayAgg , django.contrib.postgres.aggregates.JSONBAgg ，而且 django.contrib.postgres.aggregates.StringAgg 被反对支持 order_by 论点

  • 支持子类 RemoteUserMiddleware 该推翻 process_request() 不推翻 aprocess_request() 已经过时了

« previous | up | next »