Django 6.0.dev 文档

Home | Table of contents | Index | Modules

« previous | up | next »

Django 3.2版本说明¶

April 6, 2021

欢迎来到Django 3.2！

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

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

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

python兼容性¶

Django 3.2支持Python3.6、3.7、3.8、3.9和3.10(从3.2.9开始)。我们 highly recommend 并且仅官方支持每个系列的最新版本。

Django 3.2中的新功能¶

自动 `AppConfig` 发现¶

大多数可插入应用程序定义了 AppConfig 中的亚类 apps.py 子模块。许多人定义了 default_app_config 指向这个类的变量 __init__.py 。

当 apps.py 子模块存在并定义了一个 AppConfig 子类别，Django现在自动使用该配置，因此您可以删除 default_app_config 。

default_app_config 使其可以仅声明应用程序的路径 INSTALLED_APPS (例如： 'django.contrib.admin' ）而不是应用程序配置的路径（例如 'django.contrib.admin.apps.AdminConfig' ).它的推出是为了与前一种风格向后兼容，旨在将生态系统切换到后一种风格，但这种切换并没有发生。

具有自动 AppConfig 发现， default_app_config 不再需要。因此，它被废弃了。

看见配置应用程序获取完整的详细信息。

自定义自动创建的公钥类型¶

定义模型时，如果模型中没有用定义字段 primary_key=True 添加了隐式主密钥。现在可以通过 DEFAULT_AUTO_FIELD 设置和 AppConfig.default_auto_field 属性不再需要在所有型号中重写公钥。

维护历史行为、默认值 DEFAULT_AUTO_FIELD 是 AutoField .从3.2个新项目开始 DEFAULT_AUTO_FIELD 设置为 BigAutoField .此外，新应用程序是通过以下方式生成的 AppConfig.default_auto_field 设置为 BigAutoField .未来Django会发布默认值 DEFAULT_AUTO_FIELD 将变更为 BigAutoField 。

为了避免将来不必要的迁移，要么显式设置 DEFAULT_AUTO_FIELD 至 AutoField **

DEFAULT_AUTO_FIELD = "django.db.models.AutoField"

或根据每个应用程序配置它：：

from django.apps import AppConfig


class MyAppConfig(AppConfig):
    default_auto_field = "django.db.models.AutoField"
    name = "my_app"

或根据每个型号：：：

from django.db import models


class MyModel(models.Model):
    id = models.AutoField(primary_key=True)

预计默认值会发生变化，如果您没有明确的设置，系统检查将提供警告 DEFAULT_AUTO_FIELD 。

更改的值时 DEFAULT_AUTO_FIELD ，当前不能生成已有自动创建直通表主键的迁移。请参阅 DEFAULT_AUTO_FIELD 有关迁移此类表的详细信息，请参阅文档。

函数索引¶

新的 *expressions 的位置论据 Index() 允许在表达和数据库函数上创建功能索引。例如：：

from django.db import models
from django.db.models import F, Index, Value
from django.db.models.functions import Lower, Upper


class MyModel(models.Model):
    first_name = models.CharField(max_length=255)
    last_name = models.CharField(max_length=255)
    height = models.IntegerField()
    weight = models.IntegerField()

    class Meta:
        indexes = [
            Index(
                Lower("first_name"),
                Upper("last_name").desc(),
                name="first_last_name_idx",
            ),
            Index(
                F("height") / (F("weight") + Value(5)),
                name="calc_idx",
            ),
        ]

使用 Meta.indexes 选择。

`pymemcache` 支持¶

新的 django.core.cache.backends.memcached.PyMemcacheCache 缓存后端允许使用 pymemcache 用于Memcached的库。 pymemcache 需要3.4.0或更高版本。有关更多详细信息，请参阅 documentation on caching in Django 。

管理站点的新装饰师¶

新的 display() 装饰器允许轻松地向可与之一起使用的自定义显示功能添加选项 list_display 或 readonly_fields 。

同样，新的 action() 装饰器允许轻松地向可与之一起使用的动作功能添加选项 actions 。

使用 @display 装饰者的优点是现在可以使用 @property 当需要在自定义方法上指定属性时，装饰器。在此之前，有必要使用 property() 在将所需的属性分配给方法后，改为函数。

使用装饰器的优点是，这些选项更容易处理，因为可以由代码编辑器中的完成实用程序建议它们。它们只是一种便利，并且仍然为引擎盖下的功能设置了相同的属性。

次要特征¶

`django.contrib.admin`¶

ModelAdmin.search_fields 现在允许搜索带有空白的引用短语。
如果目标模型已在管理员中注册，只读相关字段现在将呈现为可导航链接。
管理员现在支持主题化，并包括根据浏览器设置启用的黑暗主题。看到主题支持了解更多详细信息。
ModelAdmin.autocomplete_fields 现在尊重 ForeignKey.to_field 和 ForeignKey.limit_choices_to 搜索相关模型时。
管理员现在安装一个最终的全部捕获视图，该视图将未经身份验证的用户重定向到登录页面，而不考虑URL是否有效。这可以防止潜在的模型枚举隐私问题。

虽然不建议，但您可以设置新的 AdminSite.final_catch_all_view 至 False 禁用全面视图。

`django.contrib.auth`¶

PBKDF 2密码哈希器的默认迭代计数从216，000增加到260，000。
Argon 2密码哈希器的默认变体更改为Argon 2id。 memory_cost 和 parallelism 分别增加到102，400和8，以匹配 argon2-cffi 默认值。

增加 memory_cost 将所需内存从512 KB推到100 MB。这仍然相当保守，但可能会在内存受限的环境中导致问题。如果是这种情况，可以对现有哈希器进行子分类以覆盖默认设置。
Argon 2、MD5、PBKDF 2、SHA-1密码哈希器的默认盐量从71位增加到128位。

`django.contrib.contenttypes`¶

新的 absolute_max 论据 generic_inlineformset_factory() 允许自定义在提供时可以实例化的最大数量的表单 POST 数据看到限制实例化表单的最大数量了解更多详细信息。
新的 can_delete_extra 论据 generic_inlineformset_factory() 允许删除删除额外表格的选项。看到 can_delete_extra 以获取更多信息。

`django.contrib.gis`¶

这个 GDALRaster.transform() 方法现在支持 SpatialReference 。
这个 DataSource 类现在支持 pathlib.Path 。
这个 LayerMapping 类现在支持 pathlib.Path 。

`django.contrib.postgres`¶

新的 ExclusionConstraint.include 属性允许在PostgreSQL 12+上创建覆盖排除约束。
新的 ExclusionConstraint.opclasses 属性允许设置PostgreSQL运算符类。
新 JSONBAgg.ordering 属性确定聚合元素的顺序。
新的 JSONBAgg.distinct 属性确定聚合值是否不同。
这个 CreateExtension 操作现在检查该扩展是否已存在于数据库中，如果存在，则跳过迁移。
新的 CreateCollation 和 RemoveCollation 操作允许在PostgreSQL上创建和删除排序规则。看到使用迁移管理排序规则了解更多详细信息。
查找 ArrayField 现在允许包含运算式的（非嵌套）数组作为右侧。
新的 OpClass() express允许使用自定义运算符类在express上创建函数索引。看到函数索引了解更多详细信息。

`django.contrib.sitemaps`¶

新的 Sitemap 属性 alternates ， languages 和 x_default 允许生成网站地图 alternates 到您页面的本地化版本。

`django.contrib.syndication`¶

新的 item_comments hook允许为每个提要项指定评论URL。

数据库后端¶

第三方数据库后台现在可以使用新的跳过Django测试套件中的预期失败测试或标记为预期失败测试 DatabaseFeatures.django_test_skips 和 django_test_expected_failures 属性。

装饰者¶

新的 no_append_slash() 装饰器允许将单个视图排除在外 APPEND_SLASH URL规范化。

错误报告¶

自定义 ExceptionReporter 子类现在可以定义 html_template_path 和 text_template_path 属性来重写用于呈现异常报告的模板。

文件上传¶

新的 FileUploadHandler.upload_interrupted() 回调允许处理中断的上传。

形式¶

新的 absolute_max 论据 formset_factory() ， inlineformset_factory() ，以及 modelformset_factory() 允许自定义在提供时可以实例化的最大数量的表单 POST 数据看到限制实例化表单的最大数量了解更多详细信息。
新的 can_delete_extra 论据 formset_factory() ， inlineformset_factory() ，以及 modelformset_factory() 允许删除删除额外表格的选项。看到 can_delete_extra 以获取更多信息。
BaseFormSet 现在，当管理表单丢失或被篡改时，会报告用户面临错误，而不是引发异常。要自定义此错误消息，请传递 error_messages 用钥匙争论 'missing_management_form' 实例化表单集时。

通用视图¶

这个 week_format 的属性 WeekMixin 和 WeekArchiveView 现在支持 '%V' ISO 8601周格式。

管理命令¶

loaddata 现在支持存储在XZ档案中的固定装置 (.xz ）和LZMA档案 (.lzma )。
dumpdata 现在可以在 bz2 ， gz ， lzma ，或 xz 格式。
makemigrations 现在可以在没有活动数据库连接的情况下调用。在这种情况下，将跳过检查一致的迁移历史记录。
BaseCommand.requires_system_checks 现在支持指定标签列表。在执行命令之前，将检查所选标签中注册的系统检查是否存在错误。在早期版本中，要么执行所有系统检查，要么不执行任何系统检查。
更新了Windows上对彩色终端输出的支持。自动检测各种现代终端环境，并改进了在其他情况下启用支持的选项。看到语法颜色标记了解更多详细信息。

迁徙¶

新的 Operation.migration_name_fragment 属性允许提供文件名片段，该片段将用于命名仅包含该操作的迁移。
迁移现在支持从 pathlib ，以及 os.PathLike 实例。

模型¶

新的 no_key 的参数 QuerySet.select_for_update() ，在PostgreSQL上支持，允许获取较弱的锁，不会阻止创建通过新元素引用锁定行的行。
When() 表达现在允许使用 condition 论点与 lookups 。
新的 Index.include 和 UniqueConstraint.include 属性允许创建覆盖索引并覆盖PostgreSQL 11+上的唯一约束。
新的 UniqueConstraint.opclasses 属性允许设置PostgreSQL运算符类。
这个 QuerySet.update() 方法现在尊重 order_by() SQL和MariaDB上的条款。
FilteredRelation() 现在支持嵌套关系。
这个 of 的论点 QuerySet.select_for_update() 现在允许在MySQL 8.0.1+上使用。
Value() 表达现在自动解析其 output_field 到适当的 Field 基于所提供的类型的子类别 value 为 bool ， bytes ， float ， int ， str ， datetime.date ， datetime.datetime ， datetime.time ， datetime.timedelta ， decimal.Decimal ，以及 uuid.UUID 实例.因此，解决了一个 output_field 对于数据库函数和组合表达，使用混合类型时可能会崩溃 Value() .您需要显式设置 output_field 在这种情况下。
新的 QuerySet.alias() 方法允许为不需要选择但用于过滤、排序或作为复杂表达的一部分的表达创建可重复使用的别名。
新的 Collate 函数允许通过指定的数据库排序来过滤和排序。
这个 field_name 的论点 QuerySet.in_bulk() 现在，如果中仅指定了一个字段，则接受不同的字段 QuerySet.distinct() 。
新的 tzinfo 属性的参数 TruncDate 和 TruncTime 数据库函数允许截断特定时区中的日期时间。
新的 db_collation 论据 CharField 和 TextField 允许为该字段设置数据库排序规则。
添加了 Random 数据库功能。
聚合函数， F() ， OuterRef() ，和其他表达现在允许使用变换。看到公式可以引用转换了解更多细节。
新的 durable 论据 atomic() 确保如果原子块无错误退出，则将提交原子块中所做的更改。标记为持久的嵌套原子块将引发 RuntimeError 。
添加了 JSONObject 数据库功能。

分页¶

新的 django.core.paginator.Paginator.get_elided_page_range() 方法允许生成省略了一些值的页面范围。如果有大量页面，这有助于在模板中生成合理数量的页面链接。

请求和响应¶

响应标头现在存储在 HttpResponse.headers .这可以用来代替原来的类似于dict的界面 HttpResponse 对象这两个界面都将继续受到支持。看到设置标题字段了解更多细节。
新的 headers 的参数 HttpResponse ， SimpleTemplateResponse ，以及 TemplateResponse 允许设置响应 headers 关于实例化。

安防¶

这个 SECRET_KEY 现在，在首次访问时检查设置是否有有效值，而不是在首次加载设置时检查设置。这使得运行不依赖于 SECRET_KEY 无需提供价值。因此，呼叫 configure() 未提供有效的 SECRET_KEY ，然后继续访问 settings.SECRET_KEY 现在将筹集 ImproperlyConfigured 例外。
新的 Signer.sign_object() 和 Signer.unsign_object() 方法允许签署复杂的数据结构。看到保护复杂的数据结构了解更多详细信息。

另外， signing.dumps() 和 loads() 成为 TimestampSigner.sign_object() 和 unsign_object() 。

串行化¶

新的 JSONL 序列化器允许使用SON Lines格式 dumpdata 和 loaddata .这对于填充大型数据库可能很有用，因为数据是逐行加载到内存中的，而不是一次全部加载。

信号¶

Signal.send_robust() 现在记录异常。

模板¶

floatformat 模板筛选器现在允许使用 g 后缀强制按 THOUSAND_SEPARATOR 对于活动区域。
缓存的模板 Cached template loaders 现在已在开发中正确重新加载。

测验¶

中指定给类属性的对象 TestCase.setUpTestData() 现在针对每种测试方法进行隔离。现在需要此类对象支持创建深副本 copy.deepcopy() .删除不支持的对象 deepcopy() 已被弃用并将在Django 4.1中删除。
DiscoverRunner 现在使 faulthandler 在默认情况下可以通过使用 test --no-faulthandler 选择。
DiscoverRunner 以及 test 管理命令现在可以跟踪时间，包括数据库设置和总运行时间。这可以通过使用 test --timing 选择。
Client 现在在遵循307和308重定向时保留请求查询字符串。
新的 TestCase.captureOnCommitCallbacks() 方法捕获传递给 transaction.on_commit() 在列表中。这使您可以测试此类回调，而无需使用较慢的回调 TransactionTestCase 。
TransactionTestCase.assertQuerysetEqual() 属性的默认值时，现在支持与另一个查询集进行直接比较，而不限于与对象的字符串表示形式列表进行比较 transform 争论。

公用事业¶

新的 depth 的参数 django.utils.timesince.timesince() 和 django.utils.timesince.timeuntil() 函数允许指定要返回的相邻时间单位的数量。

验证器¶

内置验证器现在将提供的值包括在 params 提出的论点 ValidationError .这允许自定义错误消息使用 %(value)s 占位符.
这个 ValidationError 相等运算符现在忽略 messages 和 params 订购。

3.2中向后不兼容的更改¶

数据库后端API¶

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

新的 DatabaseFeatures.introspected_field_types 属性取代了这些功能：
- can_introspect_autofield
- can_introspect_big_integer_field
- can_introspect_binary_field
- can_introspect_decimal_field
- can_introspect_duration_field
- can_introspect_ip_address_field
- can_introspect_positive_integer_field
- can_introspect_small_integer_field
- can_introspect_time_field
- introspected_big_auto_field_type
- introspected_small_auto_field_type
- introspected_boolean_field_type
启用对覆盖指数的支持 (Index.include ）并涵盖独特的限制 (UniqueConstraint.include ），设置 DatabaseFeatures.supports_covering_indexes 至 True 。
第三方数据库后台必须对列数据库排序规则实施支持 CharField s和 TextField s或设置 DatabaseFeatures.supports_collation_on_charfield 和 DatabaseFeatures.supports_collation_on_textfield 至 False .如果不支持非确定性排序，请设置 supports_non_deterministic_collations 至 False 。
DatabaseOperations.random_function_sql() 被删除，转而采用新的 Random 数据库功能。
DatabaseOperations.date_trunc_sql() 和 DatabaseOperations.time_trunc_sql() 现在选择可选的 tzname 参数以便在特定时区进行截断。
DatabaseClient.runshell() 现在从 DatabaseClient.settings_to_cmd_args_env() 法第三方数据库后台必须实施 DatabaseClient.settings_to_cmd_args_env() 或覆盖 DatabaseClient.runshell() 。
第三方数据库后台必须实现对功能索引的支持 (Index.expressions ）或设置 DatabaseFeatures.supports_expression_indexes 至 False 。如果 COLLATE 不是 CREATE INDEX 陈述，集 DatabaseFeatures.collate_as_index_expression 至 True 。