Django 3.1发布说明

August 4, 2020

欢迎来到Django 3.1！

这些发行说明涵盖 new features ，以及一些 backwards incompatible changes 从Django 3.0或更早版本升级时您需要注意这一点。我们 dropped some features 已经到了弃用周期的末尾，我们已经 begun the deprecation process for some features 。

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

python兼容性

Django 3.1支持Python 3.6、3.7、3.8和3.9（自3.1.3起）。我们 highly recommend 并且仅官方支持每个系列的最新版本。

Django 3.1中的新功能

同步视图和中间件支持

Django现在支持完全同步的请求路径，包括：

要开始使用Deliverc视图，您需要使用 async def **

async def my_view(request):
    await asyncio.sleep(0.5)
    return HttpResponse("Hello, async world!")

无论您是在WSGI还是ASGI模式下运行，都支持所有同步功能。然而，在WSGI模式下使用Deliverc代码会带来性能损失。您可以在中阅读有关详细信息的更多信息 异步支持 文件。

您可以随心所欲地混合Inbox和同步视图、中间件和测试。Django将确保您始终获得正确的执行上下文。我们预计大多数项目将保持其大部分视图同步，并且只有少数几个以Inbox模式运行-但这完全是您的选择。

Django的ORM、缓存层和其他执行长期运行网络调用的代码片段还不支持Expressc访问。我们希望在即将推出的版本中添加对它们的支持。同步视图是理想的，但是，如果您在视图内执行大量API或HTTP调用，那么您现在可以本地并行执行所有这些HTTP调用，以大大加快视图的执行速度。

同步支持应该是完全向后兼容的，我们已经尝试确保它对您现有的同步代码没有速度回归。它应该对任何现有的Django项目没有明显影响。

JSONField适用于所有支持的数据库后台

Django现在包括 models.JSONField 和 forms.JSONField 可在所有支持的数据库后台使用。这两个字段都支持使用自定义的SON编码器和解码器。模型场支持内省， 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 。

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

次要特征

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。

  • select 2库从4.0.7版本升级到4.0.13。

django.contrib.auth

  • PBKDF 2密码哈希器的默认迭代计数从180，000增加到216，000。

  • 新的 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

django.contrib.gis

django.contrib.humanize

  • intword 模板过滤器现在支持负整数。

django.contrib.postgres

django.contrib.sessions

  • 这个 SESSION_COOKIE_SAMESITE 现在的设置允许 'None' （字符串）值显式声明cookie是与所有同站点和跨站点请求一起发送的。

django.contrib.staticfiles

隐藏物

CSRF

  • 这个 CSRF_COOKIE_SAMESITE 现在的设置允许 'None' （字符串）值显式声明cookie是与所有同站点和跨站点请求一起发送的。

电子邮件

错误报告

文件存储

  • FileSystemStorage.save() 方法现在支持 pathlib.Path 。

  • FileField 和 ImageField 现在接受呼叫 storage .这允许您在运行时修改使用的存储，例如为不同的环境选择不同的存储。

形式

国际化

  • 这个 LANGUAGE_COOKIE_SAMESITE 现在的设置允许 'None' （字符串）值显式声明cookie是与所有同站点和跨站点请求一起发送的。

  • 增加了对阿尔及利亚阿拉伯语、伊博语、吉尔吉斯语、塔吉克语和土库曼语的支持和翻译。

管理命令

  • 新的 check --database 选项允许指定数据库别名以运行 database 系统检查。以前，这些检查是针对所有配置的 DATABASES 通过使 database 标签到命令。

  • 新的 migrate --check 当检测到未应用的迁移时，选项会使命令以非零状态退出。

  • 新的 returncode 论据 CommandError 允许自定义管理命令的退出状态。

  • 新的 dbshell -- ARGUMENTS 选项允许将额外参数传递到数据库的命令行客户端。

  • 这个 flush 和 sqlflush 命令现在包括SQL来重置SQLite上的序列。

模型

  • 新的 ExtractIsoWeekDay 功能从ISO-8601工作日提取 DateField 和 DateTimeField ，以及新的 iso_week_day 查找允许按ISO-8601每周的一天进行查询。

  • QuerySet.explain() 现在支持：

    • TREE 格式为SQL 8.0.16+，

    • analyze SQL 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() 方法现在通过使用在SQL上生成更有效的SQL DELETE 而不是 TRUNCATE 不需要重置序列的表的陈述。

  • SQLite函数现在标记为 deterministic 在Python 3.8+上。这允许在检查约束和部分索引中使用它们。

  • 新的 UniqueConstraint.deferrable 属性允许创建可推迟的唯一约束。

分页

  • Paginator 现在可以迭代以产生其页面。

请求和响应

安防

模板

  • 重命名的 translate 和 blocktranslate 在模板代码中引入了模板标签以进行国际化。老 trans 和 blocktrans 模板标签别名继续有效，并将在可预见的未来保留。

  • 这个 include 模板标签现在接受模板名称的迭代。

测验

URLs

  • Path converters 现在可以筹集 ValueError 在……里面 to_url() 在反向URL时指示不匹配。

公用事业

其他

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 参数作为要传递给命令行客户端的额外参数列表。

  • 这个 sequences 的位置论据 DatabaseOperations.sql_flush() 被布尔仅关键字参数替换 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 .如果存在真正的SON数据类型，则设置 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的支持

对MariaDB 10.1的上游支持将于2020年10月结束。Django 3.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旧版本生成的密钥不同。升级到Django 3.1后，对任何之前缓存的模板片段的第一个请求都将是缓存未命中。

  • 返回重定向回退或来自 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 以前是二元组的模块现在是列表。

  • 管理日历小部件现在根据开放组规范处理两位数的年份，即69和99之间的值映射到上一个世纪，0和68之间的值映射到当前世纪。

  • 仅限日期格式将从默认列表中删除 DATETIME_INPUT_FORMATS 。

  • 这个 FileInput 小部件不再使用 required 初始数据存在时的HTML属性。

  • 未登记的人 django.views.debug.ExceptionReporterFilter 类被删除。按照 自定义错误报告 文档、要使用的类 DEFAULT_EXCEPTION_REPORTER_FILTER 需要继承 django.views.debug.SafeExceptionReporterFilter 。

  • 由设置的缓存超时 cache_page() 装饰师现在优先于 max-age 指令从该 Cache-Control 标题。

  • 提供非本地远程现场 ForeignKey.to_field 现在提出了争论 FieldError 。

  • SECURE_REFERRER_POLICY 现在默认为 'same-origin' 。请参阅 What's New 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 转换为SON序列化器，或 allow_unicode=False 到YML序列化器。

  • 自动加载器不再监视内置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 ，现在产生2-tuple选择，包含 ModelChoiceIteratorValue 作为第一个例子 value 每个选择中的元素。在大多数情况下，这是透明的代理，但如果您需要 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 。

新的 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() 该方法被废弃，因为它依赖于特定于jSYS的方式来表示AJax调用，而当前的使用倾向于使用JavaScript Fetch API .根据您的用例，您可以编写自己的AJax检测方法，也可以使用新的 HttpRequest.accepts() 如果您的代码取决于客户端，则使用方法 Accept HTTP标头。

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

  • 传球 None 作为第一个论点 django.utils.deprecation.MiddlewareMixin.__init__() 已弃用。

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

  • 会话的编码格式与Django旧版本生成的格式不同。对旧格式的支持将持续到Django 4.0。

  • 纯粹的文献记录 providing_args 论据 Signal 已被废弃。如果您依赖此参数作为文档，则可以将文本移动到代码注释或文档字符串。

  • 叫唤 django.utils.crypto.get_random_string() 无.class=‘class 3’> 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 过渡设置已弃用。

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 被移除。

« previous | up | next »