django3.1发行说明

2020年8月4日

欢迎使用django3.1！

这些发行说明涵盖了 new features 以及一些 backwards incompatible changes 当从django3.0或更早版本升级时，您需要注意。我们已经 dropped some features 已经到了他们的折旧周期结束，我们已经 begun the deprecation process for some features .

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

python兼容性

Django 3.1支持Python3.6、3.7、3.8和3.9(从3.1.3开始)。我们 强烈推荐 并且仅官方支持每个系列的最新版本。

新的Django 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项目产生明显的影响。

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

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

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上的序列。

模型

分页

  • Paginator 现在可以迭代生成它的页面。

请求和响应

安全性

模板

  • 重新命名的 translate 和 blocktranslate 模板标记是为了在模板代码中国际化而引入的。年长的 trans 和 blocktrans 模板标记别名继续工作，并将在可预见的将来保留。

  • 这个 include template标记现在接受iterable的模板名称。

测验

  • SimpleTestCase 现在实现 debug() 方法来允许在不收集结果和捕获异常的情况下运行测试。这可以用来支持在调试器下运行测试。

  • 新的 MIGRATE 测试数据库设置允许在创建测试数据库期间禁用迁移。

  • Django测试运行程序现在支持 test --buffer 用于放弃通过测试的输出的选项。

  • DiscoverRunner 现在跳过在数据库上运行系统检查 referenced by tests .

  • TransactionTestCase 在MySQL上，由于 flush 命令改进。作为一个副作用，后者不再自动重置序列的拆卸。启用 TransactionTestCase.reset_sequences 如果您的测试需要此功能。

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() 替换为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的支持

对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 改为属性。

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() 方法被弃用，因为它依赖于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 过渡设置已弃用。

3.1中删除的功能

这些特性已经到了其弃用周期的末尾，并在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 被移除。

« previous | up | next »