Django3.1

一，Python兼容性

Django 3.1支持Python 3.6、3.7、3.8和3.9（自3.1.3起）。建议并仅正式支持每个系列的最新版本。

---

二，异步视图和中间件支持

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

• 异步视图
• 异步中间件
• 异步测试和测试客户端

2，要开始使用异步视图，需要使用声明一个视图：async def

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

• 无论是在WSGI还是ASGI模式下运行，都支持所有异步功能。但是，在WSGI模式下使用异步代码会降低性能。
• 可以混合使用异步和同步视图，中间件和测试。Django将确保始终拥有正确的执行上下文。希望大多数项目将大多数视图保持同步，并且只有少数几个在异步模式下运行，但这完全是开发者自己的选择。
• Django 3.1版本中的ORM，缓存层和其他长时间运行网络调用的代码尚不支持异步访问。会在后期发布的版本中增加对他们的支持。异步视图是理想的选择，但是，如果在视图内进行大量的API或HTTP调用，则现在可以本地并行执行所有这些HTTP调用，从而大大加快视图的执行速度。
• Django对异步的支持完全向后兼容，对现有的同步代码没有速度限制，它不会对任何现有的Django项目产生明显的影响。

---

三，新增JSONField字段

1，Django 3.1新增了models.JSONField和forms.JSONField 两种新的模型字段类型，用于保存json编码的数据。MariaDB 10.2.7+、MySQL 5.7.8+、Oracle、PostgreSQL和SQLite 3.9.0+都支持JSONField。
2，JSONField可以自定义编码器和解码器，这从它的定义上就可以看出来：

class JSONField(encoder=None, decoder=None, **options)

• JSONField.encoder可选参数。用于对诸如datetime.datetime 或者uuid之类的标准JSON序列化不了的数据指定自定义的编码器。它必须是json.JSONEncoder的子类，比如DjangoJSONEncoder
• JSONField.decoder可选参数。用于解码我们自定义的编码数据。必须是json.JSONDecoder的子类。

3，如果为JSONField字段提供一个default默认值，他的值必须是一个不可变类型。
4，对于forms.JSONField，除了同样可以自定义编码器和解码器，还有一些表单特有的性质。

• 默认渲染的HTML元素：Textarea。
• 空值：''(空字符串)。
• 错误信息的键：required，invalid。

5，如果你的项目使用django.contrib.postgres.fields.JSONField，以及相关的表单字段和转换，则应进行调整以使用新字段，并生成和应用数据库迁移。

---

四，DEFAULT_HASHING_ALGORITHM设置

1，新的DEFAULT_HASHING_ALGORITHM过渡设置允许指定默认哈希算法，以用于编码Cookie和管理站点中的密码重置令牌，用户会话以及由django.core.signing.Signer和创建的签名django.core.signing.dumps()。
2，在Django 3.1中添加了对SHA-256的支持。如果要将同一项目的多个实例升级到Django 3.1，则应在过渡期间设置DEFAULT_HASHING_ALGORITHM为‘sha1’，以允许与Django的较早版本兼容。请注意，这里需要Django3.1.1+。过渡到3.1后，您可以停止覆盖DEFAULT_HASHING_ALGORITHM。
3，此设置在此版本中已经弃用，因为在Django4.0中将删除对使用SHA-1算法的令牌，cookie，会话和签名的支持。

---

五，其他功能

1，杂项

• SQLite后端现在支持pathlib.Path该NAME设置。
• 在settings.py由所产生的startproject命令现在使用 pathlib.Path的，而不是os.path用于构建文件系统路径。
• TIME_ZONE现在，在支持时区的数据库上允许该设置。

2，实用工具

• filepath_to_uri()现在支持 pathlib.Path。
• parse_duration() 现在支持ISO 8601格式的小数部分的逗号分隔符。
• parse_datetime()， parse_duration()和 parse_time()现在支持毫秒分隔符。

3，测试

• SimpleTestCase现在实现了debug()允许运行测试而不收集结果和捕获异常的方法。这可用于支持在调试器下运行测试。
• 新的MIGRATE测试数据库设置允许在创建测试数据库期间禁用迁移。
• Django测试运行器现在支持放弃输出以通过测试的选项。test --buffer
• DiscoverRunner现在跳过在测试未引用的数据库上运行系统检查。
• TransactionTestCase由于flush命令的改进，现在在MySQL上的拆卸速度更快。作为副作用，后者不会在拆卸时自动重置序列。
• TransactionTestCase.reset_sequences如果您的测试需要此功能，则启用 。

4，网址

• 路径转换器现在可以提高 ValueError在to_url()表示没有匹配倒车URL时。

5，模板

• 改名后translate和blocktranslate模板标签介绍了在模板代码国际化。较早的trans 和blocktrans模板标签别名将继续起作用，并将在可预见的将来保留。
• 该include模板标签现在接受模板名称iterables。

6，安全

• SECURE_REFERRER_POLICY现在，该设置默认为 'same-origin'。进行此配置后， SecurityMiddleware将所有没有的Referrer Policy标头设置为 same-origin。这样可以防止将Referer标头发送到其他来源。如果需要以前的行为，请显式设置 SECURE_REFERRER_POLICY为None。
• 默认算法django.core.signing.Signer， django.core.signing.loads()以及django.core.signing.dumps()变更为SHA-256。直到Django 4.0为止，仍支持使用旧SHA-1算法制作的签名。 同样，新algorithm参数 Signer允许自定义哈希算法。

7，请求和响应

• 如果ALLOWED_HOSTS为和DEBUG=True，则现在允许在Host标头中使用localhost的子域，例如static.localhost。
• HttpResponse.set_cookie()而HttpResponse.set_signed_cookie() 现在允许使用samesite='None'（串），明确规定该cookie与所有在同一站点内和跨站点请求发送。
• 新HttpRequest.accepts()方法根据AcceptHTTP标头返回请求是否接受给定的MIME类型。

8，分页

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

9，型号

• 新ExtractIsoWeekDay功能从DateField和中 提取ISO-8601工作日DateTimeField，新的iso_week_day 查询功能允许按ISO-8601工作日进行查询。
• QuerySet.explain() 现在支持：
  TREE MySQL 8.0.16+上的格式，
  analyze MySQL 8.0.18+和MariaDB上的选项。
• 添加的PositiveBigIntegerField行为与a的行为类似，PositiveIntegerField不同之处在于它仅允许特定值（与数据库有关）的限制下的值。从0到的 值9223372036854775807在Django支持的所有数据库中都是安全的。
• 新RESTRICT选项 模拟SQL约束的行为。on_deleteForeignKeyOneToOneFieldON DELETE RESTRICT
• CheckConstraint.check 现在支持布尔表达式。
• RelatedManager.add()，create()和 set()方法现在接受可以调用的中值 through_defaults的论点。
• 新is_dst 参数QuerySet.datetimes()确定不存在和不明确的日期时间的处理方式。
• 新的F表达式bitxor()方法允许 按位XOR运算。
• QuerySet.bulk_create() 现在在使用MariaDB 10.5+时在对象上设置主键。
• DatabaseOperations.sql_flush()现在，该方法通过对不需要重置序列的表使用DELETE而不是TRUNCATE语句来在MySQL上生成更有效的SQL 。
• SQLite函数现在deterministic在Python 3.8+上被标记为。这允许在检查约束和部分索引中使用它们。
• 新UniqueConstraint.deferrable属性允许创建可延迟的唯一约束。

10，管理命令

• 新选项允许指定数据库别名以运行系统检查。以前，这些检查是通过将 标记传递给命令来为所有配置的启用的。check --databasedatabaseDATABASESdatabase
• 当检测到未应用的迁移时，新选项使命令以非零状态退出。migrate --check
• 新的returncode参数用于 CommandError允许自定义管理命令的退出状态。
• 新选项允许将额外的参数传递给数据库的命令行客户端。dbshell -- ARGUMENTS
• 在flush与sqlflush命令现在包括SQL到SQLite的复位序列。

11，国际

• LANGUAGE_COOKIE_SAMESITE现在，该设置允许'None' （字符串）值明确声明cookie是与所有相同站点和跨站点请求一起发送的。
• 增加了对阿尔及利亚阿拉伯语，伊博语，吉尔吉斯语，塔吉克语和土库曼语的支持和翻译。

12，表格

• ModelChoiceIterator，使用 ModelChoiceField和 ModelMultipleChoiceField，现在使用 ModelChoiceIteratorValue的是可以通过小部件可用于访问模型实例。有关详细信息，请参见迭代关系选择。
• django.forms.DateTimeField现在接受的ISO 8601日期时间格式，包括可选的时区，例如，一个子集的日期2019-10-10T06:47， 2019-10-10T06:47:23+04:00或2019-10-10T06:47:23Z。如果提供了时区，则将始终保留该时区，即使USE_TZ是，也会返回时区感知日期时间False。 另外，DateTimeField现在DATE_INPUT_FORMATS除了DATETIME_INPUT_FORMATS将字段输入转换为datetime 值时还使用。
• MultiWidget.widgets现在接受允许自定义subwidgetname属性的字典。
• 新BoundField.widget_type属性可用于基于窗口小部件类型动态调整表单呈现。

13，文件存储

• FileSystemStorage.save()方法现在支持pathlib.Path。
• FileField并且 ImageField现在接受一个可调用的storage。这样，您可以在运行时修改已使用的存储，例如为不同的环境选择不同的存储。

14，错误报告

• django.views.debug.SafeExceptionReporterFilter现在可以从request.META异常报告中过滤敏感值。
• 新的SafeExceptionReporterFilter.cleansed_substitute和 SafeExceptionReporterFilter.hidden_settings属性允许自定义敏感设置并request.META在异常报告中进行过滤。
• 现在，DEFAULT_EXCEPTION_REPORTER_FILTER在应用设置过滤时，可以使用技术404调试视图 。
• 新版本DEFAULT_EXCEPTION_REPORTER允许提供一个 django.views.debug.ExceptionReporter子类来定制异常报告的生成。有关详细信息，请参见自定义错误报告。

15，电子邮件

• 文件电子邮件后端EMAIL_FILE_PATH使用的设置现在支持。pathlib.Path

16，CSRF

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

17, 缓存

• 根据以下说明，cache_control()装饰器和 patch_cache_control()方法现在no-cache在Cache-Control标头的指令中支持多个字段名称：RFC 7234＃section-5.2.2.2。
• delete()现在返回True是否成功删除密钥，False否则返回。

18，django.contrib.sessions

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

19，django.contrib.staticfiles

• 该STATICFILES_DIRS设置现在支持pathlib.Path。

20，django.contrib.postgres

• 新BloomIndex类允许bloom在数据库中创建索引。新的 BloomExtension迁移操作将安装bloom扩展，以添加对此索引的支持。
• get_FOO_display()现在支持 ArrayField和 RangeField。
• 新的rangefield.lower_inc，rangefield.lower_inf，rangefield.upper_inc，并rangefield.upper_inf查找允许查询RangeField通过绑定类型。
• rangefield.contained_by现在支持 SmallAutoField， AutoField， BigAutoField， SmallIntegerField，和 DecimalField。
• SearchQuery现在'websearch'在PostgreSQL 11+上支持 搜索类型。
• SearchQuery.value 现在支持查询表达式。
• 新SearchHeadline类允许突出显示搜索结果。
• search 查找现在支持查询表达式。
• 新的cover_density参数 SearchRank允许按覆盖密度排序。
• 新normalization参数 SearchRank允许等级归一化。
• 新ExclusionConstraint.deferrable属性允许创建可推迟的排除约束。

21，django.contrib.humanize

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

22，django.contrib.gis

• relate 现在，MariaDB支持查找。
• 添加了LinearRing.is_counterclockwise属性。
• AsGeoJSON 现在在Oracle上受支持。
• 添加了AsWKB和 AsWKT功能。
• 添加了对PostGIS 3和GDAL 3的支持。

23，django.contrib.contenttypes

• 新选项允许从中已删除的先前安装的应用程序中删除过时的内容类型。remove_stale_contenttypes --include-stale-appsINSTALLED_APPS

24，django.contrib.auth

• PBKDF2密码哈希器的默认迭代计数从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为止，仍支持使用旧哈希算法的用户会话。

25，django.contrib.admin

• 新django.contrib.admin.EmptyFieldListFilter的 ModelAdmin.list_filter允许在管理更改列表视图中过滤空值（空字符串和null）。
• 现在，管理员变更列表视图右侧栏中的过滤器包含一个链接，用于清除所有过滤器。
• 管理员现在在较大的屏幕上具有侧边栏，以便于导航。默认情况下启用此功能，但可以通过使用自定义AdminSite并将其设置AdminSite.enable_nav_sidebar为来禁用False。 渲染侧栏需要访问当前请求才能设置CSS和ARIA角色权限。这需要使用 'django.template.context_processors.request'中的 'context_processors'选项OPTIONS。
• XRegExp 已从版本2.0.0升级到3.2.0。
• jQuery从版本3.4.1升级到3.5.1。
• Select2库从版本4.0.7升级到4.0.13。

---

六，Django 3.1中向后不兼容的更改

1，数据库后端

• DatabaseOperations.fetch_returned_insert_columns()现在需要一个附加returning_params参数。
• connection.timezone属性现在是'UTC'在默认情况下，或 TIME_ZONE当USE_TZ是True 对数据库的支持时区。以前，它是None在支持时区的数据库上。
• connection.nodbconnection属性更改为 connection.nodbcursor()方法，现在返回一个上下文管理器，该管理器产生一个游标，并在退出该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。如果JSON的数据类型为true，则设置 DatabaseFeatures.has_native_json_field为True。如果 jsonfield.contains和jsonfield.contained_by不支持，设置DatabaseFeatures.supports_json_field_contains为 False。
• 第三方数据库后端必须实现的自省JSONField 或设置can_introspect_json_field为False。

2，对MariaDB 10.1的上游支持将于2020年10月结束。Django3.1支持MariaDB 10.2和更高版本。
3，管理员不再支持旧版Internet Explorer浏览器。
4，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)