Django 2.1 发行说明 — Django 文档

Django 2.1 发行说明

2018 年 8 月 1 日

欢迎来到 Django 2.1！

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

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

Python兼容性

Django 2.1 支持 Python 3.5、3.6 和 3.7。 Django 2.0 是最后一个支持 Python 3.4 的版本。 我们【X3X】强烈推荐【X23X】，官方只支持各系列的最新版本。

Django 2.1 中的新功能

模型“查看”权限

“查看”权限被添加到模型 Meta.default_permissions。 运行 :djadmin:`migrate` 时将自动创建新权限。

这允许授予用户对管理员中模型的只读访问权限。 ModelAdmin.has_view_permission() 是新的。 该实现是向后兼容的，因为不需要分配“查看”权限来允许具有“更改”权限的用户编辑对象。

有几个 向后不兼容的考虑 。

小功能

django.contrib.admin

• ModelAdmin.search_fields 现在接受任何查找，例如 field__exact。
• jQuery 从 2.2.3 版本升级到 3.3.1。
• 新的 ModelAdmin.delete_queryset() 方法允许自定义“删除选定对象”操作的删除过程。
• 您现在可以 覆盖默认管理站点 。
• 新的 ModelAdmin.sortable_by 属性和 ModelAdmin.get_sortable_by() 方法允许限制可以在更改列表页面中排序的列。
• ModelAdmin.list_display 中元素的 admin_order_field 属性现在可能是一个查询表达式。
• 新的 ModelAdmin.get_deleted_objects() 方法允许自定义删除视图的删除过程和“删除选定”操作。
• actions.html、change_list_results.html、date_hierarchy.html、pagination.html、prepopulated_fields_js.html、search_form.html和submit_line.html模板现在可以 覆盖每个应用程序或每个模型 （除了全局覆盖）。
• 管理员更改列表和更改表单对象工具现在可以 覆盖每个应用程序、每个模型，或全局 与 change_list_object_tools.html 和 change_form_object_tools.html 模板。
• InlineModelAdmin.has_add_permission() 现在作为第二个位置参数传递父对象，obj。
• 管理员操作现在可以 指定权限 以限制它们对某些用户的可用性。

django.contrib.auth

• :djadmin:`createsuperuser` 现在提示允许绕过 :setting:`AUTH_PASSWORD_VALIDATORS` 检查。

django.contrib.gis

• 新的 GEOSGeometry.buffer_with_style() 方法是 buffer() 的一个版本，允许自定义缓冲区的样式。
• OpenLayersWidget 现在基于 OpenLayers 4.6.5（以前是 3.20.1）。

django.contrib.sessions

• 添加了 :setting:`SESSION_COOKIE_SAMESITE` 设置以在会话 cookie 上设置 SameSite cookie 标志。

缓存

• 本地内存缓存后端 现在使用最近最少使用 (LRU) 剔除策略而不是伪随机策略。
• 低级缓存API新的touch()方法更新缓存键的超时时间。

CSRF

• 添加了 :setting:`CSRF_COOKIE_SAMESITE` 设置以在 CSRF cookie 上设置 SameSite cookie 标志。

表格

• ImageField 的小部件现在使用 HTML 属性 accept="image/*" 呈现。

国际化

• 添加了 get_supported_language_variant() 函数。
• 地域语言变体的未翻译字符串现在使用通用语言的翻译。 例如，未翻译的 pt_BR 字符串使用 pt 翻译。

管理命令

• 新的 inspectdb --include-views 选项允许为数据库视图创建模型。
• BaseCommand 类现在使用自定义帮助格式化程序，因此 --verbosity 或 --settings 等标准选项出现在帮助输出的最后，为子类命令的选项提供了更突出的位置.

迁移

• 添加了对 functools.partialmethod 对象序列化的支持。
• 为了支持冻结环境，可以从 .pyc 文件加载迁移。

型号

• 模型现在可以使用 PEP 487 中的 __init_subclass__()。
• A BinaryField 现在可以设置为 editable=True 如果您希望将其包含在模型形式中。
• 添加了许多新的文本数据库函数：Chr、Left、LPad、LTrim、Ord、 重复、替换、右、RPad、RTrim和Trim[X212X]Trim
• 新的 TruncWeek 函数将 DateField 和 DateTimeField 截断为一周的星期一。
• 现在可以使用减号否定查询表达式。
• QuerySet.order_by() 和 distinct(*fields) 现在支持使用字段转换。
• BooleanField 现在可以是 null=True。 鼓励这样做而不是 NullBooleanField，后者可能在未来被弃用。
• 新的 QuerySet.explain() 方法显示查询集查询的数据库执行计划。
• QuerySet.raw() 现在支持 [X37X]prefetch_related()。

请求和响应

• 添加了 HttpRequest.get_full_path_info()。
• 将 samesite 参数添加到 HttpResponse.set_cookie() 以允许设置 SameSite cookie 标志。
• FileResponse 的新 as_attachment 参数设置 Content-Disposition 标头，使浏览器询问用户是否要下载文件。 FileResponse 还尝试在适当的地方设置 Content-Type 和 Content-Length 标头。

模板

• 新的 :tfilter:`json_script` 过滤器安全地将 Python 对象输出为 JSON，包装在 <script> 标签中，准备与 JavaScript 一起使用。

测试

• 添加了对 307 和 308 重定向的测试 Client 支持。
• 测试 Client 现在将请求数据字典序列化为 JSON if content_type='application/json'。 您可以使用测试客户端的 json_encoder 参数自定义 JSON 编码器。
• 新的 SimpleTestCase.assertWarnsMessage() 方法是 assertWarnsRegex() 的简单版本。

2.1 中向后不兼容的变化

数据库后端API

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

• 为了遵守 PEP 249，数据库不支持功能的例外情况从 NotImplementedError 更改为 django.db.NotSupportedError。
• 将 allow_sliced_subqueries 数据库功能标志重命名为 allow_sliced_subqueries_with_in。
• DatabaseOperations.distinct_sql() 现在需要一个额外的 params 参数并返回一个 SQL 和参数的元组，而不是一个 SQL 字符串。
• DatabaseFeatures.introspected_boolean_field_type 从方法变为属性。

django.contrib.gis

• 删除了对 SpatiaLite 4.0 的支持。

不再支持 MySQL 5.5

MySQL 5.5 上游支持的结束时间是 2018 年 12 月。 Django 2.1 支持 MySQL 5.6 及更高版本。

不再支持 PostgreSQL 9.3

对 PostgreSQL 9.3 的上游支持将于 2018 年 9 月结束。 Django 2.1 支持 PostgreSQL 9.4 及更高版本。

从默认 PASSWORD_HASHERS 设置中删除 BCryptPasswordHasher

如果您在 Django 1.4 或 1.5 中使用 bcrypt（在 Django 1.6 中添加 BCryptSHA256PasswordHasher 之前），您可能有一些使用 BCryptPasswordHasher 哈希器的密码。

您可以检查是否是这种情况：

from django.contrib.auth import get_user_model
User = get_user_model()
User.objects.filter(password__startswith='bcrypt$$')

如果你想继续允许使用这些密码，你必须定义 :setting:`PASSWORD_HASHERS` 设置（如果你还没有）并包括 'django.contrib.auth.hashers.BCryptPasswordHasher'。

移动 wrap_label 小部件模板上下文变量

为了修复在使用 RadioSelect 和 CheckboxSelectMultiple 和 MultiWidget 时缺少 <label>，wrap_label 上下文变量现在显示为每个的属性选项。 例如，在自定义 input_option.html 模板中，将 {% if wrap_label %} 更改为 {% if widget.wrap_label %}。

SameSite 饼干

用于 django.contrib.sessions、django.contrib.messages 和 Django 的 CSRF 保护的 cookie 现在默认将 SameSite 标志设置为 Lax。 尊重此标志的浏览器不会在跨域请求中发送这些 cookie。 如果您依赖旧行为，请将 :setting:`SESSION_COOKIE_SAMESITE` 和/或 :setting:`CSRF_COOKIE_SAMESITE` 设置为 None。

新模型“查看”权限的注意事项

自定义管理表单需要考虑只查看的情况

使用新的“查看”权限，当用户没有更改权限时，现有的自定义管理表单可能会引发错误，因为表单可能访问不存在的字段。 通过覆盖 ModelAdmin.get_form() 并检查用户是否具有“更改”权限并返回默认表单来解决此问题：

class MyAdmin(admin.ModelAdmin):
    def get_form(self, request, obj=None, **kwargs):
        if not self.has_change_permission(request, obj):
            return super().get_form(request, obj, **kwargs)
        return CustomForm

新的默认视图权限可能允许对管理视图进行不必要的访问

如果您拥有代号为 view_<modelname> 形式的自定义权限，管理员中的新查看权限处理将允许查看这些模型的更改列表和详细信息页面。 如果这是不需要的，您必须更改您的自定义权限代号。

杂项

• mysqlclient的最低支持版本从1.3.3增加到1.3.7。
• 删除了对 SQLite < 3.7.15 的支持。
• Set-Cookie 的 Expires 指令的日期格式已更改为遵循 RFC 7231#section-7.1.1.1 而不是 Netscape 的 cookie 标准。 删除了 Tue, 25-Dec-2018 22:26:13 GMT 等日期中出现的连字符。 除了不解析新格式的过时浏览器之外，这种更改应该只是装饰性的。
• allowed_hosts 现在是私有 API django.utils.http.is_safe_url() 的必需参数。
• SelectMultiple 小部件呈现的 multiple 属性现在使用 HTML5 布尔语法，而不是 XHTML 的 multiple="multiple"。
• 由表单小部件呈现的 HTML 不再包含空元素上的结束斜线，例如 <br>。 这在 XHTML 中是不兼容的，尽管一些小部件已经使用了 HTML5 的一些方面，例如布尔属性。
• SelectDateWidget的空选项的值从0变为空字符串，这主要可能需要在比较HTML的测试中做一些调整。
• User.has_usable_password() 和 is_password_usable() 函数不再返回 False 如果密码是 None 或空字符串，或者密码使用不在 :setting:`PASSWORD_HASHERS` 设置中的散列器。 这种未记录的行为是 Django 1.6 中的一个回归，并阻止使用此类密码的用户请求密码重置。 审核您的代码以确认您对这些 API 的使用不依赖于旧行为。
• 由于迁移现在是从 .pyc 文件加载的，如果您在 Python 2 和 Python 3 混合环境中工作，则可能需要删除它们。
• 使用 None 作为 JSONField 查找值现在匹配具有指定键和空值的对象，而不是没有键的对象。
• 管理 CSS 类 field-box 重命名为 fieldBox 以防止与赋予名为“box”的模型字段的类发生冲突。
• 由于管理员的 actions.html、change_list_results.html、date_hierarchy.html、pagination.html、prepopulated_fields_js.html、search_form.html 和 [ X92X] 模板现在可以按应用程序或模型覆盖，您可能需要使用为不同目的编写的名称重命名现有模板。
• QuerySet.raw() 现在像常规查询集一样缓存其结果。 如果您不想缓存，请使用 iterator()。
• 数据库路由器 allow_relation() 方法在更多情况下被调用。 编写不当的路由器可能需要相应地更新。
• 在运行管理命令之前不再停用翻译。 如果您的自定义命令需要停用翻译（例如，将未翻译的内容插入数据库），请使用新的 @no_translations 装饰器 。
• 管理命令不再允许 --settings 和 --pythonpath 参数的缩写形式。
• 私有 django.db.models.sql.constants.QUERY_TERMS 常量被删除。 Lookup Registration API 的 get_lookup() 和 get_lookups() 方法可能是合适的替代方法。 与 QUERY_TERMS 常量相比，它们允许您的代码也考虑已注册的任何自定义查找。
• 与 py-bcrypt 的兼容性被删除，因为它没有维护。 改用 bcrypt。

2.1 中已弃用的功能

杂项

• ForceRHR GIS 功能已弃用，取而代之的是新的 ForcePolygonCW 功能。
• django.utils.http.cookie_date() 被弃用，取而代之的是 http_date()，它遵循最新的 RFC 格式。
• {% load staticfiles %} 和 {% load admin_static %} 已弃用，取而代之的是 {% load static %}，它们的工作原理相同。
• django.contrib.staticfiles.templatetags.static() 已弃用，取而代之的是 django.templatetags.static.static()。
• Django 3.0 中将删除对不接受 obj 作为第二个位置参数的 InlineModelAdmin.has_add_permission() 方法的支持。

2.1 中删除的功能

这些功能已达到弃用周期的终点，并在 Django 2.1 中删除。 有关详细信息，包括如何删除这些功能的使用，请参阅 1.11 中弃用的功能。

• contrib.auth.views.login()、logout()、password_change()、password_change_done()、password_reset()、password_reset_done()、password_reset_confirm()和password_reset_complete() 被移除。
• contrib.auth.views.logout_then_login()的extra_context参数被移除。
• django.test.runner.setup_databases() 被移除。
• django.utils.translation.string_concat() 被移除。
• django.core.cache.backends.memcached.PyLibMCCache 不再支持将 pylibmc 行为设置作为 OPTIONS 的顶级属性传递。
• django.utils.http.is_safe_url()的host参数被移除。
• 删除了渲染 {% include %} 模板标记时引发的异常静音。
• DatabaseIntrospection.get_indexes() 被移除。
• authenticate() 认证后端方法需要 request 作为第一个位置参数。
• django.db.models.permalink() 装饰器被移除。
• USE_ETAGS 设置被删除。 CommonMiddleware 和 django.utils.cache.patch_response_headers() 不再设置 ETag。
• Model._meta.has_auto_field 属性被移除。
• url() 支持正则表达式组中的内联标志（(?i)、(?L)、(?m)、(?s) 和 [ X119X]) 被删除。
• 删除了对不带 renderer 参数的 Widget.render() 方法的支持。