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月结束。
Django 3.2支持Python3.6、3.7、3.8、3.9和3.10(从3.2.9开始)。我们 highly recommend 并且仅官方支持每个系列的最新版本。
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
现在允许将表达式作为右侧的(非嵌套)数组。
django.contrib.sitemaps
¶新的 Sitemap
属性 alternates
, languages
和 x_default
允许生成站点地图 候补 到页面的本地化版本。
第三方数据库后端现在可以使用新的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()
.
增加了 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()
。
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
订购。
本节描述第三方数据库后端可能需要的更改。
新的 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
。
django.contrib.admin
¶管理中的分页链接现在是1索引而不是0索引,即第一页的查询字符串是 ?p=1
而不是 ?p=0
.
新的admin catch-all视图将打破在admin URL之后路由并与admin URL前缀匹配的URL模式。您可以调整URL顺序,如有必要,也可以设置 AdminSite.final_catch_all_view
至 False
,禁用全部捕获视图。看见 django3.2的新增功能 了解更多详细信息。
缩小的JavaScript文件不再包含在管理员中。如果需要缩小这些文件,请考虑使用第三方应用程序或外部生成工具。与管理员打包的小型供应商JavaScript文件(例如。 jquery.min.js )仍然包括在内。
ModelAdmin.prepopulated_fields
英语不再像条子一样停下来 'a'
或 'an'
.
django.contrib.gis
¶已删除对PostGIS 2.2的支持。
Oracle后端现在会在重定向多边形并将其保存到数据库之前克隆多边形(以及包含多边形的几何体集合)。它们不再在原地发生变异。如果在保存模型后使用多边形,您可能会注意到这一点。
对PostgreSQL 9.5的上游支持将于2021年2月结束。django3.2支持postgresql9.6及更高版本。
MySQL 5.6的上游支持将于2021年4月结束。django3.2支持MySQL 5.7及更高版本。
Django现在支持非``pytz``时区,如Python3.9+ zoneinfo
模块及其后端口。
无证件者 SpatiaLiteOperations.proj4_version()
方法被重命名为 proj_version()
.
slugify()
现在删除前导和尾随的短划线和下划线。
支持 argon2-cffi
删除<19.1.0。
禁用国际化时,缓存键不再包含该语言 (USE_I18N = False
)并启用本地化 (USE_L10N = True
). 在这种配置中升级到django3.2之后,对任何先前缓存的值的第一个请求都将是缓存未命中。
ForeignKey.validate()
现在使用 _base_manager
而不是 _default_manager
检查相关实例是否存在。
当应用程序定义 AppConfig
中的子类 apps.py
子模块,Django现在自动使用此配置,即使它没有使用 default_app_config
. 集合 default = False
在 AppConfig
如果需要阻止此行为,则使用子类。看到了吗 django3.2的新增功能 了解更多详细信息。
实例化抽象模型现在引发 TypeError
.
关键字参数 setup_databases()
现在只显示关键字。
无证件者 django.utils.http.limited_parse_qsl()
功能已删除。请使用 urllib.parse.parse_qsl()
相反。
django.test.utils.TestContextDecorator
现在使用 addCleanup()
所以在 setUp()
方法之前调用 TestContextDecorator.disable()
.
SessionMiddleware
现在提出一个 SessionInterrupted
异常而不是 SuspiciousOperation
当会话在并发请求中被破坏时。
这个 django.db.models.Field
相等运算符现在可以正确地区分跨模型继承的字段实例。此外,现在定义了这些字段的顺序。
无证件者 django.core.files.locks.lock()
函数现在返回 False
如果文件无法锁定,而不是引发 BlockingIOError
.
密码重置机制现在会在用户电子邮件更改时使令牌失效。
makemessages
命令不再处理使用 makemessages --locale
选项,当它们包含连字符时 ('-'
)。
这个 django.contrib.auth.forms.ReadOnlyPasswordHashField
表单域现在为 disabled
默认情况下。因此, UserChangeForm.clean_password()
不再需要返回初始值。
这个 cache.get_many()
, get_or_set()
, has_key()
, incr()
, decr()
, incr_version()
,以及 decr_version()
缓存操作现在可以正确处理 None
以与任何其他值相同的方式存储在缓存中,而不是表现得好像键不存在一样。
由于 python-memcached
限制,以前的行为将保留给已弃用的 MemcachedCache
后端。
SQLite支持的最低版本从3.8.3提高到3.9.0。
CookieStorage
现在将消息存储在 RFC 6265 符合格式。对使用旧格式的cookie的支持一直持续到Django 4.1。
支持的最低版本 asgiref
从3.2.10增加到3.3.2。
分配不支持使用创建深度副本的对象 copy.deepcopy()
将属性分类到 TestCase.setUpTestData()
被贬低。
在中使用布尔值 BaseCommand.requires_system_checks
被贬低。使用 '__all__'
而不是 True
和 []
(空列表)而不是 False
.
这个 whitelist
论证与 domain_whitelist
属性 EmailValidator
已弃用。使用 allowlist
而不是 whitelist
和 domain_allowlist
而不是 domain_whitelist
. 可能需要重命名 whitelist
在现有的迁移中。
这个 default_app_config
应用程序配置变量已弃用,因为现在自动 AppConfig
发现。看到了吗 django3.2的新增功能 了解更多详细信息。
自动呼叫 repr()
在中的查询集上 TransactionTestCase.assertQuerysetEqual()
与字符串值相比,不推荐使用。如果需要前面的行为,请显式设置 transform
至 repr
。
这个 django.core.cache.backends.memcached.MemcachedCache
后端已弃用,因为 python-memcached
出现了一些问题,似乎没有得到维护。使用 django.core.cache.backends.memcached.PyMemcacheCache
或 django.core.cache.backends.memcached.PyLibMCCache
取而代之的是。
使用的消息格式 django.contrib.messages.storage.cookie.CookieStorage
与旧版本的Django生成的格式不同。对旧格式的支持一直持续到Django 4.1。
12月 18, 2023