Django 4.1 版本发行说明¶

2022 年 8 月 3 日

欢迎使用 Django 4.1！

这些发布说明涵盖了新功能，以及从 Django 4.0 或更早版本升级时需要注意的一些不兼容变更。我们已经开始了某些功能的弃用过程。

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

Python 兼容性¶

Django 4.1 支持 Python 3.8、3.9、3.10 和 3.11（从 4.1.3 开始）。我们 强烈建议 并且只官方支持每个系列的最新发布版本。

Django 4.1 新特性¶

基于类的视图的异步处理程序。¶

现在，视图的子类可以定义异步的 HTTP 方法处理程序：

import asyncio
from django.http import HttpResponse
from django.views import View


class AsyncView(View):
    async def get(self, request, *args, **kwargs):
        # Perform view logic using await.
        await asyncio.sleep(1)
        return HttpResponse("Hello async world!")

请参阅异步类视图以获取更多详细信息。

异步的 ORM 接口。¶

QuerySet 现在为所有数据访问操作提供了异步接口。这些接口的命名方式与现有的同步操作相同，但带有一个 a 前缀，例如 acreate()、aget() 等等。

新的接口允许您编写异步代码，而无需将 ORM 操作包装在 sync_to_async() 中：

async for author in Author.objects.filter(name__startswith="A"):
    book = await author.books.afirst()

值得注意的是，目前数据库操作仍然是同步的，但正在进行贡献工作，以将异步支持推向 SQL 编译器并集成异步数据库驱动程序。新的异步查询集接口目前为您封装了必要的 sync_to_async() 操作，将允许您的代码充分利用 ORM 异步支持的发展。

请参阅异步查询以获取详细信息和限制。

约束的验证¶

在 Meta.constraints 选项中定义的 Check、unique 和 exclusion 约束现在在模型验证期间进行检查。

表单渲染的可访问性¶

为了帮助使用屏幕阅读器和其他辅助技术的用户，从这个版本开始提供了基于 <div> 的新表单模板。这些模板提供比旧模板更可访问的导航，并能够正确地将相关控件（如单选列表）分组到字段集中。

推荐使用新模板，并且在 Django 5.0 中，当在模板中输出表单时（如 {{ form }}），新模板将成为默认的表单呈现样式。

为了方便采用新的输出样式，现在可以通过项目级别的 FORM_RENDERER 设置来配置默认的表单和表单集模板。

请查看下面的表单部分以获取完整的详细信息。

次要特性¶

`django.contrib.admin`¶

管理员深色模式 CSS 变量现在应用在一个单独的样式表和模板块中。
提供自定义 FieldListFilter 子类的 ModelAdmin 列表过滤器现在可以在使用 __in 查询时控制查询字符串值的分隔符，用于多个值的过滤。
管理员的 history view 现在支持分页。
相关的小部件包装现在有一个指向对象修改表单的链接。
AdminSite.get_app_list() 方法现在允许更改管理员首页上应用程序和模型的顺序。

`django.contrib.auth`¶

PBKDF2 密码哈希器的默认迭代次数从 320 , 000 增加到 390 , 000 。
RemoteUserBackend.configure_user() 方法现在允许将用户属性与远程系统（如 LDAP 目录）中的属性同步。

`django.contrib.gis`¶

新的 GEOSGeometry.make_valid() 方法允许将无效的几何图形转换为有效的几何图形。
GEOSGeometry.normalize() 的新参数 clone 允许创建几何图形的归一化克隆。

`django.contrib.postgres`¶

新的 BitXor() 聚合函数返回所有非空输入值的按位 XOR 的 int 值。
SpGistIndex 现在在 PostgreSQL 14+ 上支持覆盖索引。
ExclusionConstraint 现在在 PostgreSQL 14+ 上支持使用 SP-GiST 索引的覆盖排除约束。
新的 DateTimeRangeField 和 DecimalRangeField 的 default_bounds 属性允许为列表和元组输入指定边界。
ExclusionConstraint 现在允许使用 OpClass() 表达式指定操作符类。

`django.contrib.sitemaps`¶

默认的站点地图索引模板 <sitemapindex> 现在在可用时包括 <lastmod> 时间戳，通过新的 get_latest_lastmod() 方法。自定义站点地图索引模板应该根据调整后的上下文变量进行更新。

`django.contrib.staticfiles`¶

ManifestStaticFilesStorage 现在会将 CSS 源映射引用的路径替换为它们的哈希版本。

数据库后端¶

第三方数据库后端现在可以使用 DatabaseFeatures.minimum_database_version 属性指定数据库的最低要求版本，它是一个元组（例如 (10, 0) 表示 "10.0"）。如果指定了最低版本，后端还必须实现 DatabaseWrapper.get_database_version()，该方法返回当前数据库版本的元组。后端的 DatabaseWrapper.init_connection_state() 方法必须调用 super() 以便进行版本检查。

表单¶

渲染表单时默认使用的模板，例如在模板中作为 {{ form }} 显示，现在可以在项目级别通过在提供给 FORM_RENDERER 的类上设置 form_template_name 来配置。

Form.template_name 现在是一个属性，延迟到渲染器，但可以用一个字符串值覆盖，以指定每个表单类的模板名称。

同样，可以通过匹配的 formset_template_name 渲染器属性来指定用于渲染表单集的默认模板。
新的 div.html 表单模板引用了 Form.template_name_div 属性，并与 Form.as_div() 方法匹配，使用 HTML <div> 元素来渲染表单。

推荐使用这种新的输出样式，而不是现有的 as_table()、as_p() 和 as_ul() 样式，因为模板实现了 <fieldset> 和 <legend> 来组合相关的输入，对屏幕阅读器用户更容易导航。

从 Django 5.0 开始，基于 div 的输出将成为默认的渲染样式。
为了平稳过渡到新的 <div> 输出样式，提供了两个过渡性的表单渲染器类：django.forms.renderers.DjangoDivFormRenderer 和 django.forms.renderers.Jinja2DivFormRenderer，分别适用于 Django 和 Jinja2 模板后端。

您可以通过 FORM_RENDERER 设置之一来应用其中之一。例如：
```
FORM_RENDERER = "django.forms.renderers.DjangoDivFormRenderer"
```
一旦 <div> 输出样式成为默认样式（从 Django 5.0 开始），这些过渡渲染器将被弃用，并计划在 Django 6.0 中移除。届时可以删除 FORM_RENDERER 声明。
如果新的 <div> 输出样式不适用于您的项目，您应该定义一个渲染器子类，指定 form_template_name 和 formset_template_name 以适应您所需的样式，并相应地设置 FORM_RENDERER。

例如，对于 as_p() 使用的 <p> 输出样式，您可以定义一个表单渲染器设置，将 form_template_name 设置为 "django/forms/p.html"，将 formset_template_name 设置为 "django/forms/formsets/p.html"。
新的 legend_tag() 允许通过 label_tag() 的新 tag 参数以 <legend> 标签方式呈现字段标签。
对于 modelformset_factory() 和 inlineformset_factory()，新的 edit_only 参数允许防止创建新对象。
媒体的 js 和 css 类属性现在允许使用可散列的对象，而不仅仅是路径字符串，只要这些对象实现了 __html__() 方法（通常在使用 html_safe() 装饰器时）。
新的 BoundField.use_fieldset 和 Widget.use_fieldset 属性有助于识别那些应该在 <fieldset> 中与 <legend> 一起分组的小部件。
BaseFormSet 的 error_messages 参数现在允许通过传递 'too_few_forms' 和 'too_many_forms' 键来自定义无效表单数量的错误消息。
IntegerField、FloatField 和 DecimalField 现在可以选择接受一个 step_size 参数。这用于设置 step HTML 属性，并在表单提交时进行验证。

国际化¶

i18n_patterns() 函数现在支持同时包含脚本和区域的语言。

管理命令¶

makemigrations --no-input 现在记录默认答案和无法创建迁移的原因。
新的 makemigrations --scriptable 选项将日志输出和输入提示重定向到 stderr，仅将生成的迁移文件的路径写入 stdout。
新的 migrate --prune 选项允许从 django_migrations 表中删除不存在的迁移。
由 startproject、startapp、optimizemigration、makemigrations 和 squashmigrations 创建的 Python 文件现在如果在您的 PATH 上存在 black 命令，将会使用它进行格式化。
新的 optimizemigration 命令允许优化迁移操作。

迁移¶

新的 RenameIndex 操作允许重命名在 Meta.indexes 或 index_together 选项中定义的索引。
迁移自动检测器现在在重命名 Meta.indexes 中定义的索引时，生成 RenameIndex 操作，而不是 RemoveIndex 和 AddIndex。
迁移自动检测器现在会在将 Meta.index_together 中定义的索引移动到 Meta.indexes 时生成 RenameIndex 操作，而不是 AlterIndexTogether 和 AddIndex。

模型¶

Window 表达式的 order_by 参数现在可以接受对字段和转换的字符串引用。
新的 CONN_HEALTH_CHECKS 设置允许启用对持久数据库连接进行健康检查，以减少失败的请求次数，例如在数据库服务器重新启动后。
现在，当插入一行时违反唯一约束时，QuerySet.bulk_create() 支持更新字段。这在 MariaDB、MySQL、PostgreSQL 和 SQLite 3.24+ 上都受支持。
QuerySet.iterator() 现在支持在提供了 chunk_size 参数的情况下预取相关对象。在旧版本中，不进行预取。
Q 对象和查询集现在可以使用 ^ 作为异或（XOR）运算符进行组合。XOR 在 MariaDB 和 MySQL 上有本地支持。对于不支持 XOR 的数据库，查询将被转换为使用 AND、OR 和 NOT 的等效查询。
新的 Field.non_db_attrs 属性允许自定义不影响列定义的字段属性。
在 PostgreSQL 上，AutoField、BigAutoField 和 SmallAutoField 现在作为标识列（identity columns）创建，而不是带有序列的序列列（serial columns）。

请求和响应¶

HttpResponse.set_cookie() 现在支持 timedelta 对象作为 max_age 参数。

安全¶

新的 SECRET_KEY_FALLBACKS 设置允许提供一组值用于密钥轮换。
SECURE_PROXY_SSL_HEADER 设置现在支持在头部值中以逗号分隔的协议列表。

信号¶

pre_delete 和 post_delete 信号现在会分发删除的 origin。

模板¶

在包装 json_script 模板过滤器时，不再需要 HTML <script> 元素的 id 属性。
在开发环境中，当 DEBUG 为 True 且未指定 OPTIONS['loaders'] 时，现在会启用 cached template loader。如果需要，您可以指定 OPTIONS['loaders'] 来覆盖这个设置。

测试¶

DiscoverRunner 现在支持在 macOS、Windows 和任何默认 multiprocessing 启动方法为 spawn 的系统上并行运行测试。
django.test.TestCase 中标记为持久的嵌套原子块现在会引发 RuntimeError，与测试外部相同。
SimpleTestCase.assertFormError() 和 assertFormsetError() 现在支持直接传递表单/表单集对象。

URLs¶

新的 ResolverMatch.captured_kwargs 属性存储了从 URL 解析的捕获的关键字参数。
新的 ResolverMatch.extra_kwargs 属性存储了传递给视图函数的额外关键字参数。

实用程序¶

SimpleLazyObject 现在支持加法操作。
mark_safe() 现在保留懒惰对象。

验证器¶

新的 StepValueValidator 用于检查一个值是否是给定步长的整数倍。这个新的验证器用于表示数值的表单字段的新参数 step_size。

4.1 版本中的不兼容变更¶

数据库后端 API¶

本节介绍了第三方数据库后端可能需要的更改。

BaseDatabaseFeatures.has_case_insensitive_like 从 True 改为 False，以反映大多数数据库的行为。
DatabaseIntrospection.get_key_columns() 已被移除。请改用 DatabaseIntrospection.get_relations()。
DatabaseOperations.ignore_conflicts_suffix_sql() 方法被替换为 DatabaseOperations.on_conflict_suffix_sql()，它接受 fields、on_conflict、update_fields 和 unique_fields 参数。
DatabaseOperations.insert_statement() 方法的 ignore_conflicts 参数被替换为接受 django.db.models.constants.OnConflict 的 on_conflict 参数。
DatabaseOperations._convert_field_to_tz() 被替换为 DatabaseOperations._convert_sql_to_tz()，它接受 sql、params 和 tzname 参数。
DatabaseOperations 上的多个日期和时间方法现在接受 sql 和 params 参数，而不再接受 field_name，并返回包含一些 SQL 和要插入该 SQL 的参数的 2 元组。已更改的方法具有以下新签名：
- DatabaseOperations.date_extract_sql(lookup_type, sql, params)
- DatabaseOperations.datetime_extract_sql(lookup_type, sql, params, tzname)
- DatabaseOperations.time_extract_sql(lookup_type, sql, params)
- DatabaseOperations.date_trunc_sql(lookup_type, sql, params, tzname=None)
- DatabaseOperations.datetime_trunc_sql(self, lookup_type, sql, params, tzname)
- DatabaseOperations.time_trunc_sql(lookup_type, sql, params, tzname=None)
- DatabaseOperations.datetime_cast_date_sql(sql, params, tzname)
- DatabaseOperations.datetime_cast_time_sql(sql, params, tzname)

`django.contrib.gis`¶

移除对 GDAL 2.1 的支持。
移除对 PostGIS 2.4 的支持。

不再支持 PostgreSQL 10 。¶

PostgreSQL 10 的上游支持将在 2022 年 11 月结束。 Django 4.1 支持 PostgreSQL 11 及更高版本。

不再支持 MariaDB 10.2¶

MariaDB 10.2 的上游支持将在 2022 年 5 月结束。 Django 4.1 支持 MariaDB 10.3 及更高版本。

管理后台的变更列表搜索跨多值关系的变更¶

管理员 changelist 使用多个搜索词进行搜索现在在单个调用 filter() 中应用，而不是在连续的 filter() 调用中应用。

对于多值关系，这意味着来自相关模型的行必须匹配所有词项，而不是任何词项。例如，如果 search_fields 设置为 ['child__name', 'child__age']，用户搜索 'Jamal 17'，那么只有与一些名为 Jamal 的 17 岁孩子存在关系的父母行才会被返回，而不会返回仅仅因为有一个名为 Jamal 的更年轻或更年长的孩子以及其他一些 17 岁孩子的父母。

有关这种差异的更多讨论，请参阅跨多值关联主题。在 Django 4.0 及更早版本中，get_search_results() 遵循第二个示例查询，但这种未记录的行为导致了具有过多连接的查询。

未保存的模型实例的反向外键变更¶

为了统一与未保存的模型实例的多对多关系的行为，反向外键现在在调用未保存对象的 related managers 时会引发 ValueError。

杂项¶

ForeignKey、ManyToManyField 和 GenericRelation 的相关管理器现在被缓存在它们所属的 Model 实例上。这个变更在 Django 4.1.2 中被撤销了。
DiscoverRunner 现在会为标记为 unittest.expectedFailure() 的测试意外成功返回非零错误码。
CsrfViewMiddleware 现在不再像在 DOM 中遮蔽 CSRF 令牌一样遮蔽 CSRF cookie。
CsrfViewMiddleware 现在使用 request.META['CSRF_COOKIE'] 来存储未遮蔽的 CSRF 密钥，而不是遮蔽版本。这是一个未记录的、私有的 API。
ModelAdmin.actions 和 inlines 属性现在默认为空元组，而不是空列表，以防止意外的变更。
在 CSS 表单媒体的 <link> 标签中不再包含 type="text/css" 属性。
formset:added 和 formset:removed JavaScript 事件现在是纯 JavaScript 事件，不依赖于 jQuery。有关此更改的更多详细信息，请参阅内联表单事件。
未记录的 django.utils.log.log_response() 函数的 exc_info 参数已被替换为 exception。
未记录的 django.views.static.was_modified_since() 函数的 size 参数已被移除。
管理员注销界面现在使用 POST 请求。
未记录的 InlineAdminFormSet.non_form_errors 属性已被替换为 non_form_errors() 方法。这与 BaseFormSet 保持一致。
根据上面，在开发中现在启用了缓存模板加载器。如果有必要，你可以指定 OPTIONS['loaders'] 来覆盖这个设置。
未记录的 django.contrib.auth.views.SuccessURLAllowedHostsMixin 混合类已被替换为 RedirectURLMixin。
BaseConstraint 的子类必须实现 validate() 方法，以允许这些约束用于验证。
未记录的 URLResolver._is_callback()、URLResolver._callback_strs 和 URLPattern.lookup_str() 已被移动到 django.contrib.admindocs.utils。
Model.full_clean() 方法现在将 exclude 值转换为一个 set。最好将 exclude 值作为一个 set 传递给 Model.clean_fields()、Model.full_clean()、Model.validate_unique() 和 Model.validate_constraints() 方法。
asgiref 的最小支持版本从 3.4.1 提高到 3.5.2。
组合表达式不再在参数类型匹配时猜测 output_field 的不稳定行为。因此，解析数据库函数和组合表达式的 output_field 现在可能会在混合类型的情况下崩溃。在这种情况下，你需要明确设置 output_field。
makemessages 命令在不需要更新时不再更改 .po 文件。在旧版本中，POT-Creation-Date 总是会被更新。

4.1 版本中弃用的功能¶

通过 GET 方式注销登录¶

通过 GET 请求注销到 内置的注销视图 已经不推荐使用。请改为使用 POST 请求。

如果您想保留 HTML 链接的用户体验，可以使用一个被样式化为链接的表单：

<form id="logout-form" method="post" action="{% url 'admin:logout' %}">
  {% csrf_token %}
  <button type="submit">{% translate "Log out" %}</button>
</form>

#logout-form {
  display: inline;
}
#logout-form button {
  background: none;
  border: none;
  cursor: pointer;
  padding: 0;
  text-decoration: underline;
}

杂项¶

对于扁平化的 URL 列表的站点地图索引模板的上下文已被弃用。自定义站点地图索引模板应该根据调整后的上下文变量进行更新，期望一个具有 location 和可选 lastmod 属性的对象列表。
CSRF_COOKIE_MASKED 过渡设置已移除。
在 Python 3.6 及更高版本中，django.utils.functional.cached_property() 的 name 参数已被弃用，因为它不再必要。
django.contrib.postgres.constraints.ExclusionConstraint 的 opclasses 参数已被弃用，而应使用 ExclusionConstraint.expressions 中的 OpClass()。要使用它，你需要在 INSTALLED_APPS 中添加 'django.contrib.postgres'。

在进行这些更改后，makemigrations 将生成一个新的迁移，其中包含两个操作：RemoveConstraint 和 AddConstraint。由于这些更改不影响数据库架构，可以使用 SeparateDatabaseAndState 操作来仅更新迁移状态而不运行任何 SQL。将生成的操作移动到 SeparateDatabaseAndState 的 state_operations 参数中。例如：
```
class Migration(migrations.Migration):
    ...

    operations = [
        migrations.SeparateDatabaseAndState(
            database_operations=[],
            state_operations=[
                migrations.RemoveConstraint(...),
                migrations.AddConstraint(...),
            ],
        ),
    ]
```
未记录的能够将 errors=None 传递给 SimpleTestCase.assertFormError() 和 assertFormsetError() 已被弃用。请改用 errors=[]。
由于存在远程代码执行的风险，django.contrib.sessions.serializers.PickleSerializer 已被弃用。
在没有提供 chunk_size 参数的情况下，对预取相关对象的查询集使用 QuerySet.iterator() 的用法已被弃用。在旧版本中，不会进行预取。提供 chunk_size 的值表示希望每个块所需的预取额外查询。
将未保存的模型实例传递给相关的过滤器已被弃用。在 Django 5.0 中，将引发异常。
RemoteUserBackend.configure_user() 的签名中添加了 created=True。不接受此参数的 RemoteUserBackend 子类的支持已被弃用。
别名 django.utils.timezone.utc 到 datetime.timezone.utc 的使用已经被弃用。请直接使用 datetime.timezone.utc。
在 SimpleTestCase.assertFormError() 和 assertFormsetError() 中传递响应对象和表单/表单集名称已被弃用。请使用以下方式：
```
assertFormError(response.context["form_name"], ...)
assertFormsetError(response.context["formset_name"], ...)
```
或者直接传递表单/表单集对象。
未记录的 django.contrib.gis.admin.OpenLayersWidget 模块已被弃用。
django.contrib.auth.hashers.CryptPasswordHasher 已废弃。
在 Expression.asc() 和 Expression.desc() 方法以及 OrderBy 表达式中传递 nulls_first=False 或 nulls_last=False 的能力已被弃用。请改用 None。
"django/forms/default.html" 和 "django/forms/formsets/default.html" 模板，它们是表格模板的代理，已被弃用。请使用具体的模板。
未记录的 LogoutView.get_next_page() 方法已被重命名为 get_success_url()。

在 4.1 版本中移除的功能¶

这些功能已经结束了其弃用周期，并在 Django 4.1 中被移除。

有关这些更改的详细信息，包括如何删除对这些功能的使用，请参阅在 3.2 中被废弃的功能。

不再支持将不支持使用 copy.deepcopy() 创建深层副本的对象分配给 TestCase.setUpTestData() 中的类属性。
不再支持在 BaseCommand.requires_system_checks 中使用布尔值。
django.core.validators.EmailValidator 的 whitelist 参数和 domain_whitelist 属性已被移除。
default_app_config 应用程序配置变量已被移除。
TransactionTestCase.assertQuerysetEqual() 在与字符串值进行比较时不再调用 repr() 方法来处理查询集。
django.core.cache.backends.memcached.MemcachedCache 已被移除。
对 django.contrib.messages.storage.cookie.CookieStorage 使用的 Django 3.2 之前的消息格式的支持已被移除。

Django 4.1 版本发行说明¶

Python 兼容性¶

Django 4.1 新特性¶

基于类的视图的异步处理程序。¶

异步的 ORM 接口。¶

约束的验证¶

表单渲染的可访问性¶

CSRF_COOKIE_MASKED 设置¶

次要特性¶

django.contrib.admin¶

django.contrib.auth¶

django.contrib.gis¶

django.contrib.postgres¶

django.contrib.sitemaps¶

django.contrib.staticfiles¶

数据库后端¶

表单¶

国际化¶

管理命令¶

迁移¶

模型¶

请求和响应¶

安全¶

信号¶

模板¶

测试¶

URLs¶

实用程序¶

验证器¶

4.1 版本中的不兼容变更¶

数据库后端 API¶

django.contrib.gis¶

不再支持 PostgreSQL 10 。¶

不再支持 MariaDB 10.2¶

管理后台的变更列表搜索跨多值关系的变更¶

未保存的模型实例的反向外键变更¶

杂项¶

4.1 版本中弃用的功能¶

通过 GET 方式注销登录¶

杂项¶

在 4.1 版本中移除的功能¶

附加信息

Support Django!

内容

获取帮助

下载：

Diamond and Platinum Members

`CSRF_COOKIE_MASKED` 设置¶

`django.contrib.admin`¶

`django.contrib.auth`¶

`django.contrib.gis`¶

`django.contrib.postgres`¶

`django.contrib.sitemaps`¶

`django.contrib.staticfiles`¶

`django.contrib.gis`¶