2020年8月4日
欢迎使用django3.1!
这些发行说明涵盖了 new features 以及一些 backwards incompatible changes 当从django3.0或更早版本升级时,您需要注意。我们已经 dropped some features 已经到了他们的折旧周期结束,我们已经 begun the deprecation process for some features .
见 如何将Django升级到更新版本 如果正在更新现有项目,则提供指南。
Django 3.1支持Python3.6、3.7、3.8和3.9(从3.1.3开始)。我们 强烈推荐 并且仅官方支持每个系列的最新版本。
Django现在支持完全异步的请求路径,包括:
要开始使用异步视图,您需要使用 async def
::
async def my_view(request):
await asyncio.sleep(0.5)
return HttpResponse("Hello, async world!")
无论您是在WSGI还是ASGI模式下运行,都支持所有异步特性。但是,在WSGI模式下使用异步代码会导致性能下降。有关详细信息,请参阅 异步支持 文档。
你可以自由地同步视图和中间件。Django将确保您始终得到正确的执行上下文。我们预计大多数项目将保持其大部分视图同步,并且只有少数几个视图以异步模式运行—但这完全是您的选择。
Django的ORM、缓存层和其他执行长时间运行的网络调用的代码还不支持异步访问。我们希望在即将发布的版本中添加对它们的支持。异步视图是理想的,但是,如果您在视图中执行大量的API或HTTP调用,那么现在可以在本机并行地执行所有这些HTTP调用,从而大大加快视图的执行速度。
异步支持应该是完全向后兼容的,并且我们已经尝试确保它对您现有的同步代码没有速度倒退。它应该不会对任何现有的Django项目产生明显的影响。
Django现在包括 models.JSONField
和 forms.JSONField
可用于所有受支持的数据库后端。这两个字段都支持使用自定义JSON编码器和解码器。模型字段支持自省, lookups, and transforms 以前仅限PostgreSQL::
from django.db import models
class ContactInfo(models.Model):
data = models.JSONField()
ContactInfo.objects.create(
data={
"name": "John",
"cities": ["London", "Cambridge"],
"pets": {"dogs": ["Rufus", "Meg"]},
}
)
ContactInfo.objects.filter(
data__name="John",
data__pets__has_key="dogs",
data__cities__contains="London",
).delete()
如果您的项目使用 django.contrib.postgres.fields.JSONField
,以及相关的表单字段和转换,您应该调整以使用新字段,并生成和应用数据库迁移。现在,旧的字段和转换作为对新字段和转换的引用 deprecated as of this release .
DEFAULT_HASHING_ALGORITHM
设置¶新的 DEFAULT_HASHING_ALGORITHM
过渡设置允许指定用于对管理站点中的Cookie、密码重置令牌、用户会话和创建的签名进行编码的默认散列算法 django.core.signing.Signer
和 django.core.signing.dumps()
。
Django 3.1中添加了对SHA-256的支持。如果要将同一项目的多个实例升级到Django 3.1,则应设置 DEFAULT_HASHING_ALGORITHM
至 'sha1'
在过渡期间,为了允许与Django的旧版本兼容。请注意,这需要Django 3.1.1+。完成向3.1的过渡后,即可停止覆盖 DEFAULT_HASHING_ALGORITHM
。
此设置在此版本中已弃用,因为Django4.0将删除对使用SHA-1算法的令牌、Cookie、会话和签名的支持。
django.contrib.admin
¶新的 django.contrib.admin.EmptyFieldListFilter
对于 ModelAdmin.list_filter
允许在管理变更列表视图中筛选空值(空字符串和空值)。
管理变更列表视图右边栏中的过滤器现在包含一个清除所有过滤器的链接。
管理员现在在更大的屏幕上有一个侧边栏,便于导航。默认情况下启用,但可以使用自定义 AdminSite
设置 AdminSite.enable_nav_sidebar
到 False
.
呈现边栏需要访问当前请求,以便设置CSS和ARIA角色提供。这需要使用 'django.template.context_processors.request'
在 'context_processors'
选择权 OPTIONS
.
最初为空 extra
现在可以删除内联,方式与动态创建的内联相同。
XRegExp
已从版本2.0.0升级到3.2.0。
jQuery从3.4.1版升级到3.5.1版。
Select2库从版本4.0.7升级到4.0.13。
django.contrib.auth
¶PBKDF2密码哈希器的默认迭代计数从180000增加到216000。
新的 PASSWORD_RESET_TIMEOUT
设置允许定义密码重置链接有效的秒数。这是鼓励而不是反对 PASSWORD_RESET_TIMEOUT_DAYS
设置,这将在django4.0中删除。
密码重置机制现在使用SHA-256哈希算法。对使用旧哈希算法的令牌的支持一直到django4.0。
AbstractBaseUser.get_session_auth_hash()
现在使用SHA-256哈希算法。对使用旧哈希算法的用户会话的支持一直持续到django4.0。
django.contrib.contenttypes
¶新的 remove_stale_contenttypes --include-stale-apps
选项允许从以前安装的已从中删除的应用程序中删除过时的内容类型 INSTALLED_APPS
.
django.contrib.gis
¶relate
现在MariaDB支持查找。
增加了 LinearRing.is_counterclockwise
财产。
AsGeoJSON
现在Oracle支持。
增加了对PostGIS 3和GDAL3的支持。
django.contrib.humanize
¶intword
模板过滤器现在支持负整数。
django.contrib.postgres
¶新的 BloomIndex
类允许创建 bloom
数据库中的索引。新的 BloomExtension
迁移操作安装 bloom
扩展以添加对此索引的支持。
get_FOO_display()
现在支持 ArrayField
和 RangeField
.
新的 rangefield.lower_inc
, rangefield.lower_inf
, rangefield.upper_inc
和 rangefield.upper_inf
查找允许查询 RangeField
按绑定类型。
rangefield.contained_by
现在支持 SmallAutoField
, AutoField
, BigAutoField
, SmallIntegerField
和 DecimalField
.
SearchQuery
现在支持 'websearch'
PostgreSQL 11+上的搜索类型。
SearchQuery.value
现在支持查询表达式。
新的 SearchHeadline
类允许突出显示搜索结果。
search
lookup现在支持查询表达式。
新的 cover_density
参数 SearchRank
允许按覆盖密度进行排名。
新的 normalization
参数 SearchRank
允许等级规范化。
新的 ExclusionConstraint.deferrable
属性允许创建可延迟的排除约束。
django.contrib.sessions
¶这个 SESSION_COOKIE_SAMESITE
设置现在允许 'None'
(字符串)值,显式声明cookie与所有相同站点和跨站点请求一起发送。
django.contrib.staticfiles
¶这个 STATICFILES_DIRS
设置现在支持 pathlib.Path
.
这个 cache_control()
装饰工和 patch_cache_control()
方法现在支持 no-cache
指令 Cache-Control
标题,根据 RFC 7234#section-5.2.2.2 .
delete()
现在又回来了 True
如果密钥被成功删除, False
否则的话。
这个 CSRF_COOKIE_SAMESITE
设置现在允许 'None'
(字符串)值,显式声明cookie与所有相同站点和跨站点请求一起发送。
这个 EMAIL_FILE_PATH
设置,由 file email backend ,现在支持 pathlib.Path
.
django.views.debug.SafeExceptionReporterFilter
现在过滤敏感值 request.META
在异常报告中。
新的 SafeExceptionReporterFilter.cleansed_substitute
和 SafeExceptionReporterFilter.hidden_settings
属性允许自定义敏感设置和 request.META
在异常报告中过滤。
技术404调试视图现在考虑 DEFAULT_EXCEPTION_REPORTER_FILTER
应用设置筛选时。
新的 DEFAULT_EXCEPTION_REPORTER
允许提供 django.views.debug.ExceptionReporter
子类以自定义异常报告生成。看到了吗 自定义错误报告 有关详细信息。
FileSystemStorage.save()
方法现在支持 pathlib.Path
.
FileField
和 ImageField
现在接受一个 storage
. 这允许您在运行时修改使用的存储,例如为不同的环境选择不同的存储。
ModelChoiceIterator
,使用人 ModelChoiceField
和 ModelMultipleChoiceField
,现在使用 ModelChoiceIteratorValue
小部件可以使用它来访问模型实例。看到了吗 迭代关系选择 有关详细信息。
django.forms.DateTimeField
现在接受ISO8601日期时间格式子集中的日期,包括可选时区,例如。 2019-10-10T06:47
, 2019-10-10T06:47:23+04:00
或 2019-10-10T06:47:23Z
. 如果提供了时区,则将始终保留时区,即使在 USE_TZ
是 False
.
此外, DateTimeField
现在使用 DATE_INPUT_FORMATS
除了 DATETIME_INPUT_FORMATS
将字段输入转换为 datetime
价值。
MultiWidget.widgets
现在接受一个允许定制子部件的字典 name
属性。
新的 BoundField.widget_type
属性可用于根据小部件类型动态调整窗体呈现。
这个 LANGUAGE_COOKIE_SAMESITE
设置现在允许 'None'
(字符串)值,显式声明cookie与所有相同站点和跨站点请求一起发送。
增加了对阿尔及利亚阿拉伯语、伊博语、吉尔吉斯语、塔吉克语和土库曼语的支持和翻译。
新的 check --database
选项允许指定用于运行 database
系统检查。以前对所有配置的都启用了这些检查 DATABASES
通过传递 database
标记到命令。
新的 migrate --check
选项使命令在检测到未应用的迁移时以非零状态退出。
新的 returncode
的参数 CommandError
允许自定义管理命令的退出状态。
新的 dbshell -- ARGUMENTS
选项允许向数据库的命令行客户端传递额外的参数。
新的 ExtractIsoWeekDay
函数从中提取ISO-8601周天数 DateField
和 DateTimeField
和新的 iso_week_day
查找允许按ISO-8601查询。
QuerySet.explain()
现在支持:
TREE
MySQL8.0.16+上的格式,
analyze
MySQL 8.0.18+和MariaDB上的选项。
补充 PositiveBigIntegerField
就像一个 PositiveIntegerField
但它只允许在某个(依赖于数据库的)限制下使用值。值来自 0
到 9223372036854775807
在Django支持的所有数据库中都是安全的。
新的 RESTRICT
选择权 on_delete
的参数 ForeignKey
和 OneToOneField
模拟SQL约束的行为 ON DELETE RESTRICT
.
CheckConstraint.check
现在支持布尔表达式。
这个 RelatedManager.add()
, create()
和 set()
方法现在在 through_defaults
争论。
新的 is_dst
的参数 QuerySet.datetimes()
确定不存在且不明确的日期时间的处理方式。
新的 F
表达 bitxor()
方法允许 bitwise XOR operation .
QuerySet.bulk_create()
现在在使用MariaDB 10.5+时设置对象的主键。
这个 DatabaseOperations.sql_flush()
方法现在通过使用 DELETE
而不是 TRUNCATE
不需要重置序列的表的语句。
SQLite函数现在标记为 deterministic
在python3.8+上。这允许在检查约束和部分索引中使用它们。
新的 UniqueConstraint.deferrable
属性允许创建可延迟的唯一约束。
Paginator
现在可以迭代生成它的页面。
如果 ALLOWED_HOSTS
是空的 DEBUG=True
,localhost的子域现在允许在 Host
标题,例如。 static.localhost
.
HttpResponse.set_cookie()
和 HttpResponse.set_signed_cookie()
现在允许使用 samesite='None'
(字符串)显式声明cookie与所有相同站点和跨站点请求一起发送。
新的 HttpRequest.accepts()
方法根据 Accept
HTTP头。
这个 SECURE_REFERRER_POLICY
设置现在默认为 'same-origin'
. 有了这个配置, SecurityMiddleware
设置 推荐人政策 报头到 same-origin
对所有还没有的响应。这样可以防止 Referer
标头正在发送到其他来源。如果需要前面的行为,请显式设置 SECURE_REFERRER_POLICY
到 None
.
的默认算法 django.core.signing.Signer
, django.core.signing.loads()
和 django.core.signing.dumps()
改为SHA-256。在django4.0之前,对使用旧SHA-1算法的签名的支持仍然存在。
还有,新的 algorithm
的参数 Signer
允许自定义哈希算法。
重新命名的 translate
和 blocktranslate
模板标记是为了在模板代码中国际化而引入的。年长的 trans
和 blocktrans
模板标记别名继续工作,并将在可预见的将来保留。
这个 include
template标记现在接受iterable的模板名称。
SimpleTestCase
现在实现 debug()
方法来允许在不收集结果和捕获异常的情况下运行测试。这可以用来支持在调试器下运行测试。
新的 MIGRATE
测试数据库设置允许在创建测试数据库期间禁用迁移。
Django测试运行程序现在支持 test --buffer
用于放弃通过测试的输出的选项。
DiscoverRunner
现在跳过在数据库上运行系统检查 referenced by tests .
TransactionTestCase
在MySQL上,由于 flush
命令改进。作为一个副作用,后者不再自动重置序列的拆卸。启用 TransactionTestCase.reset_sequences
如果您的测试需要此功能。
Path converters 现在可以提高 ValueError
在里面 to_url()
在反转URL时指示不匹配。
filepath_to_uri()
现在支持 pathlib.Path
.
parse_duration()
现在支持ISO 8601格式的十进制小数逗号分隔符。
parse_datetime()
, parse_duration()
和 parse_time()
现在支持毫秒的逗号分隔符。
SQLite后端现在支持 pathlib.Path
对于 NAME
设置。
这个 settings.py
由 startproject
命令现在使用 pathlib.Path
而不是 os.path
用于构建文件系统路径。
这个 TIME_ZONE
现在在支持时区的数据库上允许设置。
本节描述第三方数据库后端可能需要的更改。
DatabaseOperations.fetch_returned_insert_columns()
现在需要额外的 returning_params
争论。
connection.timezone
财产现在 'UTC'
默认情况下,或 TIME_ZONE
什么时候? USE_TZ
是 True
在支持时区的数据库上。以前是的 None
在支持时区的数据库上。
connection._nodb_connection
属性更改为 connection._nodb_cursor()
方法,现在返回一个上下文管理器,该管理器生成一个游标,并在退出时自动关闭游标和连接 with
语句。
DatabaseClient.runshell()
现在需要额外的 parameters
参数作为要传递给命令行客户端的额外参数的列表。
这个 sequences
的位置参数 DatabaseOperations.sql_flush()
替换为boolean关键字only参数 reset_sequences
.如果 True
,将重置被截断表的序列。
这个 allow_cascade
的参数 DatabaseOperations.sql_flush()
现在是只包含关键字的参数。
这个 using
的位置参数 DatabaseOperations.execute_sql_flush()
已删除。该方法现在使用被调用实例的数据库。
第三方数据库后端必须实现对 JSONField
或设置 DatabaseFeatures.supports_json_field
到 False
. 如果不支持存储原语,则设置 DatabaseFeatures.supports_primitives_in_json_field
到 False
. 如果JSON有一个真正的数据类型,则设置 DatabaseFeatures.has_native_json_field
到 True
.如果 jsonfield.contains
和 jsonfield.contained_by
不支持,设置 DatabaseFeatures.supports_json_field_contains
到 False
.
第三方数据库后端必须对 JSONField
或设置 can_introspect_json_field
到 False
.
对MariaDB 10.1的上游支持将于2020年10月结束。django3.1支持MariaDB 10.2及更高版本。
contrib.admin
浏览器支持¶管理员不再支持旧版Internet Explorer浏览器。看到了吗 the admin FAQ 有关支持的浏览器的详细信息。
AbstractUser.first_name
max_length
增加到150¶迁徙 django.contrib.auth.models.User.first_name
包括在内。如果有自定义用户模型继承自 AbstractUser
,您需要为您的用户模型生成和应用数据库迁移。
如果要保留名字的30个字符限制,请使用自定义格式:
from django import forms
from django.contrib.auth.forms import UserChangeForm
class MyUserChangeForm(UserChangeForm):
first_name = forms.CharField(max_length=30, required=False)
如果您希望在编辑用户时在管理员中保留此限制,请设置 UserAdmin.form
使用此表单:
from django.contrib.auth.admin import UserAdmin
from django.contrib.auth.models import User
class MyUserAdmin(UserAdmin):
form = MyUserChangeForm
admin.site.unregister(User)
admin.site.register(User, MyUserAdmin)
使用的缓存键 cache
并由 make_template_fragment_key()
与旧版本的Django生成的密钥不同。升级到django3.1之后,对任何先前缓存的模板片段的第一个请求都将是缓存未命中。
从中返回重定向回退或204 HTTP响应的决策背后的逻辑 set_language()
视图现在基于 Accept
HTTP头而不是 X-Requested-With
HTTP标头存在。
的兼容性导入 django.core.exceptions.EmptyResultSet
在里面 django.db.models.query
, django.db.models.sql
和 django.db.models.sql.datastructures
被移除。
的兼容性导入 django.core.exceptions.FieldDoesNotExist
在里面 django.db.models.fields
被移除。
的兼容性导入 django.forms.utils.pretty_name()
和 django.forms.boundfield.BoundField
在里面 django.forms.forms
被移除。
的兼容性导入 Context
, ContextPopException
和 RequestContext
在里面 django.template.base
被移除。
的兼容性导入 django.contrib.admin.helpers.ACTION_CHECKBOX_NAME
在里面 django.contrib.admin
被移除。
这个 STATIC_URL
和 MEDIA_URL
设置为相对路径的设置现在以服务器提供的值作为前缀 SCRIPT_NAME
(或) /
如果未设置)。此更改不应影响设置为有效URL或绝对路径的设置。
ConditionalGetMiddleware
不再添加 ETag
带有空的响应的标题 content
.
django.utils.decorators.classproperty()
装潢师被公之于众 django.utils.functional.classproperty()
.
floatformat
模板过滤器现在输出(正) 0
四舍五入为零的负数。
Meta.ordering
和 Meta.unique_together
中的模型选项 django.contrib
以前是元组的模块现在是列表。
管理日历小部件现在根据opengroup规范处理两位数的年份,即69到99之间的值映射到上一个世纪,0到68之间的值映射到当前世纪。
从的默认列表中删除仅日期格式 DATETIME_INPUT_FORMATS
.
这个 FileInput
小部件不再使用 required
初始数据存在时的HTML属性。
无证件者 django.views.debug.ExceptionReporterFilter
类被删除。根据 自定义错误报告 文档,要与之一起使用的类 DEFAULT_EXCEPTION_REPORTER_FILTER
需要继承自 django.views.debug.SafeExceptionReporterFilter
.
由设置的缓存超时 cache_page()
现在decorator优先于 max-age
来自 Cache-Control
标题。
在中提供非本地远程字段 ForeignKey.to_field
现在争论起来了 FieldError
.
SECURE_REFERRER_POLICY
现在默认为 'same-origin'
. 见 有什么新鲜事 Security section 更多详细信息。
check
管理命令现在运行 database
系统只检查使用指定的数据库别名 check --database
选择权。
migrate
管理命令现在运行 database
系统只检查要迁移的数据库。
管理CSS类 row1
和 row2
为了 :nth-child(odd)
和 :nth-child(even)
伪类。
这个 make_password()
函数现在要求其参数为字符串或字节。其他类型应显式转换为这些类型之一。
无证件者 version
参数 AsKML
功能已删除。
JSON and YAML serializers ,使用人 dumpdata
,现在默认使用Unicode转储所有数据。如果你需要以前的行为,通过 ensure_ascii=True
到JSON序列化程序,或 allow_unicode=False
到YAML序列化程序。
自动重新加载程序不再监视内置Django翻译文件中的更改。
支持的最低版本 mysqlclient
从1.3.13增加到1.4.0。
无证件者 django.contrib.postgres.forms.InvalidJSONInput
和 django.contrib.postgres.forms.JSONString
已移动到 django.forms.fields
.
无证件者 django.contrib.postgres.fields.jsonb.JsonAdapter
类被删除。
这个 {{% localize off %}}
标记和 unlocalize
过滤不再尊重 DECIMAL_SEPARATOR
设置。
支持的最低版本 asgiref
从3.2增加到3.2.10。
这个 Media 类现在呈现 <script>
没有 type
要遵循的属性 WHATWG recommendations .
ModelChoiceIterator
,使用人 ModelChoiceField
和 ModelMultipleChoiceField
现在生成包含选项的元组 ModelChoiceIteratorValue
实例作为第一个 value
每个选项中的元素。在大多数情况下,代理是透明的,但是如果您需要 field
值本身,使用 ModelChoiceIteratorValue.value
改为属性。
JSONField
¶django.contrib.postgres.fields.JSONField
和 django.contrib.postgres.forms.JSONField
被否决,赞成 models.JSONField
和 forms.JSONField
.
无证件者 django.contrib.postgres.fields.jsonb.KeyTransform
和 django.contrib.postgres.fields.jsonb.KeyTextTransform
也不赞成使用 django.db.models.fields.json
.
新的 JSONField
s, KeyTransform
和 KeyTextTransform
可用于所有受支持的数据库后端。
PASSWORD_RESET_TIMEOUT_DAYS
设置已弃用,取而代之的是 PASSWORD_RESET_TIMEOUT
.
未记录的用法 isnull
使用非布尔值进行查找,因为右侧已弃用,请使用 True
或 False
相反。
几乎没有记载的 django.db.models.query_utils.InvalidQuery
异常类被弃用,取而代之的是 FieldDoesNotExist
和 FieldError
.
这个 django-admin.py
不赞成使用入口点 django-admin
.
这个 HttpRequest.is_ajax()
方法被弃用,因为它依赖于jQuery特定的方式来表示AJAX调用,而当前的使用倾向于使用JavaScript Fetch API . 根据您自己的情况,您可以使用新的方法,也可以使用自己的方法 HttpRequest.accepts()
方法,如果您的代码依赖于客户端 Accept
HTTP头。
如果您正在编写自己的AJAX检测方法, request.is_ajax()
完全可以复制 request.headers.get('x-requested-with') == 'XMLHttpRequest'
.
经过 None
作为第一个论点 django.utils.deprecation.MiddlewareMixin.__init__()
被贬低。
编码Cookie所用的值的格式 CookieStorage
与Django的旧版本生成的格式不同。对旧格式的支持一直持续到django4.0。
会话的编码格式与Django的旧版本生成的格式不同。对旧格式的支持一直持续到django4.0。
纯粹的文献资料 providing_args
的参数 Signal
已弃用。如果依赖此参数作为文档,则可以将文本移动到代码注释或docstring。
调用 django.utils.crypto.get_random_string()
没有 length
参数已弃用。
这个 list
的消息 ModelMultipleChoiceField
被否决,赞成 invalid_list
.
将原始列别名传递给 QuerySet.order_by()
已弃用。通过在 RawSQL
而是事先。
这个 NullBooleanField
不推荐使用Model字段,而是支持 BooleanField(null=True, blank=True)
。
django.conf.urls.url()
的别名 django.urls.re_path()
被贬低。
这个 {{% ifequal %}}
和 {{% ifnotequal %}}
模板标记已弃用,取而代之的是 {{% if %}}
. {{% if %}}
涵盖了所有用例,但是如果您需要继续使用这些标记,可以将它们从Django提取到模块中,并作为内置标记包含在 'builtins'
选择权 OPTIONS
.
DEFAULT_HASHING_ALGORITHM
过渡设置已弃用。
这些特性已经到了其弃用周期的末尾,并在django3.1中被删除。
见 2.2中不推荐的功能 有关这些更改的详细信息,包括如何删除这些功能的用法。
django.utils.timezone.FixedOffset
被移除。
django.core.paginator.QuerySetPaginator
被移除。
模型的 Meta.ordering
不影响 GROUP BY
查询。
django.contrib.postgres.fields.FloatRangeField
和 django.contrib.postgres.forms.FloatRangeField
被移除。
这个 FILE_CHARSET
设置被删除。
django.contrib.staticfiles.storage.CachedStaticFilesStorage
被移除。
这个 RemoteUserBackend.configure_user()
方法要求 request
作为第一个位置参数。
支持 SimpleTestCase.allow_database_queries
和 TransactionTestCase.multi_db
被移除。
12月 18, 2023