- Django 1.7 版本发行说明
- Python 兼容性
- Django 1.7 的新特性包括:
- 模式迁移
- 应用加载重构
- Field 子类的新方法
- 从
Manager
中调用自定义的QuerySet
方法 - 在遍历反向关系时使用自定义管理器
- 新的系统检查框架
- 新的
Prefetch
对象用于高级的prefetch_related
操作。 - 管理快捷方式支持时区
- 使用数据库游标作为上下文管理器
- 自定义查找
- 改进了
Form
错误处理 - 次要特性
- django.contrib.admin
- django.contrib.auth
django.contrib.formtools
- django.contrib.gis
- django.contrib.messages
- django.contrib.redirects
- django.contrib.sessions
- django.contrib.sitemaps
- django.contrib.sites
- django.contrib.staticfiles
- django.contrib.syndication
- 缓存
- 跨站请求伪造(Cross Site Request Forgery,CSRF)
- 电子邮件
- 文件存储
- 文件上传
- 表单
- 国际化
- 管理命令
- 模型
- 信号
- 模板
- 请求和响应
- 测试
- 实用程序
- 验证器
- 1.7 版中向后不兼容的变化
allow_syncdb
/allow_migrate
- initial_data
deconstruct()
和可序列化性- 应用加载的变化
- 管理命令和 INSTALLED_APPS 的顺序
ValidationError
构造函数和内部存储- 关于
LocMemCache
对 pickle 错误的行为 - 现在缓存键从请求的绝对 URL 生成
- 将
None
传递给Manager.db_manager()
- 可能需要使用
pytz
- 关于相关管理器的
remove()
和clear()
方法 - 管理员登录重定向策略
select_for_update()
需要在事务中使用- Contrib 中间件从默认的
MIDDLEWARE_CLASSES
中移除 - 杂项
- 在 1.7 中被废弃的功能
django.core.cache.get_cache
django.utils.dictconfig
/django.utils.importlib
django.utils.module_loading.import_by_path
django.utils.tzinfo
django.utils.unittest
django.utils.datastructures.SortedDict
- 自定义模型包的 SQL 位置
django.contrib.sites
的重新组织ModelAdmin
上的declared_fieldsets
属性django.contrib.contenttypes
的重新组织syncdb
util
模块已重命名为utils
- 在
ModelAdmin
上的get_formsets
方法 IPAddressField
BaseMemcachedCache._get_memcache_timeout
方法- 自然键序列化选项
- 将
POST
和GET
参数合并到WSGIRequest.REQUEST
中 django.utils.datastructures.MergeDict
类- 语言代码
zh-cn
、zh-tw
和fy-nl
django.utils.functional.memoize
函数- 地理网站地图
- 将可调用参数传递给查询集方法
ADMIN_FOR
设置SplitDateTimeWidget
与DateTimeField
validate
django.core.management.BaseCommand
ModelAdmin
验证器django.db.backends.DatabaseValidation.validate_field
- 从
future
库加载ssi
和url
模板标签 django.utils.text.javascript_quote
fix_ampersands
工具方法和模板过滤器- 数据库测试设置的重新组织
- FastCGI 支持
contrib.sites
中的对象已移动django.forms.forms.get_declared_fields()
- 私有查询查找 API
- 在 1.7 版本中移除的功能
Django 1.7 版本发行说明
2014 年 9 月 2 日
欢迎使用 Django 1.7 !
这些发布说明涵盖了 新功能,以及在从 Django 1.6 或更旧版本升级时需要注意的一些 不兼容的变更。我们已经 开始了一些功能的弃用过程,并且一些功能已经完成了其弃用过程,已经 被移除。
Python 兼容性
Django 1.7 需要 Python 2.7、3.2、3.3 或 3.4。我们 强烈建议 并且只官方支持每个系列的最新版本。
Django 1.6 系列是最后一个支持 Python 2.6 的版本。 Django 1.7 是第一个支持 Python 3.4 的版本。
这个改变应该只影响少数 Django 用户,因为大多数操作系统供应商现在都将 Python 2.7 或更新版本作为默认版本发布。然而,如果您仍在使用 Python 2.6,那么您需要继续使用 Django 1.6,直到您可以升级您的 Python 版本。根据我们的支持政策,Django 1.6 将继续获得安全支持,直到 Django 1.8 发布为止。
Django 1.7 的新特性包括:
模式迁移
Django 现在内置了对模式迁移的支持。它允许通过创建迁移文件来更新、修改和删除模型,这些迁移文件代表了模型的变更,可以在任何开发、暂存或生产数据库上运行。
迁移在 自己的文档中 中有详细的介绍,但其中一些关键特性包括:
syncdb
已经被弃用,被migrate
取代。不用担心 - 对syncdb
的调用仍然会像以前一样工作。新的
makemigrations
命令提供了一种自动检测模型更改并为其创建迁移的简便方法。django.db.models.signals.pre_syncdb
和django.db.models.signals.post_syncdb
已经被弃用,分别由 pre_migrate 和 post_migrate 取代。这些新信号具有稍微不同的参数。请查阅文档以获取详细信息。数据库路由器上的
allow_syncdb
方法现在被称为allow_migrate
,但仍然执行相同的功能。具有allow_syncdb
方法的路由器仍然可以工作,但该方法名称已被弃用,您应尽快更改它(只需要重命名即可)。不再为具有迁移的应用程序加载
initial_data
fixture;如果您想为应用程序加载初始数据,建议您为应用程序创建一个迁移,并在迁移的operations
部分中定义一个 RunPython 或 RunSQL 操作。对于具有迁移的应用程序,测试回滚行为会有所不同;特别是,Django 不再在非事务性数据库上或
TransactionTestCase
内模拟回滚,除非明确请求(除非明确请求)。不建议没有迁移的应用程序依赖于(具有 ForeignKey 或 ManyToManyField 的)具有迁移的应用程序。
应用加载重构
在过去,Django 应用与模型紧密耦合。一个名为 “应用缓存” 的单例处理已安装的应用和模型。许多 API 中使用模型模块作为应用的标识符。
随着 Django 应用程序 概念的成熟,这段代码显示出了一些不足之处。它已经被重构为一个 “应用程序注册表”,在这里模型模块不再起到核心作用,同时可以将配置数据附加到应用程序。
迄今为止的改进包括:
- 应用程序可以在启动时运行代码,在 Django 执行任何其他操作之前,使用其配置的 ready() 方法。
- 即使在
models.py
之外定义模型,应用程序标签也会被正确地分配给模型。您不再需要显式设置 app_label。 - 如果一个应用程序没有任何模型,完全可以省略
models.py
。 - 可以使用应用程序配置的 label 属性重新标记应用程序,以解决标签冲突。
- 可以使用应用程序配置的 verbose_name 来自定义在管理员界面中的应用程序名称。
- 管理员界面在 Django 启动时会自动调用 autodiscover()。因此,您可以从您的 URL 配置中删除这行代码。
- Django 在启动时通过一种确定性且简单的过程导入所有应用程序配置和模型。这将使诊断导入问题(如导入循环)变得更容易。
Field 子类的新方法
为了支持模式迁移并使未来版本的 Django 更容易添加复合键,Field API 现在有一个新的必需方法:deconstruct()
。
该方法不接受任何参数,并返回一个包含四个元素的元组:
name
:字段在其父模型上的属性名称,如果它不是模型的一部分,则为None
。path
:字段类的点分隔的 Python 路径,包括类名。args
:作为列表的位置参数。kwargs
:作为字典的关键字参数。
这四个值允许将任何字段序列化到文件中,并且允许字段进行安全复制,这是这些新功能的重要组成部分。
这个变化不会影响您,除非您编写自定义的 Field 子类;如果您这样做,如果您的子类以任何方式更改了 __init__
的方法签名,您可能需要重新实现 deconstruct()
方法。如果您的字段只是继承自内置的 Django 字段,并且没有重写 __init__
,则无需进行任何更改。
如果您确实需要重写 deconstruct()
,一个好的起点是内置的 Django 字段(django/db/models/fields/__init__.py
),因为其中一些字段,包括 DecimalField
和 DateField
,已经重写了它,并展示了如何在超类上调用该方法,只需添加或删除额外的参数。
这也意味着字段的所有参数本身必须是可序列化的;要了解我们认为什么是可序列化的,以及如何使您自己的类可序列化,请阅读 迁移序列化文档。
从 Manager
中调用自定义的 QuerySet
方法
历史上,制作可重用的模型查询的推荐方法是在自定义 Manager
类上创建方法。这种方法的问题在于,在第一次方法调用之后,您会得到一个 QuerySet
实例,无法调用其他自定义的管理器方法。
尽管没有记录,但通常可以通过创建自定义的 QuerySet
来解决这个问题,以便可以链接自定义方法;但是这个解决方案有很多缺点:
- 自定义的
QuerySet
和其自定义方法在第一次调用values()
或values_list()
后就丢失了。 - 仍然需要编写自定义的
Manager
来返回自定义的QuerySet
类,并且所有希望在Manager
上使用的方法都必须被代理到QuerySet
上。整个过程违反了 DRY 原则。
现在可以直接使用 QuerySet.as_manager() 类方法来 创建具有 QuerySet 方法的 Manager:
class FoodQuerySet(models.QuerySet):
def pizzas(self):
return self.filter(kind="pizza")
def vegetarian(self):
return self.filter(vegetarian=True)
class Food(models.Model):
kind = models.CharField(max_length=50)
vegetarian = models.BooleanField(default=False)
objects = FoodQuerySet.as_manager()
Food.objects.pizzas().vegetarian()
在遍历反向关系时使用自定义管理器
现在可以在遍历反向关系时 指定自定义的管理器:
class Blog(models.Model):
pass
class Entry(models.Model):
blog = models.ForeignKey(Blog)
objects = models.Manager() # Default Manager
entries = EntryManager() # Custom Manager
b = Blog.objects.get(id=1)
b.entry_set(manager="entries").all()
新的系统检查框架
我们新增了一个新的 系统检查框架,用于检测常见问题(比如无效的模型)并提供解决这些问题的提示。这个框架是可扩展的,因此您可以为自己的应用程序和库添加自定义检查。
要执行系统检查,您可以使用 check 管理命令。这个命令替代了旧的 validate
管理命令。
新的 Prefetch
对象用于高级的 prefetch_related
操作。
新的 Prefetch 对象允许自定义预取操作。
您可以指定用于遍历特定关系的 QuerySet
,或者自定义预取结果的存储位置。
这使得可以过滤预取的关系、从预取的关系中调用 select_related(),或者多次使用不同的查询集预取相同的关系。有关更多详细信息,请参阅 prefetch_related()。
管理快捷方式支持时区
在管理员中日期和时间输入小部件旁边的 “today” 和 “now” 快捷方式现在在 当前时区 中运行。以前,它们使用浏览器的时区,这可能导致在时区不匹配服务器的当前时区时保存错误的值。
此外,小部件现在在浏览器和服务器时区不同时显示帮助信息,以明确解释字段中插入的值将如何被解释。
使用数据库游标作为上下文管理器
在 Python 2.7 之前,数据库游标可以用作上下文管理器。具体的后端游标定义了上下文管理器的行为。但是,Python 2.7 改变了魔术方法查找的行为,游标不再能用作上下文管理器。
Django 1.7 允许将游标用作上下文管理器。也就是说,可以使用以下方式:
with connection.cursor() as c:
c.execute(...)
替换成:
c = connection.cursor()
try:
c.execute(...)
finally:
c.close()
自定义查找
现在可以为 ORM 编写自定义查找和转换。自定义查找与 Django 内置的查找(例如 lte
、icontains
)类似,而转换是一个新概念。
django.db.models.Lookup 类提供了一种为模型字段添加查找运算符的方式。例如,可以为 DateFields
添加 day_lte
运算符。
django.db.models.Transform 类允许在最终查找之前对数据库值进行转换。例如,可以编写一个 year
转换,从字段的值中提取年份。转换允许进行链式操作。在将 year
转换添加到 DateField
后,可以对转换后的值进行筛选,例如 qs.filter(author__birthdate__year__lte=1981)
。
有关自定义查找和转换的更多信息,请参阅 自定义查找 文档。
改进了 Form
错误处理
Form.add_error()
以前在处理表单错误方面有两种主要模式:
- 在某些函数(例如
Field.clean()
、Form.clean_<fieldname>()
或Form.clean()
用于非字段错误的情况)中引发 ValidationError。 - 在
Form.clean()
中针对特定字段或在“clean”方法之外(例如直接从视图中)添加错误时,会涉及到Form._errors
。
使用前一种模式是直接的,因为表单可以根据上下文(即引发异常的方法)猜测错误的归属,并自动处理它们。这仍然是可能时添加错误的规范方式。然而,后一种模式很繁琐且容易出错,因为处理边缘情况的负担落在用户身上。
新的 add_error() 方法允许在任何地方将错误添加到特定的表单字段,无需担心诸如创建 django.forms.utils.ErrorList
实例或处理 Form.cleaned_data
等细节。这个新的 API 取代了操作 Form._errors
,后者现在变成了一个私有的 API。
请参阅 使用 Form.add_error() 进行字段验证,以获取使用 Form.add_error()
的示例。
错误元数据
ValidationError 构造函数接受元数据,如错误 code
或 params
,然后可以将其插入到错误消息中(有关更多详细信息,请参阅 引发 ValidationError);然而,在 Django 1.7 之前,这些元数据在错误添加到 Form.errors 后立即被丢弃。
Form.errors 和 django.forms.utils.ErrorList
现在存储了 ValidationError
实例,因此可以通过新的 Form.errors.as_data 方法在任何时候检索这些元数据。
检索到的 ValidationError
实例可以通过其错误 code
进行标识,从而可以进行诸如重写错误消息或在特定错误存在时编写视图中的自定义逻辑等操作。它还可以用于以自定义格式(例如 XML)序列化错误。
新的 Form.errors.as_json() 方法是一个方便的方法,它返回以 JSON 格式序列化的错误消息以及错误代码。as_json()
使用了 as_data()
,并展示了如何扩展新系统的思路。
错误容器和向后兼容性
为了支持上述功能,需要对各种错误容器进行重大更改,特别是 Form.errors、django.forms.utils.ErrorList
和 ValidationError 的内部存储。这些容器曾经存储错误字符串,现在存储 ValidationError
实例,并且公共 API 已经进行了适应,使这些更改尽可能透明,但如果您曾经使用过私有 API,一些更改可能不兼容向后;有关更多详细信息,请参阅 ValidationError 构造函数和内部存储。
次要特性
django.contrib.admin
- 现在可以在自定义的 AdminSite 上实现 site_header、site_title 和 index_title 属性,以便轻松更改管理站点的页面标题和页眉文本。不再需要覆盖模板!
- 在 django.contrib.admin 中的按钮现在使用
border-radius
CSS 属性来实现圆角,而不再使用 GIF 背景图像。 - 一些管理模板现在在其
<body>
标签中具有app-<app_name>
和model-<model_name>
类,以允许按应用程序或模型自定义 CSS 样式。 - 管理员变更列表单元格现在在 HTML 中具有
field-<field_name>
类,以启用样式自定义。 - 现在可以通过新的 django.contrib.admin.ModelAdmin.get_search_fields() 方法,按请求自定义管理员的搜索字段。
- 可以重写 ModelAdmin.get_fields() 方法来自定义 ModelAdmin.fields 的值。
- 除了现有的
admin.site.register
语法之外,您还可以使用新的 register() 装饰器来注册一个 ModelAdmin。 - 您可以指定 ModelAdmin.list_display_links
= None
来禁用更改列表页面网格上的链接。 - 现在可以指定 ModelAdmin.view_on_site 来控制是否显示 “在站点上查看” 链接。
- 您可以通过在
admin_order_field
值前面加上连字符来指定 ModelAdmin.list_display 值的降序排序。 - 可以重写 ModelAdmin.get_changeform_initial_data() 方法来定义设置更改表单初始数据的自定义行为。
django.contrib.auth
- 传递给 email_user() 的任何
**kwargs
都会传递给底层的 send_mail() 调用。 - permission_required() 装饰器可以接受一组权限,而不仅仅是单个权限。
- 您可以重写新的 AuthenticationForm.confirm_login_allowed() 方法,以更轻松地自定义登录策略。
django.contrib.auth.views.password_reset()
接受一个可选的html_email_template_name
参数,用于发送包含 HTML 的多部分电子邮件以进行密码重置。- 添加了 AbstractBaseUser.get_session_auth_hash() 方法,如果您的 AUTH_USER_MODEL 继承自 AbstractBaseUser,那么现在在启用了
django.contrib.auth.middleware.SessionAuthenticationMiddleware
的情况下,更改用户密码会使旧的会话失效。有关更多详细信息,请参阅 密码更改时的会话失效。
django.contrib.formtools
- 对
WizardView.done()
的调用现在包括一个form_dict
,以便更容易按步骤名称访问表单。
django.contrib.gis
- 默认包含在小部件中的 OpenLayers 库版本已从 2.11 更新为 2.13 。
- 如果安装了 GEOS 3.3 或更高版本,预处理的几何图形现在还支持
crosses
、disjoint
、overlaps
、touches
和within
谓词。
django.contrib.messages
- 使用 Cookie 的 django.contrib.messages 后端现在将遵循 SESSION_COOKIE_SECURE 和 SESSION_COOKIE_HTTPONLY 设置。
- 消息上下文处理器 现在会添加一个名为
DEFAULT_MESSAGE_LEVELS
的默认级别字典。 - Message 对象现在具有一个
level_tag
属性,其中包含消息级别的字符串表示。
django.contrib.redirects
- RedirectFallbackMiddleware 具有两个新属性 (response_gone_class 和 response_redirect_class),用于指定中间件返回的 HttpResponse 实例的类型。
django.contrib.sessions
"django.contrib.sessions.backends.cached_db"
会话后端现在尊重 SESSION_CACHE_ALIAS。在之前的版本中,它总是使用default
缓存。
django.contrib.sitemaps
- sitemap framework 现在使用 lastmod 来设置响应中的
Last-Modified
标头。这使得 ConditionalGetMiddleware 可以处理对设置了lastmod
的站点地图的条件GET
请求。
django.contrib.sites
- 新的 django.contrib.sites.middleware.CurrentSiteMiddleware 允许在每个请求上设置当前站点。
django.contrib.staticfiles
可以通过子类化 静态文件存储类 来覆盖收集的静态文件和目录的权限,方法是设置 file_permissions_mode 和 directory_permissions_mode 参数。请参阅 collectstatic 以查看示例用法。
CachedStaticFilesStorage
后端有一个名为 ManifestStaticFilesStorage 的兄弟类,它根本不使用缓存系统,而是使用一个名为staticfiles.json
的 JSON 文件来存储原始文件名(例如css/styles.css
)和散列文件名(例如css/styles.55e7cbb9ba48.css
)之间的映射关系。当运行 collectstatic 管理命令时,会创建staticfiles.json
文件,对于 Amazon S3 等远程存储来说,这应该是一个更经济的替代方案。有关更多信息,请参阅 ManifestStaticFilesStorage 文档。
findstatic 现在接受详细程度为 2 的 verbosity 标志,这意味着它将显示搜索的目录的相对路径。请参阅 findstatic 以查看示例输出。
django.contrib.syndication
- Atom1Feed 辅助工具中的
updated
元素现在使用updateddate
而不是pubdate
,允许在 feed 中包含published
元素(该元素依赖于pubdate
)。
缓存
- 现在可以通过 django.core.cache.caches 访问在 CACHES 中配置的缓存。这个类似字典的对象为每个线程提供一个不同的实例。它取代了已被弃用的
django.core.cache.get_cache()
。 - 如果直接实例化缓存后端,请注意它们不再是线程安全的,因为 django.core.cache.caches 现在为每个线程提供不同的实例。
- 将 CACHES 设置的 TIMEOUT 参数定义为
None
将默认将缓存键设置为 “永不过期”。以前,只能将timeout=None
传递给缓存后端的set()
方法。
跨站请求伪造(Cross Site Request Forgery,CSRF)
- CSRF_COOKIE_AGE 设置方便了使用基于会话的 CSRF Cookie。
电子邮件
- send_mail() 现在接受一个
html_message
参数,用于发送多部分 text/plain 和 text/html 的电子邮件。 - SMTP EmailBackend 现在接受一个
timeout
参数。
文件存储
- 在 Windows 上,文件锁定以前依赖于 PyWin32 软件包;如果未安装该软件包,则文件锁定会默默失败。现在已经移除了这个依赖项,文件锁定在 Windows 和 Unix 上都使用本地实现。
文件上传
- 新的 UploadedFile.content_type_extra 属性包含在文件上传的
content-type
标头中传递的额外参数。 - 新的 FILE_UPLOAD_DIRECTORY_PERMISSIONS 设置控制在文件上传期间创建的目录的文件系统权限,就像 FILE_UPLOAD_PERMISSIONS 一样控制文件本身的权限。
- FileField.upload_to 属性现在是可选的。如果省略或给定
None
或空字符串,将不会使用子目录来存储上传的文件。 - 上传的文件现在在响应交付给客户端之前明确关闭。只要在上传处理程序中的名称为
file
,部分上传的文件也会被关闭。 - Storage.get_available_name() 现在追加一个下划线加上一个随机的 7 个字符的字母数字字符串(例如,
"_x3a1gho"
),而不是通过一个下划线后跟一个数字(例如,"_1"
,"_2"
等)来进行迭代,以防止拒绝服务攻击。这个更改也在 1.6.6、1.5.9 和 1.4.14 安全发布版中进行了更改。
表单
- RadioSelect 和 CheckboxSelectMultiple 渲染的单选按钮或复选框的
<label>
和<input>
标签现在分别包括for
和id
属性。每个单选按钮或复选框都包括一个id_for_label
属性以输出元素的 ID。 - Textarea 渲染的
<textarea>
标签现在如果 TextField 模型字段有max_length
,则会包括一个maxlength
属性。 - Field.choices 现在允许您通过包含一个空字符串或
None
的元组作为键以及自定义标签作为值来自定义 “空选项” 标签。在这种情况下,默认的空选项"----------"
将被省略。 - MultiValueField 允许通过将
require_all_fields
参数设置为False
来添加可选子字段。将尊重每个单独字段的required
属性,并且当任何必填字段为空时,将引发新的incomplete
验证错误。 - 表单上的 clean() 方法不再需要返回
self.cleaned_data
。如果它返回一个已更改的字典,那么仍将使用该字典。 - 在 Django 1.6 中的一个临时回归之后,现在可以再次使 TypedChoiceField 的
coerce
方法返回任意值。 - SelectDateWidget.months 可以用于自定义在选择小部件中显示的月份的措辞。
- 添加了
min_num
和validate_min
参数到 formset_factory(),以允许验证提交的表单的最小数量。 Form
和ModelForm
使用的元类已经重新设计,以支持更多的继承情况。以前的限制,阻止同时继承Form
和ModelForm
已经被移除,只要ModelForm
在方法解析顺序 (MRO) 中首先出现。- 现在可以通过将字段的名称设置为
None
来在子类中从Form
中删除字段。 - 现在可以自定义
ModelForm
中的unique
、unique_for_date
和unique_together
约束的错误消息。为了支持unique_together
或任何其他NON_FIELD_ERROR
,ModelForm
现在会查找ModelForm
内部Meta
类的error_messages
字典中的NON_FIELD_ERROR
键。有关更多详细信息,请参阅 关于模型的 error_messages 的考虑。
国际化
- django.middleware.locale.LocaleMiddleware.response_redirect_class 属性允许您自定义中间件发出的重定向。
- LocaleMiddleware 现在将用户选择的语言存储在会话键
_language
中。这应该只使用LANGUAGE_SESSION_KEY
常量来访问。以前它存储在键django_language
中,而LANGUAGE_SESSION_KEY
常量不存在,但为 Django 保留的键应该以下划线开头。为了向后兼容,在 1.7 中仍然从django_language
读取。随着写入,会话将迁移到新的键。 - blocktrans 标签现在支持一个
trimmed
选项。此选项将从{% blocktrans %}
标签的内容的开头和结尾删除换行符,替换每行开头和结尾的任何空白,并使用空格字符将所有行合并为一行,以分隔它们。这对于缩进{% blocktrans %}
标签的内容非常有用,而不会使缩进字符出现在.po
文件中相应的条目中,从而使翻译过程更加容易。 - 当你在项目的根目录运行 makemessages 时,任何提取出来的字符串现在将自动分发到正确的应用程序或项目消息文件中。详细信息请参见 本地化:如何创建语言文件。
- makemessages 命令现在总是会将
--previous
命令行标志添加到msgmerge
命令中,以保留先前翻译的模糊字符串在.po
文件中。 - 引入了以下用于调整语言 cookie 选项的设置:LANGUAGE_COOKIE_AGE、LANGUAGE_COOKIE_DOMAIN 和 LANGUAGE_COOKIE_PATH。
- 添加了用于 Esperanto 的 本地格式化。
管理命令
新的 --no-color 选项用于
django-admin
,用于禁用管理命令输出的颜色标记。新的 dumpdata —natural-foreign 和 dumpdata —natural-primary 选项,以及
serializers.serialize()
的新参数use_natural_foreign_keys
和use_natural_primary_keys
允许在序列化时使用自然主键。不再需要为 createcachetable 命令提供缓存表名或
--database
选项。Django 会从你的设置文件中获取这些信息。如果你配置了多个缓存或多个数据库,所有缓存表都会被创建。runserver 命令进行了一些改进:
- 在 Linux 系统上,如果安装了 pyinotify,开发服务器将在文件更改时立即重新加载。以前,它每秒轮询文件系统以检测更改,这会导致重新加载前有一小段延迟,并降低笔记本电脑的电池寿命。
- 此外,当翻译文件更新后,即在运行 compilemessages 后,开发服务器会自动重新加载。
- 所有 HTTP 请求都会记录到控制台,包括以前被过滤掉的用于静态文件或
favicon.ico
的请求。
如果安装并激活了第三方工具 ANSICON,Windows 下的管理命令现在可以生成带有语法着色的输出。
collectstatic 命令现在在 Windows NT 6 (Windows Vista 及更新版本) 上支持符号链接选项。
如果安装了 sqlparse Python 库,初始 SQL 数据现在将更好地工作。
请注意,它已被弃用,推荐使用迁移的 RunSQL 操作,这样可以受益于改进后的行为。
模型
- 新增了 QuerySet.update_or_create() 方法。
- 新的 default_permissions 模型
Meta
选项允许你自定义(或禁用)默认添加、修改和删除权限的创建。 - 现在在抽象类中可以显式使用 OneToOneField 用于 多表继承。
- 现在可以通过将 OneToOneField 的 related_name 设置为
'+'
或以'+'
结尾来避免创建反向关系。 - F 表达式 支持幂运算符(
**
)。 - 由
ForeignKey
和GenericForeignKey
创建的关联管理器的remove()
和clear()
方法现在接受bulk
关键字参数,用于控制是否批量执行操作(即使用QuerySet.update()
)。默认为True
。 - 现在可以将
None
用作 iexact 查找的查询值。 - 现在在定义
ForeignKey
或ManyToManyField
时,可以将可调用对象作为属性 limit_choices_to 的值传递。 - 在 QuerySet.values() 的结果上调用 only() 和 defer() 现在会引发错误(之前会导致数据库错误或不正确的数据)。
- 在指定单一字段集合时,可以使用单一列表而不是列表的列表来设置 index_together。
- 现在允许自定义中间模型具有多个外键与参与多对多关系的任何模型相关联,前提是你通过设置新的 ManyToManyField.through_fields 参数来明确指定应该使用哪些外键。
- 现在,将模型实例分配给非关联字段将会抛出错误。之前,如果字段接受整数作为输入并将其作为主键,这样的操作是有效的。
- 整数字段现在会根据它们的 internal_type 验证数据库后端特定的最小值和最大值。以前,模型字段的验证不会阻止保存超出其关联列数据类型范围的值,从而导致完整性错误。
- 现在可以通过使用关联字段的属性名称来显式 order_by() 一个关系的
_id
字段。
信号
- 在 setting_changed 信号中添加了
enter
参数。 - 现在可以使用
'app_label.ModelName'
形式的str
来连接模型信号,就像相关字段一样,以惰性引用它们的发送者。
模板
- Context.push() 方法现在返回一个上下文管理器,在退出
with
语句时会自动调用 pop()。此外,push() 现在接受参数,这些参数将传递给用于构建新上下文级别的dict
构造函数。 - 新的 Context.flatten() 方法将一个
Context
的堆栈返回为一个扁平的字典。 Context
对象现在可以进行相等性比较(内部使用 Context.flatten() 进行比较,因此只要它们的扁平化版本相同,每个Context
的堆栈的内部结构就不重要)。- widthratio 模板标签现在接受一个
"as"
参数,以将结果存储在一个变量中。 - include 模板标签现在还接受任何具有
render()
方法的对象(例如Template
)作为参数。字符串参数将如常使用 get_template() 进行查找。 - 现在可以递归地使用 include 模板。
- 当
TEMPLATE_DEBUG
为True
时,模板对象现在具有一个设置的 origin 属性。这允许在django.template
基础结构之外检查和记录模板的来源。 - 在模板渲染过程中引发的
TypeError
异常不再被消除声音。 - 以下函数现在接受一个
dirs
参数,这是一个列表或元组,用于覆盖TEMPLATE_DIRS
:- django.template.loader.get_template()
- django.template.loader.select_template()
- django.shortcuts.render()
django.shortcuts.render_to_response()
- time 过滤器现在接受与时区相关的 格式说明符
'e'
,'O'
,'T'
和'Z'
,并且能够处理 时区感知的datetime
实例,执行预期的渲染。 - cache 标签现在会尝试使用名为 “template_fragments” 的缓存(如果存在),否则会回退使用默认缓存。它还现在接受一个可选的
using
关键字参数,以控制使用哪个缓存。 - 新的 truncatechars_html 过滤器根据指定的字符数截断字符串,考虑到 HTML。
请求和响应
- 新的 HttpRequest.scheme 属性指定请求的协议(通常是
http
或https
)。 - 快捷方式 redirect() 现在支持相对 URL。
- JsonResponse 是 HttpResponse 的一个子类,它可以轻松创建 JSON 编码的响应。
测试
- DiscoverRunner 新增了两个属性,test_suite 和 test_runner,它们有助于重写测试的收集和运行方式。
- assertRedirects() 添加了
fetch_redirect_response
参数。由于测试客户端无法获取外部 URL,这使您可以在不属于您的 Django 应用程序的重定向上使用assertRedirects
。 - 在 assertRedirects() 中进行比较时,现在可以正确处理协议。
- Client 的所有请求方法现在都添加了
secure
参数。如果设置为True
,请求将通过 HTTPS 发送。 - 如果断言失败,assertNumQueries() 现在会打印出已执行查询的列表。
- 由测试处理程序生成的
WSGIRequest
实例现在附加到 django.test.Response.wsgi_request 属性。 - 测试的数据库设置已经收集到一个名为 TEST 的字典中。
实用程序
- 提高了 strip_tags() 的准确性(但如文档中所述,它仍然不能保证产生 HTML 安全的结果)。
验证器
- RegexValidator 现在接受可选的 flags 和布尔型 inverse_match 参数。inverse_match 属性确定在正则表达式模式匹配(
True
)或不匹配(默认为False
)提供的value
时是否引发 ValidationError。flags 属性设置编译正则表达式字符串时使用的标志。 - URLValidator 现在接受一个可选的
schemes
参数,允许自定义接受的 URI 方案(而不是默认的http(s)
和ftp(s)
)。 - validate_email() 现在接受包含 IPv6 字面量的地址,例如
example@[2001:db8::1]
,如 RFC 5321 中规定。
1.7 版中向后不兼容的变化
警告
除了本节中概述的更改之外,确保查看任何已删除功能的 废弃计划。如果您在给定功能的废弃时间段内未更新您的代码,其删除可能会被视为向后不兼容的更改。
allow_syncdb
/ allow_migrate
尽管 Django 仍然会查看 allow_syncdb
方法,尽管它们应该重命名为 allow_migrate
,但传递给这些方法的模型有一些微妙的区别。
对于具有迁移的应用程序,allow_migrate
现在将传递 历史模型,这些模型是特殊的带有自定义属性、方法或管理器的版本模型。确保您的 allow_migrate
方法只引用了 model._meta
中的字段或其他项。
initial_data
具有迁移的应用程序在完成迁移后将不再加载 initial_data
修复程序。没有迁移的应用程序将在模拟旧的 syncdb
行为的 migrate
阶段继续加载这些修复程序,但任何新的应用程序将不再支持这一功能。
相反,我们鼓励您在需要时在迁移中加载初始数据(使用 RunPython
操作和您的模型类);这有一个附加优势,即每次更改模式时都不需要更新初始数据。
另外,就像 Django 的旧 syncdb
代码一样,initial_data
也已经开始了弃用路径,并将在 Django 1.9 中移除。
deconstruct()
和可序列化性
Django 现在要求所有 Field 类及其构造函数参数都必须可序列化。如果你以任何方式修改了自定义 Field 的构造函数签名,你需要实现一个 deconstruct()
方法;我们已经在自定义字段文档中扩展了 关于实现这个方法的说明。
所有字段参数需要是可 序列化的 要求意味着任何传递到 Field 构造函数中的自定义类实例,比如自定义的 Storage 子类,都需要在它们上面定义一个 deconstruct 方法,尽管 Django 提供了一个方便的类装饰器,对大多数应用都适用。
应用加载的变化
启动序列
Django 1.7 在启动时会立即加载应用程序配置和模型。虽然这种行为更为直接,被认为更加健壮,但不能完全排除回归问题。有关您可能遇到的一些问题的解决方案,请参阅 错误调试。
独一无二的脚本
如果你在一个普通的 Python 脚本中使用 Django,而不是管理命令,并且依赖于 DJANGO_SETTINGS_MODULE 环境变量,现在你必须在脚本开头显式地初始化 Django,如下所示:
>>> import django
>>> django.setup()
否则,你将遇到一个 AppRegistryNotReady
异常。
WSGI 脚本
在 Django 1.3 之前,创建一个 WSGI 应用程序的推荐方法是:
import django.core.handlers.wsgi
application = django.core.handlers.wsgi.WSGIHandler()
在 Django 1.4 中,对 WSGI 的支持得到改进,并且 API 发生了变化:
from django.core.wsgi import get_wsgi_application
application = get_wsgi_application()
如果你的 WSGI 脚本仍在使用前一种风格,你需要升级到后一种风格,否则你将遇到一个 AppRegistryNotReady
异常。
应用程序注册表的一致性
不再允许安装具有相同标签的多个应用程序。在 Django 的早期版本中,这种情况不总是正常工作,但也不会完全崩溃。
如果你有两个具有相同标签的应用程序,你应该为其中一个创建一个 AppConfig,并在其中覆盖其 label。然后,你应该在引用该应用程序或其模型的任何代码中,将旧标签调整为新标签。
不再允许通过不同路径两次导入同一模型。从 Django 1.6 开始,只有在手动将一个目录和一个子目录放在 PYTHONPATH 上时,才会发生这种情况。有关迁移说明,请参阅 1.4 发布说明中的新项目布局部分。
您应该确保:
- 所有模型都在列在 INSTALLED_APPS 中或具有明确 app_label 的应用程序中定义。
- 模型不会作为加载其应用程序的副作用而导入。具体而言,您不应该在应用程序的根模块或定义其配置类的模块中导入模型。
从版本 1.9 开始,Django 将强制执行这些要求,经过一段废弃期之后。
继承 AppCommand 类
AppCommand 的子类现在必须实现 handle_app_config() 方法,而不是 handle_app()
。这个方法接收一个 AppConfig 实例,而不是一个模型模块。
检查应用程序信息
由于 INSTALLED_APPS 现在支持应用程序配置类,而不仅仅是应用程序模块,因此你应该检查直接访问此设置的代码,并改为使用应用程序注册表 (django.apps.apps)。
应用程序注册表保留了一些旧的应用程序缓存的特性。尽管应用程序缓存是一个私有 API,但过时的方法和参数将通过标准的废弃路径逐步移除,但以下变更将立即生效:
- 当找不到模型时,
get_model
现在会引发 LookupError,而不是返回None
。 get_model
和get_models
的only_installed
参数不再存在,get_model
的seed_cache
参数也不再存在。
管理命令和 INSTALLED_APPS 的顺序
当多个应用程序提供具有相同名称的管理命令时,Django 会从 INSTALLED_APPS 中排在前面的应用程序加载命令。之前的版本会从排在最后的应用程序加载命令。
这将管理命令的发现与 Django 的其他部分保持一致,这些部分依赖于 INSTALLED_APPS 的顺序,比如静态文件、模板和翻译。
ValidationError
构造函数和内部存储
当 ValidationError
构造函数接收到错误容器作为参数时(例如,一个 list
或一个 ErrorList
),其行为已经发生了变化:
- 它会在将字符串添加到其内部存储之前,将其转换为
ValidationError
的实例。 - 它不会存储给定的容器,而是将其内容复制到自己的内部存储中;以前容器本身被添加到
ValidationError
实例并用作内部存储。
这意味着如果你访问 ValidationError
的内部存储,比如 error_list
、error_dict
或 update_error_dict()
的返回值,你可能会在以前找到字符串的地方找到 ValidationError
的实例。
此外,如果你直接将 update_error_dict()
的返回值赋给 Form._errors
,你可能会无意中添加 list
实例,而期望的是 ErrorList
实例。这是一个问题,因为与简单的 list
不同,ErrorList
知道如何处理 ValidationError
的实例。
现在,大多数需要使用这些私有 API 的用例都可以使用新引入的 Form.add_error() 方法来处理:
# Old pattern:
try:
...
except ValidationError as e:
self._errors = e.update_error_dict(self._errors)
# New pattern:
try:
...
except ValidationError as e:
self.add_error(None, e)
如果你需要同时兼容 Django <= 1.6 和 1.7,由于在 Django 1.7 之前没有提供 Form.add_error() 方法,你可以使用以下解决方法将任何 list
转换为 ErrorList
:
try:
...
except ValidationError as e:
self._errors = e.update_error_dict(self._errors)
# Additional code to ensure ``ErrorDict`` is exclusively
# composed of ``ErrorList`` instances.
for field, error_list in self._errors.items():
if not isinstance(error_list, self.error_class):
self._errors[field] = self.error_class(error_list)
关于 LocMemCache
对 pickle 错误的行为
在以前的 Django 版本中存在一个不一致之处,关于不同缓存后端如何处理 pickle 错误。django.core.cache.backends.locmem.LocMemCache
以前在发生这种错误时会静默失败,这与其他后端不一致,并导致了与缓存相关的错误。在 Django 1.7 中已经修复了这个问题,详情请参阅 #21200。
现在缓存键从请求的绝对 URL 生成
在以前的 Django 版本中,缓存键是使用请求的路径和查询字符串生成的,但不包括 scheme 和 host。如果一个 Django 应用程序服务多个子域或域名,缓存键可能会发生冲突。在 Django 1.7 中,缓存键会根据请求的绝对 URL 包括 scheme、host、path 和查询字符串而变化。例如,缓存键的 URL 部分现在是从 https://www.example.com/path/to/?key=val
生成的,而不是 /path/to/?key=val
。Django 1.7 生成的缓存键将与旧版本的 Django 生成的键不同。升级到 Django 1.7 后,对任何以前缓存的 URL 的第一个请求将导致缓存未命中。
将 None
传递给 Manager.db_manager()
在以前的 Django 版本中,可以在模型管理器实例上使用 db_manager(using=None)
来获取一个使用默认路由行为的管理器实例,覆盖任何手动指定的数据库路由。在 Django 1.7 中,传递给 db_manager 的值为 None
将产生一个保留任何手动分配的数据库路由的路由器 — 管理器将 不 被重置。这是为了解决路由信息在连接中级联的方式存在的不一致性。详情请参阅 #13724。
可能需要使用 pytz
如果你的项目处理 1970 年之前或 2037 年之后的日期时间,并且当 Django 遇到它们时引发 ValueError,那么你将需要安装 pytz。如果你使用了 Django 的时区相关的日期格式或 django.contrib.syndication,可能会受到这个问题的影响。
关于相关管理器的 remove()
和 clear()
方法
ForeignKey
、GenericForeignKey
和 ManyToManyField
创建的相关管理器的 remove()
和 clear()
方法存在一些问题。一些操作在没有包装在事务中的情况下运行多个数据修改查询,而一些操作在存在默认过滤条件时(即当相关模型上的默认管理器实现了自定义的 get_queryset()
时)不会尊重默认过滤条件。
修复这些问题引入了一些向后不兼容的更改:
ForeignKey
相关管理器的默认remove()
实现从一系列的Model.save()
调用更改为单个QuerySet.update()
调用。这个改变意味着不再发送pre_save
和post_save
信号。你可以使用bulk=False
关键字参数来恢复到以前的行为。GenericForeignKey
相关管理器的remove()
和clear()
方法现在执行批量删除。不再在每个实例上调用Model.delete()
方法。你可以使用bulk=False
关键字参数来恢复到以前的行为。- 与
ManyToManyField
相关的管理器的remove()
和clear()
方法在涉及到过滤时执行嵌套查询,这可能会根据你的数据库和数据本身是否成问题而有所不同。有关更多详情,请参阅 此说明。
管理员登录重定向策略
在历史上,Django 管理站点会将未经授权或未经身份验证的用户的请求直接传递给登录视图,而不进行 HTTP 重定向。在 Django 1.7 中,这种行为发生了变化,以符合更传统的工作流程,其中任何未经授权的请求到管理页面都会被重定向(通过 HTTP 状态码 302)到登录页面,其中 next
参数设置为引用的路径。用户在成功登录后将被重定向到那里。
还请注意,管理员登录表单已更新,不再包含无用的 this_is_the_login_form
字段,而且 ValidationError
代码已设置为更常规的 invalid_login
键。
select_for_update()
需要在事务中使用
在历史上,使用 select_for_update() 的查询可以在自动提交模式下,在事务之外执行。在 Django 1.6 之前,Django 的自动事务模式允许使用这种方式锁定记录,直到下一次写操作。Django 1.6 引入了数据库级别的自动提交;自那时起,在这种上下文中执行将取消 select_for_update()
的效果。因此,现在假定这是一个错误并引发异常。
这个更改是因为这样的错误可能是由包含一个期望全局事务的应用程序(例如:ATOMIC_REQUESTS 设置为 True
)或者 Django 的旧的自动提交行为,在一个不需要它们的项目中运行时引起的;而且,这样的错误可能会表现为数据损坏的问题。这个更改也是在 Django 1.6.3 中进行的。
如果您在测试类中使用 select_for_update()
并且该测试类是 TransactionTestCase 的子类而不是 TestCase,则此更改可能导致测试失败。
Contrib 中间件从默认的 MIDDLEWARE_CLASSES
中移除
应用加载重构 弃用了使用不在 INSTALLED_APPS 设置中的应用程序中的模型。这暴露出默认的 INSTALLED_APPS 和全局默认值(django.conf.global_settings
)中的 MIDDLEWARE_CLASSES
之间的不兼容性。为了使这些设置保持同步,并且在使用最小设置测试可重用应用程序等情况下防止弃用警告,从默认设置中移除了 SessionMiddleware、AuthenticationMiddleware 和 MessageMiddleware。这些类仍然会包含在由 startproject 生成的默认设置中。大多数项目不会受到这个更改的影响,但如果你之前没有在项目设置中声明 MIDDLEWARE_CLASSES
并依赖于全局默认值,你应该确保新的默认值符合你的项目需求。你还应该检查任何访问 django.conf.global_settings.MIDDLEWARE_CLASSES
的代码。
杂项
django.core.files.uploadhandler.FileUploadHandler.new_file() 方法现在传递了一个额外的
content_type_extra
参数。如果你有一个自定义的 FileUploadHandler,实现了new_file()
方法,请确保它接受这个新参数。ModelFormSet 在调用
save(commit=False)
时不再删除实例。请查看 can_delete 以获取如何手动从删除的表单中删除对象的说明。加载空的 fixture 现在会发出一个
RuntimeWarning
,而不是引发 CommandError。当 DEBUG 为
False
时,django.contrib.staticfiles.views.serve() 现在会引发一个 Http404 异常,而不是 ImproperlyConfigured。这个更改消除了将视图有条件地添加到根 URLconf 的需要,从而使其能够通过名称安全地反转。它还消除了访问者通过请求不存在或尚未收集的静态文件而生成虚假的 HTTP 500 错误的能力。django.db.models.Model.__eq__() 方法现在以一种新的方式定义,其中代理模型的实例和其基模型的实例在主键匹配时被视为相等。以前,只有完全相同类的实例在主键匹配时被视为相等。
django.db.models.Model.__eq__() 方法已更改,因此两个没有主键值的
Model
实例不会被视为相等(除非它们是同一个实例)。当在没有主键值的实例上调用 django.db.models.Model.__hash__() 方法时,现在会引发
TypeError
。这是为了避免在容器中使用可变的__hash__
值。在 SQLite 数据库中,AutoField 列现在将使用
AUTOINCREMENT
选项创建,以确保单调递增。这将导致 SQLite 上的主键编号行为发生变化,与大多数其他 SQL 数据库保持一致。这仅适用于新创建的表。如果你有一个使用较早版本的 Django 创建的数据库,你需要迁移它以利用这个功能。例如,你可以执行以下操作:django.contrib.auth.models.AbstractUser
不再定义 get_absolute_url() 方法。旧的定义返回"/users/%s/" % urlquote(self.username)
,这是任意的,因为应用程序可以或不可以在urlpatterns
中定义这样的 URL。在你自己的自定义用户对象上定义一个get_absolute_url()
方法,或者如果你想要一个用户的 URL,可以使用 ABSOLUTE_URL_OVERRIDES。django.test.LiveServerTestCase 类的静态资源服务功能已经简化:现在它只能在运行测试时服务于已经存在于 STATIC_ROOT 中的内容。像在开发时使用 DEBUG = True 那样透明地提供所有静态资源的能力已经移动到一个新的类中,该类位于
staticfiles
应用程序中(实际负责此功能的应用程序):django.contrib.staticfiles.testing.StaticLiveServerTestCase。换句话说,LiveServerTestCase
本身的功能减弱了,但同时也减少了魔法。这样做的原因是将非 contrib 代码与 contrib 应用程序的依赖关系移除。
旧的缓存 URI 语法(例如
"locmem://"
)不再受支持。尽管它之前可以工作,但它并没有被记录或正式支持。如果你仍在使用它,请更新到当前的 CACHES 语法。在继承情况下,
Form
字段的默认排序方式已更改为遵循正常的 Python MRO。现在,字段是通过反向迭代 MRO 来发现的,最顶层的类最后被考虑。这只会在你同时在当前类和父类Form
中定义字段并且依赖于默认字段顺序时影响你。SelectDateWidget 的
required
参数已被移除。这个小部件现在会像其他小部件一样尊重表单字段的is_required
属性。Widget.is_hidden
现在是一个只读属性,通过检查input_type == 'hidden'
的存在来获取其值。select_related() 现在与其他类似的调用(如
prefetch_related
)以相同的方式链式调用。也就是说,select_related('foo', 'bar')
等同于select_related('foo').select_related('bar')
。以前,后者等同于select_related('bar')
。GeoDjango 不再支持 GEOS < 3.1 。
数据库后端的
init_connection_state
方法现在在自动提交模式下执行(除非你将 AUTOCOMMIT 设置为False
)。如果你维护一个自定义数据库后端,你应该检查这个方法。django.db.backends.BaseDatabaseFeatures.allows_primary_key_0
属性已重命名为allows_auto_pk_0
,以更好地描述它。对于所有包含在 Django 中的数据库后端,除了 MySQL,它都为True
,因为 MySQL 允许主键值为 0。它只禁止具有值 0 的 autoincrement 主键。禁止在子模型中定义与父模型中已定义的字段同名的字段,因为这会导致模型行为的歧义。此外,在模型继承层次结构中发生字段冲突将导致系统检查错误。例如,如果使用多继承,你需要在父模型中定义自定义主键字段,否则默认的
id
字段将发生冲突。有关详细信息,请参阅 多重继承。django.utils.translation.parse_accept_lang_header()
现在返回小写的区域设置,而不是提供的大小写。由于区域设置应该被视为不区分大小写,这使得我们能够加速区域设置的检测。django.utils.translation.get_language_from_path()
和django.utils.translation.trans_real.get_supported_language_variant()
现在不再接受supported
参数。django.contrib.contenttypes.views
中的shortcut
视图现在支持协议相对 URL(例如//example.com
)。GenericRelation 现在支持一个可选的
related_query_name
参数。设置related_query_name
可以在相关对象和内容类型之间添加关系,用于过滤、排序和其他查询操作。在 PostgreSQL 上运行测试时,USER 将需要对内置的
postgres
数据库进行读取访问权限。这是替代了以前连接到实际非测试数据库的行为。作为 系统检查框架 的一部分,字段、模型和模型管理器 都实现了一个已在检查框架中注册的
check()
方法。如果你已经在其中一个对象上有一个名为check()
的现有方法,你需要将其重命名。如上述 “缓存” 部分所提到的,将 CACHES 设置的 TIMEOUT 参数定义为
None
将设置缓存键为 “不过期”。以前,对于 memcache 后端,TIMEOUT 为0
会设置不过期的键,但这与set("key", "value", timeout=0)
的设置和过期(即不缓存)行为不一致。如果你想要不过期的键,请更新你的设置,将0
改为None
,因为后者现在在设置中也表示设置和过期。sql*
管理命令现在尊重 DATABASE_ROUTERS 的allow_migrate()
方法。如果你的模型与非默认数据库同步,请使用--database
标志来获取这些模型的 SQL(以前它们总是包含在输出中)。解码 URL 中的查询字符串现在在输入不是有效的 UTF-8 时会回退到 ISO-8859-1 编码。
通过将
django.contrib.auth.middleware.SessionAuthenticationMiddleware
添加到默认项目模板(仅适用于 1.7.2 之前的版本),在使用 runserver 访问页面之前必须创建一个数据库。将
schemes
参数添加到URLValidator
中可能会在你之前使用自定义正则表达式来验证 schemes 的情况下出现向后不兼容的更改。如果 schemes 中没有列出的任何 scheme 将失败验证,即使正则表达式匹配给定的 URL。
在 1.7 中被废弃的功能
django.core.cache.get_cache
django.core.cache.get_cache
已被 django.core.cache.caches 取代。
django.utils.dictconfig
/django.utils.importlib
django.utils.dictconfig
和 django.utils.importlib
分别是在 Python 版本 2.7 之前提供的 logging.config 和 importlib 的副本。它们已经被弃用。
django.utils.module_loading.import_by_path
当前的 django.utils.module_loading.import_by_path
函数捕获 AttributeError
、ImportError
和 ValueError
异常,并重新引发 ImproperlyConfigured 异常。这种异常掩盖使得诊断循环导入问题变得不必要地困难,因为它让问题看起来像是来自 Django 内部。它已被弃用,推荐使用 import_string()。
django.utils.tzinfo
django.utils.tzinfo
提供了两个 tzinfo 的子类,分别是 LocalTimezone
和 FixedOffset
。它们已经被弃用,推荐使用更正确的替代方案,由 django.utils.timezone 提供的 django.utils.timezone.get_default_timezone() 和 django.utils.timezone.get_fixed_timezone()。
django.utils.unittest
django.utils.unittest
在所有 Python 版本上提供了对 unittest2
库的统一访问。由于 unittest2
在 Python 2.7 中成为标准库的 unittest 模块,并且 Django 1.7 不再支持旧的 Python 版本,因此该模块不再有用。它已被弃用,请改用 unittest。
django.utils.datastructures.SortedDict
由于 Python 2.7 中已经添加了 OrderedDict 到标准库中,因此不再需要 SortedDict
,它已经被弃用。
SortedDict
提供的两个额外且已弃用的方法(insert()
和 value_for_index()
)已被移除。如果您曾依赖这些方法来更改类似表单字段的结构,现在应将这些 OrderedDict
视为不可变对象,并重写它们以更改其内容。
例如,您可能希望覆盖 MyFormClass.base_fields
(尽管该属性不被视为公共 API)以更改所有 MyFormClass
实例的字段顺序;或者类似地,您可以在 MyFormClass.__init__()
中从内部覆盖 self.fields
,以更改特定表单实例的字段。例如(来自 Django 自身):
PasswordChangeForm.base_fields = OrderedDict(
(k, PasswordChangeForm.base_fields[k])
for k in ["old_password", "new_password1", "new_password2"]
)
自定义模型包的 SQL 位置
以前,如果模型组织在一个包中(myapp/models/
)而不是简单的 myapp/models.py
,Django 会在 myapp/models/sql/
中查找初始 SQL 数据。这个问题已经被修复,Django 将按文档中的方式搜索 myapp/sql/
。在解决了这个问题后,添加了迁移,从而废弃了初始 SQL 数据。因此,尽管这个改变仍然存在,但废弃已经不相关,因为整个功能将在 Django 1.9 中被移除。
django.contrib.sites
的重新组织
当 django.contrib.sites
不在 INSTALLED_APPS 中时,它提供的功能会减少。应用程序加载的重构在这种情况下添加了一些限制。因此,两个对象被移动,旧的位置已被弃用:
- RequestSite 现在位于
django.contrib.sites.requests
中。 - get_current_site() 现在位于
django.contrib.sites.shortcuts
中。
ModelAdmin
上的 declared_fieldsets
属性
ModelAdmin.declared_fieldsets
已经被弃用。尽管它是一个私有 API,但它将按照常规的弃用路径进行处理。这个属性主要被一些绕过了 ModelAdmin.get_fieldsets()
方法的方法使用,但这被视为一个错误,并已得到解决。
django.contrib.contenttypes
的重新组织
由于 django.contrib.contenttypes.generic
定义了与管理和模型相关的对象,导入该模块可能会触发意外的副作用。因此,其内容已被拆分为 contenttypes 子模块,并且 django.contrib.contenttypes.generic
模块已被弃用:
- GenericForeignKey 和 GenericRelation 现在位于 fields 中。
- BaseGenericInlineFormSet 和 generic_inlineformset_factory() 现在位于 forms 中。
- GenericInlineModelAdmin、GenericStackedInline 和 GenericTabularInline 现在位于 admin 中。
syncdb
syncdb
命令已被弃用,推荐使用新的 migrate 命令。migrate
命令接受与以前的 syncdb
相同的参数,还添加了一些额外的参数,因此只需更改调用的名称而不需要做其他更改。
util
模块已重命名为 utils
在 Django 代码库中,以下实例的 util.py
已重命名为 utils.py
,以统一所有 util 和 utils 的引用:
django.contrib.admin.util
django.contrib.gis.db.backends.util
django.db.backends.util
django.forms.util
在 ModelAdmin
上的 get_formsets
方法
ModelAdmin.get_formsets
已弃用,推荐使用新的 get_formsets_with_inlines(),以更好地处理在 ModelAdmin
上有选择地显示内联表单的情况。
IPAddressField
django.db.models.IPAddressField
和 django.forms.IPAddressField
字段已弃用,推荐使用 django.db.models.GenericIPAddressField 和 django.forms.GenericIPAddressField。
BaseMemcachedCache._get_memcache_timeout
方法
BaseMemcachedCache._get_memcache_timeout()
方法已重命名为 get_backend_timeout()
。尽管它是一个私有 API,但它将经历正常的弃用过程。
自然键序列化选项
--natural
和 -n
选项对于 dumpdata 已被弃用。请改用 dumpdata —natural-foreign。
类似地,对于 serializers.serialize()
的 use_natural_keys
参数已被弃用。请改用 use_natural_foreign_keys
。
将 POST
和 GET
参数合并到 WSGIRequest.REQUEST
中
已经强烈建议使用 GET
和 POST
而不是 REQUEST
,因为前者更加明确。属性 REQUEST
已弃用,并将在 Django 1.9 中移除。
django.utils.datastructures.MergeDict
类
MergeDict
主要用于将 POST
和 GET
参数合并到 WSGIRequest
上的 REQUEST
属性中。要合并字典,请使用 dict.update()
。类 MergeDict
已被弃用,并将在 Django 1.9 中移除。
语言代码 zh-cn
、zh-tw
和 fy-nl
目前用于简体中文的语言代码 zh-cn
,繁体中文的语言代码 zh-tw
和 (西弗里西亚) 弗里西亚语的语言代码 fy-nl
已被弃用,应分别替换为语言代码 zh-hans
,zh-hant
和 fy
。如果您使用这些语言代码,应重命名区域目录并更新您的设置以反映这些更改。弃用的语言代码将在 Django 1.9 中移除。
django.utils.functional.memoize
函数
函数 memoize
已被弃用,应替换为 functools.lru_cache
装饰器(从 Python 3.2 开始可用)。
Django 在较旧的 Python 版本中附带了这个装饰器的后移版本,并且可以在 django.utils.lru_cache.lru_cache
中使用。弃用的函数将在 Django 1.9 中移除。
地理网站地图
Google 已停止支持 Geo Sitemaps 格式。因此,Django 对 Geo Sitemaps 的支持已被弃用,并将在 Django 1.8 中移除。
将可调用参数传递给查询集方法
查询集的可调用参数是一个未记录的功能,不可靠。已弃用,并将在 Django 1.9 中移除。
可调用参数在构建查询集时被求值,而不是在查询集被评估时求值,因此与在传递参数之前对其进行求值相比,此功能并没有提供任何好处,并且会导致混淆,使人误以为参数可能在查询时被求值。
ADMIN_FOR
设置
ADMIN_FOR
功能,是 admindocs 的一部分,已被移除。您可以根据需要从配置中移除此设置。
SplitDateTimeWidget
与 DateTimeField
SplitDateTimeWidget
在 DateTimeField 上的支持已被弃用,请改用与 SplitDateTimeField 一起使用的 SplitDateTimeWidget
。
validate
validate
管理命令已被弃用,推荐使用 check 命令。
django.core.management.BaseCommand
requires_model_validation
已被弃用,改为使用新的 requires_system_checks
标志。如果缺少后者标志,则将使用前者标志的值。定义同时 requires_system_checks
和 requires_model_validation
将导致错误。
check()
方法取代了旧的 validate()
方法。
ModelAdmin
验证器
ModelAdmin.validator_class
和 default_validator_class
属性已被弃用,推荐使用新的 checks_class
属性。
ModelAdmin.validate()
方法已被弃用,推荐使用 ModelAdmin.check()
。
django.contrib.admin.validation
模块已被弃用。
django.db.backends.DatabaseValidation.validate_field
这个方法已被弃用,推荐使用新的 check_field
方法。check_field()
所需的功能与 validate_field()
提供的相同,但输出格式不同。需要这种功能的第三方数据库后端应提供 check_field()
的实现。
从 future
库加载 ssi
和 url
模板标签
Django 1.3 引入了 {% load ssi from future %}
和 {% load url from future %}
语法,用于前向兼容 ssi
和 url 模板标签。这个语法现在已被弃用,并将在 Django 1.9 中移除。您可以简单地删除 {% load ... from future %}
标签。
django.utils.text.javascript_quote
javascript_quote()
是一个位于 django.utils.text
中的未记录函数。它在 javascript_catalog()
视图的内部使用,但该视图的实现已更改为使用 json.dumps()
。如果您依赖此函数来提供来自不受信任的字符串的安全输出,您应该使用 django.utils.html.escapejs
或 escapejs 模板过滤器。如果您只需要生成有效的 JavaScript 字符串,可以简单地使用 json.dumps()
。
fix_ampersands
工具方法和模板过滤器
django.utils.html.fix_ampersands
方法和 fix_ampersands
模板过滤器已被弃用,因为 Django 的标准 HTML 转义功能已经处理了 ampersands 的转义。与 fix_ampersands
结合使用可能会导致重复转义,或者如果输出被视为安全,则存在引入 XSS 漏洞的风险。除了 fix_ampersands
,未记录的调用 fix_ampersands
的 django.utils.html.clean_html
也已被弃用。由于这是一项加速弃用,fix_ampersands
和 clean_html
将在 Django 1.8 中移除。
数据库测试设置的重新组织
所有以 TEST_
前缀的数据库设置已被弃用,推荐使用数据库设置中的 TEST 字典中的条目。旧设置将在 Django 1.9 之前受到支持。为了与较旧版本的 Django 向后兼容,您可以定义这两个版本的设置,只要它们匹配即可。
FastCGI 支持
通过 runfcgi
管理命令提供的 FastCGI 支持将在 Django 1.9 中移除。请使用 WSGI 部署您的项目。
contrib.sites
中的对象已移动
在应用加载重构后,django.contrib.sites.models
中的两个对象需要移动,因为它们在没有安装 django.contrib.sites
的情况下必须可用,而无需导入 django.contrib.sites.models
。从 django.contrib.sites.requests
导入 RequestSite
,从 django.contrib.sites.shortcuts
导入 get_current_site()
。旧的导入位置将在 Django 1.9 之前继续工作。
django.forms.forms.get_declared_fields()
Django 不再在内部使用此功能。尽管它是一个私有 API,但它将按照正常的弃用周期进行处理。
私有查询查找 API
私有 API django.db.models.sql.where.WhereNode.make_atom()
和 django.db.models.sql.where.Constraint
已被弃用,推荐使用新的 自定义查询 API。
在 1.7 版本中移除的功能
这些功能已经完成了它们的弃用周期,并在 Django 1.7 中被移除。有关详细信息,包括如何删除对这些功能的使用,请参阅 在 1.5 中被废弃的功能。
django.utils.simplejson
已被移除。django.utils.itercompat.product
已被移除。- INSTALLED_APPS 和 TEMPLATE_DIRS 不再自动将纯字符串转换为元组。
- HttpResponse、SimpleTemplateResponse、TemplateResponse、
render_to_response()
、index() 和 sitemap() 不再接受mimetype
参数。 - HttpResponse 如果其内容是一个迭代器,会立即消耗它。
AUTH_PROFILE_MODULE
设置以及用户模型上的get_profile()
方法已被移除。cleanup
管理命令已被移除。daily_cleanup.py
脚本已被移除。- select_related() 不再具有
depth
关键字参数。 - 从 django.test.utils 中的
get_warnings_state()
/restore_warnings_state()
函数以及 django.test.*TestCase 中的save_warnings_state()
/restore_warnings_state()
已被移除。 - AuthenticationForm 中的
check_for_test_cookie
方法已被移除。 - 支持 base36 编码的用户 ID 的
django.contrib.auth.views.password_reset_confirm()
版本(django.contrib.auth.views.password_reset_confirm_uidb36
)已被移除。 django.utils.encoding.StrAndUnicode
混合类已被移除。