Django 3.1發佈，支持異步 view 和 middleware

Django 3.1已於8月4日正式發佈，官方文檔更新了發佈說明，全文翻譯如下。

本發行說明涵蓋了新版中的各項新功能，以及從Django 3.0或更早版本升級時需要注意的一些向後不兼容的更改。我們刪除了一些已完全棄用的功能，並且開始了某些功能的棄用流程。

如果要更新現有項目，請參閱"將Django升級到較新版本"的指南。

Python兼容性

Django 3.1支持Python 3.6、3.7和3.8。我們 強烈建議 並且僅正式支持每個系列的最新版本。

Django 3.1的新功能

異步視圖和中間件支持

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編碼器和解碼器。model字段支持以前僅適用於PostgreSQL的introspection、lookup和transform：

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以及相關的表單字段和轉換，則應進行調整以使用新字段，並生成和應用數據庫遷移。目前，舊的字段和轉換保留爲對新字段和轉換的引用，並且在此版本中已棄用。

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的較早版本。到3.1的遷移完成後，你可以停止覆蓋DEFAULT_HASHING_ALGORITHM。

此設置在這個版本中已棄用，因爲在Django 4.0中將刪除對使用SHA-1算法的令牌、cookie、會話和簽名的支持。

次要功能

django.contrib.admin

新的用於ModelAdmin.list_filter的django.contrib.admin.EmptyFieldListFilter允許在管理員更改列表視圖中過濾空值（空字符串和null）。
現在，管理員更改列表視圖右側欄中的過濾器包含一個鏈接，可清除所有過濾器。
現在，在較大的屏幕上爲管理員提供了側邊欄，以方便導航。它是默認啓用的，但可以使用自定義AdminSite並將AdminSite.enable_nav_sidebar設置爲False來禁用它。

渲染側欄需要訪問當前請求才能設置CSS和ARIA角色權限。這需要在OPTIONS的“context_processors”選項中使用“django.template.context_processors.request”。

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密碼哈希器的默認迭代計數從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爲止，仍支持使用舊哈希算法的用戶會話。

django.contrib.contenttypes

新的remove_stale_contenttypes–include-stale-apps選項允許從之前安裝的應用程序（已從INSTALLED_APPS中刪除）中刪除過時的內容類型。

django.contrib.gis

MariaDB現在支持relate查找。
添加了LinearRing.is_counterclockwise屬性。
Oracle現在支持AsGeoJSON。
添加了AsWKB和AsWKT函數。
添加了對PostGIS3和GDAL3的支持。

django.contrib.humanize¶

intword模板過濾器現在支持負整數。

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現在在PostgreSQL 11+上支持"websearch"搜索類型。
SearchQuery.value現在支持查詢表達式。
新的SearchHeadline類允許高亮顯示搜索結果。
search查找現在支持查詢表達式。
SearchRank的新cover_density參數允許按覆蓋密度排名。
SearchRank的新normalization參數允許進行排名規範化。
新的ExclusionConstraint.deferrable屬性允許創建可延期的排除約束。

django.contrib.sessions

現在，SESSION_COOKIE_SAMESITE設置允許“None”（字符串）值，明確聲明Cookie是與所有相同站點和跨站點請求一起發送的。

django.contrib.staticfiles

STATICFILES_DIRS設置現在支持pathlib.Path。

Cache

現在，根據RFC7234#section-5.2.2.2，cache_control()裝飾器和patch_cache_control()方法在Cache-Control標頭的no-cache指令中支持多個字段名稱。
如果成功刪除鍵，delete()現在返回True，否則返回False。

CSRF

CSRF_COOKIE_SAMESITE設置現在允許“None”（字符串）值，明確聲明該cookie是與所有相同站點和跨站點請求一起發送的。

Email

文件電子郵件後端使用的EMAIL_FILE_PATH設置現在支持pathlib.Path。

錯誤報告

django.views.debug.SafeExceptionReporterFilter現在可以過濾異常報告中request.META中的敏感值。
新的SafeExceptionReporterFilter.cleansed_substitute和SafeExceptionReporterFilter.hidden_settings屬性允許自定義敏感設置和異常報告中的request.META篩選。
現在，在應用設置過濾時，技術性404調試視圖會遵循DEFAULT_EXCEPTION_REPORTER_FILTER。
新的DEFAULT_EXCEPTION_REPORTER允許提供django.views.debug.ExceptionReporter子類來自定義生成異常報告。有關詳細信息，請參見自定義錯誤報告。

文件存儲

FileSystemStorage.save()方法現在支持pathlib.Path。
FileField和ImageField現在接受可調用的storage。這樣，你可以在運行時修改已使用的storage，例如爲不同的環境選擇不同的存儲。

格式

現在，ModelChoiceField和ModelMultipleChoiceField使用的ModelChoiceIterator使用ModelChoiceIteratorValue，小部件可以使用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現在除了DATETIME_INPUT_FORMATS之外還使用DATE_INPUT_FORMATS。

MultiWidget.widgets現在接受一個字典，該字典允許自定義子小部件的name屬性。
新的BoundField.widget_type屬性可用於根據小部件類型動態調整格式渲染。

國際化

現在，LANGUAGE_COOKIE_SAMESITE設置允許“None”（字符串）值，明確聲明Cookie是與所有相同站點和跨站點請求一起發送的。
增加了對阿爾及利亞阿拉伯語、伊博語、吉爾吉斯語、塔吉克語和土庫曼語的支持和翻譯。

管理命令

新的check–database選項允許指定數據庫別名以運行database系統檢查。以前，將database標籤傳遞給命令，可以爲所有已配置的DATABASES啓用這些檢查。
當檢測到未應用的遷移時，新的migration–check選項使命令以非零狀態退出。
CommandError的新returncode參數允許自定義管理命令的退出狀態。
新的dbshell-ARGUMENTS選項允許將額外的參數傳遞給數據庫的命令行客戶端。
現在，flush和sqlflush命令包括了SQL來重置SQLite上的序列。

模式

新的ExtractIsoWeekDay函數從DateField和DateTimeField中提取ISO-8601工作日，新的iso_week_day查找允許按ISO-8601工作日查詢。
QuerySet.explain()現在支持：
- MySQL 8.0.16+上的TREE格式，
- MySQL8.0.18+和MariaDB上的analyzer選項。
添加了PositiveBigIntegerField，它的行爲與PositiveIntegerField相似，不同之處在於它只允許特定（與數據庫有關）限制內的值。在Django支持的所有數據庫中，0到9223372036854775807的值都是安全的。
ForeignKey和OneToOneField的on_delete參數的新RESTRICT選項可模擬SQL約束ONDELETERESTRICT的行爲。
CheckConstraint.check現在支持布爾表達式。
現在，RelatedManager.add()、create()和set()方法接受可調用對象作爲through_defaults參數中的值。
QuerySet.datetimes()的新is_dst參數可確定不存在和不明確的日期時間的處理方式。
新的F表達式bitxor()方法允許按位XOR操作。
現在，使用MariaDB 10.5+時，QuerySet.bulk_create()設置對象的主鍵。
現在，對於不需要重置序列的表，使用DELETE而不是TRUNCATE語句後，DatabaseOperations.sql_flush()方法可在MySQL上生成更有效的SQL。
SQLite函數現在在Python 3.8+上被標記爲deterministic。這樣就可以在檢查約束和部分索引中使用它們。
新的UniqueConstraint.deferrable屬性允許創建可延遲的唯一約束。

分頁

現在可以遍歷Paginator以產生其頁面。

請求和響應

如果ALLOWED_HOSTS爲空並且DEBUG=True，則現在在Host標頭中允許localhost的子域，例如static.localhost。
HttpResponse.set_cookie()和HttpResponse.set_signed_cookie()現在允許使用samesite=‘None’（字符串），來明確聲明cookie是與所有相同站點和跨站點請求一起發送的。
新的HttpRequest.accepts()方法根據AcceptHTTP標頭，返回請求是否接受給定的MIME類型。

安全

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算法制作的簽名。

同樣，Signator的新algorithm參數允許自定義哈希算法。

模板

在模板代碼中引入了重命名的translate和blocktranslate模板標籤，用於國際化用途。較早的trans和blocktrans模板標籤別名將繼續生效，並在可預見的將來繼續保留。
現在，include模板標籤可以接受模板名稱的可迭代項。

測試

SimpleTestCase現在實現debug()方法，以允許運行測試時無需收集結果和捕獲異常。這可用於支持在調試器下運行測試。
新的MIGRATE測試數據庫設置允許在創建測試數據庫期間禁用遷移。
Django測試運行器現在支持test–buffer選項，以放棄通過測試的輸出。
DiscoverRunner現在對測試未引用的數據庫跳過系統檢查。
由於flush命令的改進，MySQL上的TransactionTestCase清除現在更快。副作用是後者不再會在清除時自動重置序列。如果你的測試需要此功能，請啓用TransactionTestCase.reset_sequences。

網址

路徑轉換器現在可以在to_url()中引發ValueError，以在反向URL時指示不匹配情況。

實用工具

filepath_to_uri()現在支持pathlib.Path。
parse_duration()現在支持ISO8601格式的小數部分的逗號分隔符。
parse_datetime()、parse_duration()和parse_time()現在支持毫秒的逗號分隔。

雜項

SQLite後端現在支持NAME設置的pathlib.Path。
現在，由startproject命令生成的settings.py使用pathlib.Path代替os.path來構建文件系統路徑。
現在，在支持時區的數據庫上允許使用TIME_ZONE設置。

3.1中向後不兼容的更改

數據庫後端API

本節描述了第三方數據庫後端中可能需要的更改。

現在，DatabaseOperations.fetch_returned_insert_columns()需要一個額外的returning_params參數。
現在，connection.timezone屬性默認爲“UTC”，或者在支持時區的數據庫上，當USE_TZ爲True時爲TIME_ZONE。以前，它在支持時區的數據庫上爲None。
新版將connection._nodb_connection屬性更改爲connection._nodb_cursor()方法，並返回一個上下文管理器，該管理器產生一個遊標，並在退出with語句時自動關閉遊標和連接。
現在，DatabaseClient.runshell()需要一個額外parameters參數，作爲傳遞給命令行客戶端的附加參數。
DatabaseOperations.sql_flush()的sequences位置參數由僅布爾型關鍵字參數reset_sequences取代。如果爲True，則將重置截斷表的序列。
現在，DatabaseOperations.sql_flush()的allow_cascade參數是僅關鍵字的參數。
DatabaseOperations.execute_sql_flush()的using位置參數已刪除。該方法現在使用被調用實例的數據庫。
第三方數據庫後端必須實現對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的introspection，或將can_introspect_json_field設置爲False。

不再支持MariaDB 10.1

對MariaDB 10.1的上游支持將於2020年10月結束。Django 3.1支持MariaDB 10.2和更高版本。

contrib.admin瀏覽器支持

管理員不再支持舊版Internet Explorer瀏覽器。有關支持瀏覽器的詳細信息，請參見管理員常見問題解答。

AbstractUser.first_namemax_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較早版本生成的鍵不同。升級到Django 3.1後，對任何先前緩存的模板片段的第一個請求將是緩存未命中。
現在，從set_language()視圖返回重定向回退或204 HTTP響應的決策，背後的邏輯是基於AcceptHTTP標頭，而不是X-Requested-WithHTTP標頭。
django.db.models.query、django.db.models.sql和django.db.models.sql.datastructures中的django.core.exceptions.EmptyResultSet的兼容性導入已刪除。
django.db.models.fields中django.core.exceptions.FieldDoesNotExist的兼容性導入已刪除。
django.forms.forms中的django.forms.utils.pretty_name()和django.forms.boundfield.BoundField的兼容性導入已刪除。
django.template.base中的Context、ContextPopException和RequestContext的兼容性導入已刪除。
django.contrib.admin中的django.contrib.admin.helpers.ACTION_CHECKBOX_NAME的兼容性導入已刪除。
設置爲相對路徑的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選項以前是元組，現在是列表。
現在，管理員日曆小部件可根據開放組規範處理兩位數的年份，即，將69到99之間的值映射到上一個世紀，將0到68之間的值映射到當前的世紀。
僅日期格式從DATETIME_INPUT_FORMATS的默認列表中刪除。
存在初始數據時，FileInput小部件不再使用required HTML屬性渲染。
沒有文檔的django.views.debug.ExceptionReporterFilter類已刪除。根據自定義錯誤報告文檔，與DEFAULT_EXCEPTION_REPORTER_FILTER一起使用的類需要從django.views.debug.SafeExceptionReporterFilter繼承。
現在，由cache_page()裝飾器設置的緩存超時優先於Cache-Control標頭中的max-age指令。
現在，在ForeignKey.to_field參數中提供非本地遠程字段會引發FieldError。
SECURE_REFERRER_POLICY現在默認爲“same-origin”。有關詳細信息，請參見上面的“安全”部分。
checkmanagement命令現在運行database系統，僅檢查使用check --database選項指定的數據庫別名。
現在，migrate管理命令運行database系統，僅檢查要遷移的數據庫。
移除了管理員CSS類row1和row2，而使用了:nth-child(odd)和:nth-child(even)僞類。
現在，make_password()函數要求其參數爲字符串或字節。其他類型應顯式轉換爲其中一種。
AsKML函數的無文檔version參數已刪除。
現在，默認情況下，轉儲數據使用的JSON和YAML序列化器轉儲所有使用Unicode的數據。如果你需要以前的行爲，則將sure_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。

3.1中已棄用的功能

PostgreSQLJSONField

棄用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中的轉換。

新的JSONFields、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()方法，因爲它依賴於表示AJAX調用的jQuery特定方式，而當前用法傾向於使用JavaScript Fetch API。根據你的用例，你可以編寫自己的AJAX檢測方法，或者如果代碼依賴於客戶端的Accept HTTP標頭，則可以使用新的HttpRequest.accepts()方法。

如果你正在編寫自己的AJAX檢測方法，則可以完全按照request.headers.get（‘x-requested-with’）=='XMLHttpRequest’的方式複製request.is_ajax()。

將None作爲第一個參數傳遞給django.utils.deprecation.MiddlewareMixin.init()的做法已棄用。
CookieStorage使用的cookie值的編碼格式與Django較早版本生成的格式不同。對舊格式的支持一直持續到Django 4.0。
會話的編碼格式不同於舊版Django生成的格式。對舊格式的支持一直持續到Django 4.0。
用於Signal的純文檔化的providing_args參數已棄用。如果你將此參數用作文檔，則可以將文本移至代碼註釋或文檔字符串。
不帶length參數的django.utils.crypto.get_random_string()已棄用。
棄用ModelMultipleChoiceField的list消息，應使用invalid_list。
將URL kwargs通過TemplateView直接傳遞到上下文的做法已棄用。應使用view.kwargs在模板中引用它們。
將原始列別名傳遞給QuerySet.order_by()的做法已棄用。預先在RawSQL中傳遞別名可以實現相同的結果。
棄用NullBooleanField模型字段，而應使用BooleanField(null=True)。
django.urls.re_path()的django.conf.urls.url()別名已棄用。
棄用{％ ifequal ％}和{％ ifnotequal ％}模板標籤，而應使用{％ if ％}。{％ if ％}涵蓋了所有用例，但是如果你需要繼續使用這些標記，則可以將它們從Django中提取到模塊中，並作爲內置標記包含在OPTIONS中的“builtins”選項中。
棄用DEFAULT_HASHING_ALGORITHM過渡設置。

3.1中刪除的功能

這些功能已到棄用週期的末端，並已在Django 3.1中刪除。

有關這些更改的詳細信息，請參閱2.2中棄用的功能，包括如何移除對這些功能的應用。

django.utils.timezone.FixedOffset已刪除。
django.core.paginator.QuerySetPaginator已刪除。
模型的Meta.ordering不會影響GROUPBY查詢。
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的支持。

原文鏈接： https://docs.djangoproject.com/en/3.1/releases/3.1/