Django REST framework API 指南(27):Settings

wcode發表於2018-03-24

官方原文連結
本系列文章 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.userrequest.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 模組接受的擴充套件浮點值(naninf-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

相關文章