Django 3.1 发行说明 — Django 文档

来自菜鸟教程
Django/docs/3.1.x/releases/3.1
跳转至：导航、​搜索

Django 3.1 发行说明

2020 年 8 月 4 日

欢迎使用 Django 3.1！

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

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

Python兼容性

Django 3.1 支持 Python 3.6、3.7、3.8 和 3.9（从 3.1.3 开始）。 我们【X3X】强烈推荐【X23X】，官方只支持各系列的最新版本。


Django 3.1 中的新功能

异步视图和中间件支持

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 项目没有明显影响。


所有支持的数据库后端的 JSONField

Django 现在包括 models.JSONField 和 forms.JSONField，可用于所有支持的数据库后端。 这两个字段都支持使用自定义 JSON 编码器和解码器。 模型字段支持以前仅用于 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，加上相关的表单字段和转换，您应该调整以使用新字段，并生成和应用数据库迁移。 目前，旧字段和转换保留为对新字段的引用，并且在此版本 中已弃用 。


DEFAULT_HASHING_ALGORITHM 设置

新的 :setting:`DEFAULT_HASHING_ALGORITHM` 过渡设置允许指定用于编码 cookie、管理站点中的密码重置令牌、用户会话和由 django.core 创建的签名的默认哈希算法。 signing.Signer 和 django.core.signing.dumps()。

在 Django 3.1 中添加了对 SHA-256 的支持。 如果您将同一项目的多个实例升级到 Django 3.1，您应该在转换期间将 :setting:`DEFAULT_HASHING_ALGORITHM` 设置为 'sha1'，以便与旧版本的兼容姜戈。 请注意，这需要 Django 3.1.1+。 一旦过渡到 3.1 完成，您就可以停止覆盖 :setting:`DEFAULT_HASHING_ALGORITHM`。

此设置在此版本中已弃用，因为将在 Django 4.0 中删除对使用 SHA-1 算法的令牌、cookie、会话和签名的支持。


小功能

django.contrib.admin

  • ModelAdmin.list_filter 的新 django.contrib.admin.EmptyFieldListFilter 允许在管理更改列表视图中过滤空值（空字符串和空值）。

  • 管理更改列表视图右侧边栏中的过滤器现在包含一个用于清除所有过滤器的链接。

  • 管理员现在在更大的屏幕上有一个侧边栏，以便于导航。 它默认启用，但可以通过使用自定义 AdminSite 并将 AdminSite.enable_nav_sidebar 设置为 False 来禁用。

    渲染侧边栏需要访问当前请求，以便设置 CSS 和 ARIA 角色可供性。 这需要使用'django.template.context_processors.request'在里面'context_processors'选项 ：设置：`选项 ` .

  • 现在可以删除最初为空的 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 密码哈希器的默认迭代计数从 180,000 增加到 216,000。
  • 新的 :setting:`PASSWORD_RESET_TIMEOUT` 设置允许定义密码重置链接有效的秒数。 鼓励这样做而不是弃用的 PASSWORD_RESET_TIMEOUT_DAYS 设置，后者将在 Django 4.0 中删除。
  • 密码重置机制现在使用 SHA-256 散列算法。 对使用旧哈希算法的令牌的支持一直持续到 Django 4.0。
  • AbstractBaseUser.get_session_auth_hash() 现在使用 SHA-256 散列算法。 对使用旧散列算法的用户会话的支持一直持续到 Django 4.0。


django.contrib.contenttypes

  • 新的 remove_stale_contenttypes --include-stale-apps 选项允许从已从 :setting:`INSTALLED_APPS` 中删除的以前安装的应用程序中删除陈旧的内容类型。


django.contrib.gis


django.contrib.humanize


django.contrib.postgres


django.contrib.sessions


django.contrib.staticfiles


缓存


CSRF


电子邮件


错误报告


文件存储

  • FileSystemStorage.save() 方法现在支持 [X30X]。
  • FileField 和 ImageField 现在接受 storage 的可调用。 这允许您在运行时修改使用的存储，例如，为不同的环境选择不同的存储。


表格


国际化

  • :setting:`LANGUAGE_COOKIE_SAMESITE` 设置现在允许 'None'（字符串）值明确声明 cookie 与所有同站点和跨站点请求一起发送。
  • 添加了对阿尔及利亚阿拉伯语、伊博语、吉尔吉斯语、塔吉克语和土库曼语的支持和翻译。


管理命令

  • 新的 check --database 选项允许为运行 database 系统检查指定数据库别名。 以前，通过将 database 标签传递给命令，为所有配置的 :setting:`DATABASES` 启用这些检查。
  • 当检测到未应用的迁移时，新的 migrate --check 选项使命令以非零状态退出。
  • CommandError 的新 returncode 参数允许自定义管理命令的退出状态。
  • 新的 dbshell -- ARGUMENTS 选项允许将额外的参数传递给数据库的命令行客户端。
  • :djadmin:`flush` 和 :djadmin:`sqlflush` 命令现在包含用于在 SQLite 上重置序列的 SQL。


型号

  • 新的 ExtractIsoWeekDay 函数从 DateField 和 DateTimeField 中提取 ISO-8601 工作日，新的 :lookup:`iso_week_day` 查找允许按 ISO-8601 星期几查询。
  • QuerySet.explain() 现在支持：
    • MySQL 8.0.16+ 上的 TREE 格式，
    • MySQL 8.0.18+ 和 MariaDB 上的 analyze 选项。
  • 添加了 PositiveBigIntegerField，它的作用很像 PositiveIntegerField，除了它只允许在特定（依赖于数据库）限制下的值。 从 0 到 9223372036854775807 的值在 Django 支持的所有数据库中都是安全的。
  • ForeignKey 和 OneToOneField 的 on_delete 参数的新 RESTRICT 选项模拟 SQL 约束 ON DELETE RESTRICT 的行为。
  • CheckConstraint.check 现在支持布尔表达式。
  • RelatedManager.add()、create() 和 set() 方法现在接受可调用对象作为 through_defaults 参数中的值。
  • QuerySet.datetimes() 的新 is_dst 参数决定了对不存在和不明确的日期时间的处理。
  • 新的 F 表达式 bitxor() 方法允许 按位异或运算 。
  • QuerySet.bulk_create() 现在在使用 MariaDB 10.5+ 时设置对象的主键。
  • DatabaseOperations.sql_flush() 方法现在通过对不需要重置序列的表使用 DELETE 而不是 TRUNCATE 语句在 MySQL 上生成更高效的 SQL。
  • SQLite 函数现在在 Python 3.8+ 上标记为 deterministic。 这允许在检查约束和部分索引中使用它们。
  • 新的 UniqueConstraint.deferrable 属性允许创建可延迟的唯一约束。


请求和响应


安全


模板


测试

  • SimpleTestCase 现在实现了 debug() 方法，以允许在不收集结果和捕获异常的情况下运行测试。 这可用于支持在调试器下运行测试。
  • 新的 ：设置：`迁移 ` 测试数据库设置允许在测试数据库创建期间禁用迁移。
  • Django 测试运行器现在支持 [X34X] 选项来丢弃通过测试的输出。
  • DiscoverRunner 现在跳过对不是 被测试 引用的数据库运行系统检查。
  • TransactionTestCase 由于 :djadmin:`flush` 命令改进，现在在 MySQL 上的拆卸速度更快。 作为副作用，后者不再在拆卸时自动重置序列。 如果您的测试需要此功能，请启用 TransactionTestCase.reset_sequences。


网址

  • 路径转换器现在可以在to_url()中提升ValueError以在反转URL时指示不匹配。


公用事业


杂项

  • SQLite 后端现在支持 NAME 设置的 pathlib.Path。
  • :djadmin:`startproject` 命令生成的 settings.py 现在使用 pathlib.Path 而不是 os.path 来构建文件系统路径。
  • 这 ：设置：`TIME_ZONE ` 现在允许在支持时区的数据库上进行设置。


3.1 中向后不兼容的更改

数据库后端API

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

  • 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 参数作为传递给命令行客户端的额外参数列表。
  • DatabaseOperations.sql_flush() 的 sequences 位置参数被替换为布尔型关键字参数 reset_sequences。 如果True，截断表的序列将被重置。
  • DatabaseOperations.sql_flush() 的 allow_cascade 参数现在是仅关键字参数。
  • DatabaseOperations.execute_sql_flush() 的 using 位置参数被删除。 该方法现在使用被调用实例的数据库。
  • 第三方数据库后端必须实现对 JSONField 的支持或将 DatabaseFeatures.supports_json_field 设置为 False。 如果不支持存储图元，请将 DatabaseFeatures.supports_primitives_in_json_field 设置为 False。 如果 JSON 有真正的数据类型，请将 DatabaseFeatures.has_native_json_field 设置为 True。 如果不支持 [X3X]:lookup:`jsonfield.contains` 和 :lookup:`jsonfield.contained_by`，请将 DatabaseFeatures.supports_json_field_contains 设置为 False。
  • 第三方数据库后端必须对 JSONField 进行自省或将 can_introspect_json_field 设置为 False。


不再支持 MariaDB 10.1

MariaDB 10.1 的上游支持将于 2020 年 10 月结束。 Django 3.1 支持 MariaDB 10.2 及更高版本。


contrib.admin 浏览器支持

管理员不再支持旧版 Internet Explorer 浏览器。 有关支持的浏览器的详细信息，请参阅 管理常见问题解答 。


AbstractUser.first_name max_length increased to 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)

如果您希望在编辑用户时在 admin 中保留此限制，请设置 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)

杂项

  • :ttag:`cache` 使用并由 make_template_fragment_key() 生成的缓存键与旧版本 Django 生成的键不同。 升级到 Django 3.1 后，对任何先前缓存的模板片段的第一个请求将是缓存未命中。
  • 从 set_language() 视图返回重定向回退或 204 HTTP 响应的决定背后的逻辑现在基于 Accept HTTP 标头而不是 X-Requested-With HTTP标头存在。
  • 移除了django.db.models.query、django.db.models.sql和django.db.models.sql.datastructures中django.core.exceptions.EmptyResultSet的兼容性导入。
  • 移除了django.db.models.fields中django.core.exceptions.FieldDoesNotExist的兼容性导入。
  • 移除了 django.forms.forms 中 django.forms.utils.pretty_name() 和 django.forms.boundfield.BoundField 的兼容性导入。
  • 移除了django.template.base中Context、ContextPopException和RequestContext的兼容性导入。
  • 移除了django.contrib.admin中django.contrib.admin.helpers.ACTION_CHECKBOX_NAME的兼容性导入。
  • 设置为相对路径的 :setting:`STATIC_URL` 和 :setting:`MEDIA_URL` 设置现在以 SCRIPT_NAME（或 [ X163X] 如果未设置）。 此更改不应影响设置为有效 URL 或绝对路径的设置。
  • ConditionalGetMiddleware 不再将 ETag 标头添加到具有空 内容 的响应中。
  • django.utils.decorators.classproperty() 装饰器公开并移至 django.utils.functional.classproperty()。
  • :tfilter:`floatformat` 模板过滤器现在输出（正）0 用于舍入为零的负数。
  • Meta.ordering 和 Meta.unique_together 模型在 django.contrib 模块中的选项现在是列表。
  • 管理日历小部件现在根据开放组规范处理两位数的年份，即 69 到 99 之间的值映射到上一个世纪，0 到 68 之间的值映射到当前世纪。
  • 从 :setting:`DATETIME_INPUT_FORMATS` 的默认列表中删除了仅日期格式。
  • 当初始数据存在时，FileInput 小部件不再使用 required HTML 属性呈现。
  • 未记录的 django.views.debug.ExceptionReporterFilter 类被删除。 根据 自定义错误报告 文档，与 :setting:`DEFAULT_EXCEPTION_REPORTER_FILTER` 一起使用的类需要从 django.views.debug.SafeExceptionReporterFilter 继承。
  • cache_page() 装饰器设置的缓存超时现在优先于 Cache-Control 标头中的 max-age 指令。
  • 在 ForeignKey.to_field 参数中提供非本地远程字段现在会引发 FieldError。
  • :setting:`SECURE_REFERRER_POLICY` 现在默认为 'same-origin'。 有关更多详细信息，请参阅上面的 新增功能 安全部分 。
  • :djadmin:`check` 管理命令现在运行 database 系统只检查使用 check --database 选项指定的数据库别名。
  • :djadmin:`migrate` 管理命令现在运行 database 系统只检查要迁移的数据库。
  • 管理员 CSS 类 row1 和 row2 被移除，取而代之的是 :nth-child(odd) 和 :nth-child(even) 伪类。
  • make_password() 函数现在要求其参数为字符串或字节。 其他类型应显式转换为其中之一。
  • 删除了 AsKML 函数的未记录的 version 参数。
  • JSON 和 YAML 序列化程序 ，由 :djadmin:`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 类被删除。
  • 这 :ttag:`{% 本地化关闭 %} ` 标记和 :tfilter:`取消本地化` 过滤器不再尊重 ：设置：`DECIMAL_SEPARATOR` 环境。
  • asgiref的最低支持版本从3.2增加到3.2.10。
  • Media 类现在呈现没有 type 属性的 <script> 标签，以遵循 WHATWG 建议 。
  • ModelChoiceIterator，由 ModelChoiceField 和 ModelMultipleChoiceField 使用，现在产生包含 ModelChoiceIteratorValue 实例作为第一个 [X192X] 实例的 2 元组选择每个选择中的元素。 在大多数情况下，此代理是透明的，但如果您需要 field 值本身，请改用 ModelChoiceIteratorValue.value 属性。


3.1 中弃用的功能

PostgreSQL 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 中的转换。

新的 JSONFields、KeyTransform 和 KeyTextTransform 可用于所有支持的数据库后端。


杂项

  • PASSWORD_RESET_TIMEOUT_DAYS 设置已弃用 :setting:`PASSWORD_RESET_TIMEOUT`。

  • 不推荐使用 :lookup:`isnull` 查找与右侧的非布尔值的未记录用法，请改用 True 或 False。

  • 几乎没有记录的 django.db.models.query_utils.InvalidQuery 异常类已被弃用，取而代之的是 FieldDoesNotExist 和 FieldError。

  • django-admin.py 入口点已弃用，取而代之的是 django-admin。

  • HttpRequest.is_ajax() 方法已被弃用，因为它依赖于 jQuery 特定的方式来表示 AJAX 调用，而当前的用法倾向于使用 JavaScript Fetch API。 根据您的用例，您可以编写自己的 AJAX 检测方法，或者如果您的代码依赖于客户端 Accept HTTP 标头，则使用新的 HttpRequest.accepts() 方法。

    如果您正在编写自己的 AJAX 检测方法，则 request.is_ajax() 可以完全复制为 request.headers.get('x-requested-with') == 'XMLHttpRequest'。

  • 不推荐将 None 作为第一个参数传递给 django.utils.deprecation.MiddlewareMixin.__init__()。

  • CookieStorage 使用的 cookie 值的编码格式与旧版本 Django 生成的格式不同。 对旧格式的支持一直持续到 Django 4.0。

  • session 的编码格式与旧版本 Django 生成的格式不同。 对旧格式的支持一直持续到 Django 4.0。

  • Signal 的纯文档 providing_args 参数已弃用。 如果您依赖此参数作为文档，则可以将文本移至代码注释或文档字符串。

  • 不推荐不使用 length 参数调用 django.utils.crypto.get_random_string()。

  • ModelMultipleChoiceField 的 list 消息已弃用，取而代之的是 invalid_list。

  • 不推荐将原始列别名传递给 QuerySet.order_by()。 可以通过在 RawSQL 中预先传递别名来实现相同的结果。

  • NullBooleanField 模型字段已弃用，取而代之的是 BooleanField(null=True)。

  • django.conf.urls.url() 别名 django.urls.re_path() 已弃用。

  • 这{% ifequal %}和{% ifnotequal %}模板标签已被弃用 :ttag:`{% 如果 %} ` . {% if %}涵盖所有用例，但如果您需要继续使用这些标签，可以将它们从 Django 中提取到一个模块中，并作为内置标签包含在 '内置' 选项 ：设置：`选项 ` .

  • DEFAULT_HASHING_ALGORITHM 过渡设置已弃用。


3.1 中删除的功能

这些功能已达到弃用周期的终点，并在 Django 3.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 的支持。



取自“https://cainiaojiaocheng.com/index.php?title=Django/docs/3.1.x/releases/3.1&oldid=21520”
Powered by MediaWiki