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