Django 5.1 版本发行说明

2024 年 8 月 7 日

欢迎使用 Django 5.1！

这些发布说明涵盖了 新功能，以及从 Django 5.0 或更早版本升级时应注意的一些 不兼容的更改。我们已经 开始对一些功能进行弃用处理。

如果你要更新现有的项目，请看 如何将 Django 更新至新的版本 指南。

Python 兼容性

Django 5.1 支持 Python 3.10、3.11、3.12 和 3.13（截至 5.1.3）。我们 强烈建议 并且仅官方支持每个系列的最新版本。

Django 5.1 新特性

{% querystring %} 模版标签

Django 5.1 引入了 {% querystring %} 模板标签，简化了 URL 中查询参数的修改，使得生成在添加或更改特定参数的同时保持现有查询参数的链接变得更加容易。

例如，在模板中处理分页和查询字符串可能会很繁琐。考虑以下模板片段，它动态生成了一个用于在分页视图中导航到下一页的 URL：

{# Linebreaks added for readability, this should be one, long line. #}
<a href="?{% for key, values in request.GET.iterlists %}
  {% if key != "page" %}
    {% for value in values %}
      {{ key }}={{ value }}&amp;
    {% endfor %}
  {% endif %}
{% endfor %}page={{ page.next_page_number }}">Next page</a>

当切换到使用这个新的模板标签时，上面的代码神奇地变成了：

<a href="{% querystring page=page.next_page_number %}">Next page</a>

PostgreSQL 连接池

Django 5.1 还引入了对 PostgreSQL 的 连接池 支持。由于建立新连接的时间可能相对较长，保持连接打开可以减少延迟。

要使用 psycopg 的连接池，你可以在 OPTIONS 中将 "pool" 选项设置为一个字典，传递给 ConnectionPool，或者设置为 True 以使用 ConnectionPool 的默认值：

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        # ...
        "OPTIONS": {
            "pool": {
                "min_size": 2,
                "max_size": 4,
                "timeout": 10,
            }
        },
    },
}

默认情况下需要身份验证的中间件

新的 LoginRequiredMiddleware 将所有未经身份验证的请求重定向到登录页面。视图可以使用新的 login_not_required() 装饰器来允许未经身份验证的请求。

LoginRequiredMiddleware 尊重通过 login_required() 装饰器设置的 login_url 和 redirect_field_name 值，但不支持通过 LoginRequiredMixin 设置 login_url 或 redirect_field_name。

要启用此功能，请将 "django.contrib.auth.middleware.LoginRequiredMiddleware" 添加到你的 MIDDLEWARE 设置中。

次要特性

django.contrib.admin

django.contrib.auth

  • PBKDF2 密码哈希器的默认迭代次数从 720,000 增加到 870,000。

  • ScryptPasswordHasher 的默认 parallelism 从 1 增加到 5，以遵循 OWASP 的建议。

  • 新的 AdminUserCreationForm 和现有的 AdminPasswordChangeForm 现在支持通过在表单保存时设置不可用密码来禁用基于密码的身份验证。现在在访问用户创建和密码更改页面时，管理界面中也提供了此功能。

  • login_required()、permission_required() 和 user_passes_test() 装饰器现在支持包装异步视图函数。

  • ReadOnlyPasswordHashWidget 现在包含一个重置用户密码的按钮，取代了之前嵌入在 ReadOnlyPasswordHashField 帮助文本中的链接，从而提高了 UserChangeForm 的整体可访问性。

django.contrib.gis

django.contrib.postgres

  • BTreeIndex 现在支持 deduplicate_items 参数。

django.contrib.sessions

数据库后端

错误报告

  • 为了提高可访问性，技术性的 404 和 500 错误页面现在对页眉、页脚和主要内容区域使用 HTML 地标元素。

文件存储

表单

  • 为了提高可访问性并使屏幕阅读器能够将字段集与其帮助文本关联起来，表单字段集现在包含 aria-describedby HTML 属性。

管理命令

迁移

模型

模板

  • 自定义标签现在可以在 Parser 对象上设置额外的数据，这些数据稍后将在 Template 实例上可用。例如，模板加载器或其他模板客户端可以使用这些数据。

  • 模板引擎 现在实现了一个 check() 方法，该方法已经注册到检查框架中。

测试

验证器

5.1 版本中不向后兼容的变更

django.contrib.gis

  • 移除对 PostGIS 2.5 的支持。

  • 已移除对 PROJ 版本低于 6 的支持。

  • 移除对 GDAL 2.4 的支持。

  • GeoIP2 在提供目录路径时不再同时打开城市和国家数据库，而是优先使用城市数据库（如果可用）。国家数据库是城市数据库的子集，通常不需要同时使用两者。如果你需要在与城市数据库相同的目录中使用国家数据库，请显式地将国家数据库路径传递给构造函数。

不再支持 MariaDB 10.4

上游对 MariaDB 10.4 的支持将于 2024 年 6 月结束。Django 5.1 支持 MariaDB 10.5 及更高版本。

不再支持 PostgreSQL 12

上游对 PostgreSQL 12 的支持将于 2024 年 11 月结束。Django 5.1 支持 PostgreSQL 13 及更高版本。

杂项

  • 为了提高可访问性，管理界面的变更列表过滤器现在在 <nav> 标签中渲染，而不是 <div>。

  • 为了提高可访问性，管理界面的页脚现在在 <footer> 标签中渲染，而不是 <div>，并且移动到 <div id="main"> 元素下方。

  • 为了提高可访问性，当字段集有名称并使用 collapse 类时，用于 ModelAdmin.fieldsets 和 InlineModelAdmin.fieldsets 的可展开小部件现在包含 <details> 和 <summary> 元素。

  • JavaScript 文件 collapse.js 已被移除，因为它在 Django 管理站点中不再需要。

  • SimpleTestCase.assertURLEqual() 和 assertInHTML() 现在在 msg_prefix 中添加 ": "。这与其他断言的行为一致。

  • truncatechars_html 和 truncatewords_html 模板过滤器使用的 django.utils.text.Truncator 现在使用 html.parser.HTMLParser 子类。这使得操作更加健壮和快速，但输出可能会有细微差异。

  • 未记录的 django.urls.converters.get_converter() 函数已被移除。

  • SQLite 的最低支持版本从 3.27.0 提高到 3.31.0。

  • FileField 现在在保存没有 name 的文件时会引发 FieldError。

  • ImageField.update_dimension_fields(force=True) 在将图像保存到存储后不再调用。如果你的存储后端调整了图像大小，width_field 和 height_field 将与图像的宽度和高度不匹配。

  • asgiref 的最低支持版本从 3.7.0 提高到 3.8.1。

  • To improve performance, the delete_selected admin action now uses QuerySet.bulk_create() when creating multiple LogEntry objects. As a result, pre_save and post_save signals for LogEntry are not sent when multiple objects are deleted via this admin action.

在 5.1 版本中废弃的功能

杂项

  • ModelAdmin.log_deletion() 和 LogEntryManager.log_action() 方法已被弃用。子类应实现 ModelAdmin.log_deletions() 和 LogEntryManager.log_actions()。

  • 未记录的 django.utils.itercompat.is_iterable() 函数和 django.utils.itercompat 模块已被弃用。请使用 isinstance(..., collections.abc.Iterable) 代替。

  • django.contrib.gis.geoip2.GeoIP2.coords() 方法已被弃用。请使用 django.contrib.gis.geoip2.GeoIP2.lon_lat() 代替。

  • django.contrib.gis.geoip2.GeoIP2.open() 方法已被弃用。请使用 GeoIP2 构造函数代替。

  • 在 Model.save() 和 Model.asave() 中传递位置参数已被弃用，建议仅使用关键字参数。

  • 设置 django.contrib.gis.gdal.OGRGeometry.coord_dim 已被弃用。请使用 set_3d() 代替。

  • 不推荐使用 django.urls.register_converter() 覆盖现有的转换器。

  • CheckConstraint 的 check 关键字参数已被弃用，建议使用 condition。

  • 未记录的 FileSystemStorage 的 OS_OPEN_FLAGS 属性已被弃用。要允许覆盖存储中的文件，请将新的 allow_overwrite 选项设置为 True。

  • FieldCacheMixin 的 get_cache_name() 方法已被弃用，建议使用 cache_name 缓存属性。

在 5.1 版本中移除的功能

这些功能已达到其弃用周期的末尾，并在 Django 5.1 中被移除。

有关这些更改的详细信息，包括如何移除这些功能的使用，请参阅 在 4.2 版本中弃用的功能。

  • BaseUserManager.make_random_password() 方法已被移除。

  • 模型的 Meta.index_together 选项已被移除。

  • length_is 模板过滤器已被移除。

  • django.contrib.auth.hashers.SHA1PasswordHasher、django.contrib.auth.hashers.UnsaltedSHA1PasswordHasher 和 django.contrib.auth.hashers.UnsaltedMD5PasswordHasher 已被移除。

  • django.contrib.postgres.fields.CICharField、django.contrib.postgres.fields.CIEmailField 和 django.contrib.postgres.fields.CITextField 模型已被移除，仅支持历史迁移。

  • django.contrib.postgres.fields.CIText 混入类已被移除。

  • BaseGeometryWidget 的 map_width 和 map_height 属性已被移除。

  • SimpleTestCase.assertFormsetError() 方法已被移除。

  • TransactionTestCase.assertQuerysetEqual() 方法已被移除。

  • 支持将编码的 JSON 字符串字面量传递给 JSONField 及相关查找和表达式的功能已被移除。

  • 支持将位置参数传递给 Signer 和 TimestampSigner 的功能已被移除。

  • DEFAULT_FILE_STORAGE 和 STATICFILES_STORAGE 设置已被移除。

  • django.core.files.storage.get_storage_class() 函数已被移除。

« previous | up | next »