Django 5.1.dev 文档

Home | Table of contents | Index | Modules

« previous | up | next »

Django 3.2版本说明¶

April 6, 2021

欢迎使用django3.2！

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

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

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

python兼容性¶

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

django3.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`¶

PBKDF2密码哈希器的默认迭代计数从216000增加到260000。
Argon2密码哈希器的默认变量更改为Argon2id。 memory_cost 和 parallelism 分别增加到102400和8以匹配 argon2-cffi 默认值。

增加 memory_cost 将所需内存从512 KB推送到100 MB。这仍然相当保守，但在内存受限的环境中可能会导致问题。如果是这种情况，则可以将现有哈希器子类化以覆盖默认值。
Argon2、MD5、PBKDF2、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() 表达式允许使用自定义运算符类在表达式上创建函数索引。看见功能指标了解更多详细信息。

`django.contrib.sitemaps`¶

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

`django.contrib.syndication`¶

新的 item_comments 钩子允许为每个提要项指定一个注释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() 关于MySQL和MariaDB的子句。
FilteredRelation() 现在支持嵌套关系。
这个 of 的参数 QuerySet.select_for_update() 现在MySQL8.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 . 这可以代替 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 序列化程序允许使用JSON行格式 dumpdata 和 loaddata . 这对于填充大型数据库非常有用，因为数据是逐行加载到内存中的，而不是一次全部加载。

信号¶

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

模板¶

floatformat 模板过滤现在允许使用 g 后缀以强制按 THOUSAND_SEPARATOR 用于活动区域设置。
使用缓存的模板 Cached template loaders 现在可以在开发中正确重新加载。

测验¶

为中的类属性指定的对象 TestCase.setUpTestData() 现在每种测试方法都是独立的。现在需要这样的对象来支持使用 copy.deepcopy() . 分配不支持的对象 deepcopy() 已弃用，将在django4.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 。