Django REST framework API 指南（27）：Settings

官方原文連接
本系列文章 github 地址
轉載請註明出處

Settings

Namespaces are one honking great idea - let's do more of those!

— [The Zen of Python][cite]

REST framework 的配置是在名爲 REST_FRAMEWORK 的單個 Django 設置中的全部命名空間。

例如，你的項目的 settings.py 文件可能包含以下所示的內容：

REST_FRAMEWORK = {
    'DEFAULT_RENDERER_CLASSES': (
        'rest_framework.renderers.JSONRenderer',
    ),
    'DEFAULT_PARSER_CLASSES': (
        'rest_framework.parsers.JSONParser',
    )
}
複製代碼

訪問 settings

若是你須要訪問項目中 REST framework 的 API 設置值，則應使用 api_settings 對象。例如。

from rest_framework.settings import api_settings

print api_settings.DEFAULT_AUTHENTICATION_CLASSES
複製代碼

api_settings 對象將檢查用戶定義的設置，不然將回退到默認值。任何使用字符串導入路徑引用類的設置都會自動導入並返回被引用的類，而不是字符串文字。

---

API 參考

API 策略設置

如下設置控制基本 API 策略，並應用於每一個基於 APIView 類的視圖或基於 @api_view 函數的視圖。

DEFAULT_RENDERER_CLASSES

渲染器類的列表或元組，用於肯定返回 Response 對象時可能使用的默認渲染器集。

默認值：

(
    'rest_framework.renderers.JSONRenderer',
    'rest_framework.renderers.BrowsableAPIRenderer',
)
複製代碼

DEFAULT_PARSER_CLASSES

解析器類的列表或元組，用於肯定訪問 request.data 屬性時使用的默認解析器集。

默認值：

(
    'rest_framework.parsers.JSONParser',
    'rest_framework.parsers.FormParser',
    'rest_framework.parsers.MultiPartParser'
)
複製代碼

DEFAULT_AUTHENTICATION_CLASSES

身份驗證類的列表或元組，用於肯定在訪問 request.user 或 request.auth 屬性時使用的默認身份驗證集。

默認值：

(
    'rest_framework.authentication.SessionAuthentication',
    'rest_framework.authentication.BasicAuthentication'
)
複製代碼

DEFAULT_PERMISSION_CLASSES

權限類的列表或元組，用於肯定在視圖開始時檢查的默認權限集。權限必須由列表中的每一個類授予。

默認值：

(
    'rest_framework.permissions.AllowAny',
)
複製代碼

DEFAULT_THROTTLE_CLASSES

限流類的列表或元組，用於肯定在視圖開始時檢查的默認限流類集。

默認值： ()

DEFAULT_CONTENT_NEGOTIATION_CLASS

內容協商類，用於肯定如何爲響應選擇渲染器，並給定傳入請求。

默認值：'rest_framework.negotiation.DefaultContentNegotiation'

DEFAULT_SCHEMA_CLASS

將用於 schema 生成的視圖檢查類。

默認值：'rest_framework.schemas.AutoSchema'

---

Generic view settings

如下設置控制通用基於類的視圖的行爲。

DEFAULT_FILTER_BACKENDS

用於通用過濾的過濾器後端類列表。若是設置爲 None，則禁用通用過濾。

PAGE_SIZE

用於分頁的默認頁面大小。若是設置爲 None，則默認狀況下禁用分頁。

默認值：None

SEARCH_PARAM

查詢參數的名稱，可用於指定 SearchFilter 使用的搜索詞。

默認值：search

ORDERING_PARAM

排序參數的名稱，可用於指定 OrderingFilter 返回結果的排序。

默認值：ordering

---

版本控制設置

DEFAULT_VERSION

當沒有版本信息存在時，默認的 request.version 值。

默認值：None

ALLOWED_VERSIONS

若是設置，則此值將限制版本控制方案可能返回的版本集合，若是提供的版本不在此集合中，則會引起錯誤。

默認值：None

VERSION_PARAM

用於版本控制參數的字符串，例如媒體類型或 URL 查詢參數。

默認值：'version'

---

認證設置

如下設置控制未經身份驗證的請求的行爲。

UNAUTHENTICATED_USER

用於初始化未經身份驗證的請求的 request.user的類。（若是要徹底刪除驗證，能夠經過從 INSTALLED_APPS 中除去 django.contrib.auth，將 UNAUTHENTICATED_USER 設置爲 None。）

默認值： django.contrib.auth.models.AnonymousUser

UNAUTHENTICATED_TOKEN

用於初始化未經身份驗證的請求的 request.auth 的類。

默認值：None

---

測試設置

如下設置控制 APIRequestFactory 和 APIClient 的行爲

TEST_REQUEST_DEFAULT_FORMAT

進行測試請求時應使用的默認格式。

這應該與 TEST_REQUEST_RENDERER_CLASSES 設置中的其中一個渲染器類的格式相匹配。

默認值： 'multipart'

TEST_REQUEST_RENDERER_CLASSES

構建測試請求時支持的渲染器類。

構建測試請求時可使用任何這些渲染器類的格式，例如：client.post('/users', {'username': 'jamie'}, format='json')

默認值：

(
    'rest_framework.renderers.MultiPartRenderer',
    'rest_framework.renderers.JSONRenderer'
)
複製代碼

---

Schema 生成控制

SCHEMA_COERCE_PATH_PK

若是設置，則在生成 schema 路徑參數時，會將 URL conf 中的 'pk' 標識符映射到實際字段名稱上。一般這將是 'id' 。因爲 「primary key」 是實現細節，所以這提供了更適合的表示，而 「identifier」 是更通常的概念。

默認值：True

SCHEMA_COERCE_METHOD_NAMES

若是設置，則用於將內部視圖方法名稱映射到 schema 生成中使用的外部操做名稱。這使咱們可以生成比代碼庫中內部使用的名稱更適合外部表示的名稱。

默認值： {'retrieve': 'read', 'destroy': 'delete'}

---

內容類型控制

URL_FORMAT_OVERRIDE

經過在請求 URL 中使用 format=… 查詢參數，可用於覆蓋默認內容協商 Accept header 行爲的 URL 參數的名稱。

例如： http://example.com/organizations/?format=csv

若是此設置的值爲 None，則 URL 格式覆蓋將被禁用。

默認值： 'format'

FORMAT_SUFFIX_KWARG

URL conf 中用於提供格式後綴的參數名稱。使用 format_suffix_patterns 包含後綴 URL patterns 時應用此設置。

例如：http://example.com/organizations.csv/

默認值：'format'

---

日期和時間格式

如下設置用於控制如何分析和渲染日期和時間表示。

DATETIME_FORMAT

格式字符串，默認狀況下用於渲染 DateTimeField 序列化字段的輸出。若是爲 None，那麼 DateTimeField 序列化字段將返回 Python datetime 對象，而且日期時間編碼將由渲染器決定。

能夠是 None，'iso-8601' 或 Python strftime 格式字符串中的任何一個。

默認值：'iso-8601'

DATETIME_INPUT_FORMATS

默認使用的格式字符串列表，用於解析 DateTimeField 序列化字段的輸入。

能夠是包含字符串 'iso-8601' 或 Python strftime 格式字符串的列表。

默認值： ['iso-8601']

DATE_FORMAT

格式字符串，默認狀況下用於渲染 DateField 序列化字段的輸出。若是爲 None，那麼 DateField 序列化字段將返回 Python date 對象，而且日期編碼將由渲染器決定。

能夠是 None，'iso-8601' 或 Python strftime 格式字符串中的任何一個。

默認值：'iso-8601'

DATE_INPUT_FORMATS

默認使用的格式字符串列表，用於解析 DateField 序列化字段的輸入。

能夠是包含字符串 'iso-8601' 或 Python strftime 格式字符串的列表。

默認值：['iso-8601']

TIME_FORMAT

格式字符串，默認狀況下用於渲染 imeField 序列化字段的輸出。若是爲 None，那麼 TimeField 序列化字段將返回 Python time 對象，而且時間編碼將由渲染器決定。

能夠是 None，'iso-8601' 或 Python strftime 格式字符串中的任何一個。

默認值： 'iso-8601'

TIME_INPUT_FORMATS

默認使用的格式字符串列表，用於解析 TimeField 序列化字段的輸入。

能夠是包含字符串 'iso-8601' 或 Python strftime 格式字符串的列表。

默認值：['iso-8601']

---

編碼

UNICODE_JSON

設置爲 True 時，JSON 響應將容許 unicode 字符做爲響應。例如：

{"unicode black star":"★"}
複製代碼

當設置爲 False 時，JSON 響應將轉義非ascii字符，以下所示：

{"unicode black star":"\u2605"}
複製代碼

兩種樣式都符合 RFC 4627，而且在語法上都是有效 JSON。在檢查 API 響應時，unicode 樣式更受用戶歡迎。

默認值： True

COMPACT_JSON

當設置爲 True 時，JSON 響應將返回緊湊表示，':' 和 ',' 字符以後沒有間隔。例如：

{"is_admin":false,"email":"jane@example"} 
複製代碼

當設置爲 False 時，JSON 響應將返回稍微更冗長的表示，以下所示：

{"is_admin": false, "email": "jane@example"}
複製代碼

默認樣式是返回縮小的響應，符合 Heroku 的 API 設計準則。

默認值： True

STRICT_JSON

當設置爲 True 時，JSON 渲染和解析只會遵循語法上有效的 JSON，而 Python 的 json 模塊接受的擴展浮點值（nan，inf，-inf）會引起異常。這是推薦的設置，由於一般不支持這些值。例如，Javascript 的 JSON.Parse 和 PostgreSQL 的 JSON 數據類型都不接受這些值。

當設置爲 False 時，JSON 的渲染和解析將是寬鬆的。可是，這些值仍然無效，須要在代碼中專門處理。

默認值：True

COERCE_DECIMAL_TO_STRING

在不支持原生十進制類型的 API 表示形式中返回小數對象時，一般最好將該值做爲字符串返回。這樣能夠避免二進制浮點實現所帶來的精度損失。

設置爲 True 時，序列化 DecimalField 類將返回字符串而不是 Decimal 對象。設置爲 False 時，序列化將返回 Decimal 對象，默認 JSON 編碼器將做爲浮點數返回。

默認值： True

---

View names and descriptions

如下設置用於生成視圖名稱和描述，如 OPTIONS 請求的響應中所使用的，以及可瀏覽 API 中使用的設置。

VIEW_NAME_FUNCTION

表示生成視圖名稱時應使用的函數的字符串。

這應該是一個具備如下簽名的函數：

view_name(cls, suffix=None)
複製代碼

• cls: 視圖類。一般，名稱函數會在生成描述性名稱時經過訪問 cls .__ name__ 來檢查類的名稱。
• suffix: 區分視圖中各個視圖時使用的可選後綴。

默認值：'rest_framework.views.get_view_name'

VIEW_DESCRIPTION_FUNCTION

表示生成視圖描述時應使用的函數的字符串。

此設置能夠更改成支持除默認 markdown 之外的標記樣式。例如，你可使用它支持在可瀏覽的 API 中輸出的視圖文檔字符串中的 rst 標記。

這應該是一個具備如下簽名的函數：

view_description(cls, html=False)
複製代碼

• cls: 視圖類。一般，description 函數會在生成描述時檢查類的文檔字符串，方法是訪問 cls .__ doc__
• html: 指示是否須要 HTML 輸出的布爾值。在可瀏覽的 API 中使用時爲 true，在生成 OPTIONS 響應時使用 False。

默認值： 'rest_framework.views.get_view_description'

HTML Select 字段截取

用於在可瀏覽 API 中渲染關係字段的 select 字段截取的全局設置。

HTML_SELECT_CUTOFF

html_cutoff 值的全局設置。必須是整數。

默認值： 1000

HTML_SELECT_CUTOFF_TEXT

表明 html_cutoff_text 全局設置的字符串。

默認值： "More than {count} items..."

---

雜項設置

EXCEPTION_HANDLER

一個字符串，表示在返回任何給定異常的響應時應使用的函數。若是該函數返回 None，則會引起 500 錯誤。

此設置能夠更改成支持默認 {"detail": "Failure..."} 響應之外的錯誤響應。例如，你可使用它來提供 API 響應，如 {"errors": [{"message": "Failure...", "code": ""} ...]}.

這應該是一個具備如下簽名的函數：

exception_handler(exc, context)
複製代碼

• exc: 異常。

默認值： 'rest_framework.views.exception_handler'

NON_FIELD_ERRORS_KEY

表示應該用於序列化錯誤的關鍵字的字符串，該字符串不引用特定字段，而表明通常錯誤。

默認值：'non_field_errors'

URL_FIELD_NAME

一個字符串，表示用於由 HyperlinkedModelSerializer 生成的 URL 字段的鍵

默認值： 'url'

NUM_PROXIES

一個 0 或更大的整數，可用於指定 API 在後臺運行的應用程序代理的數量。這容許限流器更準確地識別客戶端 IP 地址。若是設置爲 None，那麼限流器將使用寬鬆的 IP 匹配方式。

默認值：None