【Django新版本发布】【Django 4.2 发行说明】

Django 4.2 发行说明¶
2023 年 4 月 3 日

欢迎使用 Django 4.2！

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

如果您要更新现有项目，请参阅如何将 Django 升级到更新版本指南。

Django 4.2 被指定为长期支持版本。它将在发布后至少三年内收到安全更新。对之前的 LTS Django 3.2 的支持将于 2024 年 4 月结束。

Python 兼容性¶
Django 4.2 支持 Python 3.8、3.9、3.10 和 3.11。我们强烈推荐 并且只正式支持每个系列的最新版本。

Django 4.2 中的新功能¶
Psycopg 3 支持¶
Django 现在支持psycopg 3.1.8 或更高版本。要更新您的代码，请安装psycopg 库，您无需更改， ENGINE因为django.db.backends.postgresql 它支持这两个库。

对的支持psycopg2可能会在将来的某个时候被弃用和删除。

请注意，psycopg3 在 .x 基础上引入了一些重大变化psycopg2。因此，您可能需要进行一些更改以解决 与 psycopg2 的差异。

对列和表的评论¶
新的Field.db_comment和 Meta.db_table_comment 选项允许分别在列和表上创建注释。例如：

from django.db import models

class Question(models.Model):
text = models.TextField(db_comment=“Poll question”)
pub_date = models.DateTimeField(
db_comment=“Date and time when the question was published”,
)

class Meta:
    db_table_comment = "Poll questions"

class Answer(models.Model):
question = models.ForeignKey(
Question,
on_delete=models.CASCADE,
db_comment=“Reference to a question”,
)
answer = models.TextField(db_comment=“Question answer”)

class Meta:
    db_table_comment = "Question answers"

此外，新AlterModelTableComment 操作允许更改 Meta.db_table_comment.

BREACH 攻击的缓解措施¶
GZipMiddleware现在包括对 BREACH 攻击的缓解。它会将最多 100 个随机字节添加到 gzip 响应中，使 BREACH 攻击更加困难。在Heal The Breach (HTB) 论文中阅读有关缓解技术的更多信息。

内存文件存储¶
新django.core.files.storage.InMemoryStorage类提供了一种非持久性存储，可通过避免磁盘访问来加快测试速度。

自定义文件存储¶
新STORAGES设置允许配置多个自定义文件存储后端。它还控制用于管理 文件（"default"密钥）和静态文件（"staticfiles"密钥）的存储引擎。

从此版本开始，旧的DEFAULT_FILE_STORAGE和设置已弃用。STATICFILES_STORAGE

次要功能¶
django.contrib.admin¶
管理员的浅色或深色主题现在可以在 UI 中切换，也可以设置为遵循系统设置。
管理员的字体堆栈现在更喜欢系统 UI 字体，不再需要下载字体。此外，CSS 变量可用于更轻松地覆盖默认字体系列。
admin /delete_confirmation.html模板现在有一些额外的块和脚本钩子来简化定制。
filter_horizontal和 小部件的选择选项 filter_vertical现在是可过滤的。
该admin/base.html模板现在有一个新块nav-breadcrumbs ，其中包含导航地标和breadcrumbs块。
ModelAdmin.list_editable现在在进行编辑时使用原子事务。
jQuery 从版本 3.6.0 升级到 3.6.4。
django.contrib.auth¶
PBKDF2 密码哈希器的默认迭代计数从 390,000 增加到 600,000。
UserCreationForm现在为自定义用户模型保存多对多表单字段。
新的BaseUserCreationForm现在是用于自定义用户创建表单的推荐基类。
django.contrib.gis¶
GeoJSON序列化器现在输出 id序列化特征的键，默认为对象的主键。
该类GDALRaster现在支持 pathlib.Path.
该类GeoIP2现在支持 .mmdb 从 DB-IP 下载的文件。
OpenLayers 模板小部件不再包含内联 CSS（这也删除了前一个map_css块）以更好地遵守严格的内容安全策略。
OpenLayersWidget现在基于 OpenLayers 7.2.2（以前是 4.6.5）。
新的isempty查找和 IsEmpty() 表达式允许过滤 PostGIS 上的空几何图形。
新的FromWKB() 和FromWKT() 函数允许从 Well-known binary (WKB) 和 Well-known text (WKT) 表示创建几何图形。
django.contrib.postgres¶
新的trigram_strict_word_similar查找和 表达式允许使用 trigram 严格的单词相似性TrigramStrictWordSimilarity()。 TrigramStrictWordDistance()
查找arrayfield.overlap现在支持QuerySet.values() 并values_list()作为右侧。
django.contrib.sitemaps¶
新Sitemap.get_languages_for_item()方法允许自定义显示项目的语言列表。
django.contrib.staticfiles¶
ManifestStaticFilesStorage现在实验性地支持用 散列对应的语句替换 JavaScript 模块的路径import和语句。export如果你想尝试它，子类化ManifestStaticFilesStorage并将 support_js_module_import_aggregation属性设置为True.
新ManifestStaticFilesStorage.manifest_hash属性提供清单中所有文件的哈希值，并在其中一个文件更改时更改。
数据库后端¶
PostgreSQL"assume_role"现在支持新选项以允许指定会话角色。OPTIONS
PostgreSQL 3.1.8+"server_side_binding"现在支持 新选项以允许使用 服务器端绑定游标。OPTIONSpsycopg
错误报告¶
调试页面现在显示例外说明和 Python 3.11+ 上的细粒度错误位置。
会话 cookie 现在被视为凭据，因此**********在错误报告中被隐藏并替换为星号 ( )。
表格¶
ModelForm现在接受自定义表单域的新Meta选项 。formfield_callback
modelform_factory()现在尊重 formfield_callback的form属性Meta。
国际化¶
添加了对中央库尔德语 (Sorani) 语言的支持和翻译。
记录¶
django.db.backends记录器现在记录级别的事务管理查询（BEGIN、COMMIT和ROLLBACK）DEBUG。
管理命令¶
makemessages命令现在支持带有私有子标签的语言环境，例如nl_NL-x-informal.
新选项将模型更改合并到最新迁移中并优化生成的操作。makemigrations --update
迁移¶
迁移现在支持enum.Flag对象的序列化。
模型¶
QuerySet现在广泛支持对 Window 函数进行过滤，但执行聚合时对窗口函数的析取过滤器查找除外。
prefetch_related()现在支持 Prefetch带有切片查询集的对象。
Field现在支持在实例上 注册查找。
的新robust参数on_commit() 允许执行在成功提交数据库事务后可能会失败的操作。
新KT()表达式表示 的键、索引或路径转换的文本值 JSONField。
Now现在支持 MySQL 的微秒精度和 SQLite 的毫秒精度。
F()BooleanField 现在可以使用~F()（反转运算符）否定输出的表达式。
Model现在提供一些使用数据库的方法的异步版本，使用a前缀：adelete()、 arefresh_from_db()和asave()。
相关管理器现在提供异步版本的方法来更改一组相关对象，使用a前缀：aadd()、 aclear()、aremove()和 aset()。
CharField.max_length不再需要在支持无限VARCHAR 列的 PostgreSQL 上设置。
请求和响应¶
StreamingHttpResponse当 Django 通过 ASGI 提供服务时，现在支持异步迭代器。
测试¶
该选项现在使用 .test --debug-sqlsqlparse

、、和 类现在支持参数，该参数接受标头名称RequestFactory和 值的字典。这允许使用更自然的语法来声明标头。AsyncRequestFactoryClientAsyncClientheaders

Before:

self.client.get(“/home/”, HTTP_ACCEPT_LANGUAGE=“fr”)
await self.async_client.get(“/home/”, ACCEPT_LANGUAGE=“fr”)

After:

self.client.get(“/home/”, headers={“accept-language”: “fr”})
await self.async_client.get(“/home/”, headers={“accept-language”: “fr”})
公用事业¶
encoder函数的新参数django.utils.html.json_script() 允许自定义 JSON 编码器类。
urllib.parse.urlsplit()now strips ‘\r’、‘\n’和的私人内部销售副本’\t’（请参阅CVE-2022-0391和bpo-43882）。这是为了保护可能错误地使用内部 url_has_allowed_host_and_scheme()函数的项目，而不是使用其中一个记录的函数来处理 URL 重定向。Django 函数没有受到影响。
新django.utils.http.content_disposition_header()函数返回Content-Disposition由指定的 HTTP 标头值RFC 6266。
验证器¶
所使用的常用密码列表CommonPasswordValidator已更新至最新版本。
4.2 中向后不兼容的更改¶
数据库后端 API ¶
本节介绍第三方数据库后端可能需要的更改。

DatabaseFeatures.allows_group_by_pk被删除，因为它只保留以适应 MySQL 扩展，该扩展已被 MySQL 5.7.15 中的适当功能依赖性检测所取代。请注意， 如果您的后端支持标准指定的子句DatabaseFeatures.allows_group_by_selected_pks中的功能依赖性检测，则它仍然受支持并且应该启用 。GROUP BYSQL:1999
inspectdb现在使用display_sizefrom DatabaseIntrospection.get_table_description()而不是 internal_sizefor CharField。
放弃对 MariaDB 10.3 的支持¶
对 MariaDB 10.3 的上游支持将于 2023 年 5 月结束。Django 4.2 支持 MariaDB 10.4 及更高版本。

不再支持 MySQL 5.7 ¶
对 MySQL 5.7 的上游支持将于 2023 年 10 月结束。Django 4.2 支持 MySQL 8 及更高版本。

放弃对 PostgreSQL 11 的支持¶
对 PostgreSQL 11 的上游支持将于 2023 年 11 月结束。Django 4.2 支持 PostgreSQL 12 及更高版本。

update_fields现在Model.save()可能需要设置¶
为了避免更新不必要的列， QuerySet.update_or_create()现在传递update_fields给 Model.save()调用。因此，在自定义方法中修改的任何字段都应在调用之前save()添加到 关键字参数中。有关更多详细信息，请参阅 覆盖预定义的模型方法。update_fieldssuper()

杂项¶
未记录的django.http.multipartparser.parse_header()功能已删除。改用django.utils.http.parse_header_parameters()。
{% blocktranslate asvar … %}结果现在被标记为安全的 (HTML) 输出目的。
autofocus管理员搜索框中的 HTML 属性已被删除，因为它可能会让屏幕阅读器感到困惑。
该选项不再创建丢失的迁移文件。makemigrations --check
aliasfor 的参数已Expression.get_group_by_cols()删除。
最低支持版本sqlparse从0.2.2增加到0.3.1。
negated表达式的 未记录参数Exists已删除。
is_summary未记录方法的参数被Query.add_annotation() 删除。
SQLite 的最低支持版本从 3.9.0 增加到 3.21.0。
最低支持版本asgiref从3.5.2增加到3.6.0。
UserCreationForm现在拒绝仅大小写不同的用户名。如果您需要以前的行为，请 BaseUserCreationForm改用。
最低支持版本mysqlclient从 1.4.0 增加到 1.4.3。
最低支持版本argon2-cffi从19.1.0增加到19.2.0。
最低支持版本Pillow从6.2.0增加到6.2.1。
最低支持版本jinja2从2.9.2增加到2.11.0。
redis-py的最低支持版本从 3.0.0 增加到 3.4.0。
必须为手动实例化的WSGIRequest对象提供类似文件的对象wsgi.input。以前，Django 比 WSGI 规范指定的预期行为更宽松。
PROJ删除了对 < 5 的支持。
EmailBackend现在验证 a hostname和 certificates。如果您需要限制较少且不推荐的先前行为，请子类化 EmailBackend并覆盖该ssl_context属性。
4.2 中弃用的功能¶
index_together不推荐使用indexes¶
该Meta.index_together 选项已弃用，取而代之的是该indexes 选项。

迁移现有index_together应作为迁移处理。例如：

class Author(models.Model):
rank = models.IntegerField()
name = models.CharField(max_length=30)

class Meta:
    index_together = [["rank", "name"]]

应该变成：

class Author(models.Model):
rank = models.IntegerField()
name = models.CharField(max_length=30)

class Meta:
    indexes = [models.Index(fields=["rank", "name"])]

运行该makemigrations命令将生成一个迁移，其中包含一个RenameIndex将重命名现有索引的操作。

迁移AlterIndexTogether操作现在仅正式支持 Django 4.2 之前的迁移文件。出于向后兼容的原因，它仍然是公共 API 的一部分，并且没有弃用或删除它的计划，但它不应该用于新的迁移。使用 AddIndex和 RemoveIndex操作代替。

不推荐将编码的 JSON 字符串文字JSONField传递给¶
JSONField及其关联的查找和聚合用于允许传递 JSON 编码的字符串文字，这导致从数据库后端的角度来看字符串文字是否已经编码的歧义。

在弃用期间，将尝试对字符串文字进行 JSON 解码，并在成功时发出警告，指出传递非编码形式。

用于传递 JSON 编码字符串文字的代码：

Document.objects.bulk_create(
Document(data=Value(“null”)),
Document(data=Value(“[]”)),
Document(data=Value(‘“foo-bar”’)),
)
Document.objects.annotate(
JSONBAgg(“field”, default=Value(“[]”)),
)
应该变成：

Document.objects.bulk_create(
Document(data=Value(None, JSONField())),
Document(data=[]),
Document(data=“foo-bar”),
)
Document.objects.annotate(
JSONBAgg(“field”, default=[]),
)
从 Django 5.1+ 开始，字符串文字将被隐式解释为 JSON 字符串文字。

杂项¶
该BaseUserManager.make_random_password()方法已弃用。查看 使用 Python模块生成密码的秘诀和最佳实践。secrets

模板length_is过滤器已弃用，取而代之的是标签中的length 和运算符。例如=={% if %}

{% if value|length == 4 %}…{% endif %}
{% if value|length == 4 %}True{% else %}False{% endif %}
代替：

{% if value|length_is:4 %}…{% endif %}
{{ value|length_is:4 }}
django.contrib.auth.hashers.SHA1PasswordHasher, django.contrib.auth.hashers.UnsaltedSHA1PasswordHasher和 django.contrib.auth.hashers.UnsaltedMD5PasswordHasher已弃用。

django.contrib.postgres.fields.CICharField不推荐使用 CharField(db_collation=“…”)不区分大小写的非确定性排序规则。

django.contrib.postgres.fields.CIEmailField不推荐使用 EmailField(db_collation=“…”)不区分大小写的非确定性排序规则。

django.contrib.postgres.fields.CITextField不推荐使用 TextField(db_collation=“…”)不区分大小写的非确定性排序规则。

django.contrib.postgres.fields.CITextmixin 已弃用。

的map_height和map_width属性BaseGeometryWidget已弃用，请改用 CSS 来调整地图小部件的大小。

SimpleTestCase.assertFormsetError()已弃用，取而代之的是 assertFormSetError().

TransactionTestCase.assertQuerysetEqual()已弃用，取而代之的是 assertQuerySetEqual().

将位置参数传递给SignerandTimestampSigner已弃用，取而代之的是仅关键字参数。

该DEFAULT_FILE_STORAGE设置已弃用，取而代之的是 STORAGES[“default”]。

该STATICFILES_STORAGE设置已弃用，取而代之的是 STORAGES[“staticfiles”]。

该django.core.files.storage.get_storage_class()功能已弃用。