Django 1.11发行说明

2017年4月4日

欢迎来到Django 1.11!

这些发行说明涵盖了 new features 以及一些 backwards incompatible changes 从django 1.10或更旧版本升级时,您需要注意。我们已经 begun the deprecation process for some features .

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

Django 1.11被指定为 long-term support release . 它将在发布后至少三年内收到安全更新。对之前LTS(Django 1.8)的支持将于2018年4月结束。

python兼容性

Django1.11需要python 2.7、3.4、3.5、3.6或3.7(从1.11.17开始)。我们 强烈推荐 只有官方支持每个系列的最新版本。

django 1.11.x系列是最后一个支持python 2的系列。下一个主要版本django 2.0将只支持python 3.4+。

默认情况下,反预测警告不再响亮。

与旧版本的django不同,django自己的拒绝警告在默认情况下不再显示。这与Python的默认行为一致。

此更改允许第三方应用程序支持Django 1.11 LTS和Django 1.8 LTS,而无需添加代码以避免出现拒绝警告。

在Django2.0发布之后,我们建议第三方应用程序作者放弃对1.11之前所有版本的Django的支持。那时,您应该能够使用 python -Wd 这样就出现了反预测警告。在修复了拒绝警告之后,您的应用程序应该与Django 2.0兼容。

Django 1.11的新功能

基于类的模型索引

新的 django.db.models.indexes 模块包含易于创建数据库索引的类。使用将索引添加到模型 Meta.indexes 选择权。

这个 Index 类创建b树索引,就像您使用 db_index 在模型栏上或 index_together 在模型上 Meta 班级。它可以子类化以支持不同的索引类型,例如 GinIndex 。它还允许定义索引列的顺序(ASC/DESC)。

基于模板的小部件呈现

为了方便自定义小部件,表单小部件呈现现在使用模板系统而不是Python完成。见 窗体呈现API .

您可能需要调整为数不多的自定义小部件 backwards incompatible changes .

Subquery 表达

新的 SubqueryExists 数据库表达式允许创建显式子查询。子查询可以使用 OuterRef 类。

次要特征

django.contrib.admin

django.contrib.auth

  • pbkdf2密码散列器的默认迭代计数增加了20%。

  • 这个 LoginViewLogoutView 基于类的视图取代已弃用的 login()logout() 基于函数的视图。

  • 这个 PasswordChangeViewPasswordChangeDoneViewPasswordResetViewPasswordResetDoneViewPasswordResetConfirmViewPasswordResetCompleteView 基于类的视图取代已弃用的 password_change()password_change_done()password_reset()password_reset_done()password_reset_confirm()password_reset_complete() 基于函数的视图。

  • 新的 post_reset_login 的属性 PasswordResetConfirmView 允许在成功重置密码后自动登录用户。如果你有多个 AUTHENTICATION_BACKENDS 配置,使用 post_reset_login_backend 属性来选择要使用的属性。

  • 为了避免通过HTTP引用头泄漏密码重置令牌的可能性(例如,如果重置页包含对托管在其他域上的CSS或javascript的引用),请 PasswordResetConfirmView (但不是被否决的 password_reset_confirm() 基于函数的视图)将令牌存储在会话中,并将其重定向到自身,以便在URL中没有令牌的情况下向用户显示密码更改表单。

  • update_session_auth_hash() 现在旋转会话密钥以允许更改密码以使被盗会话cookie失效。

  • 新的 success_url_allowed_hosts 的属性 LoginViewLogoutView 允许指定一组在登录和注销后可以安全重定向的主机。

  • 添加了密码验证程序 help_textUserCreationForm .

  • 这个 HttpRequest 现在传递给 authenticate() 如果它接受一个 request 参数。

  • 这个 user_login_failed() 信号现在接收到 request 参数。

  • PasswordResetForm 支持自定义用户模型,该模型使用的电子邮件字段名不是 'email' . 集合 CustomUser.EMAIL_FIELD 字段的名称。

  • get_user_model() 现在可以在导入时调用,甚至在定义模型的模块中也可以调用。

django.contrib.contenttypes

  • 当在中检测到过时的内容类型时, remove_stale_contenttypes 命令,现在有一个相关对象列表,例如 auth.Permission 也将被删除。以前,只列出内容类型(此提示出现在 migrate 而不是在单独的命令中)。

django.contrib.gis

  • 新的 GEOSGeometry.from_gml()OGRGeometry.from_gml() 方法允许从GML创建几何图形。

  • 增加了对 dwithin 在空间上查找。

  • 这个 Area 函数, Distance 函数和距离查找现在可以在空间上使用大地坐标。

  • 基于Openlayers的表单小部件现在使用 OpenLayers.jshttps://cdnjs.cloudflare.com 哪个比旧的更适合生产使用 https://openlayers.org/ 来源。它们也被更新为使用Openlayers 3。

  • PostGIS迁移现在可以更改字段维度。

  • 增加了通过 sizeshapeoffset 创建时的参数 GDALRaster 物体。

  • 添加了对 IsValid 函数, MakeValid 函数,以及 isvalid 查找。

  • 增加了对Oracle的支持 AsGML 函数, BoundingCircle 函数, IsValid 函数,以及 isvalid 查找。

django.contrib.postgres

  • 新的 distinct 的参数 StringAgg 确定连接的值是否不同。

  • 新的 GinIndexBrinIndex 类允许创建 GINBRIN 数据库中的索引。

  • django.contrib.postgres.fields.JSONField 接受新的 encoder 参数指定自定义类来编码标准编码器不支持的数据类型。

  • 新的 CIText 混合和 CITextExtension 迁移操作允许使用PostgreSQL citext 不区分大小写查找的扩展。提供三个字段: CICharFieldCIEmailField ,以及 CITextField

  • 新的 JSONBAgg 允许将值聚合为JSON数组。

  • 这个 HStoreField (模型字段)和 HStoreField (窗体字段)允许存储空值。

隐藏物

  • memcached后端现在传递 OPTIONS 作为客户端构造函数的关键字参数,允许对客户端行为进行更高级的控制。见 cache arguments 示例文档。

  • memcached后端现在允许在 LOCATION 为了方便在环境变量中使用此类字符串的第三方服务。

CSRF

  • 增加了 CSRF_USE_SESSIONS 允许在用户会话而不是cookie中存储CSRF令牌的设置。

数据库后端

  • 增加了 skip_locked 参数 QuerySet.select_for_update() 在PostgreSQL 9.5+和Oracle上执行查询 FOR UPDATE SKIP LOCKED .

  • 增加了 TEST['TEMPLATE'] 允许PostgreSQL用户指定用于创建测试数据库的模板的设置。

  • QuerySet.iterator() 现在使用 server-side cursors 在PostgreSQL上。此功能将部分工作内存负载(用于保存查询结果)转移到数据库,并可能增加数据库内存使用量。

  • 添加了对 'isolation_level' 选择权 OPTIONS 允许指定 transaction isolation level . 为了避免可能的数据丢失,建议从mysql的默认级别repeatable read切换到read committed。

  • 为添加了支持 cx_Oracle 5.3。

电子邮件

  • 增加了 EMAIL_USE_LOCALTIME 设置为允许在本地时区而不是在UTC中发送SMTP日期头。

  • EmailMessage.attach()attach_file() 现在回到mime类型 application/octet-stream 当为指定了无法解码为utf-8的二进制内容时, text/* 附件。

文件存储

  • 把它包装起来 io.TextIOWrapperFile 现在有 readable()writable()seekable() 方法。

形式

国际化

管理命令

迁徙

  • 添加了对序列化的支持 uuid.UUID 对象。

模型

请求和响应

串行化

  • 新的 django.core.serializers.base.Serializer.stream_class 属性允许子类自定义默认流。

  • 编码器 JSON serializer 现在可以通过传递 cls 关键字参数 serializers.serialize() 功能。

  • DjangoJSONEncoder 现在序列化 timedelta 对象(由使用 DurationField

模板

  • mark_safe() 现在可以用作装饰。

  • 这个 Jinja2 模板后端现在通过设置 'context_processors' 选择权 OPTIONS .

  • 这个 regroup 标签现在返回 namedtuple 而不是字典,这样您可以直接在循环中解包Group对象,例如 {{% for grouper, list in regrouped %}} .

  • 增加了一个 resetcycle 模板标记以允许重置 cycle 模板标签。

  • 现在可以为特定目录指定特定目录 filesystem.Loader .

测验

验证器

1.11中的向后不兼容更改

django.contrib.gis

  • 简化代码库,因为它比 contrib.gis 第一次被释放, GDAL 现在是geodjango的必需依赖项。在旧版本中,它只需要用于sqlite。

  • contrib.gis.maps 被删除,因为它与一个退出版本的谷歌地图API接口,似乎是未维护。如果你在使用它, let us know .

  • 这个 GEOSGeometry 相等运算符现在还比较srid。

  • 基于Openlayers的表单小部件现在使用Openlayers 3,并且 gis/openlayers.htmlgis/openlayers-osm.html 模板已更新。如果您将这些小部件子类化或扩展模板,请检查您的项目。而且,新的小部件的工作方式与旧的小部件略有不同。不使用小部件中的工具栏,而是单击以绘制、单击并拖动以移动地图,然后单击并拖动点/顶点/角来移动地图。

  • 对小于4.0的空间碎片的支持被丢弃。

  • 放弃对gdal 1.7和1.8的支持。

  • 中的小部件 contrib.gis.forms.widgets 管理员的 OpenLayersWidget 使用 form rendering API 而不是 loader.render_to_string() . 如果您使用的是自定义小部件模板,则需要确保表单呈现器能够找到它。例如,您可以使用 TemplatesSetting 渲染器。

django.contrib.staticfiles

  • collectstatic 如果存在引用循环(例如, 'foo.css' 参考文献 'bar.css' 它本身引用了 'foo.css' )或者,如果引用其他文件的文件链太深,无法在多次传递中解析。在后一种情况下,使用 ManifestStaticFilesStorage.max_post_process_passes .

  • 使用时 ManifestStaticFilesStorage ,运行时清单中找不到静态文件,现在引发 ValueError 而不是返回一个不变的路径。您可以通过设置 ManifestStaticFilesStorage.manifest_strictFalse .

数据库后端API

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

  • 这个 DatabaseOperations.time_trunc_sql() 方法已添加到支持中 TimeField 截断。它接受一个 lookup_typefield_name 参数并返回相应的SQL以截断给定的时间字段 field_name 只有特定的时间对象。这个 lookup_type 参数可以是 'hour''minute''second' .

  • 这个 DatabaseOperations.datetime_cast_time_sql() 方法被添加以支持 time 查找。它接受一个 field_nametzname 参数,并返回将日期时间值强制转换为时间值所需的SQL。

  • 使能 FOR UPDATE SKIP LOCKED 支持,设置 DatabaseFeatures.has_select_for_update_skip_locked = True .

  • 新的 DatabaseFeatures.supports_index_column_ordering 属性指定数据库是否允许定义索引中列的顺序。默认值为 True 以及 DatabaseIntrospection.get_constraints() 方法应包括 'orders' 在返回的每个词典中键入 'ASC' 和/或 'DESC' 与索引中每列的顺序相对应的值。

  • inspectdb 不再调用 DatabaseIntrospection.get_indexes() 已弃用。自定义数据库后端应确保返回所有类型的索引 DatabaseIntrospection.get_constraints() .

  • 更名为 ignores_quoted_identifier_case 特点到 ignores_table_name_case 更准确地反映它是如何使用的。

  • 这个 name 关键字参数添加到 DatabaseWrapper.create_cursor(self, name=None) 方法允许在支持它的后端使用服务器端游标。

放弃对PostgreSQL 9.2和Postgis 2.0的支持

PostgreSQL 9.2的上游支持将于2017年9月结束。因此,Django1.11将PostgreSQL 9.3设置为其官方支持的最低版本。

对Postgis2.0的支持也被删除,因为PostgreSQL 9.2是支持它的最后一个版本。

此外,PSycopg2的最低支持版本从2.4.5增加到2.5.4。

LiveServerTestCase 绑定到端口零

与其选择一个端口范围并迭代以找到一个空闲端口, LiveServerTestCase 绑定到端口0并依赖操作系统分配可用端口。这个 DJANGO_LIVE_TEST_SERVER_ADDRESS 环境变量不再使用,而且由于它也不再使用,因此 manage.py test --liveserver 选项被删除。

如果你需要绑定 LiveServerTestCase 对于特定端口,使用 port 在django 1.11.2中添加的属性。

防止不安全重定向 django.contrib.authi18n 意见

LoginViewLogoutView (以及不推荐使用的基于函数的等价物),以及 set_language() 保护用户不被重定向到非HTTPS next 应用程序通过https运行时的URL。

QuerySet.get_or_create()update_or_create() 验证参数

为了防止打字错误安静地传递, get_or_create()update_or_create() 检查它们的参数是否为模型字段。这应该是向后不兼容的,只是事实上它可能会在您的项目中暴露一个bug。

pytz 是必需的依赖项和支持 settings.TIME_ZONE = None 被移除

为了简化Django的时区处理, pytz 现在是必需的依赖项。它与Django一起自动安装。

支持 settings.TIME_ZONE = None 由于该行为不常用且用处可疑,因此将其删除。如果要根据系统时区自动检测时区,可以使用 tzlocal **

from tzlocal import get_localzone

TIME_ZONE = get_localzone().zone

其工作原理类似于 settings.TIME_ZONE = None except that it also sets os.environ['TZ']. Let us know 如果有这样的用例,您发现无法调整代码来设置 TIME_ZONE

管理模板中的HTML更改

<p class="help"> 替换为 <div> 标记以允许在帮助文本中包含列表。

只读字段被包装在 <div class="readonly">...</div> 而不是 <p>...</p> 允许任何类型的HTML作为字段的内容。

由于引入了基于模板的小部件呈现而发生的更改

中的一些未记录类 django.forms.widgets 被移除:

  • SubWidget

  • RendererMixin, ChoiceFieldRenderer, RadioFieldRenderer, CheckboxFieldRenderer

  • ChoiceInput, RadioChoiceInput, CheckboxChoiceInput

无证件者 Select.render_option() 方法已删除。

这个 Widget.format_output() 方法已删除。而是使用自定义的小部件模板。

一些小部件值,例如 <select> 选项,现在本地化为 settings.USE_L10N=True . 您可以使用使用 localize 用于关闭本地化的模板标记。

django.template.backends.django.Template.render() 禁止非dict上下文

为了与多个模板引擎兼容, django.template.backends.django.Template.render() (从高级模板加载器API返回,例如 loader.get_template() )必须接收上下文词典,而不是 ContextRequestContext . 如果您要传递这两个类中的任何一个,请改为传递一个字典——这样做与Django的旧版本向后兼容。

迁移操作中的模型状态更改

为了提高应用迁移的速度,相关模型的呈现会延迟到需要它们的操作(例如 RunPython )如果您有一个自定义操作可用于 from_state 论点 database_forwards()database_backwards() ,必须使用 clear_delayed_apps_cache() 方法如中所述 writing your own migration operation .

PostgreSQL上的服务器端游标

要做的改变 QuerySet.iterator() 在PostgreSQL上使用服务器端游标可防止在事务池模式下使用PgBouncer运行Django。要实现这一点,请使用 DISABLE_SERVER_SIDE_CURSORS 设置(在Django 1.11.1中添加)在 DATABASES .

事务池和服务器端游标 更多讨论。

其他

  • 如果源中没有任何项具有 pubdateupdateddate 属性, SyndicationFeed.latest_post_date() 现在返回当前的UTC日期/时间,而不是没有时区信息的日期时间。

  • CSRF故障记录到 django.security.csrf 记录器而不是 django.request .

  • ALLOWED_HOSTS 运行测试时不再禁用验证。如果应用程序包含具有自定义主机名的测试,则必须在 ALLOWED_HOSTS . 见 测试和多个主机名 .

  • 使用外键的ID(例如 'field_id'ModelAdmin.list_display 显示相关对象的ID。删除 _id 如果要使用对象的字符串表示形式的旧行为,请使用后缀。

  • 在模型形式中, CharField 具有 null=True 现在保存 NULL 对于空值而不是空字符串。

  • 关于Oracle, Model.validate_unique() 不再检查空字符串的唯一性,因为数据库将值解释为 NULL .

  • 如果你是子类 AbstractUser 超驰 clean() ,一定要调用 super() . BaseUserManager.normalize_email() 在新的 AbstractUser.clean() 方法,以便在模型表单验证等情况下应用规范化。

  • EmailFieldURLField 不再接受 strip 关键字参数。删除它,因为它在旧版本的django中没有效果,因为这些字段总是去掉空白。

  • 这个 checkedselected 表单小部件呈现的属性现在使用HTML5布尔语法而不是XHTML checked='checked'selected='selected' .

  • RelatedManager.add()remove()clear()set() 现在清除 prefetch_related() 隐藏物。

  • 为了防止可能丢失保存的设置, setup_test_environment() 如果在调用前第二次调用,则现在引发异常 teardown_test_environment() .

  • 无证件者 DateTimeAwareJSONEncoder 别名 DjangoJSONEncoder (在Django 1.0中重命名)被删除。

  • 这个 cached template loader 如果 OPTIONS['loaders'] 未指定,并且 OPTIONS['debug']False (后一个选项默认为 DEBUG )这可能是向后不兼容的,如果你有一些 template tags that aren't thread safe .

  • 在运行 migrate 命令。使用新的 remove_stale_contenttypes 改为命令。

  • 管理员的小工具 IntegerField 使用 type="number" 而不是 type="text" .

  • 条件HTTP头现在按照 RFC 7232 条件请求规范而不是旧的 RFC 2616 .

  • patch_response_headers() 不再添加 Last-Modified 标题。根据 RFC 7234#section-4.2.2 ,此头与提供显式到期时间的其他缓存头(例如, ExpiresCache-Control . UpdateCacheMiddlewareadd_never_cache_headers() 调用 patch_response_headers() 因此也会受到这种变化的影响。

  • 在管理模板中, <p class="help"> 替换为 <div> 标记以允许在帮助文本中包含列表。

  • ConditionalGetMiddleware 不再设置 Date 标头,因为Web服务器设置该标头。它也不再设置 Content-Length 标头,因为这现在是由 CommonMiddleware

    如果有一个中间件修改响应的内容并出现在 CommonMiddlewareMIDDLEWAREMIDDLEWARE_CLASSES 设置,您必须重新排序中间件,以便在 Content-Length 设置,或让响应修改中间件重置 Content-Length 标题。

  • get_model()get_models() 现在提高 AppRegistryNotReady 如果在加载所有应用程序的模型之前调用它们。以前,它们只需要加载目标应用程序的模型,因此可以返回模型而不建立所有关系。如果你需要 get_model() 设置 require_ready 参数 False .

  • 未使用的 BaseCommand.can_import_settings 属性被删除。

  • 无证件者 django.utils.functional.lazy_property 被移除。

  • 为了与非多部分请求保持一致, MultiPartParser.parse() 现在叶子 request.POST 不变的如果你要修改的话 QueryDict ,您现在必须先复制它,例如 request.POST.copy() .

  • 支持 cx_Oracle <5.2被移除。

  • IPython<1.0的支架从 shell 命令。

  • 私有API的签名 Widget.build_attrs() 从改变 extra_attrs=None, **kwargsbase_attrs, extra_attrs=None .

  • 类文件对象(例如, StringIOBytesIO )上载到 ImageField 现在使用测试客户机需要 name 属性的值通过 validate_image_file_extension 验证器。见注释 Client.post() .

  • FileField 现在移动而不是复制它接收的文件。使用默认的文件上载设置,文件大于 FILE_UPLOAD_MAX_MEMORY_SIZE 现在具有与临时文件相同的权限(通常 0o600 )而不是系统的标准umask(通常 0o6644 )设置 FILE_UPLOAD_PERMISSIONS 如果您需要相同的权限,无论文件大小如何。

1.11中不推荐的功能

其他

  • contrib.authlogin()logout() 不赞成使用基于函数的视图,而赞成使用新的基于类的视图 LoginViewLogoutView .

  • 未使用的 extra_context 参数 contrib.auth.views.logout_then_login() 被贬低。

  • contrib.authpassword_change()password_change_done()password_reset()password_reset_done()password_reset_confirm()password_reset_complete() 不赞成使用基于函数的视图,而赞成使用新的基于类的视图 PasswordChangeViewPasswordChangeDoneViewPasswordResetViewPasswordResetDoneViewPasswordResetConfirmViewPasswordResetCompleteView .

  • django.test.runner.setup_databases() 被移到 django.test.utils.setup_databases() . 旧位置已弃用。

  • django.utils.translation.string_concat() 被否决,赞成 django.utils.text.format_lazy() . string_concat(*strings) 可替换为 format_lazy('{{}}' * len(strings), *strings) .

  • 对于 PyLibMCCache 缓存后端,通过 pylibmc 行为设置作为的顶级属性 OPTIONS 被贬低。把它们放在 behaviors 关键在 OPTIONS 相反。

  • 这个 host 参数 django.utils.http.is_safe_url() 为支持新的 allowed_hosts 参数。

  • 在呈现 {{% include %}} 模板标记已被弃用,因为该行为通常比帮助更容易混淆。在Django 2.1中,将引发异常。

  • DatabaseIntrospection.get_indexes() 被否决,赞成 DatabaseIntrospection.get_constraints() .

  • authenticate() 现在通过 request 论据 authenticate() 验证后端的方法。支持不接受的方法 request 因为第一个位置参数将在Django 2.1中删除。

  • 这个 USE_ETAGS 设置已弃用,取而代之的是 ConditionalGetMiddleware 现在又增加了 ETag 无论设置如何,都会返回响应的头。 CommonMiddlewaredjango.utils.cache.patch_response_headers() 当折旧结束时将不再设置etags。

  • Model._meta.has_auto_field 已弃用,以便检查if Model._meta.auto_field is not None .

  • 使用正则表达式组 iLmsu# 在里面 url() 被贬低。唯一有用的组是 (?i) 然而,对于不区分大小写的URL,不区分大小写的URL不是一个好的实践,因为它们为搜索引擎创建多个条目。另一种解决方案可能是创建一个 handler404 它在URL中查找大写字符,并重定向到等效的小写字母。

  • 这个 renderer 参数添加到 Widget.render() 方法。不接受该参数的方法将在折旧期内工作。