API ¶

變更日誌

Added in version 2.2: 從 flask.url_for 移動，後者會呼叫此方法。

make_response(rv)¶

將檢視函數的傳回值轉換為 response_class 的實例。

參數:

rv (ft.ResponseReturnValue) –

檢視函數的傳回值。檢視函數必須傳回一個回應。不允許傳回 None，或檢視在沒有傳回的情況下結束。以下類型允許用於 view_rv

str: 回應物件是使用編碼為 UTF-8 的字串作為主體建立的。
bytes: 回應物件是使用位元組作為主體建立的。
dict: 將在傳回之前 jsonify 的字典。
list: 將在傳回之前 jsonify 的列表。
generator 或 iterator: 傳回 str 或 bytes 的 generator，以作為回應串流。
tuple: 可以是 (body, status, headers)、(body, status) 或 (body, headers)，其中 body 是此處允許的任何其他類型，status 是字串或整數，而 headers 是字典或 (key, value) tuple 的列表。如果 body 是 response_class 實例，則 status 會覆寫現有值，且 headers 會被擴展。
response_class: 物件會保持不變地傳回。
其他 Response 類別: 物件會被強制轉換為 response_class。
callable(): 該函數會作為 WSGI 應用程式呼叫。結果會用於建立回應物件。

回傳類型:

變更日誌

Changed in version 2.2: generator 將會轉換為串流回應。list 將會轉換為 JSON 回應。

Changed in version 1.1: dict 將會轉換為 JSON 回應。

Changed in version 0.9: 先前，tuple 被解釋為回應物件的引數。

preprocess_request()¶

在分派請求之前呼叫。呼叫在應用程式和當前藍圖（如果有的話）中註冊的 url_value_preprocessors。然後呼叫在應用程式和藍圖中註冊的 before_request_funcs。

如果任何 before_request() 處理器傳回非 None 值，則該值會被視為檢視的傳回值來處理，並且會停止進一步的請求處理。

回傳類型:: ft.ResponseReturnValue | None

process_response(response)¶

可以被覆寫，以便在回應物件被傳送到 WSGI 伺服器之前修改它。預設情況下，這將呼叫所有以 after_request() 修飾的函數。

變更日誌

Changed in version 0.5: 從 Flask 0.5 開始，為請求後執行註冊的函數會以註冊的相反順序呼叫。

參數:: response (Response) – response_class 物件。
Returns:: 一個新的回應物件或相同的物件，必須是 response_class 的實例。
回傳類型:: 回應

do_teardown_request(exc=_sentinel)¶

在請求被分派且回應被傳回之後，緊接在請求上下文彈出之前呼叫。

這會呼叫所有以 teardown_request() 和 Blueprint.teardown_request() 修飾的函數（如果藍圖處理了請求）。最後，會發送 request_tearing_down 訊號。

這是由 RequestContext.pop() 呼叫，在測試期間可能會延遲呼叫以保持對資源的存取。

參數:: exc (BaseException | None) – 在分派請求時引發的未處理例外。如果未傳遞，則從當前例外資訊中偵測。傳遞給每個 teardown 函數。
回傳類型:: None

變更日誌

Changed in version 0.9: 新增了 exc 引數。

do_teardown_appcontext(exc=_sentinel)¶

在應用程式上下文彈出之前立即呼叫。

在處理請求時，應用程式上下文會在請求上下文之後彈出。請參閱 do_teardown_request()。

這會呼叫所有以 teardown_appcontext() 修飾的函數。然後發送 appcontext_tearing_down 訊號。

這是由 AppContext.pop() 呼叫。

變更日誌

在 0.9 版本中新增。

參數:: exc (BaseException | None)
回傳類型:: None

app_context()¶

建立 AppContext。使用作為 with 區塊以推送上下文，這會使 current_app 指向此應用程式。

當處理請求和執行 CLI 命令時，應用程式上下文會由 RequestContext.push() 自動推送。在這些情況之外手動建立上下文時，請使用此方法。

with app.app_context():
    init_db()

請參閱應用程式上下文。

變更日誌

在 0.9 版本中新增。

回傳類型:: AppContext

request_context(environ)¶

建立代表 WSGI 環境的 RequestContext。使用 with 區塊以推送上下文，這會使 request 指向此請求。

請參閱請求上下文。

通常您不應從自己的程式碼中呼叫此方法。當處理請求時，請求上下文會由 wsgi_app() 自動推送。使用 test_request_context() 建立環境和上下文，而不是此方法。

參數:: environ (WSGIEnvironment) – WSGI 環境
回傳類型:: RequestContext

test_request_context(*args, **kwargs)¶

為從給定值建立的 WSGI 環境建立 RequestContext。這在測試期間最有用，您可能希望在不分派完整請求的情況下執行使用請求資料的函數。

請參閱請求上下文。

使用 with 區塊以推送上下文，這會使 request 指向為建立的環境的請求。

with app.test_request_context(...):
    generate_report()

當使用 shell 時，手動推送和彈出上下文可能更容易，以避免縮排。

ctx = app.test_request_context(...)
ctx.push()
...
ctx.pop()

採用與 Werkzeug 的 EnvironBuilder 相同的引數，以及應用程式的一些預設值。請參閱連結的 Werkzeug 文件以取得大多數可用的引數。此處列出了 Flask 特有的行為。

參數:

path – 正在請求的 URL 路徑。
base_url – 應用程式正在服務的基本 URL，path 相對於此 URL。如果未給定，則從 PREFERRED_URL_SCHEME、subdomain、SERVER_NAME 和 APPLICATION_ROOT 建構。
subdomain – 要附加到 SERVER_NAME 的子網域名稱。
url_scheme – 要使用的 scheme，而不是 PREFERRED_URL_SCHEME。
data – 請求主體，可以是字串或表單鍵和值的字典。
json – 如果給定，這會序列化為 JSON 並作為 data 傳遞。也會預設 content_type 為 application/json。
args (Any) – 傳遞給 EnvironBuilder 的其他位置引數。
kwargs (Any) – 傳遞給 EnvironBuilder 的其他關鍵字引數。

回傳類型:

RequestContext

wsgi_app(environ, start_response)¶

實際的 WSGI 應用程式。這並未在 __call__() 中實作，以便可以套用中介軟體，而不會遺失對應用程式物件的參考。而不是這樣做

app = MyMiddleware(app)

更好的做法是這樣做

app.wsgi_app = MyMiddleware(app.wsgi_app)

然後您仍然擁有原始的應用程式物件，並且可以繼續呼叫其方法。

變更日誌

Changed in version 0.7: 即使發生未處理的錯誤，也會呼叫請求和應用程式上下文的 Teardown 事件。其他事件可能不會被呼叫，具體取決於分派期間何時發生錯誤。請參閱回呼和錯誤。

參數:

environ (WSGIEnvironment) – WSGI 環境。
start_response (StartResponse) – 接受狀態碼、標頭列表和可選例外上下文以啟動回應的可呼叫物件。

回傳類型:

cabc.Iterable[bytes]

aborter_class¶: alias of Aborter

add_template_filter(f, name=None)¶

註冊自訂範本篩選器。運作方式與 template_filter() 修飾器完全相同。

參數:

name (str | None) – 篩選器的選用名稱，否則將使用函數名稱。
f (Callable[[...], Any])

回傳類型:

None

add_template_global(f, name=None)¶

註冊自訂範本全域函數。運作方式與 template_global() 修飾器完全相同。

變更日誌

Added in version 0.10.

參數:

name (str | None) – 全域函數的選用名稱，否則將使用函數名稱。
f (Callable[[...], Any])

回傳類型:

None

add_template_test(f, name=None)¶

註冊自訂範本測試。運作方式與 template_test() 修飾器完全相同。

變更日誌

Added in version 0.10.

參數:

name (str | None) – 測試的選用名稱，否則將使用函數名稱。
f (Callable[[...], bool])

回傳類型:

None

add_url_rule(rule, endpoint=None, view_func=None, provide_automatic_options=None, **options)¶

註冊用於路由傳入請求和建構 URL 的規則。route() 修飾器是使用 view_func 引數呼叫此方法的捷徑。以下兩者是等效的

@app.route("/")
def index():
    ...

def index():
    ...

app.add_url_rule("/", view_func=index)

參見 URL 路由註冊。

如果沒有傳遞 endpoint 參數，路由的端點名稱預設為檢視函式的名稱。如果該端點已註冊函式，則會引發錯誤。

methods 參數預設為 ["GET"]。HEAD 總是自動加入，而 OPTIONS 預設也會自動加入。

不一定需要傳遞 view_func，但如果規則應該參與路由，則必須在某個時間點使用 endpoint() 裝飾器將端點名稱與檢視函式建立關聯。

app.add_url_rule("/", endpoint="index")

@app.endpoint("index")
def index():
    ...

如果 view_func 具有 required_methods 屬性，這些方法會被加入到傳遞的和自動的方法中。如果它具有 provide_automatic_methods 屬性，則當參數未傳遞時，會將其用作預設值。

參數:

rule (str) – URL 規則字串。
endpoint (str | None) – 與規則和檢視函式關聯的端點名稱。用於路由和建立 URL 時。預設為 view_func.__name__。
view_func (ft.RouteCallable | None) – 與端點名稱關聯的檢視函式。
provide_automatic_options (bool | None) – 自動新增 OPTIONS 方法並回應 OPTIONS 請求。
options (t.Any) – 傳遞給 Rule 物件的額外選項。

回傳類型:

None

after_request(f)¶

註冊一個函式，使其在此物件的每個請求之後執行。

函式會使用回應物件呼叫，並且必須傳回回應物件。這允許函式在傳送回應之前修改或替換回應。

如果函式引發例外，則不會呼叫任何剩餘的 after_request 函式。因此，這不應該用於必須執行的動作，例如關閉資源。請改用 teardown_request()。

這在應用程式和藍圖物件上都可用。在應用程式上使用時，這會在每個請求之後執行。在藍圖上使用時，這會在藍圖處理的每個請求之後執行。若要在藍圖中註冊並在每個請求之後執行，請使用 Blueprint.after_app_request()。

參數:: f (T_after_request)
回傳類型:: T_after_request

app_ctx_globals_class¶: _AppCtxGlobals 的別名

auto_find_instance_path()¶

如果在應用程式類別的建構子中未提供實例路徑，則嘗試尋找實例路徑。它基本上會計算到一個名為 instance 的資料夾的路徑，該資料夾位於您的主要檔案或套件旁邊。

變更日誌

在 0.8 版本中新增。

回傳類型:: str

before_request(f)¶

註冊一個函式，使其在每個請求之前執行。

例如，這可用於開啟資料庫連線，或從 session 中載入已登入的使用者。

@app.before_request
def load_user():
    if "user_id" in session:
        g.user = db.session.get(session["user_id"])

函式將在不帶任何引數的情況下被呼叫。如果它傳回非 None 值，則該值會被視為來自檢視的傳回值，並且會停止進一步的請求處理。

這在應用程式和藍圖物件上都可用。在應用程式上使用時，這會在每個請求之前執行。在藍圖上使用時，這會在藍圖處理的每個請求之前執行。若要在藍圖中註冊並在每個請求之前執行，請使用 Blueprint.before_app_request()。

參數:: f (T_before_request)
回傳類型:: T_before_request

config_class¶: Config 的別名

context_processor(f)¶

註冊一個範本上下文處理器函式。這些函式在呈現範本之前執行。傳回的 dict 的鍵會新增為範本中可用的變數。

這在應用程式和藍圖物件上都可用。在應用程式上使用時，這會針對每個呈現的範本呼叫。在藍圖上使用時，這會針對從藍圖檢視呈現的範本呼叫。若要在藍圖中註冊並影響每個範本，請使用 Blueprint.app_context_processor()。

參數:: f (T_template_context_processor)
回傳類型:: T_template_context_processor

create_global_jinja_loader()¶

建立 Jinja2 環境的載入器。可用於僅覆寫載入器並保持其餘部分不變。不建議覆寫此函式。相反地，應該覆寫 jinja_loader() 函式。

全域載入器在應用程式和個別藍圖的載入器之間進行調度。

變更日誌

Added in version 0.7.

回傳類型:: DispatchingJinjaLoader

property debug: bool¶

是否啟用偵錯模式。當使用 flask run 啟動開發伺服器時，未處理的例外狀況會顯示互動式偵錯器，並且在程式碼變更時會重新載入伺服器。這對應到 DEBUG 設定鍵。如果設定得太晚，可能無法如預期般運作。

在生產環境部署時，請勿啟用偵錯模式。

預設值：False

delete(rule, **options)¶

route() 的快捷方式，使用 methods=["DELETE"]。

變更日誌

Added in version 2.0.

參數:

rule (str)
options (Any)

回傳類型:

Callable[[T_route], T_route]

endpoint(endpoint)¶

修飾檢視函式，以將其註冊到給定的端點。如果使用 add_url_rule() 新增規則時沒有 view_func，則會使用此裝飾器。

app.add_url_rule("/ex", endpoint="example")

@app.endpoint("example")
def example():
    ...

參數:: endpoint (str) – 要與檢視函式關聯的端點名稱。
回傳類型:: Callable[[F], F]

errorhandler(code_or_exception)¶

註冊一個函式，以依程式碼或例外類別處理錯誤。

一個裝飾器，用於註冊給定錯誤碼的函式。範例

@app.errorhandler(404)
def page_not_found(error):
    return 'This page does not exist', 404

您也可以為任意例外註冊處理常式

@app.errorhandler(DatabaseError)
def special_exception_handler(error):
    return 'Database connection failed', 500

這在應用程式和藍圖物件上都可用。在應用程式上使用時，這可以處理來自每個請求的錯誤。在藍圖上使用時，這可以處理來自藍圖處理的請求的錯誤。若要在藍圖中註冊並影響每個請求，請使用 Blueprint.app_errorhandler()。

變更日誌

在 0.7 版本中新增：對於應用程式範圍的錯誤處理常式，請使用 register_error_handler() 而不是直接修改 error_handler_spec。

在 0.7 版本中新增：現在還可以額外註冊自訂例外類型，這些類型不一定需要是 HTTPException 類別的子類別。

參數:: code_or_exception (type[Exception] | int) – 處理常式的程式碼（整數），或任意例外
回傳類型:: Callable[[T_error_handler], T_error_handler]

get(rule, **options)¶

route() 的快捷方式，使用 methods=["GET"]。

變更日誌

Added in version 2.0.

參數:

rule (str)
options (Any)

回傳類型:

Callable[[T_route], T_route]

handle_url_build_error(error, endpoint, values)¶

如果引發了 BuildError，則會由 url_for() 呼叫。如果此函式傳回值，則會由 url_for 傳回，否則將重新引發錯誤。

url_build_error_handlers 中的每個函式都會使用 error、endpoint 和 values 呼叫。如果函式傳回 None 或引發 BuildError，則會跳過它。否則，其傳回值會由 url_for 傳回。

參數:

error (BuildError) – 正在處理的活動 BuildError。
endpoint (str) – 正在建立的端點。
values (dict[str, Any]) – 傳遞給 url_for 的關鍵字引數。

回傳類型:

property has_static_folder: bool¶: 如果設定了 static_folder，則為 True。

變更日誌

在 0.5 版本中新增。

inject_url_defaults(endpoint, values)¶

將給定端點的 URL 預設值直接注入到傳遞的 values 字典中。這在內部使用，並在 URL 建立時自動呼叫。

變更日誌

Added in version 0.7.

參數:

endpoint (str)
values (dict[str, Any])

回傳類型:

None

iter_blueprints()¶

依照藍圖註冊的順序迭代所有藍圖。

變更日誌

在 0.11 版本中新增。

回傳類型:: t.ValuesView[Blueprint]

property jinja_env: Environment¶

用於載入範本的 Jinja 環境。

環境會在第一次存取此屬性時建立。之後變更 jinja_options 將不會有任何效果。

jinja_environment¶: Environment 的別名

property jinja_loader: BaseLoader | None¶: 此物件範本的 Jinja 載入器。預設情況下，如果設定了 template_folder，則這是一個指向 template_folder 的 jinja2.loaders.FileSystemLoader 類別。

變更日誌

在 0.5 版本中新增。

jinja_options: dict[str, t.Any] = {}¶: 在 create_jinja_environment() 中傳遞給 Jinja 環境的選項。在建立環境之後變更這些選項（存取 jinja_env）將不會有任何效果。

變更日誌

在 1.1.0 版本中變更：這是一個 dict 而不是 ImmutableDict，以允許更輕鬆的設定。

json_provider_class¶: DefaultJSONProvider 的別名

property logger: Logger¶

應用程式的標準 Python Logger，名稱與 name 相同。

在偵錯模式下，記錄器的 level 將設定為 DEBUG。

如果沒有設定任何處理常式，則會新增預設處理常式。請參閱記錄以取得更多資訊。

變更日誌

在 1.1.0 版本中變更：記錄器採用與 name 相同的名稱，而不是硬式編碼 "flask.app"。

在 1.0.0 版本中變更：行為已簡化。記錄器始終命名為 "flask.app"。層級僅在設定期間設定，它不會每次都檢查 app.debug。僅使用一種格式，而不是根據 app.debug 使用不同的格式。不會移除任何處理常式，並且僅在尚未設定任何處理常式時才新增處理常式。

Added in version 0.3.

make_aborter()¶

建立要指派給 aborter 的物件。該物件由 flask.abort() 呼叫以引發 HTTP 錯誤，也可以直接呼叫。

預設情況下，這會建立 aborter_class 的實例，預設值為 werkzeug.exceptions.Aborter。

變更日誌

在 2.2 版本中新增。

回傳類型:: Aborter

make_config(instance_relative=False)¶

由 Flask 建構子用於建立 config 屬性。instance_relative 參數從 Flask 的建構子傳入（在那裡命名為 instance_relative_config），並指示 config 應該相對於實例路徑還是應用程式的根路徑。

變更日誌

在 0.8 版本中新增。

參數:: instance_relative (bool)
回傳類型:: Config

property name: str¶: 應用程式的名稱。這通常是匯入名稱，不同之處在於，如果匯入名稱是 main，則會從執行檔中猜測出來。當 Flask 需要應用程式的名稱時，此名稱會用作顯示名稱。可以設定和覆寫以變更值。

變更日誌

在 0.8 版本中新增。

patch(rule, **options)¶

route() 的快捷方式，使用 methods=["PATCH"]。

變更日誌

Added in version 2.0.

參數:

rule (str)
options (Any)

回傳類型:

Callable[[T_route], T_route]

permanent_session_lifetime¶

一個 timedelta，用於設定永久 session 的到期日。預設值為 31 天，這使得永久 session 大約可以存活一個月。

此屬性也可以從 config 中使用 PERMANENT_SESSION_LIFETIME 設定鍵進行設定。預設值為 timedelta(days=31)

post(rule, **options)¶

route() 的快捷方式，使用 methods=["POST"]。

變更日誌

Added in version 2.0.

參數:

rule (str)
options (Any)

回傳類型:

Callable[[T_route], T_route]

put(rule, **options)¶

route() 的快捷方式，使用 methods=["PUT"]。

變更日誌

Added in version 2.0.

參數:

rule (str)
options (Any)

回傳類型:

Callable[[T_route], T_route]

redirect(location, code=302)¶

建立重新導向回應物件。

這由 flask.redirect() 呼叫，也可以直接呼叫。

參數:

location (str) – 要重新導向的 URL。
code (int) – 重新導向的狀態碼。

回傳類型:

BaseResponse

變更日誌

Added in version 2.2: 從 flask.redirect 移動而來，該函式會呼叫此方法。

register_blueprint(blueprint, **options)¶

在應用程式上註冊 Blueprint。傳遞給此方法的關鍵字引數將覆寫在藍圖上設定的預設值。

在應用程式的 blueprints 中記錄藍圖後，呼叫藍圖的 register() 方法。

參數:

blueprint (Blueprint) – 要註冊的藍圖。
url_prefix – 藍圖路由將以此為前綴。
subdomain – 藍圖路由將在此子網域上匹配。
url_defaults – 藍圖路由將對檢視函式引數使用這些預設值。
options (t.Any) – 額外的關鍵字引數會傳遞至 BlueprintSetupState。它們可以在 record() 回呼中存取。

回傳類型:

None

變更日誌

Changed in version 2.0.1: name 選項可用於變更藍圖註冊時使用的（前綴點號）名稱。這允許同一個藍圖使用唯一的名稱多次註冊，以用於 url_for。

Added in version 0.7.

register_error_handler(code_or_exception, f)¶

替代的錯誤附加函式，用於 errorhandler() 裝飾器，對於非裝飾器用法更為直接易用。

變更日誌

Added in version 0.7.

參數:

code_or_exception (type[Exception] | int)
f (ft.ErrorHandlerCallable)

回傳類型:

None

route(rule, **options)¶

裝飾器，用於註冊具有給定 URL 規則和選項的檢視函式。呼叫 add_url_rule()，其中包含有關實作的更多詳細資訊。

@app.route("/")
def index():
    return "Hello, World!"

參見 URL 路由註冊。

如果未傳遞 endpoint 參數，則路由的端點名稱預設為檢視函式的名稱。

methods 參數預設為 ["GET"]。HEAD 和 OPTIONS 會自動新增。

參數:

rule (str) – URL 規則字串。
options (Any) – 傳遞至 Rule 物件的額外選項。

回傳類型:

Callable[[T_route], T_route]

secret_key¶

如果設定了密鑰，密碼編譯元件可以使用它來簽署 Cookie 和其他內容。當您想要使用安全 Cookie 時，請將其設定為複雜的隨機值。

此屬性也可以從組態中透過 SECRET_KEY 組態金鑰進行組態。預設值為 None。

select_jinja_autoescape(filename)¶

如果應該為給定的模板名稱啟用自動跳脫，則傳回 True。如果未給定模板名稱，則傳回 True。

變更日誌

Changed in version 2.2: 現在預設為 .svg 檔案啟用自動跳脫。

在 0.5 版本中新增。

參數:: filename (str)
回傳類型:: bool

shell_context_processor(f)¶

註冊 Shell 環境處理器函式。

變更日誌

在 0.11 版本中新增。

參數:: f (T_shell_context_processor)
回傳類型:: T_shell_context_processor

should_ignore_error(error)¶

呼叫此函式以判斷是否應忽略錯誤，就拆解系統而言。如果此函式傳回 True，則拆解處理常式將不會傳遞錯誤。

變更日誌

Added in version 0.10.

參數:: error (BaseException | None)
回傳類型:: bool

property static_folder: str | None¶: 已組態靜態資料夾的絕對路徑。如果未設定靜態資料夾，則為 None。

property static_url_path: str | None¶

靜態路由可存取的 URL 前綴。

如果在初始化期間未組態，則會從 static_folder 衍生而來。

teardown_appcontext(f)¶

註冊一個函式，在應用程式環境內容彈出時呼叫。應用程式環境內容通常會在每個請求的請求環境內容之後、CLI 命令結束時或手動推送的環境內容結束後彈出。

with app.app_context():
    ...

當 with 區塊結束（或呼叫 ctx.pop()）時，會在應用程式環境內容變為非活動狀態之前呼叫拆解函式。由於請求環境內容通常也管理應用程式環境內容，因此在您彈出請求環境內容時也會呼叫它。

當由於未處理的例外狀況而呼叫拆解函式時，它將會傳遞一個錯誤物件。如果註冊了 errorhandler()，它將處理例外狀況，而拆解函式將不會收到它。

拆解函式必須避免引發例外狀況。如果它們執行的程式碼可能會失敗，則必須將該程式碼用 try/except 區塊包圍，並記錄任何錯誤。

拆解函式的傳回值會被忽略。

變更日誌

在 0.9 版本中新增。

參數:: f (T_teardown)
回傳類型:: T_teardown

teardown_request(f)¶

註冊一個函式，在請求環境內容彈出時呼叫。通常這會在每個請求結束時發生，但在測試期間也可以手動推送環境內容。

with app.test_request_context():
    ...

當 with 區塊結束（或呼叫 ctx.pop()）時，會在請求環境內容變為非活動狀態之前呼叫拆解函式。

當由於未處理的例外狀況而呼叫拆解函式時，它將會傳遞一個錯誤物件。如果註冊了 errorhandler()，它將處理例外狀況，而拆解函式將不會收到它。

拆解函式必須避免引發例外狀況。如果它們執行的程式碼可能會失敗，則必須將該程式碼用 try/except 區塊包圍，並記錄任何錯誤。

拆解函式的傳回值會被忽略。

這在應用程式和藍圖物件上都可用。在應用程式上使用時，這會在每個請求之後執行。在藍圖上使用時，這會在藍圖處理的每個請求之後執行。若要向藍圖註冊並在每個請求之後執行，請使用 Blueprint.teardown_app_request()。

參數:: f (T_teardown)
回傳類型:: T_teardown

template_filter(name=None)¶

用於註冊自訂模板篩選器的裝飾器。您可以為篩選器指定名稱，否則將使用函式名稱。範例

@app.template_filter()
def reverse(s):
    return s[::-1]

參數:: name (str | None) – 篩選器的選用名稱，否則將使用函數名稱。
回傳類型:: Callable[[T_template_filter], T_template_filter]

template_global(name=None)¶

用於註冊自訂模板全域函式的裝飾器。您可以為全域函式指定名稱，否則將使用函式名稱。範例

@app.template_global()
def double(n):
    return 2 * n

變更日誌

Added in version 0.10.

參數:: name (str | None) – 全域函數的選用名稱，否則將使用函數名稱。
回傳類型:: Callable[[T_template_global], T_template_global]

template_test(name=None)¶

用於註冊自訂模板測試的裝飾器。您可以為測試指定名稱，否則將使用函式名稱。範例

@app.template_test()
def is_prime(n):
    if n == 2:
        return True
    for i in range(2, int(math.ceil(math.sqrt(n))) + 1):
        if n % i == 0:
            return False
    return True

變更日誌

Added in version 0.10.

參數:: name (str | None) – 測試的選用名稱，否則將使用函數名稱。
回傳類型:: Callable[[T_template_test], T_template_test]

test_cli_runner_class: type[FlaskCliRunner] | None = None¶: CliRunner 子類別，預設為 FlaskCliRunner，由 test_cli_runner() 使用。其 __init__ 方法應將 Flask 應用程式物件作為第一個引數。

變更日誌

在 1.0 版本中新增。

test_client_class: type[FlaskClient] | None = None¶: test_client() 方法會建立此測試用戶端類別的實例。預設值為 FlaskClient。

變更日誌

Added in version 0.7.

testing¶

測試旗標。將其設定為 True 以啟用 Flask 擴充功能的測試模式（以及未來可能也包括 Flask 本身）。例如，這可能會啟用具有額外執行階段成本的測試輔助程式，這些輔助程式預設不應啟用。

如果啟用此功能，且 PROPAGATE_EXCEPTIONS 未從預設值變更，則會隱含地啟用此功能。

此屬性也可以從組態中透過 TESTING 組態金鑰進行組態。預設值為 False。

trap_http_exception(e)¶

檢查是否應攔截 HTTP 例外狀況。預設情況下，對於所有例外狀況，這將傳回 False，除非在 TRAP_BAD_REQUEST_ERRORS 設定為 True 時，發生錯誤請求金鑰錯誤。如果 TRAP_HTTP_EXCEPTIONS 設定為 True，它也會傳回 True。

對於檢視函式引發的所有 HTTP 例外狀況，都會呼叫此函式。如果它為任何例外狀況傳回 True，則不會呼叫此例外狀況的錯誤處理常式，並且它會在追溯中顯示為一般例外狀況。這對於偵錯隱含引發的 HTTP 例外狀況很有幫助。

變更日誌

Changed in version 1.0: 在偵錯模式下，預設情況下不會攔截錯誤請求錯誤。

在 0.8 版本中新增。

參數:: e (Exception)
回傳類型:: bool

url_defaults(f)¶

應用程式所有檢視函式的 URL 預設值的回呼函式。它會使用端點和值呼叫，並應就地更新傳遞的值。

這在應用程式和藍圖物件上都可用。在應用程式上使用時，這會為每個請求呼叫。在藍圖上使用時，這會為藍圖處理的請求呼叫。若要向藍圖註冊並影響每個請求，請使用 Blueprint.app_url_defaults()。

參數:: f (T_url_defaults)
回傳類型:: T_url_defaults

url_map_class¶: Map 的別名

url_rule_class¶: Rule 的別名

url_value_preprocessor(f)¶

為應用程式中的所有檢視函式註冊 URL 值預處理器函式。這些函式將在 before_request() 函式之前呼叫。

該函式可以在將值傳遞給檢視之前，修改從匹配的 URL 捕獲的值。例如，這可以用於彈出常見的語言代碼值並將其放置在 g 中，而不是將其傳遞給每個檢視。

該函式會傳遞端點名稱和值字典。傳回值會被忽略。

這在應用程式和藍圖物件上都可用。在應用程式上使用時，這會為每個請求呼叫。在藍圖上使用時，這會為藍圖處理的請求呼叫。若要向藍圖註冊並影響每個請求，請使用 Blueprint.app_url_value_preprocessor()。

參數:: f (T_url_value_preprocessor)
回傳類型:: T_url_value_preprocessor

instance_path¶: 保留實例資料夾的路徑。

變更日誌

在 0.8 版本中新增。

config¶: 組態字典，如同 Config。這與常規字典的行為完全相同，但支援從檔案載入組態的其他方法。

aborter¶: aborter_class 的實例，由 make_aborter() 建立。flask.abort() 呼叫此函式以引發 HTTP 錯誤，也可以直接呼叫。

變更日誌

Added in version 2.2: 從 flask.abort 移動而來，該函式會呼叫此物件。

json: JSONProvider¶

提供對 JSON 方法的存取權。flask.json 中的函式將在應用程式環境內容處於活動狀態時呼叫此提供者的方法。用於處理 JSON 請求和回應。

json_provider_class 的實例。可以透過變更子類別上的該屬性或之後指派給此屬性來自訂。

預設值 DefaultJSONProvider 使用 Python 的內建 json 程式庫。不同的提供者可以使用不同的 JSON 程式庫。

變更日誌

在 2.2 版本中新增。

url_build_error_handlers: list[t.Callable[[Exception, str, dict[str, t.Any]], str]]¶: 當 url_for() 引發 BuildError 時，handle_url_build_error() 呼叫的函式清單。每個函式都使用 error、endpoint 和 values 呼叫。如果函式傳回 None 或引發 BuildError，則會跳過它。否則，其傳回值會由 url_for 傳回。

變更日誌

在 0.9 版本中新增。

teardown_appcontext_funcs: list[ft.TeardownCallable]¶: 應用程式環境內容被銷毀時呼叫的函式清單。由於應用程式環境內容也會在請求結束時拆解，因此這是儲存與資料庫斷開連線的程式碼的位置。

變更日誌

在 0.9 版本中新增。

shell_context_processors: list[ft.ShellContextProcessorCallable]¶: Shell 環境處理器函式的清單，應在建立 Shell 環境時執行。

變更日誌

在 0.11 版本中新增。

blueprints: dict[str, Blueprint]¶: 將已註冊的藍圖名稱映射到藍圖物件。字典保留藍圖註冊的順序。藍圖可以多次註冊，此字典不追蹤它們被附加的頻率。

變更日誌

Added in version 0.7.

extensions: dict[str, t.Any]¶

擴充套件可以儲存應用程式特定狀態的地方。例如，擴充套件可以在這裡儲存資料庫引擎和類似的東西。

鍵值必須符合擴充套件模組的名稱。例如，對於 flask_foo 中的 “Flask-Foo” 擴充套件，鍵值會是 'foo'。

變更日誌

Added in version 0.7.

url_map¶

此實例的 Map。您可以使用它在類別建立之後但在任何路由連接之前，變更路由轉換器。範例

from werkzeug.routing import BaseConverter

class ListConverter(BaseConverter):
    def to_python(self, value):
        return value.split(',')
    def to_url(self, values):
        return ','.join(super(ListConverter, self).to_url(value)
                        for value in values)

app = Flask(__name__)
app.url_map.converters['list'] = ListConverter

import_name¶: 此物件所屬的套件或模組名稱。一旦由建構子設定後，請勿變更此名稱。

template_folder¶: 範本資料夾的路徑，相對於 root_path，要加入到範本載入器。None 表示不應加入範本。

root_path¶: 檔案系統上套件的絕對路徑。用於查找套件中包含的資源。

view_functions: dict[str, ft.RouteCallable]¶

將端點名稱對應到視圖函式的字典。

若要註冊視圖函式，請使用 route() 裝飾器。

此資料結構為內部結構。不應直接修改，其格式可能隨時變更。

error_handler_spec: dict[ft.AppOrBlueprintKey, dict[int | None, dict[type[Exception], ft.ErrorHandlerCallable]]]¶

已註冊錯誤處理器的資料結構，格式為 {scope: {code: {class: handler}}}。scope 鍵值是處理器作用的藍圖名稱，或 None 表示適用於所有請求。code 鍵值是 HTTPException 的 HTTP 狀態碼，或 None 表示其他例外狀況。最內層的字典將例外狀況類別對應到處理器函式。

若要註冊錯誤處理器，請使用 errorhandler() 裝飾器。

此資料結構為內部結構。不應直接修改，其格式可能隨時變更。

before_request_funcs: dict[ft.AppOrBlueprintKey, list[ft.BeforeRequestCallable]]¶

在每個請求開始時呼叫的函式資料結構，格式為 {scope: [functions]}。scope 鍵值是函式作用的藍圖名稱，或 None 表示適用於所有請求。

若要註冊函式，請使用 before_request() 裝飾器。

此資料結構為內部結構。不應直接修改，其格式可能隨時變更。

after_request_funcs: dict[ft.AppOrBlueprintKey, list[ft.AfterRequestCallable[t.Any]]]¶

在每個請求結束時呼叫的函式資料結構，格式為 {scope: [functions]}。scope 鍵值是函式作用的藍圖名稱，或 None 表示適用於所有請求。

若要註冊函式，請使用 after_request() 裝飾器。

此資料結構為內部結構。不應直接修改，其格式可能隨時變更。

teardown_request_funcs: dict[ft.AppOrBlueprintKey, list[ft.TeardownCallable]]¶

即使引發例外狀況，在每個請求結束時仍會呼叫的函式資料結構，格式為 {scope: [functions]}。scope 鍵值是函式作用的藍圖名稱，或 None 表示適用於所有請求。

若要註冊函式，請使用 teardown_request() 裝飾器。

此資料結構為內部結構。不應直接修改，其格式可能隨時變更。

template_context_processors: dict[ft.AppOrBlueprintKey, list[ft.TemplateContextProcessorCallable]]¶

在呈現範本時呼叫以傳遞額外上下文值的函式資料結構，格式為 {scope: [functions]}。scope 鍵值是函式作用的藍圖名稱，或 None 表示適用於所有請求。

若要註冊函式，請使用 context_processor() 裝飾器。

此資料結構為內部結構。不應直接修改，其格式可能隨時變更。

url_value_preprocessors: dict[ft.AppOrBlueprintKey, list[ft.URLValuePreprocessorCallable]]¶

呼叫以修改傳遞到視圖函式的關鍵字引數的函式資料結構，格式為 {scope: [functions]}。scope 鍵值是函式作用的藍圖名稱，或 None 表示適用於所有請求。

若要註冊函式，請使用 url_value_preprocessor() 裝飾器。

此資料結構為內部結構。不應直接修改，其格式可能隨時變更。

url_default_functions: dict[ft.AppOrBlueprintKey, list[ft.URLDefaultCallable]]¶

呼叫以修改產生 URL 時的關鍵字引數的函式資料結構，格式為 {scope: [functions]}。scope 鍵值是函式作用的藍圖名稱，或 None 表示適用於所有請求。

若要註冊函式，請使用 url_defaults() 裝飾器。

此資料結構為內部結構。不應直接修改，其格式可能隨時變更。

藍圖物件¶

class flask.Blueprint(name, import_name, static_folder=None, static_url_path=None, template_folder=None, url_prefix=None, subdomain=None, url_defaults=None, root_path=None, cli_group=_sentinel)¶

參數:

name (str)
import_name (str)
static_folder (str | os.PathLike[str] | None)
static_url_path (str | None)
template_folder (str | os.PathLike[str] | None)
url_prefix (str | None)
subdomain (str | None)
url_defaults (dict[str, t.Any] | None)
root_path (str | None)
cli_group (str | None)

cli: Group¶: 用於為此物件註冊 CLI 命令的 Click 命令群組。一旦發現應用程式並註冊了藍圖，這些命令就可以從 flask 命令中使用。

get_send_file_max_age(filename)¶

由 send_file() 用於確定給定檔案路徑的 max_age 快取值（如果未傳遞）。

預設情況下，這會從 SEND_FILE_MAX_AGE_DEFAULT（current_app 的設定）傳回。這預設為 None，這會告知瀏覽器使用條件請求而不是定時快取，這通常是更可取的。

請注意，這與 Flask 類別中的相同方法重複。

變更日誌

在 2.0 版本中變更: 預設設定為 None 而不是 12 小時。

在 0.9 版本中新增。

參數:: filename (str | None)
回傳類型:: int | None

send_static_file(filename)¶

用於從 static_folder 提供檔案的視圖函式。如果設定了 static_folder，則會自動在 static_url_path 註冊此視圖的路由。

請注意，這與 Flask 類別中的相同方法重複。

變更日誌

在 0.5 版本中新增。

參數:: filename (str)
回傳類型:: 回應

open_resource(resource, mode='rb', encoding='utf-8')¶

開啟相對於 root_path 的資源檔案以進行讀取。藍圖相關的等效方法，如同應用程式的 open_resource() 方法。

參數:

resource (str) – 相對於 root_path 的資源路徑。
mode (str) – 在此模式下開啟檔案。僅支援讀取，有效值為 "r" （或 "rt"）和 "rb"。
encoding (str | None) – 以文字模式開啟時，使用此編碼開啟檔案。以二進制模式開啟時，這將被忽略。

回傳類型:

IO

在 3.1 版本中變更: 新增了 encoding 參數。

add_app_template_filter(f, name=None)¶

註冊一個範本過濾器，在應用程式呈現的任何範本中都可用。作用如同 app_template_filter() 裝飾器。等同於 Flask.add_template_filter()。

參數:

name (str | None) – 篩選器的選用名稱，否則將使用函數名稱。
f (Callable[[...], Any])

回傳類型:

None

add_app_template_global(f, name=None)¶

註冊一個範本全域變數，在應用程式呈現的任何範本中都可用。作用如同 app_template_global() 裝飾器。等同於 Flask.add_template_global()。

變更日誌

Added in version 0.10.

參數:

name (str | None) – 全域變數的可選名稱，否則將使用函式名稱。
f (Callable[[...], Any])

回傳類型:

None

add_app_template_test(f, name=None)¶

註冊一個範本測試，在應用程式呈現的任何範本中都可用。作用如同 app_template_test() 裝飾器。等同於 Flask.add_template_test()。

變更日誌

Added in version 0.10.

參數:

name (str | None) – 測試的選用名稱，否則將使用函數名稱。
f (Callable[[...], bool])

回傳類型:

None

add_url_rule(rule, endpoint=None, view_func=None, provide_automatic_options=None, **options)¶

向藍圖註冊 URL 規則。請參閱 Flask.add_url_rule() 以取得完整文件。

URL 規則會加上藍圖的 URL 前綴。與 url_for() 一起使用的端點名稱，會加上藍圖的名稱前綴。

參數:

rule (str)
endpoint (str | None)
view_func (ft.RouteCallable | None)
provide_automatic_options (bool | None)
options (t.Any)

回傳類型:

None

after_app_request(f)¶

如同 after_request()，但在每個請求之後執行，而不僅限於藍圖處理的請求。等同於 Flask.after_request()。

參數:: f (T_after_request)
回傳類型:: T_after_request

after_request(f)¶

註冊一個函式，使其在此物件的每個請求之後執行。

函式會使用回應物件呼叫，並且必須傳回回應物件。這允許函式在傳送回應之前修改或替換回應。

如果函式引發例外狀況，則任何剩餘的 after_request 函式都不會被呼叫。因此，不應將其用於必須執行的動作，例如關閉資源。請改用 teardown_request()。

這在應用程式和藍圖物件上都可用。在應用程式上使用時，這會在每個請求之後執行。在藍圖上使用時，這會在藍圖處理的每個請求之後執行。若要在藍圖中註冊並在每個請求之後執行，請使用 Blueprint.after_app_request()。

參數:: f (T_after_request)
回傳類型:: T_after_request

app_context_processor(f)¶

如同 context_processor()，但適用於每個視圖呈現的範本，而不僅限於藍圖。等同於 Flask.context_processor()。

參數:: f (T_template_context_processor)
回傳類型:: T_template_context_processor

app_errorhandler(code)¶

如同 errorhandler()，但適用於每個請求，而不僅限於藍圖處理的請求。等同於 Flask.errorhandler()。

參數:: code (type[Exception] | int)
回傳類型:: Callable[[T_error_handler], T_error_handler]

app_template_filter(name=None)¶

註冊一個範本過濾器，在應用程式呈現的任何範本中都可用。等同於 Flask.template_filter()。

參數:: name (str | None) – 篩選器的選用名稱，否則將使用函數名稱。
回傳類型:: Callable[[T_template_filter], T_template_filter]

app_template_global(name=None)¶

註冊一個範本全域變數，在應用程式呈現的任何範本中都可用。等同於 Flask.template_global()。

變更日誌

Added in version 0.10.

參數:: name (str | None) – 全域變數的可選名稱，否則將使用函式名稱。
回傳類型:: Callable[[T_template_global], T_template_global]

app_template_test(name=None)¶

註冊一個範本測試，在應用程式呈現的任何範本中都可用。等同於 Flask.template_test()。

變更日誌

Added in version 0.10.

參數:: name (str | None) – 測試的選用名稱，否則將使用函數名稱。
回傳類型:: Callable[[T_template_test], T_template_test]

app_url_defaults(f)¶

如同 url_defaults()，但適用於每個請求，而不僅限於藍圖處理的請求。等同於 Flask.url_defaults()。

參數:: f (T_url_defaults)
回傳類型:: T_url_defaults

app_url_value_preprocessor(f)¶

如同 url_value_preprocessor()，但適用於每個請求，而不僅限於藍圖處理的請求。等同於 Flask.url_value_preprocessor()。

參數:: f (T_url_value_preprocessor)
回傳類型:: T_url_value_preprocessor

before_app_request(f)¶

如同 before_request()，但在每個請求之前執行，而不僅限於藍圖處理的請求。等同於 Flask.before_request()。

參數:: f (T_before_request)
回傳類型:: T_before_request

before_request(f)¶

註冊一個函式，使其在每個請求之前執行。

例如，這可用於開啟資料庫連線，或從 session 中載入已登入的使用者。

@app.before_request
def load_user():
    if "user_id" in session:
        g.user = db.session.get(session["user_id"])

函式將在不帶任何引數的情況下被呼叫。如果它傳回非 None 值，則該值會被視為來自檢視的傳回值，並且會停止進一步的請求處理。

這在應用程式和藍圖物件上都可用。在應用程式上使用時，這會在每個請求之前執行。在藍圖上使用時，這會在藍圖處理的每個請求之前執行。若要在藍圖中註冊並在每個請求之前執行，請使用 Blueprint.before_app_request()。

參數:: f (T_before_request)
回傳類型:: T_before_request

context_processor(f)¶

註冊一個範本上下文處理器函式。這些函式在呈現範本之前執行。傳回的 dict 的鍵會新增為範本中可用的變數。

這在應用程式和藍圖物件上都可用。在應用程式上使用時，這會針對每個呈現的範本呼叫。在藍圖上使用時，這會針對從藍圖檢視呈現的範本呼叫。若要在藍圖中註冊並影響每個範本，請使用 Blueprint.app_context_processor()。

參數:: f (T_template_context_processor)
回傳類型:: T_template_context_processor

delete(rule, **options)¶

用於 route() 的快捷方式，帶有 methods=["DELETE"]。

變更日誌

Added in version 2.0.

參數:

rule (str)
options (Any)

回傳類型:

Callable[[T_route], T_route]

endpoint(endpoint)¶

裝飾視圖函式以將其註冊到給定的端點。如果使用 add_url_rule() 新增規則時沒有 view_func，則使用此方法。

app.add_url_rule("/ex", endpoint="example")

@app.endpoint("example")
def example():
    ...

參數:: endpoint (str) – 要與檢視函式關聯的端點名稱。
回傳類型:: Callable[[F], F]

errorhandler(code_or_exception)¶

註冊一個函式，以依程式碼或例外類別處理錯誤。

一個裝飾器，用於註冊給定錯誤碼的函式。範例

@app.errorhandler(404)
def page_not_found(error):
    return 'This page does not exist', 404

您也可以為任意例外註冊處理常式

@app.errorhandler(DatabaseError)
def special_exception_handler(error):
    return 'Database connection failed', 500

這在應用程式和藍圖物件上都可用。在應用程式上使用時，這可以處理來自每個請求的錯誤。在藍圖上使用時，這可以處理來自藍圖處理的請求的錯誤。若要在藍圖中註冊並影響每個請求，請使用 Blueprint.app_errorhandler()。

變更日誌

在版本 0.7 中新增: 使用 register_error_handler() 而不是直接修改 error_handler_spec，以用於應用程式範圍的錯誤處理器。

在 0.7 版本中新增：現在還可以額外註冊自訂例外類型，這些類型不一定需要是 HTTPException 類別的子類別。

參數:: code_or_exception (type[Exception] | int) – 處理常式的程式碼（整數），或任意例外
回傳類型:: Callable[[T_error_handler], T_error_handler]

get(rule, **options)¶

用於 route() 的快捷方式，帶有 methods=["GET"]。

變更日誌

Added in version 2.0.

參數:

rule (str)
options (Any)

回傳類型:

Callable[[T_route], T_route]

屬性 has_static_folder: bool¶: True 如果 static_folder 已設定。

變更日誌

在 0.5 版本中新增。

屬性 jinja_loader: BaseLoader | None¶: 此物件範本的 Jinja 載入器。預設情況下，如果 template_folder 有設定，則為指向它的 jinja2.loaders.FileSystemLoader 類別。

變更日誌

在 0.5 版本中新增。

make_setup_state(app, options, first_registration=False)¶

建立 BlueprintSetupState() 物件的實例，該物件稍後會傳遞給註冊回呼函式。子類別可以覆寫此方法以回傳設定狀態的子類別。

參數:

app (App)
options (dict[str, t.Any])
first_registration (bool)

回傳類型:

BlueprintSetupState

patch(rule, **options)¶

使用 methods=["PATCH"] 的 route() 的快捷方式。

變更日誌

Added in version 2.0.

參數:

rule (str)
options (Any)

回傳類型:

Callable[[T_route], T_route]

post(rule, **options)¶

使用 methods=["POST"] 的 route() 的快捷方式。

變更日誌

Added in version 2.0.

參數:

rule (str)
options (Any)

回傳類型:

Callable[[T_route], T_route]

put(rule, **options)¶

使用 methods=["PUT"] 的 route() 的快捷方式。

變更日誌

Added in version 2.0.

參數:

rule (str)
options (Any)

回傳類型:

Callable[[T_route], T_route]

record(func)¶

註冊一個函式，當藍圖在應用程式上註冊時會呼叫該函式。此函式會以狀態作為引數呼叫，該狀態由 make_setup_state() 方法回傳。

參數:: func (Callable[[BlueprintSetupState], None])
回傳類型:: None

record_once(func)¶

作用類似 record()，但會將函式包裝在另一個函式中，以確保該函式只會被呼叫一次。如果藍圖在應用程式上第二次註冊，則不會呼叫傳遞的函式。

參數:: func (Callable[[BlueprintSetupState], None])
回傳類型:: None

register(app, options)¶

由 Flask.register_blueprint() 呼叫，以向應用程式註冊在藍圖上註冊的所有視圖和回呼。建立 BlueprintSetupState 並使用它呼叫每個 record() 回呼。

參數:

app (App) – 此藍圖正在註冊的應用程式。
options (dict[str, t.Any]) – 從 register_blueprint() 轉發的關鍵字引數。

回傳類型:

None

變更日誌

變更於版本 2.3: 巢狀藍圖現在可以正確地套用子網域。

變更於版本 2.1: 多次使用相同名稱註冊相同的藍圖會產生錯誤。

變更於版本 2.0.1: 巢狀藍圖會使用它們的點狀名稱註冊。這允許同名的不同藍圖巢狀在不同的位置。

Changed in version 2.0.1: name 選項可用於變更藍圖註冊時使用的（前綴點號）名稱。這允許同一個藍圖使用唯一的名稱多次註冊，以用於 url_for。

register_blueprint(blueprint, **options)¶

在此藍圖上註冊一個 Blueprint。傳遞給此方法的關鍵字引數將覆寫在藍圖上設定的預設值。

變更日誌

Changed in version 2.0.1: name 選項可用於變更藍圖註冊時使用的（前綴點號）名稱。這允許同一個藍圖使用唯一的名稱多次註冊，以用於 url_for。

Added in version 2.0.

參數:

blueprint (Blueprint)
options (Any)

回傳類型:

None

register_error_handler(code_or_exception, f)¶

用於 errorhandler() 裝飾器的替代錯誤附加函式，對於非裝飾器用法更為直接。

變更日誌

Added in version 0.7.

參數:

code_or_exception (type[Exception] | int)
f (ft.ErrorHandlerCallable)

回傳類型:

None

route(rule, **options)¶

裝飾視圖函式，以使用給定的 URL 規則和選項註冊它。呼叫 add_url_rule()，其中有關於實作的更多詳細資訊。

@app.route("/")
def index():
    return "Hello, World!"

參見 URL 路由註冊。

如果未傳遞 endpoint 參數，則路由的端點名稱預設為檢視函式的名稱。

methods 參數預設為 ["GET"]。HEAD 和 OPTIONS 會自動新增。

參數:

rule (str) – URL 規則字串。
options (Any) – 傳遞至 Rule 物件的額外選項。

回傳類型:

Callable[[T_route], T_route]

屬性 static_folder: str | None¶: 已組態靜態資料夾的絕對路徑。如果未設定靜態資料夾，則為 None。

屬性 static_url_path: str | None¶

靜態路由可存取的 URL 前綴。

如果它在初始化期間未設定，則從 static_folder 衍生而來。

teardown_app_request(f)¶

類似 teardown_request()，但在每次請求之後，而不僅僅是藍圖處理的請求。等同於 Flask.teardown_request()。

參數:: f (T_teardown)
回傳類型:: T_teardown

teardown_request(f)¶

註冊一個函式，在請求環境內容彈出時呼叫。通常這會在每個請求結束時發生，但在測試期間也可以手動推送環境內容。

with app.test_request_context():
    ...

當 with 區塊結束（或呼叫 ctx.pop()）時，會在請求環境內容變為非活動狀態之前呼叫拆解函式。

當由於未處理的例外狀況而呼叫拆解函式時，它將被傳遞一個錯誤物件。如果註冊了 errorhandler()，它將處理例外狀況，而拆解函式將不會收到它。

拆解函式必須避免引發例外狀況。如果它們執行的程式碼可能會失敗，則必須將該程式碼用 try/except 區塊包圍，並記錄任何錯誤。

拆解函式的傳回值會被忽略。

這在應用程式和藍圖物件上都可用。在應用程式上使用時，這會在每個請求之後執行。在藍圖上使用時，這會在藍圖處理的每個請求之後執行。若要向藍圖註冊並在每個請求之後執行，請使用 Blueprint.teardown_app_request()。

參數:: f (T_teardown)
回傳類型:: T_teardown

url_defaults(f)¶

應用程式所有檢視函式的 URL 預設值的回呼函式。它會使用端點和值呼叫，並應就地更新傳遞的值。

這在應用程式和藍圖物件上都可用。在應用程式上使用時，這會為每個請求呼叫。在藍圖上使用時，這會為藍圖處理的請求呼叫。若要向藍圖註冊並影響每個請求，請使用 Blueprint.app_url_defaults()。

參數:: f (T_url_defaults)
回傳類型:: T_url_defaults

url_value_preprocessor(f)¶

為應用程式中的所有視圖函式註冊 URL 值預處理器函式。這些函式將在 before_request() 函式之前呼叫。

該函式可以在將值傳遞給檢視之前，修改從匹配的 URL 捕獲的值。例如，這可以用於彈出常見的語言代碼值並將其放置在 g 中，而不是將其傳遞給每個檢視。

該函式會傳遞端點名稱和值字典。傳回值會被忽略。

這在應用程式和藍圖物件上都可用。在應用程式上使用時，這會為每個請求呼叫。在藍圖上使用時，這會為藍圖處理的請求呼叫。若要向藍圖註冊並影響每個請求，請使用 Blueprint.app_url_value_preprocessor()。

參數:: f (T_url_value_preprocessor)
回傳類型:: T_url_value_preprocessor

import_name¶: 此物件所屬的套件或模組名稱。一旦由建構子設定後，請勿變更此名稱。

template_folder¶: 範本資料夾的路徑，相對於 root_path，以新增至範本載入器。None 如果不應新增範本。

root_path¶: 檔案系統上套件的絕對路徑。用於查找套件中包含的資源。

view_functions: dict[str, ft.RouteCallable]¶

將端點名稱對應到視圖函式的字典。

若要註冊視圖函式，請使用 route() 裝飾器。

此資料結構為內部結構。不應直接修改，其格式可能隨時變更。

error_handler_spec: dict[ft.AppOrBlueprintKey, dict[int | None, dict[type[Exception], ft.ErrorHandlerCallable]]]¶

已註冊錯誤處理器的資料結構，格式為 {scope: {code: {class: handler}}}。scope 鍵值是處理器作用的藍圖名稱，或 None 表示適用於所有請求。code 鍵值是 HTTPException 的 HTTP 狀態碼，或 None 表示其他例外狀況。最內層的字典將例外狀況類別對應到處理器函式。

若要註冊錯誤處理常式，請使用 errorhandler() 裝飾器。

此資料結構為內部結構。不應直接修改，其格式可能隨時變更。

before_request_funcs: dict[ft.AppOrBlueprintKey, list[ft.BeforeRequestCallable]]¶

在每個請求開始時呼叫的函式資料結構，格式為 {scope: [functions]}。scope 鍵值是函式作用的藍圖名稱，或 None 表示適用於所有請求。

若要註冊函式，請使用 before_request() 裝飾器。

此資料結構為內部結構。不應直接修改，其格式可能隨時變更。

after_request_funcs: dict[ft.AppOrBlueprintKey, list[ft.AfterRequestCallable[t.Any]]]¶

在每個請求結束時呼叫的函式資料結構，格式為 {scope: [functions]}。scope 鍵值是函式作用的藍圖名稱，或 None 表示適用於所有請求。

若要註冊函式，請使用 after_request() 裝飾器。

此資料結構為內部結構。不應直接修改，其格式可能隨時變更。

teardown_request_funcs: dict[ft.AppOrBlueprintKey, list[ft.TeardownCallable]]¶

即使引發例外狀況，在每個請求結束時仍會呼叫的函式資料結構，格式為 {scope: [functions]}。scope 鍵值是函式作用的藍圖名稱，或 None 表示適用於所有請求。

若要註冊函式，請使用 teardown_request() 裝飾器。

此資料結構為內部結構。不應直接修改，其格式可能隨時變更。

template_context_processors: dict[ft.AppOrBlueprintKey, list[ft.TemplateContextProcessorCallable]]¶

在呈現範本時呼叫以傳遞額外上下文值的函式資料結構，格式為 {scope: [functions]}。scope 鍵值是函式作用的藍圖名稱，或 None 表示適用於所有請求。

若要註冊函式，請使用 context_processor() 裝飾器。

此資料結構為內部結構。不應直接修改，其格式可能隨時變更。

url_value_preprocessors: dict[ft.AppOrBlueprintKey, list[ft.URLValuePreprocessorCallable]]¶

呼叫以修改傳遞到視圖函式的關鍵字引數的函式資料結構，格式為 {scope: [functions]}。scope 鍵值是函式作用的藍圖名稱，或 None 表示適用於所有請求。

若要註冊函式，請使用 url_value_preprocessor() 裝飾器。

此資料結構為內部結構。不應直接修改，其格式可能隨時變更。

url_default_functions: dict[ft.AppOrBlueprintKey, list[ft.URLDefaultCallable]]¶

呼叫以修改產生 URL 時的關鍵字引數的函式資料結構，格式為 {scope: [functions]}。scope 鍵值是函式作用的藍圖名稱，或 None 表示適用於所有請求。

若要註冊函式，請使用 url_defaults() 裝飾器。

此資料結構為內部結構。不應直接修改，其格式可能隨時變更。

傳入的請求資料¶

class flask.Request(environ, populate_request=True, shallow=False)¶

預設在 Flask 中使用的請求物件。記住匹配的端點和視圖引數。

它最終成為 request。如果您想要替換使用的請求物件，您可以子類別化它並將 request_class 設定為您的子類別。

請求物件是 Request 子類別，並提供 Werkzeug 定義的所有屬性，以及一些 Flask 特有的屬性。

參數:

environ (WSGIEnvironment)
populate_request (bool)
shallow (bool)

url_rule: Rule | None = None¶: 與請求匹配的內部 URL 規則。這可用於從 before/after 處理常式 (request.url_rule.methods) 等檢查 URL 允許哪些方法。雖然如果請求的方法對於 URL 規則無效，則有效列表可在 routing_exception.valid_methods 中找到（Werkzeug 例外狀況 MethodNotAllowed 的屬性），因為請求從未在內部繫結。

變更日誌

在 0.6 版本中新增。

view_args: dict[str, t.Any] | None = None¶: 與請求匹配的視圖引數字典。如果在匹配時發生例外狀況，則這將為 None。

routing_exception: HTTPException | None = None¶: 如果 URL 匹配失敗，則這是將被引發/作為請求處理一部分引發的例外狀況。這通常是 NotFound 例外狀況或類似的狀況。

屬性 max_content_length: int | None¶

在此請求期間將讀取的最大位元組數。如果超出此限制，則會引發 413 RequestEntityTooLarge 錯誤。如果設定為 None，則 Flask 應用程式層級不會強制執行任何限制。但是，如果它是 None 且請求沒有 Content-Length 標頭，且 WSGI 伺服器未指示它終止串流，則不會讀取任何資料以避免無限串流。

每個請求預設為 MAX_CONTENT_LENGTH 設定，其預設值為 None。它可以在特定的 request 上設定，以將限制套用於該特定視圖。應根據應用程式或視圖的特定需求適當設定此值。

變更於版本 3.1: 這可以針對每個請求設定。

變更日誌

變更於版本 0.6: 這是可透過 Flask 設定配置的。

屬性 max_form_memory_size: int | None¶

任何非檔案表單欄位在 multipart/form-data 主體中可以使用的最大大小（以位元組為單位）。如果超出此限制，則會引發 413 RequestEntityTooLarge 錯誤。如果設定為 None，則 Flask 應用程式層級不會強制執行任何限制。

每個請求預設為 MAX_FORM_MEMORY_SIZE 設定，其預設值為 500_000。它可以在特定的 request 上設定，以將限制套用於該特定視圖。應根據應用程式或視圖的特定需求適當設定此值。

變更於版本 3.1: 這是可透過 Flask 設定配置的。

屬性 max_form_parts: int | None¶

在 multipart/form-data 主體中可能存在的最大欄位數。如果超出此限制，則會引發 413 RequestEntityTooLarge 錯誤。如果設定為 None，則 Flask 應用程式層級不會強制執行任何限制。

每個請求預設為 MAX_FORM_PARTS 設定，其預設值為 1_000。它可以在特定的 request 上設定，以將限制套用於該特定視圖。應根據應用程式或視圖的特定需求適當設定此值。

變更於版本 3.1: 這是可透過 Flask 設定配置的。

屬性 endpoint: str | None¶

與請求 URL 匹配的端點。

如果匹配失敗或尚未執行，則這將為 None。

這與 view_args 結合使用，可用於重建相同的 URL 或修改後的 URL。

property blueprint: str | None¶

目前藍圖的已註冊名稱。

如果端點不屬於藍圖的一部分，或者 URL 匹配失敗或尚未執行，則此值將為 None。

這不一定與建立藍圖時使用的名稱相符。它可能已被巢狀化，或以不同的名稱註冊。

property blueprints: list[str]¶

目前藍圖的已註冊名稱，向上追溯至父藍圖。

如果沒有目前的藍圖，或 URL 匹配失敗，則這將會是一個空列表。

變更日誌

在 2.0.1 版本中新增。

on_json_loading_failed(e)¶

當 get_json() 失敗且未被靜音時呼叫。

如果此方法傳回一個值，則該值將用作 get_json() 的傳回值。預設實作會引發 BadRequest。

參數:: e (ValueError | None) – 如果解析失敗，則為此例外。如果內容類型不是 application/json，則將為 None。
回傳類型:: 任何

變更日誌

Changed in version 2.3: 在 2.3 版本中變更：引發 415 錯誤而非 400 錯誤。

property accept_charsets: CharsetAccept¶: 此用戶端支援的字元集列表，作為 CharsetAccept 物件。

property accept_encodings: Accept¶: 此用戶端接受的編碼列表。HTTP 術語中的編碼是指壓縮編碼，例如 gzip。關於字元集，請參閱 accept_charset。

property accept_languages: LanguageAccept¶: 此用戶端接受的語言列表，作為 LanguageAccept 物件。

property accept_mimetypes: MIMEAccept¶: 此用戶端支援的 MIME 類型列表，作為 MIMEAccept 物件。

access_control_request_headers¶: 與預檢請求一起傳送，以指示將與跨來源請求一起傳送哪些標頭。在回應中設定 access_control_allow_headers 以指示允許哪些標頭。

access_control_request_method¶: 與預檢請求一起傳送，以指示將用於跨來源請求的方法。在回應中設定 access_control_allow_methods 以指示允許哪些方法。

property access_route: list[str]¶: 如果存在轉發標頭，則這是從用戶端 IP 到最後一個代理伺服器的所有 IP 位址的列表。

classmethod application(f)¶

將函數裝飾為接受請求作為最後一個引數的回應器。這與 responder() 裝飾器的工作方式類似，但函數會將請求物件作為最後一個引數傳遞，並且請求物件將自動關閉

@Request.application
def my_wsgi_app(request):
    return Response('Hello World!')

從 Werkzeug 0.14 開始，HTTP 例外會自動捕獲並轉換為回應，而不是失敗。

參數:: f (t.Callable[[Request], WSGIApplication]) – 要裝飾的 WSGI 可呼叫物件
Returns:: 新的 WSGI 可呼叫物件
回傳類型:: WSGIApplication

property args: MultiDict[str, str]¶

已剖析的 URL 參數（URL 中問號後面的部分）。

預設情況下，此函數會傳回 ImmutableMultiDict。可以透過將 parameter_storage_class 設定為不同的類型來變更此行為。如果表單資料的順序很重要，則可能需要這樣做。

變更日誌

Changed in version 2.3: 在 2.3 版本中變更：無效的位元組保持百分比編碼。

property authorization: Authorization | None¶: Authorization 標頭已剖析為 Authorization 物件。如果標頭不存在，則為 None。

變更日誌

Changed in version 2.3: 在 2.3 版本中變更：Authorization 不再是 dict。token 屬性已針對使用權杖而非參數的驗證方案新增。

property base_url: str¶: 類似於 url，但不包含查詢字串。

property cache_control: RequestCacheControl¶: 用於傳入快取控制標頭的 RequestCacheControl 物件。

close()¶

關閉此請求物件的相關資源。這會明確關閉所有檔案控制代碼。您也可以在 with 語句中使用請求物件，這將自動關閉它。

變更日誌

在 0.9 版本中新增。

回傳類型:: None

content_encoding¶: Content-Encoding 實體標頭欄位用作媒體類型的修飾符。當存在時，其值指示已對實體主體應用了哪些額外的內容編碼，因此必須應用哪些解碼機制才能獲得 Content-Type 標頭欄位引用的媒體類型。

變更日誌

在 0.9 版本中新增。

property content_length: int | None¶: Content-Length 實體標頭欄位指示實體主體的大小（以位元組為單位），或者，在 HEAD 方法的情況下，指示如果請求是 GET，則本應傳送的實體主體的大小。

content_md5¶: Content-MD5 實體標頭欄位（如 RFC 1864 中定義）是實體主體的 MD5 摘要，用於提供實體主體的端對端訊息完整性檢查 (MIC)。（注意：MIC 適用於偵測傳輸過程中實體主體的意外修改，但不能防禦惡意攻擊。）

變更日誌

在 0.9 版本中新增。

content_type¶: Content-Type 實體標頭欄位指示傳送給接收者的實體主體的媒體類型，或者，在 HEAD 方法的情況下，指示如果請求是 GET，則本應傳送的媒體類型。

property cookies: ImmutableMultiDict[str, str]¶: 包含隨請求傳輸的所有 Cookie 內容的 dict。

property data: bytes¶

從 stream 讀取的原始資料。如果請求表示表單資料，則將為空。

若要取得即使它表示表單資料的原始資料，請使用 get_data()。

date¶: Date 一般標頭欄位表示訊息的原始日期和時間，其語義與 RFC 822 中的 orig-date 相同。

變更日誌

Changed in version 2.0: 在 2.0 版本中變更：datetime 物件具有時區感知能力。

dict_storage_class¶: ImmutableMultiDict 的別名

property files: ImmutableMultiDict[str, FileStorage]¶

包含所有上傳檔案的 MultiDict 物件。files 中的每個鍵都是來自 <input type="file" name=""> 的名稱。files 中的每個值都是 Werkzeug FileStorage 物件。

它基本上像您從 Python 知道的標準檔案物件一樣運作，不同之處在於它還具有一個 save() 函數，可用於將檔案儲存在檔案系統上。

請注意，只有當請求方法為 POST、PUT 或 PATCH 且發佈到請求的 <form> 具有 enctype="multipart/form-data" 時，files 才會包含資料。否則它將為空。

請參閱 MultiDict / FileStorage 文件，以取得有關所用資料結構的更多詳細資訊。

property form: ImmutableMultiDict[str, str]¶

表單參數。預設情況下，此函數會傳回 ImmutableMultiDict。可以透過將 parameter_storage_class 設定為不同的類型來變更此行為。如果表單資料的順序很重要，則可能需要這樣做。

請記住，檔案上傳將不會在此處結束，而是會在 files 屬性中結束。

變更日誌

Changed in version 0.9: 在 0.9 版本中變更：在 Werkzeug 0.9 之前的版本中，這只會包含 POST 和 PUT 請求的表單資料。

form_data_parser_class¶: FormDataParser 的別名

classmethod from_values(*args, **kwargs)¶

根據提供的值建立新的請求物件。如果給定了 environ，則會從該處填寫遺失的值。當您需要模擬來自 URL 的請求時，此方法對於小型腳本很有用。請勿將此方法用於單元測試，有一個功能齊全的用戶端物件 (Client) 允許建立多部分請求，支援 Cookie 等。

這接受與 EnvironBuilder 相同的選項。

變更日誌

Changed in version 0.5: 在 0.5 版本中變更：此方法現在接受與 EnvironBuilder 相同的引數。因此，environ 參數現在稱為 environ_overrides。

Returns:

請求物件

參數:

args (Any)
kwargs (Any)

回傳類型:

Request

property full_path: str¶: 請求的路徑，包括查詢字串。

get_data(cache=True, as_text=False, parse_form_data=False)¶

這會將來自用戶端的緩衝輸入資料讀取到一個位元組物件中。預設情況下，這會被快取，但可以透過將 cache 設定為 False 來變更此行為。

通常，在未先檢查內容長度的情況下呼叫此方法不是一個好主意，因為用戶端可能會傳送數十 MB 或更多的資料，從而在伺服器上造成記憶體問題。

請注意，如果已剖析表單資料，則此方法將不會傳回任何內容，因為表單資料剖析不會像此方法一樣快取資料。若要隱含地調用表單資料剖析函數，請將 parse_form_data 設定為 True。完成此操作後，如果表單剖析器處理資料，則此方法的傳回值將為空字串。這通常不是必要的，因為如果快取了所有資料（這是預設值），則表單剖析器將使用快取的資料來剖析表單資料。一般而言，在任何情況下呼叫此方法之前，請注意先檢查內容長度，以避免耗盡伺服器記憶體。

如果將 as_text 設定為 True，則傳回值將為已解碼的字串。

變更日誌

在 0.9 版本中新增。

參數:

cache (bool)
as_text (bool)
parse_form_data (bool)

回傳類型:

bytes | str

get_json(force=False, silent=False, cache=True)¶

將 data 剖析為 JSON。

如果 mimetype 未指示 JSON（application/json，請參閱 is_json），或剖析失敗，則會呼叫 on_json_loading_failed()，並將其傳回值用作傳回值。預設情況下，這會引發 415 不支援的媒體類型回應。

參數:

force (bool) – 忽略 mimetype 並始終嘗試剖析 JSON。
silent (bool) – 靜音 mimetype 和剖析錯誤，並傳回 None 作為替代。
cache (bool) – 儲存已剖析的 JSON 以供後續呼叫傳回。

回傳類型:

Any | None

變更日誌

Changed in version 2.3: 在 2.3 版本中變更：引發 415 錯誤而非 400 錯誤。

Changed in version 2.1: 在 2.1 版本中變更：如果內容類型不正確，則引發 400 錯誤。

property host: str¶: 請求所發往的主機名稱，如果是非標準連接埠，則包括連接埠。使用 trusted_hosts 驗證。

property host_url: str¶: 僅請求 URL 方案和主機。

property if_match: ETags¶

包含 If-Match 標頭中所有 etag 的物件。

回傳類型:: ETags

property if_modified_since: datetime | None¶: 解析後的 If-Modified-Since 標頭，以 datetime 物件表示。

變更日誌

Changed in version 2.0: 在 2.0 版本中變更：datetime 物件具有時區感知能力。

property if_none_match: ETags¶

包含 If-None-Match 標頭中所有 etag 的物件。

回傳類型:: ETags

property if_range: IfRange¶: 解析後的 If-Range 標頭。

變更日誌

變更於版本 2.0：IfRange.date 具有時區感知能力。

Added in version 0.7.

property if_unmodified_since: datetime | None¶: 解析後的 If-Unmodified-Since 標頭，以 datetime 物件表示。

變更日誌

Changed in version 2.0: 在 2.0 版本中變更：datetime 物件具有時區感知能力。

input_stream¶

原始 WSGI 輸入流，不帶任何安全檢查。

使用此屬性具有危險性。它不會防範無限流，也不會防止讀取超過 content_length 或 max_content_length 的內容。

請改用 stream。

property is_json: bool¶: 檢查 mimetype 是否指示 JSON 資料，無論是 application/json 或 application/*+json。

is_multiprocess¶: 布林值，如果應用程式由產生多個進程的 WSGI 伺服器提供服務，則為 True。

is_multithread¶: 布林值，如果應用程式由多執行緒 WSGI 伺服器提供服務，則為 True。

is_run_once¶: 布林值，如果應用程式在進程生命週期中僅執行一次，則為 True。例如，CGI 就是這種情況，但不保證僅執行一次。

property is_secure: bool¶: 如果請求是使用安全協定（HTTPS 或 WSS）發出的，則為 True。

property json: Any | None¶

如果 mimetype 指示 JSON (application/json，請參閱 is_json)，則為已解析的 JSON 資料。

呼叫帶有預設引數的 get_json()。

如果請求內容類型不是 application/json，這將引發 415 Unsupported Media Type 錯誤。

變更日誌

Changed in version 2.3: 在 2.3 版本中變更：引發 415 錯誤而非 400 錯誤。

Changed in version 2.1: 在 2.1 版本中變更：如果內容類型不正確，則引發 400 錯誤。

list_storage_class¶: 別名為 ImmutableList

make_form_data_parser()¶

建立表單資料解析器。使用一些參數實例化 form_data_parser_class。

變更日誌

在 0.8 版本中新增。

回傳類型:: FormDataParser

max_forwards¶: Max-Forwards 請求標頭欄位提供一種機制，透過 TRACE 和 OPTIONS 方法來限制可以將請求轉發到下一個入站伺服器的代理伺服器或閘道數量。

property mimetype: str¶: 類似於 content_type，但不包含參數（例如，不包含字元集、類型等），且始終為小寫。例如，如果內容類型為 text/HTML; charset=utf-8，則 mimetype 將為 'text/html'。

property mimetype_params: dict[str, str]¶: mimetype 參數，以字典形式表示。例如，如果內容類型為 text/html; charset=utf-8，則參數將為 {'charset': 'utf-8'}。

origin¶: 請求的來源主機。在回應中設定 access_control_allow_origin 以指示允許哪些來源。

parameter_storage_class¶: ImmutableMultiDict 的別名

property pragma: HeaderSet¶: Pragma 通用標頭欄位用於包含實作特定的指令，這些指令可能適用於請求/回應鏈中的任何接收者。所有 pragma 指令都指定協定觀點中的可選行為；但是，某些系統可能要求行為與指令一致。

property range: Range | None¶

解析後的 Range 標頭。

變更日誌

Added in version 0.7.

回傳類型:: Range

referrer¶: Referer[原文如此] 請求標頭欄位允許客戶端為伺服器的利益指定取得 Request-URI 的資源位址 (URI)（「referrer」，儘管標頭欄位拼寫錯誤）。

remote_user¶: 如果伺服器支援使用者身份驗證，且腳本受到保護，則此屬性包含使用者已驗證身份的使用者名稱。

property root_url: str¶: 請求 URL 的 scheme、host 和根路徑。這是應用程式存取的根目錄。

property script_root: str¶: 別名為 self.root_path。environ["SCRIPT_ROOT"]，不帶尾部斜線。

property stream: IO[bytes]¶

WSGI 輸入流，帶有安全檢查。此流只能使用一次。

使用 get_data() 以取得完整資料作為位元組或文字。data 屬性僅在資料不代表表單資料時才會包含完整位元組。form 屬性在這種情況下將包含已解析的表單資料。

與 input_stream 不同，此流可防範無限流或讀取超過 content_length 或 max_content_length 的內容。

如果設定了 max_content_length，則如果設定了 wsgi.input_terminated，則可以在流上強制執行。否則，將返回空流。

如果在基礎流耗盡之前達到限制（例如檔案太大或無限流），則無法安全地讀取流的剩餘內容。根據伺服器處理此問題的方式，客戶端可能會顯示「連線重設」失敗，而不是看到 413 回應。

變更日誌

變更於版本 2.3：預先檢查 max_content_length 並在讀取時檢查。

變更於版本 0.9：即使首先存取表單解析，也始終設定流（但可能已被使用）。

trusted_hosts: list[str] | None = None¶

處理請求時的有效主機名稱。預設情況下，所有主機都受信任，這表示無論客戶端說主機是什麼，都將被接受。

由於惡意客戶端可以將 Host 和 X-Forwarded-Host 標頭設定為任何值，因此建議設定此屬性或在代理伺服器中實作類似的驗證（如果應用程式在代理伺服器後面執行）。

變更日誌

在 0.9 版本中新增。

property url: str¶: 完整的請求 URL，包含 scheme、host、根路徑、路徑和查詢字串。

property url_root: str¶: 別名為 root_url。包含 scheme、host 和根路徑的 URL。例如，https://example.com/app/。

property user_agent: UserAgent¶: 使用者代理程式。使用 user_agent.string 取得標頭值。將 user_agent_class 設定為 UserAgent 的子類別，以提供其他屬性或其他擴充資料的解析。

變更日誌

變更於版本 2.1：內建解析器已移除。將 user_agent_class 設定為 UserAgent 子類別，以從字串解析資料。

user_agent_class¶: 別名為 UserAgent

property values: CombinedMultiDict[str, str]¶

werkzeug.datastructures.CombinedMultiDict，結合了 args 和 form。

對於 GET 請求，僅存在 args，而不存在 form。

變更日誌

變更於版本 2.0：對於 GET 請求，僅存在 args，而不存在 form。

property want_form_data_parsed: bool¶: 如果請求方法攜帶內容，則為 True。預設情況下，如果傳送了 Content-Type，則為 true。

變更日誌

在 0.8 版本中新增。

environ: WSGIEnvironment¶: WSGI 環境，包含 HTTP 標頭和來自 WSGI 伺服器的資訊。

shallow: bool¶: 建立請求物件時設定。如果為 True，則從請求 body 讀取將導致 RuntimeException。適用於防止從中介軟體修改流。

method¶: 發出請求的方法，例如 GET。

scheme¶: 請求使用的協定的 URL scheme，例如 https 或 wss。

server¶: 伺服器的位址。(host, port)、Unix socket 的 (path, None)，或如果未知則為 None。

root_path¶: 應用程式掛載在其下的前綴，不帶尾部斜線。path 在此之後。

path¶: URL 中 root_path 之後的路徑部分。這是應用程式內路由使用的路徑。

query_string¶: URL 中「?」之後的部分。這是原始值，請使用 args 取得已解析的值。

headers¶: 請求收到的標頭。

remote_addr¶: 發送請求的客戶端位址。

flask.request¶

若要存取傳入的請求資料，您可以使用全域 request 物件。Flask 會為您解析傳入的請求資料，並讓您透過該全域物件存取它。在內部，如果您處於多執行緒環境中，Flask 會確保您始終獲得活動執行緒的正確資料。

這是一個代理物件。有關更多資訊，請參閱代理物件的注意事項。

request 物件是 Request 的實例。

回應物件¶

class flask.Response(response=None, status=None, headers=None, mimetype=None, content_type=None, direct_passthrough=False)¶

Flask 中預設使用的回應物件。其運作方式類似於 Werkzeug 中的回應物件，但預設設定為 HTML mimetype。通常您不必自己建立此物件，因為 make_response() 會為您處理。

如果您想替換使用的回應物件，可以繼承此物件並將 response_class 設定為您的子類別。

變更日誌

變更於版本 1.0：回應中新增了 JSON 支援，如同請求一樣。這在測試時將測試客戶端回應資料作為 JSON 取得時非常有用。

變更於版本 1.0：新增了 max_cookie_size。

參數:

response (Iterable[str] | Iterable[bytes])
status (int | str | HTTPStatus | None)
headers (Headers)
mimetype (str | None)
content_type (str | None)
direct_passthrough (bool)

default_mimetype: str | None = 'text/html'¶: 如果未提供 mimetype，則為預設 mimetype。

accept_ranges¶

Accept-Ranges 標頭。即使名稱表示支援多個值，它也必須僅為一個字串 token。

常見的值為 'bytes' 和 'none'。

變更日誌

Added in version 0.7.

property access_control_allow_credentials: bool¶: 瀏覽器是否可以將憑證共用給 JavaScript 程式碼。作為 preflight 請求的一部分，它指示是否可以在跨域請求中使用憑證。

access_control_allow_headers¶: 哪些標頭可以與跨域請求一起傳送。

access_control_allow_methods¶: 哪些方法可以用於跨域請求。

access_control_allow_origin¶: 可以發出跨域請求的來源或 '*' (任何來源)。

access_control_expose_headers¶: 瀏覽器可以將哪些標頭共用給 JavaScript 程式碼。

access_control_max_age¶: 存取控制設定可以快取的最大秒數。

add_etag(overwrite=False, weak=False)¶

如果目前的回應尚無 etag，則新增一個。

變更日誌

變更於版本 2.0：SHA-1 用於產生值。MD5 在某些環境中可能不可用。

參數:

overwrite (bool)
weak (bool)

回傳類型:

None

age¶

Age 回應標頭欄位傳達發送者對回應（或其重新驗證）在原始伺服器上產生以來經過的時間量的估計。

Age 值是非負十進制整數，表示時間（以秒為單位）。

property allow: HeaderSet¶: Allow 實體標頭欄位列出 Request-URI 識別的資源支援的方法集。此欄位的目的嚴格來說是通知接收者與資源關聯的有效方法。Allow 標頭欄位必須出現在 405 (Method Not Allowed) 回應中。

automatically_set_content_length = True¶: 此回應物件是否應在可能的情況下自動設定 content-length 標頭？預設為 true。

變更日誌

在 0.8 版本中新增。

屬性 cache_control: ResponseCacheControl¶: Cache-Control 通用標頭欄位用於指定請求/回應鏈中所有快取機制**必須**遵守的指令。

calculate_content_length()¶

如果內容長度可用則返回內容長度，否則返回 None。

回傳類型:: int | None

call_on_close(func)¶

新增一個函數到內部函數列表中，這些函數應在關閉回應時被調用。自 0.7 版本起，此函數也會返回傳入的函數，因此可以作為裝飾器使用。

變更日誌

在 0.6 版本中新增。

參數:: func (Callable[[], Any])
回傳類型:: Callable[[], Any]

close()¶

如果可能，關閉包裝的回應。您也可以在 with 語句中使用此物件，它將自動關閉回應。

變更日誌

版本 0.9 新增: 現在可以在 with 語句中使用。

回傳類型:: None

content_encoding¶: Content-Encoding 實體標頭欄位用作媒體類型的修飾符。當存在時，其值指示已對實體主體應用了哪些額外的內容編碼，因此必須應用哪些解碼機制才能獲得 Content-Type 標頭欄位引用的媒體類型。

屬性 content_language: HeaderSet¶: Content-Language 實體標頭欄位描述封閉實體目標受眾的自然語言。請注意，這可能不等同於實體主體中使用的所有語言。

content_length¶: Content-Length 實體標頭欄位指示傳送給接收者的實體主體大小（以十進制 OCTET 數表示），或者在 HEAD 方法的情況下，指示如果請求是 GET 請求，則會傳送的實體主體大小。

content_location¶: 當封閉在訊息中的實體可以從與請求資源的 URI 不同的位置存取時，Content-Location 實體標頭欄位**可以**用於提供實體的資源位置。

content_md5¶: Content-MD5 實體標頭欄位（如 RFC 1864 中定義）是實體主體的 MD5 摘要，用於提供實體主體的端對端訊息完整性檢查 (MIC)。（注意：MIC 適用於偵測傳輸過程中實體主體的意外修改，但不能防禦惡意攻擊。）

屬性 content_range: ContentRange¶: Content-Range 標頭作為 ContentRange 物件。即使未設定標頭也可用。

變更日誌

Added in version 0.7.

屬性 content_security_policy: ContentSecurityPolicy¶

Content-Security-Policy 標頭作為 ContentSecurityPolicy 物件。即使未設定標頭也可用。

Content-Security-Policy 標頭新增額外的安全層，以協助偵測和緩解某些類型的攻擊。

屬性 content_security_policy_report_only: ContentSecurityPolicy¶

Content-Security-policy-report-only 標頭作為 ContentSecurityPolicy 物件。即使未設定標頭也可用。

Content-Security-Policy-Report-Only 標頭新增一個 csp 策略，該策略不會強制執行，但會報告，從而協助偵測某些類型的攻擊。

content_type¶: Content-Type 實體標頭欄位指示傳送給接收者的實體主體的媒體類型，或者，在 HEAD 方法的情況下，指示如果請求是 GET，則本應傳送的媒體類型。

cross_origin_embedder_policy¶: 防止文件載入任何未明確授予文件許可的跨來源資源。值必須是 werkzeug.http.COEP 列舉的成員。

cross_origin_opener_policy¶: 允許控制與跨來源文件共用瀏覽上下文群組。值必須是 werkzeug.http.COOP 列舉的成員。

屬性 data: bytes | str¶: 一個描述器，用於調用 get_data() 和 set_data()。

date¶: Date 一般標頭欄位表示訊息的原始日期和時間，其語義與 RFC 822 中的 orig-date 相同。

變更日誌

Changed in version 2.0: 在 2.0 版本中變更：datetime 物件具有時區感知能力。

default_status = 200¶: 如果未提供狀態碼，則為預設狀態碼。

delete_cookie(key, path='/', domain=None, secure=False, httponly=False, samesite=None, partitioned=False)¶

刪除 cookie。如果金鑰不存在，則會靜默失敗。

參數:

key (str) – 要刪除的 cookie 的金鑰（名稱）。
path (str | None) – 如果要刪除的 cookie 僅限於特定路徑，則必須在此處定義路徑。
domain (str | None) – 如果要刪除的 cookie 僅限於特定網域，則必須在此處定義網域。
secure (bool) – 如果為 True，則 cookie 僅可透過 HTTPS 取得。
httponly (bool) – 禁止 JavaScript 存取 cookie。
samesite (str | None) – 限制 cookie 的範圍，使其僅附加到「同網站」請求。
partitioned (bool) – 如果為 True，則 cookie 將被分割。

回傳類型:

None

expires¶: Expires 實體標頭欄位給出日期/時間，在此之後回應被視為過時。過時的快取條目通常可能不會被快取返回。

變更日誌

Changed in version 2.0: 在 2.0 版本中變更：datetime 物件具有時區感知能力。

classmethod force_type(response, environ=None)¶

強制 WSGI 回應為目前類型的回應物件。Werkzeug 在許多情況下（例如例外）會在內部使用 Response。如果您在例外上調用 get_response()，即使您正在使用自訂子類別，您也會獲得常規的 Response 物件。

此方法可以強制給定的回應類型，並且如果提供了 environ，它還會將任意 WSGI 可調用物件轉換為回應物件

# convert a Werkzeug response object into an instance of the
# MyResponseClass subclass.
response = MyResponseClass.force_type(response)

# convert any WSGI application into a response object
response = MyResponseClass.force_type(response, environ)

如果您想要在主調度器中對回應進行後處理並使用子類別提供的功能，這特別有用。

請記住，如果可能，這將就地修改回應物件！

參數:

response (Response) – 回應物件或 wsgi 應用程式。
environ (WSGIEnvironment | None) – WSGI 環境物件。

Returns:

回應物件。

回傳類型:

freeze()¶

使回應物件準備好進行 pickled。執行以下操作

將回應緩衝到列表中，忽略 implicity_sequence_conversion 和 direct_passthrough。
設定 Content-Length 標頭。
如果尚未設定 ETag 標頭，則產生一個。

變更日誌

版本 2.1 變更: 移除 no_etag 參數。

版本 2.0 變更: 始終新增 ETag 標頭。

版本 0.6 變更: 設定 Content-Length 標頭。

回傳類型:: None

classmethod from_app(app, environ, buffered=False)¶

從應用程式輸出建立新的回應物件。如果您傳遞一個始終返回產生器的應用程式，則此方法效果最佳。有時應用程式可能會使用 start_response 函數返回的 write() 可調用物件。這嘗試自動解決此類邊緣情況。但是，如果您沒有獲得預期的輸出，則應將 buffered 設定為 True，這會強制緩衝。

參數:

app (WSGIApplication) – 要執行的 WSGI 應用程式。
environ (WSGIEnvironment) – 要對其執行的 WSGI 環境。
buffered (bool) – 設定為 True 以強制緩衝。

Returns:

回應物件。

回傳類型:

get_app_iter(environ)¶

返回給定 environ 的應用程式迭代器。根據請求方法和當前狀態碼，返回值可能是空回應，而不是來自回應的回應。

如果請求方法是 HEAD 或狀態碼在 HTTP 規範要求空回應的範圍內，則返回空的可迭代物件。

變更日誌

在 0.6 版本中新增。

參數:: environ (WSGIEnvironment) – 請求的 WSGI 環境。
Returns:: 回應可迭代物件。
回傳類型:: t.Iterable[bytes]

get_data(as_text=False)¶

回應主體的字串表示形式。每當您調用此屬性時，回應可迭代物件都會被編碼和展平。如果您串流傳輸大數據，這可能會導致不必要的行為。

可以透過將 implicit_sequence_conversion 設定為 False 來停用此行為。

如果將 as_text 設定為 True，則傳回值將為已解碼的字串。

變更日誌

在 0.9 版本中新增。

參數:: as_text (bool)
回傳類型:: bytes | str

get_etag()¶

返回 (etag, is_weak) 形式的元組。如果沒有 ETag，則傳回值為 (None, None)。

回傳類型:: tuple[str, bool] | tuple[None, None]

get_json(force=False, silent=False)¶

將 data 解析為 JSON。在測試期間很有用。

如果 mimetype 未指示 JSON (application/json，請參閱 is_json)，則此方法返回 None。

與 Request.get_json() 不同，結果不會被快取。

參數:

force (bool) – 忽略 mimetype 並始終嘗試剖析 JSON。
silent (bool) – 靜默解析錯誤並返回 None。

回傳類型:

Any | None

get_wsgi_headers(environ)¶

這會在回應啟動之前自動調用，並返回為給定環境修改的標頭。它返回回應中標頭的副本，並在必要時應用一些修改。

例如，位置標頭（如果存在）會與環境的根 URL 聯接。此外，對於某些狀態碼，內容長度也會在此處自動設定為零。

變更日誌

版本 0.6 變更: 先前該函數名為 fix_headers，並就地修改回應物件。此外，自 0.6 版本起，位置和內容位置標頭中的 IRI 會被正確處理。

同樣從 0.6 版本開始，Werkzeug 將嘗試設定內容長度（如果它能夠自行計算出來）。如果回應可迭代物件中的所有字串都已編碼且可迭代物件已緩衝，則會發生這種情況。

參數:: environ (WSGIEnvironment) – 請求的 WSGI 環境。
Returns:: 返回新的 Headers 物件。
回傳類型:: Headers

get_wsgi_response(environ)¶

以元組形式返回最終的 WSGI 回應。元組中的第一個項目是應用程式迭代器，第二個是狀態，第三個是標頭列表。返回的回應是專為給定環境建立的。例如，如果 WSGI 環境中的請求方法是 'HEAD'，則回應將為空，並且僅存在標頭和狀態碼。

變更日誌

在 0.6 版本中新增。

參數:: environ (WSGIEnvironment) – 請求的 WSGI 環境。
Returns:: 一個 (app_iter, status, headers) 元組。
回傳類型:: tuple[t.Iterable[bytes], str, list[tuple[str, str]]]

implicit_sequence_conversion = True¶: 如果設定為 False，則存取回應物件上的屬性將不會嘗試消耗回應迭代器並將其轉換為列表。

變更日誌

版本 0.6.2 新增: 該屬性先前名為 implicit_seqence_conversion。（注意拼字錯誤）。如果您確實使用了此功能，則必須調整您的程式碼以適應名稱變更。

屬性 is_json: bool¶: 檢查 mimetype 是否指示 JSON 資料，無論是 application/json 或 application/*+json。

屬性 is_sequence: bool¶: 如果迭代器被緩衝，則此屬性將為 True。如果回應屬性是列表或元組，則回應物件會將迭代器視為已緩衝。

變更日誌

在 0.6 版本中新增。

屬性 is_streamed: bool¶

如果回應被串流傳輸（回應不是具有長度資訊的可迭代物件），則此屬性為 True。在這種情況下，串流傳輸表示沒有關於迭代次數的資訊。如果將產生器傳遞給回應物件，則通常為 True。

這對於在應用某些不應對串流回應進行的後處理篩選之前進行檢查很有用。

iter_encoded()¶

迭代以回應的編碼方式編碼的回應。如果回應物件作為 WSGI 應用程式被調用，除非 direct_passthrough 已啟用，否則此方法的傳回值將用作應用程式迭代器。

回傳類型:: Iterator[bytes]

屬性 json: Any | None¶

如果 mimetype 指示 JSON (application/json，請參閱 is_json)，則為已解析的 JSON 資料。

使用預設參數調用 get_json()。

last_modified¶: Last-Modified 實體標頭欄位指示原始伺服器認為變體上次修改的日期和時間。

變更日誌

Changed in version 2.0: 在 2.0 版本中變更：datetime 物件具有時區感知能力。

location¶: Location 回應標頭欄位用於將接收者重新導向到 Request-URI 以外的位置，以完成請求或識別新資源。

make_conditional(request_or_environ, accept_ranges=False, complete_length=None)¶

使回應成為請求的條件式回應。如果已為回應定義了 etag，則此方法效果最佳。add_etag 方法可用於執行此操作。如果在沒有 etag 的情況下調用，則僅設定日期標頭。

如果請求或 environ 中的請求方法不是 GET 或 HEAD，則此方法不執行任何操作。

為了在處理範圍請求時獲得最佳效能，建議您的回應資料物件實作 io.IOBase 所述的 seekable、seek 和 tell 方法。wrap_file() 返回的物件會自動實作這些方法。

它不會移除回應的主體，因為這是 __call__() 函數自動為我們執行的操作。

返回 self，以便您可以執行 return resp.make_conditional(req)，但會就地修改物件。

參數:

request_or_environ (WSGIEnvironment | Request) – 要用於使回應成為條件式回應的請求物件或 WSGI 環境。
accept_ranges (bool | str) – 此參數指示 Accept-Ranges 標頭的值。如果為 False（預設值），則不會設定標頭。如果為 True，則會設定為 "bytes"。如果它是字串，則會使用此值。
complete_length (int | None) – 僅在有效的範圍請求中使用。它將設定 Content-Range 完整長度值並計算 Content-Length 實際值。此參數對於成功完成範圍請求是強制性的。

Raises:

RequestedRangeNotSatisfiable 如果無法解析或滿足 Range 標頭。

回傳類型:

變更日誌

版本 2.0 變更: 如果長度為 0，則跳過範圍處理，而不是引發 416 Range Not Satisfiable 錯誤。

make_sequence()¶

將回應迭代器轉換為列表。預設情況下，如果需要，這會自動發生。如果停用了 implicit_sequence_conversion，則不會自動調用此方法，並且某些屬性可能會引發例外。這也會編碼所有項目。

變更日誌

在 0.6 版本中新增。

回傳類型:: None

屬性 mimetype: str | None¶: mimetype（不含字元集等的內容類型）

屬性 mimetype_params: dict[str, str]¶: mimetype 參數，以字典形式表示。例如，如果內容類型為 text/html; charset=utf-8，則參數將為 {'charset': 'utf-8'}。

變更日誌

在 0.5 版本中新增。

property retry_after: datetime | None¶

Retry-After 回應標頭欄位可用於 503 (服務無法使用中) 回應，以指出服務預期無法提供給請求用戶端的時間長度。

到期前的秒數或日期。

變更日誌

Changed in version 2.0: 在 2.0 版本中變更：datetime 物件具有時區感知能力。

set_cookie(key, value='', max_age=None, expires=None, path='/', domain=None, secure=False, httponly=False, samesite=None, partitioned=False)¶

設定 Cookie。

如果 Cookie 標頭的大小超過 max_cookie_size，則會發出警告，但仍會設定標頭。

參數:

key ( str ) – 要設定的 Cookie 的鍵 (名稱)。
value ( str ) – Cookie 的值。
max_age ( timedelta | int | None ) – 應為秒數，或 None (預設值)，如果 Cookie 僅應在用戶端瀏覽器工作階段期間持續存在。
expires ( str | datetime | int | float | None ) – 應為 datetime 物件或 UNIX 時間戳記。
path ( str | None ) – 將 Cookie 限制為給定的路徑，預設情況下它將跨越整個網域。
domain ( str | None ) – 如果您要設定跨網域 Cookie。例如，domain="example.com" 將設定一個可由網域 www.example.com、foo.example.com 等讀取的 Cookie。否則，Cookie 將僅可由設定它的網域讀取。
secure (bool) – 如果為 True，則 cookie 僅可透過 HTTPS 取得。
httponly (bool) – 禁止 JavaScript 存取 cookie。
samesite (str | None) – 限制 cookie 的範圍，使其僅附加到「同網站」請求。
partitioned (bool) – 如果為 True，則 cookie 將被分割。

回傳類型:

None

Changed in version 3.1: 新增了 partitioned 參數。

set_data(value)¶

設定新的字串作為回應。值必須是字串或位元組。如果設定了字串，則會編碼為回應的字元集 (預設為 utf-8)。

變更日誌

在 0.9 版本中新增。

參數:: value ( bytes | str )
回傳類型:: None

set_etag(etag, weak=False)¶

設定 etag，並覆寫舊的 etag (如果有的話)。

參數:

etag ( str )
weak (bool)

回傳類型:

None

property status: str¶: HTTP 狀態碼 (字串格式)。

property status_code: int¶: HTTP 狀態碼 (數字格式)。

property stream: ResponseStream¶: 回應可迭代物件，作為僅寫入串流。

property vary: HeaderSet¶: Vary 欄位值表示一組請求標頭欄位，這些欄位完全決定了在回應為最新的情況下，快取是否被允許使用該回應來回覆後續請求，而無需重新驗證。

property www_authenticate: WWWAuthenticate¶

WWW-Authenticate 標頭已剖析為 WWWAuthenticate 物件。修改物件將修改標頭值。

預設情況下未設定此標頭。若要設定此標頭，請將 WWWAuthenticate 的執行個體指派給此屬性。

response.www_authenticate = WWWAuthenticate(
    "basic", {"realm": "Authentication Required"}
)

可以傳送此標頭的多個值，為用戶端提供多個選項。指派清單以設定多個標頭。但是，修改清單中的項目不會自動更新標頭值，並且存取此屬性將始終僅傳回第一個值。

若要取消設定此標頭，請指派 None 或使用 del。

變更日誌

Changed in version 2.3: 此屬性可以指派以設定標頭。可以指派清單以設定多個標頭值。使用 del 以取消設定標頭。

Changed in version 2.3: WWWAuthenticate 不再是 dict。token 屬性已針對使用權杖而非參數的驗證挑戰新增。

response: t.Iterable[str] | t.Iterable[bytes]¶

要作為 WSGI 可迭代物件傳送的回應本文。字串或位元組清單表示固定長度的回應，任何其他可迭代物件都是串流回應。字串會編碼為 UTF-8 位元組。

請勿設定為純字串或位元組，這會導致傳送回應非常低效，因為它會一次迭代一個位元組。

direct_passthrough¶: 直接將回應本文作為 WSGI 可迭代物件傳遞。當本文是二進位檔案或其他位元組迭代器時，可以使用此選項來跳過一些不必要的檢查。使用 send_file() 而不是手動設定此選項。

autocorrect_location_header = False¶: 如果重新導向 Location 標頭是相對 URL，請使其成為絕對 URL，包括方案和網域。

變更日誌

Changed in version 2.1: 預設情況下已停用，因此回應將傳送相對重新導向。

在 0.8 版本中新增。

property max_cookie_size: int¶

唯讀檢視 MAX_COOKIE_SIZE 設定金鑰。

請參閱 Werkzeug 文件中的 max_cookie_size。

工作階段¶

如果您已設定 Flask.secret_key (或從 SECRET_KEY 設定)，則可以在 Flask 應用程式中使用工作階段。工作階段可以記住從一個請求到另一個請求的資訊。Flask 執行此操作的方式是使用簽署的 Cookie。使用者可以查看工作階段內容，但除非他們知道密碼金鑰，否則無法修改它，因此請務必將其設定為複雜且難以猜測的內容。

若要存取目前的工作階段，您可以使用 session 物件

class flask.session¶

工作階段物件的運作方式與一般 dict 非常相似，不同之處在於它會追蹤修改。

這是一個代理物件。有關更多資訊，請參閱代理物件的注意事項。

以下屬性很有趣

new¶: 如果工作階段是新的，則為 True，否則為 False。

modified¶

如果工作階段物件偵測到修改，則為 True。請注意，不會自動擷取可變結構的修改，在這種情況下，您必須明確地將屬性設定為 True。以下範例

# this change is not picked up because a mutable object (here
# a list) is changed.
session['objects'].append(42)
# so mark it as modified yourself
session.modified = True

permanent¶: 如果設定為 True，則工作階段會持續 permanent_session_lifetime 秒。預設值為 31 天。如果設定為 False (預設值)，則當使用者關閉瀏覽器時，工作階段將會刪除。

工作階段介面¶

變更日誌

在 0.8 版本中新增。

工作階段介面提供了一種簡單的方式來取代 Flask 正在使用的工作階段實作。

class flask.sessions.SessionInterface¶

為了取代使用 werkzeug 安全 Cookie 實作的預設工作階段介面，您必須實作的基本介面。您必須實作的唯一方法是 open_session() 和 save_session()，其他方法具有有用的預設值，您不需要變更。

由 open_session() 方法傳回的工作階段物件必須提供類似字典的介面，以及來自 SessionMixin 的屬性和方法。我們建議僅子類化 dict 並新增該 mixin

class Session(dict, SessionMixin):
    pass

如果 open_session() 傳回 None，則 Flask 將呼叫 make_null_session() 以建立一個工作階段，作為工作階段支援無法運作時的替代方案，因為未滿足某些需求。建立的預設 NullSession 類別將會抱怨未設定密碼金鑰。

若要取代應用程式上的工作階段介面，您只需指派 flask.Flask.session_interface

app = Flask(__name__)
app.session_interface = MySessionInterface()

可以使用相同工作階段傳送和處理多個請求並行處理。在實作新的工作階段介面時，請考慮是否必須同步讀取或寫入備份儲存區。無法保證每個請求的工作階段開啟或儲存順序，它將按照請求開始和結束處理的順序發生。

變更日誌

在 0.8 版本中新增。

null_session_class¶

make_null_session() 將在此處尋找在請求 Null 工作階段時應建立的類別。同樣地，is_null_session() 方法將對此類型執行類型檢查。

NullSession 的別名

pickle_based = False¶: 一個旗標，指示工作階段介面是否以 pickle 為基礎。Flask 擴充功能可以使用此旗標來決定如何處理工作階段物件。

變更日誌

Added in version 0.10.

make_null_session(app)¶

建立一個 Null 工作階段，如果由於組態錯誤而無法載入實際的工作階段支援，則該工作階段會作為替代物件。這主要有助於使用者體驗，因為 Null 工作階段的工作仍然是支援查閱而不抱怨，但修改會以關於哪裡失敗的有用錯誤訊息回覆。

這預設會建立 null_session_class 的執行個體。

參數:: app ( Flask )
回傳類型:: NullSession

is_null_session(obj)¶

檢查給定的物件是否為 Null 工作階段。Null 工作階段不會被要求儲存。

這預設會檢查物件是否為 null_session_class 的執行個體。

參數:: obj ( object )
回傳類型:: bool

get_cookie_name(app)¶

工作階段 Cookie 的名稱。使用 ``app.config[“SESSION_COOKIE_NAME”]``。

參數:: app ( Flask )
回傳類型:: str

get_cookie_domain(app)¶

工作階段 Cookie 上 Domain 參數的值。如果未設定，瀏覽器將僅將 Cookie 傳送到設定它的確切網域。否則，它們也會將其傳送到給定值的任何子網域。

使用 SESSION_COOKIE_DOMAIN 設定。

變更日誌

Changed in version 2.3: 預設情況下未設定，不會回溯到 SERVER_NAME。

參數:: app ( Flask )
回傳類型:: str | None

get_cookie_path(app)¶

傳回 Cookie 應有效的路徑。預設實作會使用 SESSION_COOKIE_PATH 設定變數中的值 (如果已設定)，並回溯到 APPLICATION_ROOT，如果為 None，則使用 /。

參數:: app ( Flask )
回傳類型:: str

get_cookie_httponly(app)¶

如果工作階段 Cookie 應為 httponly，則傳回 True。目前僅傳回 SESSION_COOKIE_HTTPONLY 設定變數的值。

參數:: app ( Flask )
回傳類型:: bool

get_cookie_secure(app)¶

如果 Cookie 應為安全，則傳回 True。目前僅傳回 SESSION_COOKIE_SECURE 設定的值。

參數:: app ( Flask )
回傳類型:: bool

get_cookie_samesite(app)¶

如果 Cookie 應使用 SameSite 屬性，則傳回 'Strict' 或 'Lax'。目前僅傳回 SESSION_COOKIE_SAMESITE 設定的值。

參數:: app ( Flask )
回傳類型:: str | None

get_cookie_partitioned(app)¶

如果 Cookie 應為已分割，則傳回 True。預設情況下，使用 SESSION_COOKIE_PARTITIONED 的值。

Added in version 3.1.

參數:: app ( Flask )
回傳類型:: bool

get_expiration_time(app, session)¶

一個協助程式方法，傳回工作階段的到期日，如果工作階段連結到瀏覽器工作階段，則傳回 None。預設實作傳回現在 + 應用程式上設定的永久工作階段生命週期。

參數:

app ( Flask )
session ( SessionMixin )

回傳類型:

datetime | None

should_set_cookie(app, session)¶

工作階段後端使用此方法來判斷是否應為此回應的工作階段 Cookie 設定 Set-Cookie 標頭。如果工作階段已修改，則會設定 Cookie。如果工作階段是永久性的，並且 SESSION_REFRESH_EACH_REQUEST 設定為 true，則始終會設定 Cookie。

如果工作階段已刪除，則通常會略過此檢查。

變更日誌

在 0.11 版本中新增。

參數:

app ( Flask )
session ( SessionMixin )

回傳類型:

open_session(app, request)¶

這會在每個請求開始時呼叫，在推送請求內容之後，在比對 URL 之前。

這必須傳回一個物件，該物件實作類似字典的介面以及 SessionMixin 介面。

這將傳回 None，以指示載入在某些方面失敗，但並非立即錯誤。在這種情況下，請求內容將回溯為使用 make_null_session()。

參數:

app ( Flask )
request ( Request )

回傳類型:

SessionMixin | None

save_session(app, session, response)¶

這會在每個請求結束時呼叫，在產生回應之後，在移除請求內容之前。如果 is_null_session() 傳回 True，則會略過此呼叫。

參數:

app ( Flask )
session ( SessionMixin )
response ( Response )

回傳類型:

None

class flask.sessions.SecureCookieSessionInterface¶

預設工作階段介面，透過 itsdangerous 模組將工作階段儲存在簽署的 Cookie 中。

salt = 'cookie-session'¶: 鹽，應套用在密碼金鑰之上，以用於簽署以 Cookie 為基礎的工作階段。

static digest_method(string=b'')¶

用於簽名的雜湊函數。預設值為 sha1

參數:: string ( bytes )
回傳類型:: 任何

key_derivation = 'hmac'¶: itsdangerous 支援的金鑰衍生名稱。預設值為 hmac。

serializer = <flask.json.tag.TaggedJSONSerializer object>¶: 用於酬載的 Python 序列化程式。預設值是緊湊的 JSON 衍生序列化程式，支援一些額外的 Python 類型，例如 datetime 物件或元組。

session_class¶: SecureCookieSession 的別名

open_session(app, request)¶

這會在每個請求開始時呼叫，在推送請求內容之後，在比對 URL 之前。

這必須傳回一個物件，該物件實作類似字典的介面以及 SessionMixin 介面。

這將傳回 None，以指示載入在某些方面失敗，但並非立即錯誤。在這種情況下，請求內容將回溯為使用 make_null_session()。

參數:

app ( Flask )
request ( Request )

回傳類型:

SecureCookieSession | None

save_session(app, session, response)¶

此方法在每個請求結束時呼叫，在產生回應之後，移除請求上下文之前。如果 is_null_session() 返回 True，則會跳過此方法。

參數:

app ( Flask )
session ( SessionMixin )
response ( Response )

回傳類型:

None

class flask.sessions.SecureCookieSession(initial=None)¶

基於簽名 Cookie 的 Session 基底類別。

此 session 後端將設定 modified 和 accessed 屬性。它無法可靠地追蹤 session 是新的（相對於空的），因此 new 仍然硬式編碼為 False。

參數:: initial (c.Mapping[str, t.Any] | c.Iterable[tuple[str, t.Any]] | None)

modified = False¶: 當資料變更時，此屬性會設定為 True。僅追蹤 session 字典本身；如果 session 包含可變資料（例如巢狀字典），則在修改該資料時，必須手動將此屬性設定為 True。只有當此屬性為 True 時，session Cookie 才會寫入回應。

accessed = False¶: 標頭，允許快取 Proxy 為不同的使用者快取不同的頁面。

get(key, default=None)¶

如果鍵在字典中，則傳回鍵的值，否則傳回預設值。

參數:

key (str)
default (Any)

回傳類型:

setdefault(key, default=None)¶

如果鍵不在字典中，則插入鍵並設定值為預設值。

如果鍵在字典中，則傳回鍵的值，否則傳回預設值。

參數:

key (str)
default (Any)

回傳類型:

class flask.sessions.NullSession(initial=None)¶

用於在 session 無法使用時產生更友善的錯誤訊息的類別。仍然允許對空的 session 進行唯讀存取，但在設定時會失敗。

參數:: initial (c.Mapping[str, t.Any] | c.Iterable[tuple[str, t.Any]] | None)

clear() → None. Remove all items from D.¶

參數:

args (Any)
kwargs (Any)

回傳類型:

pop(k[, d]) → v, remove specified key and return the corresponding value.¶

如果找不到鍵，則傳回預設值（如果已給定）；否則，引發 KeyError。

參數:

args (Any)
kwargs (Any)

回傳類型:

popitem(*args, **kwargs)¶

移除並傳回 (鍵, 值) 組，作為 2-tuple。

組以 LIFO（後進先出）順序傳回。如果字典為空，則引發 KeyError。

參數:

args (Any)
kwargs (Any)

回傳類型:

update([E, ]**F) → None. Update D from dict/iterable E and F.¶

如果 E 存在且具有 .keys() 方法，則執行：for k in E: D[k] = E[k] 如果 E 存在且缺少 .keys() 方法，則執行：for k, v in E: D[k] = v 在任一情況下，接著執行：for k in F: D[k] = F[k]

參數:

args (Any)
kwargs (Any)

回傳類型:

setdefault(*args, **kwargs)¶

如果鍵不在字典中，則插入鍵並設定值為預設值。

如果鍵在字典中，則傳回鍵的值，否則傳回預設值。

參數:

args (Any)
kwargs (Any)

回傳類型:

Iterator[SessionMixin]

class flask.sessions.SessionMixin¶

使用 session 屬性擴充基本字典。

property permanent: bool¶: 這反映字典中的 '_permanent' 鍵。

modified = True¶: 某些實作可以偵測到 session 的變更，並在發生變更時設定此屬性。mixin 預設值硬式編碼為 True。

accessed = True¶: 某些實作可以偵測到何時讀取或寫入 session 資料，並在發生時設定此屬性。mixin 預設值硬式編碼為 True。

注意

PERMANENT_SESSION_LIFETIME 設定可以是整數或 timedelta。permanent_session_lifetime 屬性始終是 timedelta。

測試用戶端¶

class flask.testing.FlaskClient(*args, **kwargs)¶

運作方式類似於一般的 Werkzeug 測試用戶端，但了解 Flask 的上下文，以便將請求上下文的清理延遲到 with 區塊的末尾。關於如何使用此類別的通用資訊，請參閱 werkzeug.test.Client。

變更日誌

Changed in version 0.12: app.test_client() 包含預設環境，可以在 client.environ_base 中實例化 app.test_client() 物件後設定。

基本用法在測試 Flask 應用程式章節中概述。

參數:

args (t.Any)
kwargs (t.Any)

session_transaction(*args, **kwargs)¶

當與 with 語句結合使用時，這會開啟一個 session 事務。這可用於修改測試用戶端使用的 session。一旦離開 with 區塊，session 將儲存回去。

with client.session_transaction() as session:
    session['value'] = 42

在內部，這是通過臨時測試請求上下文實現的，並且由於 session 處理可能取決於請求變數，因此此函數接受與 test_request_context() 相同的參數，這些參數會直接傳遞。

參數:

args (Any)
kwargs (Any)

回傳類型:

open(*args, buffered=False, follow_redirects=False, **kwargs)¶

從給定的引數產生一個 environ 字典，使用它向應用程式發出請求，並傳回回應。

參數:

args (t.Any) – 傳遞給 EnvironBuilder 以建立請求的 environ。如果傳遞單個 arg，它可以是現有的 EnvironBuilder 或 environ 字典。
buffered (bool) – 將應用程式傳回的迭代器轉換為列表。如果迭代器具有 close() 方法，則會自動呼叫它。
follow_redirects (bool) – 發出額外的請求以追蹤 HTTP 重定向，直到傳回非重定向狀態。TestResponse.history 列出中間回應。
kwargs (t.Any)

回傳類型:

TestResponse

變更日誌

Changed in version 2.1: 移除 as_tuple 參數。

Changed in version 2.0: 在呼叫 response.close() 時關閉請求輸入流。重定向的輸入流會自動關閉。

Changed in version 0.5: 如果在 data 參數的字典中，將字典作為檔案提供，則內容類型必須稱為 content_type 而不是 mimetype。此變更是為了與 werkzeug.FileWrapper 保持一致。

Changed in version 0.5: 新增 follow_redirects 參數。

測試 CLI 執行器¶

class flask.testing.FlaskCliRunner(app, **kwargs)¶

用於測試 Flask 應用程式 CLI 命令的 CliRunner。通常使用 test_cli_runner() 建立。請參閱使用 CLI 執行器執行命令。

參數:

app ( Flask )
kwargs (t.Any)

invoke(cli=None, args=None, **kwargs)¶

在隔離的環境中調用 CLI 命令。有關完整的方法文件，請參閱 CliRunner.invoke。有關範例，請參閱使用 CLI 執行器執行命令。

如果未給定 obj 引數，則傳遞 ScriptInfo 的實例，該實例知道如何載入正在測試的 Flask 應用程式。

參數:

cli (Any) – 要調用的命令物件。預設值為應用程式的 cli 群組。
args (Any) – 用於調用命令的字串列表。
kwargs (Any)

Returns:

a Result 物件。

回傳類型:

Result

應用程式全域變數¶

為了在請求期間從一個函數到另一個函數共享資料，全域變數是不夠好的，因為它會在多執行緒環境中中斷。 Flask 為您提供了一個特殊的物件，確保它僅對活動請求有效，並且每個請求都將傳回不同的值。簡而言之：它做了正確的事情，就像對待 request 和 session 一樣。

flask.g¶

一個命名空間物件，可以在應用程式上下文期間儲存資料。這是 Flask.app_ctx_globals_class 的實例，預設為 ctx._AppCtxGlobals。

這是請求期間儲存資源的好地方。例如，before_request 函數可以從 session ID 載入使用者物件，然後設定 g.user 以在視圖函數中使用。

這是一個代理物件。有關更多資訊，請參閱代理物件的注意事項。

變更日誌

Changed in version 0.10: 綁定到應用程式上下文而不是請求上下文。

class flask.ctx._AppCtxGlobals¶

一個純物件。用作在應用程式上下文期間儲存資料的命名空間。

建立應用程式上下文會自動建立此物件，該物件作為 g Proxy 提供。

'key' in g: 檢查屬性是否存在。

變更日誌

Added in version 0.10.

iter(g): 傳回屬性名稱的迭代器。

變更日誌

Added in version 0.10.

get(name, default=None)¶

依名稱取得屬性，或取得預設值。類似於 dict.get()。

參數:

name (str) – 要取得的屬性名稱。
default (Any | None) – 如果屬性不存在，則傳回的值。

回傳類型:

變更日誌

Added in version 0.10.

pop(name, default=_sentinel)¶

依名稱取得並移除屬性。類似於 dict.pop()。

參數:

name (str) – 要彈出的屬性名稱。
default (Any) – 如果屬性不存在，則傳回的值，而不是引發 KeyError。

回傳類型:

變更日誌

在 0.11 版本中新增。

setdefault(name, default=None)¶

如果屬性存在，則取得其值，否則設定並傳回預設值。類似於 dict.setdefault()。

參數:

name (str) – 要取得的屬性名稱。
default (Any) – 如果屬性不存在，則設定並傳回的值。

回傳類型:

變更日誌

在 0.11 版本中新增。

實用函數和類別¶

flask.current_app¶

目前請求的應用程式的 Proxy。這在不需要匯入應用程式，或者在無法匯入應用程式時（例如在使用應用程式工廠模式或在 Blueprint 和擴充套件中）存取應用程式時非常有用。

這僅在推送應用程式上下文時可用。這會在請求和 CLI 命令期間自動發生。可以使用 app_context() 手動控制。

這是一個代理物件。有關更多資訊，請參閱代理物件的注意事項。

flask.has_request_context()¶

如果您有程式碼想要測試請求上下文是否存在，則可以使用此函數。例如，您可能希望在請求物件可用時利用請求資訊，但在不可用時靜默失敗。

class User(db.Model):

    def __init__(self, username, remote_addr=None):
        self.username = username
        if remote_addr is None and has_request_context():
            remote_addr = request.remote_addr
        self.remote_addr = remote_addr

或者，您也可以僅測試任何上下文綁定的物件（例如 request 或 g）的真值

class User(db.Model):

    def __init__(self, username, remote_addr=None):
        self.username = username
        if remote_addr is None and request:
            remote_addr = request.remote_addr
        self.remote_addr = remote_addr

變更日誌

Added in version 0.7.

回傳類型:: bool

flask.copy_current_request_context(f)¶

一個裝飾函數以保留目前請求上下文的輔助函數。這在使用 Greenlet 時非常有用。裝飾函數的那一刻，就會建立請求上下文的副本，然後在呼叫函數時推送。目前的 session 也包含在複製的請求上下文中。

範例

import gevent
from flask import copy_current_request_context

@app.route('/')
def index():
    @copy_current_request_context
    def do_some_work():
        # do some work here, it can access flask.request or
        # flask.session like you would otherwise in the view function.
        ...
    gevent.spawn(do_some_work)
    return 'Regular response'

變更日誌

Added in version 0.10.

參數:: f (F)
回傳類型:: F

flask.has_app_context()¶

運作方式類似於 has_request_context()，但適用於應用程式上下文。您也可以直接對 current_app 物件執行布林檢查。

變更日誌

在 0.9 版本中新增。

回傳類型:: bool

flask.url_for(endpoint, *, _anchor=None, _method=None, _scheme=None, _external=None, **values)¶

使用給定的值，為給定的端點產生 URL。

這需要活動的請求或應用程式上下文，並呼叫 current_app.url_for()。請參閱該方法以取得完整文件。

參數:

endpoint (str) – 與要產生的 URL 關聯的端點名稱。如果這以 . 開頭，將會使用目前的藍圖名稱（如果有的話）。
_anchor (str | None) – 如果給定，將其作為 #anchor 附加到 URL。
_method (str | None) – 如果給定，則為端點產生與此方法關聯的 URL。
_scheme (str | None) – 如果給定，如果 URL 是外部的，則將具有此 scheme。
_external (bool | None) – 如果給定，則偏好 URL 為內部 (False) 或要求其為外部 (True)。外部 URL 包含 scheme 和 domain。當不在活動請求中時，URL 預設為外部的。
values (Any) – 用於 URL 規則的可變部分的數值。未知的鍵會附加為查詢字串引數，例如 ?a=b&c=d。

回傳類型:

變更日誌

Changed in version 2.2: 呼叫 current_app.url_for，允許應用程式覆寫行為。

Changed in version 0.10: 新增 _scheme 參數。

Changed in version 0.9: 新增 _anchor 和 _method 參數。

Changed in version 0.9: 在建置錯誤時呼叫 app.handle_url_build_error。

flask.abort(code, *args, **kwargs)¶

引發給定狀態碼的 HTTPException 異常。

如果 current_app 可用，它將調用其 aborter 物件，否則它將使用 werkzeug.exceptions.abort()。

參數:

code (int | Response) – 異常的狀態碼，必須在 app.aborter 中註冊。
args (Any) – 傳遞給異常的參數。
kwargs (Any) – 傳遞給異常的關鍵字參數。

回傳類型:

變更日誌

Added in version 2.2: current_app.aborter 可用時會調用它，而不是總是使用 Werkzeug 的預設 abort。（版本 2.2 新增）

flask.redirect(location, code=302, Response=None)¶

建立重新導向回應物件。

如果 current_app 可用，它將使用其 redirect() 方法，否則它將使用 werkzeug.utils.redirect()。

參數:

location (str) – 要重新導向的 URL。
code (int) – 重新導向的狀態碼。
Response (type[Response] | None) – 要使用的 response 類別。當 current_app 啟用時不使用，它會使用 app.response_class。

回傳類型:

變更日誌

Added in version 2.2: current_app.redirect 可用時會調用它，而不是總是使用 Werkzeug 的預設 redirect。（版本 2.2 新增）

flask.make_response(*args)¶

有時需要在視圖中設定額外的標頭。由於視圖不必返回 response 物件，而是可以返回一個值，該值會被 Flask 本身轉換為 response 物件，因此很難將標頭添加到其中。可以調用此函式來代替使用 return，您將獲得一個 response 物件，您可以用它來附加標頭。

如果視圖看起來像這樣，並且您想要新增一個新的標頭

def index():
    return render_template('index.html', foo=42)

您現在可以這樣做

def index():
    response = make_response(render_template('index.html', foo=42))
    response.headers['X-Parachutes'] = 'parachutes are cool'
    return response

此函式接受您可以從視圖函式返回的完全相同的參數。例如，這會建立一個帶有 404 錯誤代碼的 response

response = make_response(render_template('not_found.html'), 404)

此函式的另一個用例是強制將視圖函式的返回值轉換為 response，這對視圖裝飾器很有用

response = make_response(view_function())
response.headers['X-Parachutes'] = 'parachutes are cool'

在內部，此函式執行以下操作

如果沒有傳遞任何參數，它會建立一個新的 response 參數
如果傳遞一個參數，則使用它調用 flask.Flask.make_response()。
如果傳遞多個參數，則這些參數將作為元組傳遞給 flask.Flask.make_response() 函式。

變更日誌

在 0.6 版本中新增。

參數:: args (t.Any)
回傳類型:: 回應

flask.after_this_request(f)¶

在此請求之後執行一個函式。這對於修改 response 物件很有用。該函式會傳遞 response 物件，並且必須返回相同的或新的物件。

範例

@app.route('/')
def index():
    @after_this_request
    def add_header(response):
        response.headers['X-Foo'] = 'Parachute'
        return response
    return 'Hello World!'

如果除了視圖函式之外的其他函式想要修改 response，這會更有用。例如，考慮一個想要新增一些標頭而不將返回值轉換為 response 物件的裝飾器。

變更日誌

在 0.9 版本中新增。

參數:: f (Callable[[Any], Any] | Callable[[Any], Awaitable[Any]])
回傳類型:: Callable[[Any], Any] | Callable[[Any], Awaitable[Any]]

flask.send_file(path_or_file, mimetype=None, as_attachment=False, download_name=None, conditional=True, etag=True, last_modified=None, max_age=None)¶

將檔案內容傳送給客戶端。

第一個參數可以是檔案路徑或類檔案物件。在大多數情況下，檔案路徑是首選，因為 Werkzeug 可以管理檔案並從路徑中取得額外資訊。傳遞類檔案物件需要以二進制模式開啟檔案，並且主要在記憶體中使用 io.BytesIO 建構檔案時很有用。

永遠不要傳遞使用者提供的檔案路徑。該路徑被假定為受信任的，因此使用者可能會精心製作一個路徑來存取您不打算提供的檔案。使用 send_from_directory() 從目錄中安全地提供使用者請求的路徑。

如果 WSGI 伺服器在 environ 中設定了 file_wrapper，則會使用它，否則會使用 Werkzeug 的內建 wrapper。或者，如果 HTTP 伺服器支援 X-Sendfile，則使用 USE_X_SENDFILE = True 配置 Flask 將告訴伺服器傳送給定的路徑，這比在 Python 中讀取它更有效率。

參數:

path_or_file (os.PathLike[t.AnyStr] | str | t.BinaryIO) – 要傳送的檔案路徑，如果給定相對路徑，則相對於當前工作目錄。或者，以二進制模式開啟的類檔案物件。請確保檔案指標已定位到資料的開頭。
mimetype (str | None) – 要為檔案傳送的 MIME 類型。如果未提供，它將嘗試從檔案名稱中偵測。
as_attachment (bool) – 向瀏覽器指示它應該提供儲存檔案而不是顯示檔案。
download_name (str | None) – 瀏覽器儲存檔案時將使用的預設名稱。預設為傳遞的檔案名稱。
conditional (bool) – 根據請求標頭啟用條件式和範圍 response。需要傳遞檔案路徑和 environ。
etag (bool | str) – 計算檔案的 ETag，這需要傳遞檔案路徑。也可以是要使用的字串。
last_modified (datetime | int | float | None) – 要為檔案傳送的最後修改時間，以秒為單位。如果未提供，它將嘗試從檔案路徑中偵測。
max_age (None | (int | t.Callable[[str | None], int | None])) – 客戶端應該快取檔案多久，以秒為單位。如果設定，Cache-Control 將為 public，否則將為 no-cache 以優先考慮條件式快取。

回傳類型:

變更日誌

Changed in version 2.0: download_name 取代了 attachment_filename 參數。如果 as_attachment=False，則會與 Content-Disposition: inline 一起傳遞。（版本 2.0 變更）

Changed in version 2.0: max_age 取代了 cache_timeout 參數。conditional 預設為啟用，且 max_age 未設定。（版本 2.0 變更）

Changed in version 2.0: etag 取代了 add_etags 參數。它可以是要使用的字串，而不是產生一個。（版本 2.0 變更）

Changed in version 2.0: 傳遞繼承自 TextIOBase 的類檔案物件將引發 ValueError，而不是傳送空檔案。（版本 2.0 變更）

Added in version 2.0: 將實作移至 Werkzeug。現在這是一個 wrapper，用於傳遞一些 Flask 特定的參數。（版本 2.0 新增）

Changed in version 1.1: filename 可以是 PathLike 物件。（版本 1.1 變更）

Changed in version 1.1: 傳遞 BytesIO 物件支援範圍請求。（版本 1.1 變更）

Changed in version 1.0.3: 為了更廣泛地與 WSGI 伺服器相容，檔案名稱使用 ASCII 而不是 Latin-1 編碼。（版本 1.0.3 變更）

Changed in version 1.0: 支援 RFC 2231 中指定的 UTF-8 檔案名稱。（版本 1.0 變更）

Changed in version 0.12: 檔案名稱不再從檔案物件自動推斷。如果您想使用自動 MIME 和 etag 支援，請透過 filename_or_fp 或 attachment_filename 傳遞檔案名稱。（版本 0.12 變更）

Changed in version 0.12: 對於 MIME 偵測，attachment_filename 優先於 filename。（版本 0.12 變更）

Changed in version 0.9: cache_timeout 預設為 Flask.get_send_file_max_age()。（版本 0.9 變更）

Changed in version 0.7: 移除了類檔案物件的 MIME 猜測和 etag 支援，因為它不可靠。如果您可以，請傳遞檔案名稱，否則請自行附加 etag。（版本 0.7 變更）

Changed in version 0.5: 新增了 add_etags、cache_timeout 和 conditional 參數。預設行為是新增 etag。（版本 0.5 變更）

版本 0.2 新增。

flask.send_from_directory(directory, path, **kwargs)¶

使用 send_file() 從目錄中傳送檔案。

@app.route("/uploads/<path:name>")
def download_file(name):
    return send_from_directory(
        app.config['UPLOAD_FOLDER'], name, as_attachment=True
    )

這是從資料夾（例如靜態檔案或上傳檔案）提供檔案的安全方法。使用 safe_join() 以確保來自客戶端的路徑不是惡意製作的，以指向指定目錄之外。

如果最終路徑未指向現有的常規檔案，則會引發 404 NotFound 錯誤。

參數:

directory (os.PathLike[str] | str) – path 必須位於其下的目錄，相對於當前應用程式的根路徑。這絕不能是由客戶端提供的值，否則會變得不安全。
path (os.PathLike[str] | str) – 要傳送的檔案路徑，相對於 directory。
kwargs (t.Any) – 要傳遞給 send_file() 的參數。

回傳類型:

變更日誌

Changed in version 2.0: path 取代了 filename 參數。（版本 2.0 變更）

Added in version 2.0: 將實作移至 Werkzeug。現在這是一個 wrapper，用於傳遞一些 Flask 特定的參數。（版本 2.0 新增）

在 0.5 版本中新增。

訊息快閃¶

flask.flash(message, category='message')¶

將訊息快閃到下一個請求。為了從 session 中移除快閃訊息並將其顯示給使用者，範本必須調用 get_flashed_messages()。

變更日誌

Changed in version 0.3: 新增了 category 參數。（版本 0.3 變更）

參數:

message (str) – 要快閃的訊息。
category (str) – 訊息的類別。建議使用以下值：'message' 用於任何類型的訊息，'error' 用於錯誤，'info' 用於資訊訊息，'warning' 用於警告。但是，任何類型的字串都可以用作類別。

回傳類型:

None

flask.get_flashed_messages(with_categories=False, category_filter=())¶

從 session 中拉取所有快閃訊息並返回它們。在同一個請求中進一步調用該函式將返回相同的訊息。預設情況下，僅返回訊息，但是當 with_categories 設定為 True 時，返回值將是一個元組列表，格式為 (category, message)。

透過在 category_filter 中提供這些類別，將快閃訊息篩選為一個或多個類別。這允許在單獨的 html 區塊中渲染類別。with_categories 和 category_filter 參數是不同的

with_categories 控制是否將類別與訊息文字一起返回（True 給出元組，其中 False 僅給出訊息文字）。
category_filter 將訊息篩選為僅與提供的類別匹配的訊息。

有關範例，請參閱訊息快閃。

變更日誌

Changed in version 0.9: 新增了 category_filter 參數。（版本 0.9 變更）

Changed in version 0.3: 新增了 with_categories 參數。（版本 0.3 變更）

參數:

with_categories (bool) – 設定為 True 也會接收類別。
category_filter (Iterable[str]) – 用於限制返回值的類別篩選器。僅返回列表中的類別。

回傳類型:

list[str] | list[tuple[str, str]]

JSON 支援¶

Flask 預設使用 Python 內建的 json 模組來處理 JSON。可以透過將不同的提供者分配給 flask.Flask.json_provider_class 或 flask.Flask.json 來變更 JSON 實作。flask.json 提供的函式將在應用程式上下文處於活動狀態時使用 app.json 上的方法。

Jinja 的 |tojson 篩選器配置為使用應用程式的 JSON 提供者。該篩選器使用 |safe 標記輸出。使用它來渲染 HTML <script> 標籤內部的資料。

<script>
    const names = {{ names|tojson }};
    renderChart(names, {{ axis_data|tojson }});
</script>

flask.json.jsonify(*args, **kwargs)¶

將給定的參數序列化為 JSON，並返回帶有 application/json mimetype 的 Response 物件。從視圖返回的 dict 或 list 將自動轉換為 JSON response，而無需調用此函式。

這需要活動的請求或應用程式上下文，並調用 app.json.response()。

在 debug 模式下，輸出會使用縮排進行格式化，使其更易於閱讀。這也可以由提供者控制。

可以給定位置參數或關鍵字參數，但不能同時給定兩者。如果未給定任何參數，則會序列化 None。

參數:

args (t.Any) – 要序列化的單個值，或要視為要序列化的列表的多個值。
kwargs (t.Any) – 視為要序列化的 dict。

回傳類型:

變更日誌

Changed in version 2.2: 調用 current_app.json.response，允許應用程式覆蓋行為。（版本 2.2 變更）

Changed in version 2.0.2: decimal.Decimal 透過轉換為字串來支援。（版本 2.0.2 變更）

Changed in version 0.11: 新增了對序列化頂層陣列的支援。這在舊版瀏覽器中存在安全風險。請參閱 JSON 安全性。（版本 0.11 變更）

版本 0.2 新增。

flask.json.dumps(obj, **kwargs)¶

將資料序列化為 JSON。

如果 current_app 可用，它將使用其 app.json.dumps() 方法，否則它將使用 json.dumps()。

參數:

obj (Any) – 要序列化的資料。
kwargs (Any) – 傳遞給 dumps 實作的參數。

回傳類型:

變更日誌

Changed in version 2.3: 移除了 app 參數。（版本 2.3 變更）

Changed in version 2.2: 調用 current_app.json.dumps，允許應用程式覆蓋行為。（版本 2.2 變更）

Changed in version 2.0.2: decimal.Decimal 透過轉換為字串來支援。（版本 2.0.2 變更）

Changed in version 2.0: encoding 將在 Flask 2.1 中移除。（版本 2.0 變更）

Changed in version 1.0.3: 可以直接傳遞 app，而無需應用程式上下文進行配置。（版本 1.0.3 變更）

flask.json.dump(obj, fp, **kwargs)¶

將資料序列化為 JSON 並寫入檔案。

如果 current_app 可用，它將使用其 app.json.dump() 方法，否則它將使用 json.dump()。

參數:

obj (Any) – 要序列化的資料。
fp (IO[str]) – 為寫入文字而開啟的檔案。應使用 UTF-8 編碼以使其成為有效的 JSON。
kwargs (Any) – 傳遞給 dump 實作的引數。

回傳類型:

None

變更日誌

Changed in version 2.3: 移除了 app 參數。（版本 2.3 變更）

版本變更自 2.2：呼叫 current_app.json.dump，允許應用程式覆寫此行為。

版本變更自 2.0：寫入二進制檔案以及 encoding 引數將在 Flask 2.1 中移除。

flask.json.loads(s, **kwargs)¶

將資料反序列化為 JSON 格式。

如果 current_app 可用，將會使用其 app.json.loads() 方法，否則將使用 json.loads()。

參數:

s (str | bytes) – 文字或 UTF-8 位元組。
kwargs (Any) – 傳遞給 loads 實作的引數。

回傳類型:

變更日誌

Changed in version 2.3: 移除了 app 參數。（版本 2.3 變更）

版本變更自 2.2：呼叫 current_app.json.loads，允許應用程式覆寫此行為。

版本變更自 2.0：encoding 將在 Flask 2.1 中移除。資料必須是字串或 UTF-8 位元組。

Changed in version 1.0.3: 可以直接傳遞 app，而無需應用程式上下文進行配置。（版本 1.0.3 變更）

flask.json.load(fp, **kwargs)¶

從檔案讀取資料，並將其反序列化為 JSON 格式。

如果 current_app 可用，將會使用其 app.json.load() 方法，否則將使用 json.load()。

參數:

fp (IO) – 為讀取文字或 UTF-8 位元組而開啟的檔案。
kwargs (Any) – 傳遞給 load 實作的引數。

回傳類型:

變更日誌

Changed in version 2.3: 移除了 app 參數。（版本 2.3 變更）

版本變更自 2.2：呼叫 current_app.json.load，允許應用程式覆寫此行為。

版本變更自 2.2：app 參數將在 Flask 2.3 中移除。

版本變更自 2.0：encoding 將在 Flask 2.1 中移除。檔案必須是文字模式，或是具有 UTF-8 位元組的二進制模式。

class flask.json.provider.JSONProvider(app)¶

應用程式的標準 JSON 操作集合。這個類別的子類別可以用來自訂 JSON 行為或使用不同的 JSON 函式庫。

若要為特定的函式庫實作提供者，請繼承這個基底類別，並至少實作 dumps() 和 loads()。所有其他方法都有預設實作。

若要使用不同的提供者，可以繼承 Flask 並將 json_provider_class 設定為提供者類別，或者將 app.json 設定為該類別的實例。

參數:: app (App) – 應用程式實例。這將會以 weakref.proxy 形式儲存在 _app 屬性上。

變更日誌

在 2.2 版本中新增。

dumps(obj, **kwargs)¶

將資料序列化為 JSON。

參數:

obj (Any) – 要序列化的資料。
kwargs (Any) – 可能會傳遞給底層的 JSON 函式庫。

回傳類型:

dump(obj, fp, **kwargs)¶

將資料序列化為 JSON 並寫入檔案。

參數:

obj (Any) – 要序列化的資料。
fp (IO[str]) – 為寫入文字而開啟的檔案。應使用 UTF-8 編碼以使其成為有效的 JSON。
kwargs (Any) – 可能會傳遞給底層的 JSON 函式庫。

回傳類型:

None

loads(s, **kwargs)¶

將資料反序列化為 JSON 格式。

參數:

s (str | bytes) – 文字或 UTF-8 位元組。
kwargs (Any) – 可能會傳遞給底層的 JSON 函式庫。

回傳類型:

load(fp, **kwargs)¶

從檔案讀取資料，並將其反序列化為 JSON 格式。

參數:

fp (IO) – 為讀取文字或 UTF-8 位元組而開啟的檔案。
kwargs (Any) – 可能會傳遞給底層的 JSON 函式庫。

回傳類型:

response(*args, **kwargs)¶

將給定的引數序列化為 JSON 格式，並傳回具有 application/json mimetype 的 Response 物件。

jsonify() 函式會為目前的應用程式呼叫這個方法。

可以給定位置參數或關鍵字參數，但不能同時給定兩者。如果未給定任何參數，則會序列化 None。

參數:

args (t.Any) – 要序列化的單個值，或要視為要序列化的列表的多個值。
kwargs (t.Any) – 視為要序列化的 dict。

回傳類型:

class flask.json.provider.DefaultJSONProvider(app)¶

使用 Python 內建的 json 函式庫提供 JSON 操作。序列化以下額外的資料類型

datetime.datetime 和 datetime.date 會序列化為 RFC 822 字串。這與 HTTP 日期格式相同。
uuid.UUID 會序列化為字串。
dataclasses.dataclass 會傳遞至 dataclasses.asdict()。
Markup (或任何具有 __html__ 方法的物件) 將會呼叫 __html__ 方法以取得字串。

參數:: app (App)

static default(o)¶

將此函式套用至任何 json.dumps() 不知道如何序列化的物件。它應該傳回有效的 JSON 類型或引發 TypeError。

參數:: o (Any)
回傳類型:: 任何

ensure_ascii = True¶: 將非 ASCII 字元取代為跳脫序列。這可能與某些用戶端更相容，但可以停用以獲得更好的效能和大小。

sort_keys = True¶: 排序任何序列化字典中的鍵。這可能對某些快取情況很有用，但可以停用以獲得更好的效能。啟用時，鍵必須全部都是字串，它們在排序之前不會被轉換。

compact: bool | None = None¶: 如果 True，或在非偵錯模式下為 None，response() 輸出將不會新增縮排、換行符號或空格。如果 False，或在偵錯模式下為 None，它將會使用非精簡表示法。

mimetype = 'application/json'¶: 在 response() 中設定的 mimetype。

dumps(obj, **kwargs)¶

將資料序列化為 JSON 字串。

關鍵字引數會傳遞給 json.dumps()。從 default、ensure_ascii 和 sort_keys 屬性設定一些參數預設值。

參數:

obj (Any) – 要序列化的資料。
kwargs (Any) – 傳遞至 json.dumps()。

回傳類型:

loads(s, **kwargs)¶

從字串或位元組將資料反序列化為 JSON 格式。

參數:

s (str | bytes) – 文字或 UTF-8 位元組。
kwargs (Any) – 傳遞至 json.loads()。

回傳類型:

response(*args, **kwargs)¶

將給定的引數序列化為 JSON 格式，並傳回具有它的 Response 物件。回應 mimetype 將會是 "application/json"，並且可以使用 mimetype 變更。

如果 compact 是 False 或已啟用偵錯模式，則輸出將會格式化為更易於閱讀。

可以給定位置參數或關鍵字參數，但不能同時給定兩者。如果未給定任何參數，則會序列化 None。

參數:

args (t.Any) – 要序列化的單個值，或要視為要序列化的列表的多個值。
kwargs (t.Any) – 視為要序列化的 dict。

回傳類型:

標籤化 JSON¶

用於無損序列化非標準 JSON 類型的精簡表示法。SecureCookieSessionInterface 使用它來序列化 session 資料，但它在其他地方也可能很有用。它可以擴充以支援其他類型。

class flask.json.tag.TaggedJSONSerializer¶

使用標籤系統來精簡表示非 JSON 類型的物件的序列化器。作為中介序列化器傳遞給 itsdangerous.Serializer。

支援以下額外類型

default_tags = [<class 'flask.json.tag.TagDict'>, <class 'flask.json.tag.PassDict'>, <class 'flask.json.tag.TagTuple'>, <class 'flask.json.tag.PassList'>, <class 'flask.json.tag.TagBytes'>, <class 'flask.json.tag.TagMarkup'>, <class 'flask.json.tag.TagUUID'>, <class 'flask.json.tag.TagDateTime'>]¶: 建立序列化器時要綁定的標籤類別。可以使用 register() 在稍後新增其他標籤。

register(tag_class, force=False, index=None)¶

向此序列化器註冊新的標籤。

參數:

tag_class (type[JSONTag]) – 要註冊的標籤類別。將會使用此序列化器實例化。
force (bool) – 覆寫現有的標籤。如果為 false (預設值)，則會引發 KeyError。
index (int | None) – 在標籤順序中插入新標籤的索引。當新標籤是現有標籤的特殊情況時很有用。如果為 None (預設值)，則標籤會附加到順序的末尾。

Raises:

KeyError – 如果標籤鍵已註冊且 force 不為 true。

回傳類型:

None

tag(value)¶

必要時將值轉換為標籤化表示法。

參數:: value (Any)
回傳類型:: 任何

untag(value)¶

將標籤化表示法轉換回原始類型。

參數:: value (dict[str, Any])
回傳類型:: 任何

dumps(value)¶

標籤化值並將其傾印為精簡的 JSON 字串。

參數:: value (Any)
回傳類型:: str

loads(value)¶

從 JSON 字串載入資料並反序列化任何標籤化物件。

參數:: value (str)
回傳類型:: 任何

class flask.json.tag.JSONTag(serializer)¶

TaggedJSONSerializer 的類型標籤定義的基底類別。

參數:: serializer (TaggedJSONSerializer)

key: str = ''¶: 用於標記序列化物件的標籤。如果為空，則此標籤僅用作標籤化期間的中間步驟。

check(value)¶

檢查給定的值是否應該由此標籤標記。

參數:: value (Any)
回傳類型:: bool

to_json(value)¶

將 Python 物件轉換為有效的 JSON 類型的物件。標籤將在稍後新增。

參數:: value (Any)
回傳類型:: 任何

to_python(value)¶

將 JSON 表示法轉換回正確的類型。標籤將已被移除。

參數:: value (Any)
回傳類型:: 任何

tag(value)¶

將值轉換為有效的 JSON 類型，並在其周圍新增標籤結構。

參數:: value (Any)
回傳類型:: dict[str, Any]

讓我們來看一個範例，新增對 OrderedDict 的支援。字典在 JSON 中沒有順序，因此為了處理這個問題，我們將項目傾印為 [key, value] 配對的列表。繼承 JSONTag 並給它新的鍵 ' od' 以識別類型。session 序列化器首先處理字典，因此將新標籤插入順序的前面，因為 OrderedDict 必須在 dict 之前處理。

from flask.json.tag import JSONTag

class TagOrderedDict(JSONTag):
    __slots__ = ('serializer',)
    key = ' od'

    def check(self, value):
        return isinstance(value, OrderedDict)

    def to_json(self, value):
        return [[k, self.serializer.tag(v)] for k, v in iteritems(value)]

    def to_python(self, value):
        return OrderedDict(value)

app.session_interface.serializer.register(TagOrderedDict, index=0)

模板渲染¶

flask.render_template(template_name_or_list, **context)¶

使用給定的上下文渲染指定名稱的模板。

參數:

template_name_or_list (str | Template | list[str | Template]) – 要渲染的模板名稱。如果給定列表，則將渲染第一個存在的名稱。
context (Any) – 要在模板中提供的變數。

回傳類型:

flask.render_template_string(source, **context)¶

使用給定的上下文從給定的原始碼字串渲染模板。

參數:

source (str) – 要渲染的模板原始碼。
context (Any) – 要在模板中提供的變數。

回傳類型:

flask.stream_template(template_name_or_list, **context)¶

使用給定的上下文以串流方式渲染指定名稱的模板。這會傳回字串的迭代器，可以用作視圖的串流回應。

參數:

template_name_or_list (str | Template | list[str | Template]) – 要渲染的模板名稱。如果給定列表，則將渲染第一個存在的名稱。
context (Any) – 要在模板中提供的變數。

回傳類型:

Iterator[str]

變更日誌

在 2.2 版本中新增。

flask.stream_template_string(source, **context)¶

使用給定的上下文以串流方式從給定的原始碼字串渲染模板。這會傳回字串的迭代器，可以用作視圖的串流回應。

參數:

source (str) – 要渲染的模板原始碼。
context (Any) – 要在模板中提供的變數。

回傳類型:

Iterator[str]

變更日誌

在 2.2 版本中新增。

flask.get_template_attribute(template_name, attribute)¶

載入模板匯出的巨集（或變數）。這可以用於從 Python 程式碼中調用巨集。例如，如果您有一個名為 _cider.html 的模板，其內容如下

{% macro hello(name) %}Hello {{ name }}!{% endmacro %}

您可以像這樣從 Python 程式碼存取它

hello = get_template_attribute('_cider.html', 'hello')
return hello('World')

變更日誌

版本 0.2 新增。

參數:

template_name (str) – 模板的名稱
attribute (str) – 要存取的變數或巨集的名稱

回傳類型:

設定¶

class flask.Config(root_path, defaults=None)¶

完全如同字典般運作，但提供從檔案或特殊字典填充內容的方法。有兩種常見的模式來填充設定。

您可以從設定檔填充設定

app.config.from_pyfile('yourconfig.cfg')

或者，您可以在呼叫 from_object() 的模組中定義組態選項，或提供應載入模組的匯入路徑。也可以告知它使用相同的模組，並在呼叫之前提供組態值

DEBUG = True
SECRET_KEY = 'development key'
app.config.from_object(__name__)

在這兩種情況下（從任何 Python 檔案載入或從模組載入），只有大寫鍵會被新增到設定中。這使得可以在設定檔中使用小寫值作為不會新增到設定的暫時值，或在實作應用程式的同一個檔案中定義設定鍵。

可能最有趣的載入設定方式是從指向檔案的環境變數載入

app.config.from_envvar('YOURAPPLICATION_SETTINGS')

在這種情況下，在啟動應用程式之前，您必須將此環境變數設定為您想要使用的檔案。在 Linux 和 OS X 上，使用 export 陳述式

export YOURAPPLICATION_SETTINGS='/path/to/config/file'

在 Windows 上，請改用 set。

參數:

root_path (str | os.PathLike[str]) – 檔案讀取時的相對路徑。當組態物件由應用程式建立時，這是應用程式的 root_path。
defaults (dict[str, t.Any] | None) – 預設值的可選字典

from_envvar(variable_name, silent=False)¶

從指向組態檔的環境變數載入組態。這基本上只是一個捷徑，對於這行程式碼提供了更友善的錯誤訊息

app.config.from_pyfile(os.environ['YOURAPPLICATION_SETTINGS'])

參數:

variable_name (str) – 環境變數的名稱
silent (bool) – 如果您希望在檔案遺失時靜默失敗，請設定為 True。

Returns:

True 如果檔案成功載入。

回傳類型:

from_prefixed_env(prefix='FLASK', *, loads=json.loads)¶

載入任何以 FLASK_ 開頭的環境變數，從環境鍵中刪除前綴作為設定鍵。值會透過載入函數傳遞，嘗試將它們轉換為比字串更特定的類型。

鍵以 sorted() 順序載入。

預設載入函數嘗試將值解析為任何有效的 JSON 類型，包括字典和列表。

巢狀字典中的特定項目可以使用雙底線 (__) 分隔鍵來設定。如果中繼鍵不存在，它將被初始化為空字典。

參數:

prefix (str) – 載入以此前綴開頭的環境變數，以底線 (_) 分隔。
loads (Callable[[str], Any]) – 將每個字串值傳遞給此函數，並使用傳回值作為設定值。如果引發任何錯誤，則會忽略該錯誤，並且值保持為字串。預設值為 json.loads()。

回傳類型:

變更日誌

在 2.1 版本中新增。

from_pyfile(filename, silent=False)¶

從 Python 檔案更新設定中的值。此函數的行為就像檔案被作為模組匯入，並使用 from_object() 函數一樣。

參數:

filename (str | PathLike[str]) – 設定檔的檔案名稱。這可以是絕對檔案名稱或相對於根路徑的檔案名稱。
silent (bool) – 如果您希望在檔案遺失時靜默失敗，請設定為 True。

Returns:

True 如果檔案成功載入。

回傳類型:

變更日誌

在 0.7 版本中新增: silent 參數。

from_object(obj)¶

從給定的物件更新值。物件可以是以下兩種型別之一

字串：在這種情況下，將匯入具有該名稱的物件
實際物件參考：直接使用該物件

物件通常是模組或類別。 from_object() 僅載入模組/類別的大寫屬性。 dict 物件不適用於 from_object()，因為 dict 的鍵不是 dict 類別的屬性。

基於模組的設定範例

app.config.from_object('yourapplication.default_config')
from yourapplication import default_config
app.config.from_object(default_config)

在載入之前，不會對物件進行任何處理。如果物件是類別且具有 @property 屬性，則需要在傳遞給此方法之前實例化。

您不應使用此函數載入實際的設定，而應載入預設設定。實際設定應使用 from_pyfile() 載入，理想情況下，應從套件外部的位置載入，因為套件可能已在系統範圍內安裝。

請參閱開發/生產環境設定以取得使用 from_object() 的基於類別的設定範例。

參數:: obj (object | str) – 匯入名稱或物件
回傳類型:: None

from_file(filename, load, silent=False, text=True)¶

從使用 load 參數載入的檔案更新設定中的值。載入的資料會傳遞給 from_mapping() 方法。

import json
app.config.from_file("config.json", load=json.load)

import tomllib
app.config.from_file("config.toml", load=tomllib.load, text=False)

參數:

filename (str | PathLike[str]) – 資料檔案的路徑。這可以是絕對路徑或相對於設定根路徑的路徑。
load (Callable[[Reader], Mapping] 其中 Reader 實作了 read 方法。) – 一個可呼叫物件，它接受檔案控制代碼並傳回從檔案載入的資料的映射。
silent (bool) – 如果檔案不存在則忽略它。
text (bool) – 以文字或二進制模式開啟檔案。

Returns:

True 如果檔案成功載入。

回傳類型:

變更日誌

在 2.3 版本中變更: 新增了 text 參數。

Added in version 2.0.

from_mapping(mapping=None, **kwargs)¶

如同 update() 一樣更新設定，忽略非大寫鍵的項目。

Returns:

總是傳回 True。

參數:

mapping (Mapping[str, Any] | None)
kwargs (Any)

回傳類型:

變更日誌

在 0.11 版本中新增。

get_namespace(namespace, lowercase=True, trim_namespace=True)¶

傳回一個字典，其中包含符合指定命名空間/前綴的設定選項子集。範例用法

app.config['IMAGE_STORE_TYPE'] = 'fs'
app.config['IMAGE_STORE_PATH'] = '/var/app/images'
app.config['IMAGE_STORE_BASE_URL'] = 'http://img.website.com'
image_store_config = app.config.get_namespace('IMAGE_STORE_')

結果字典 image_store_config 看起來會像這樣

{
    'type': 'fs',
    'path': '/var/app/images',
    'base_url': 'http://img.website.com'
}

當設定選項直接映射到函數或類別建構子中的關鍵字引數時，這通常很有用。

參數:

namespace (str) – 設定命名空間
lowercase (bool) – 一個旗標，指示結果字典的鍵是否應為小寫
trim_namespace (bool) – 一個旗標，指示結果字典的鍵是否不應包含命名空間

回傳類型:

dict[str, Any]

變更日誌

在 0.11 版本中新增。

串流助手¶

flask.stream_with_context(generator_or_function: Iterator) → Iterator¶

flask.stream_with_context(generator_or_function: Callable[[...], Iterator]) → Callable[[Iterator], Iterator]

當伺服器開始回應時，請求上下文就會消失。這樣做是為了提高效率，並減少因 WSGI 中介軟體寫得不好而遇到記憶體洩漏的可能性。缺點是，如果您正在使用串流回應，則產生器將無法再存取請求綁定的資訊。

但是，此函數可以幫助您將上下文保持更長的時間

from flask import stream_with_context, request, Response

@app.route('/stream')
def streamed_response():
    @stream_with_context
    def generate():
        yield 'Hello '
        yield request.args['name']
        yield '!'
    return Response(generate())

或者，它也可以在特定的產生器周圍使用

from flask import stream_with_context, request, Response

@app.route('/stream')
def streamed_response():
    def generate():
        yield 'Hello '
        yield request.args['name']
        yield '!'
    return Response(stream_with_context(generate()))

變更日誌

在 0.9 版本中新增。

實用內部元件¶

class flask.ctx.RequestContext(app, environ, request=None, session=None)¶

請求上下文包含每個請求的資訊。 Flask 應用程式在請求開始時建立並推送它，然後在請求結束時彈出它。它將為提供的 WSGI 環境建立 URL 適配器和請求物件。

請勿嘗試直接使用此類別，而是使用 test_request_context() 和 request_context() 來建立此物件。

當請求上下文被彈出時，它將評估在應用程式上註冊的所有用於拆解執行的函數 (teardown_request())。

請求上下文會在請求結束時自動彈出。當使用互動式偵錯工具時，上下文將會還原，以便 request 仍然可以存取。同樣地，測試用戶端可以在請求結束後保留上下文。但是，拆解函數可能已經關閉了一些資源，例如資料庫連線。

參數:

app ( Flask )
environ (WSGIEnvironment)
request (Request | None)
session (SessionMixin | None)

copy()¶

建立此請求上下文的副本，具有相同的請求物件。這可以用於將請求上下文移動到不同的 Greenlet。因為實際的請求物件是相同的，所以除非鎖定對請求物件的存取，否則不能用於將請求上下文移動到不同的執行緒。

變更日誌

在 1.1 版本中變更: 使用目前的會話物件，而不是重新載入原始資料。這可以防止 flask.session 指向過時的物件。

Added in version 0.10.

回傳類型:: RequestContext

match_request()¶

可以由子類別覆寫，以掛鉤到請求的匹配。

回傳類型:: None

pop(exc=_sentinel)¶

彈出請求上下文並透過這樣做解除綁定。這也將觸發由 teardown_request() 裝飾器註冊的函數的執行。

變更日誌

在 0.9 版本中變更: 新增了 exc 引數。

參數:: exc (BaseException | None)
回傳類型:: None

flask.globals.request_ctx¶

目前的 RequestContext。如果請求上下文未啟用，則存取此代理上的屬性將引發 RuntimeError。

這是一個內部物件，對於 Flask 如何處理請求至關重要。在大多數情況下，不需要存取此物件。您很可能想要的是 request 和 session。

class flask.ctx.AppContext(app)¶

應用程式上下文包含特定於應用程式的資訊。如果應用程式上下文尚未啟用，則會在每個請求開始時建立並推送應用程式上下文。當執行 CLI 命令時，也會推送應用程式上下文。

參數:: app ( Flask )

push()¶

將應用程式上下文綁定到目前的上下文。

回傳類型:: None

pop(exc=_sentinel)¶

彈出應用程式上下文。

參數:: exc (BaseException | None)
回傳類型:: None

flask.globals.app_ctx¶

目前的 AppContext。如果應用程式上下文未啟用，則存取此代理上的屬性將引發 RuntimeError。

這是一個內部物件，對於 Flask 如何處理請求至關重要。在大多數情況下，不需要存取此物件。您很可能想要的是 current_app 和 g。

class flask.blueprints.BlueprintSetupState(blueprint, app, options, first_registration)¶

用於向應用程式註冊藍圖的臨時持有者物件。此類別的實例由 make_setup_state() 方法建立，稍後傳遞給所有註冊回呼函數。

參數:

blueprint (Blueprint)
app (App)
options (t.Any)
first_registration (bool)

app¶: 對目前應用程式的參考

blueprint¶: 對建立此設定狀態的藍圖的參考。

options¶: 包含所有傳遞給 register_blueprint() 方法的選項的字典。

first_registration¶: 由於藍圖可以向應用程式註冊多次，並且並非所有內容都希望在其上註冊多次，因此可以使用此屬性來判斷藍圖是否已在過去註冊過。

subdomain¶: 藍圖應啟用的子網域，否則為 None。

url_prefix¶: 應用於藍圖上定義的所有 URL 的前綴。

url_defaults¶: 一個包含 URL 預設值的字典，該字典會新增到使用藍圖定義的每個 URL。

add_url_rule(rule, endpoint=None, view_func=None, **options)¶

一個輔助方法，用於向應用程式註冊規則（以及可選的視圖函數）。端點會自動加上藍圖的名稱作為前綴。

參數:

rule (str)
endpoint (str | None)
view_func (ft.RouteCallable | None)
options (t.Any)

回傳類型:

None

訊號¶

訊號由 Blinker 函式庫提供。請參閱訊號以取得簡介。

flask.template_rendered¶

當模板成功呈現時，會傳送此訊號。訊號會使用模板的實例作為 template 和上下文作為字典（名為 context）調用。

訂閱者範例

def log_template_renders(sender, template, context, **extra):
    sender.logger.debug('Rendering template "%s" with context %s',
                        template.name or 'string template',
                        context)

from flask import template_rendered
template_rendered.connect(log_template_renders, app)

flask.before_render_template

此訊號在模板呈現過程之前傳送。訊號會使用模板的實例作為 template 和上下文作為字典（名為 context）調用。

訂閱者範例

def log_template_renders(sender, template, context, **extra):
    sender.logger.debug('Rendering template "%s" with context %s',
                        template.name or 'string template',
                        context)

from flask import before_render_template
before_render_template.connect(log_template_renders, app)

flask.request_started¶

當請求上下文設定完成時，在任何請求處理發生之前，會傳送此訊號。由於請求上下文已綁定，因此訂閱者可以使用標準全域代理（例如 request）存取請求。

訂閱者範例

def log_request(sender, **extra):
    sender.logger.debug('Request context is set up')

from flask import request_started
request_started.connect(log_request, app)

flask.request_finished¶

此訊號會在回應傳送至用戶端之前立即傳送。它會將要傳送的回應（名為 response）傳遞出去。

訂閱者範例

def log_response(sender, response, **extra):
    sender.logger.debug('Request context is about to close down. '
                        'Response: %s', response)

from flask import request_finished
request_finished.connect(log_response, app)

flask.got_request_exception¶

當請求處理期間發生未處理的例外狀況時，包括在偵錯時，會傳送此訊號。例外狀況會作為 exception 傳遞給訂閱者。

此訊號不會針對 HTTPException 或其他已註冊錯誤處理常式的例外狀況傳送，除非例外狀況是從錯誤處理常式引發的。

此範例示範了如果引發理論上的 SecurityException 時如何執行一些額外的記錄

from flask import got_request_exception

def log_security_exception(sender, exception, **extra):
    if not isinstance(exception, SecurityException):
        return

    security_logger.exception(
        f"SecurityException at {request.url!r}",
        exc_info=exception,
    )

got_request_exception.connect(log_security_exception, app)

flask.request_tearing_down¶

當請求正在拆解時，會傳送此訊號。即使發生例外狀況，也總是會呼叫它。目前，監聽此訊號的函數會在常規拆解處理常式之後呼叫，但這不是您可以依賴的東西。

訂閱者範例

def close_db_connection(sender, **extra):
    session.close()

from flask import request_tearing_down
request_tearing_down.connect(close_db_connection, app)

從 Flask 0.9 開始，這也會傳遞一個 exc 關鍵字引數，如果存在導致拆解的例外狀況，則該引數會參考該例外狀況。

flask.appcontext_tearing_down¶

當應用程式上下文正在拆解時，會傳送此訊號。即使發生例外狀況，也總是會呼叫它。目前，監聽此訊號的函數會在常規拆解處理常式之後呼叫，但這不是您可以依賴的東西。

訂閱者範例

def close_db_connection(sender, **extra):
    session.close()

from flask import appcontext_tearing_down
appcontext_tearing_down.connect(close_db_connection, app)

這也會傳遞一個 exc 關鍵字引數，如果存在導致拆解的例外狀況，則該引數會參考該例外狀況。

flask.appcontext_pushed¶

當應用程式上下文被推送時，會傳送此訊號。傳送者是應用程式。這通常對於單元測試很有用，以便暫時掛鉤資訊。例如，它可以用於在 g 物件上提早設定資源。

用法範例

from contextlib import contextmanager
from flask import appcontext_pushed

@contextmanager
def user_set(app, user):
    def handler(sender, **kwargs):
        g.user = user
    with appcontext_pushed.connected_to(handler, app):
        yield

在測試程式碼中

def test_user_me(self):
    with user_set(app, 'john'):
        c = app.test_client()
        resp = c.get('/users/me')
        assert resp.data == 'username=john'

變更日誌

Added in version 0.10.

flask.appcontext_popped¶: 此訊號會在應用程式上下文彈出時傳送。發送者為應用程式。這通常與 appcontext_tearing_down 訊號一致。

變更日誌

Added in version 0.10.

flask.message_flashed¶

當應用程式快閃訊息時，會傳送此訊號。訊息會以 message 關鍵字參數和類別以 category 傳送。

訂閱者範例

recorded = []
def record(sender, message, category, **extra):
    recorded.append((message, category))

from flask import message_flashed
message_flashed.connect(record, app)

變更日誌

Added in version 0.10.

類別型視圖¶

變更日誌

Added in version 0.7.

class flask.views.View¶

繼承此類別並覆寫 dispatch_request() 以建立通用類別型視圖。呼叫 as_view() 以建立視圖函式，該函式使用給定的引數建立類別的實例，並使用任何 URL 變數呼叫其 dispatch_request 方法。

請參閱類別型視圖以取得詳細指南。

class Hello(View):
    init_every_request = False

    def dispatch_request(self, name):
        return f"Hello, {name}!"

app.add_url_rule(
    "/hello/<name>", view_func=Hello.as_view("hello")
)

設定類別上的 methods 以變更視圖接受的方法。

設定類別上的 decorators，以將裝飾器列表套用至產生的視圖函式。套用至類別本身的裝飾器將不會套用至產生的視圖函式！

將 init_every_request 設定為 False 以提高效率，除非您需要在 self 上儲存請求全域資料。

methods: ClassVar[Collection[str] | None] = None¶: 此視圖註冊用於的方法。預設使用與 route 和 add_url_rule 相同的預設值（["GET", "HEAD", "OPTIONS"]）。

provide_automatic_options: ClassVar[bool | None] = None¶: 控制是否自動處理 OPTIONS 方法。預設使用與 route 和 add_url_rule 相同的預設值（True）。

decorators: ClassVar[list[Callable[[...], Any]]] = []¶: 要依序套用至產生的視圖函式的裝飾器列表。請記住，@decorator 語法是由下而上套用的，因此列表中的第一個裝飾器將會是最底層的裝飾器。

變更日誌

在 0.8 版本中新增。

init_every_request: ClassVar[bool] = True¶

預設為每個請求建立此視圖類別的新實例。如果視圖子類別將其設定為 False，則每個請求都會使用相同的實例。

單一實例更有效率，尤其是在初始化期間完成複雜設定時。但是，跨請求在 self 上儲存資料已不再安全，應改為使用 g。

變更日誌

在 2.2 版本中新增。

dispatch_request()¶

實際的視圖函式行為。子類別必須覆寫此方法並傳回有效的回應。來自 URL 規則的任何變數都會作為關鍵字參數傳遞。

回傳類型:: ft.ResponseReturnValue

classmethod as_view(name, *class_args, **class_kwargs)¶

將類別轉換為可為路由註冊的視圖函式。

預設情況下，產生的視圖將為每個請求建立視圖類別的新實例，並呼叫其 dispatch_request() 方法。如果視圖類別將 init_every_request 設定為 False，則每個請求都會使用相同的實例。

除了 name 之外，傳遞給此方法的所有其他引數都會轉發到視圖類別 __init__ 方法。

變更日誌

版本變更自 2.2: 新增了 init_every_request 類別屬性。

參數:

name (str)
class_args (t.Any)
class_kwargs (t.Any)

回傳類型:

ft.RouteCallable

class flask.views.MethodView¶

將請求方法分派到對應的實例方法。例如，如果您實作 get 方法，它將用於處理 GET 請求。

這對於定義 REST API 很有用。

methods 會根據類別上定義的方法自動設定。

請參閱類別型視圖以取得詳細指南。

class CounterAPI(MethodView):
    def get(self):
        return str(session.get("counter", 0))

    def post(self):
        session["counter"] = session.get("counter", 0) + 1
        return redirect(url_for("counter"))

app.add_url_rule(
    "/counter", view_func=CounterAPI.as_view("counter")
)

dispatch_request(**kwargs)¶

實際的視圖函式行為。子類別必須覆寫此方法並傳回有效的回應。來自 URL 規則的任何變數都會作為關鍵字參數傳遞。

參數:: kwargs (t.Any)
回傳類型:: ft.ResponseReturnValue

URL 路由註冊¶

一般來說，有三種方式可以定義路由系統的規則

您可以使用 flask.Flask.route() 裝飾器。
您可以使用 flask.Flask.add_url_rule() 函式。
您可以直接存取底層 Werkzeug 路由系統，該系統公開為 flask.Flask.url_map。

路由中的變數部分可以使用角括號 (/user/<username>) 指定。預設情況下，URL 中的變數部分接受不含斜線的任何字串，但也可以使用 <converter:name> 指定不同的轉換器。

變數部分會作為關鍵字參數傳遞至視圖函式。

提供以下轉換器

`string`	接受不含斜線的任何文字 (預設值)
`int`	接受整數
`float`	類似 `int`，但用於浮點數值
`path`	類似預設值，但也接受斜線
`any`	符合提供的其中一個項目
`uuid`	接受 UUID 字串

可以使用 flask.Flask.url_map 定義自訂轉換器。

以下是一些範例

@app.route('/')
def index():
    pass

@app.route('/<username>')
def show_user(username):
    pass

@app.route('/post/<int:post_id>')
def show_post(post_id):
    pass

務必記住的一個重要細節是 Flask 如何處理尾隨斜線。目的是保持每個 URL 的唯一性，因此適用以下規則

如果規則以斜線結尾，並且使用者在沒有斜線的情況下請求，則使用者會自動重新導向至附加尾隨斜線的相同頁面。
如果規則不以尾隨斜線結尾，並且使用者使用尾隨斜線請求頁面，則會引發 404 找不到錯誤。

這與網頁伺服器處理靜態檔案的方式一致。這也使得安全地使用相對連結目標成為可能。

您也可以為同一個函式定義多個規則。但是，它們必須是唯一的。也可以指定預設值。例如，以下是接受選用頁面的 URL 的定義

@app.route('/users/', defaults={'page': 1})
@app.route('/users/page/<int:page>')
def show_users(page):
    pass

這指定 /users/ 將是第一頁的 URL，而 /users/page/N 將是第 N 頁的 URL。

如果 URL 包含預設值，它將重新導向到其更簡單的形式，並顯示 301 重新導向。在上面的範例中，/users/page/1 將重新導向到 /users/。如果您的路由處理 GET 和 POST 請求，請確保預設路由僅處理 GET，因為重新導向無法保留表單資料。

@app.route('/region/', defaults={'id': 1})
@app.route('/region/<int:id>', methods=['GET', 'POST'])
def region(id):
   pass

以下是 route() 和 add_url_rule() 接受的參數。唯一的區別在於，使用 route 參數時，視圖函式是使用裝飾器而不是 view_func 參數定義的。

`rule`	作為字串的 URL 規則
`endpoint`	註冊 URL 規則的端點。如果未明確聲明，Flask 本身會假設視圖函式的名稱是端點的名稱。
`view_func`	在服務對所提供端點的請求時要呼叫的函式。如果未提供此項，則稍後可以透過將函式儲存在 `view_functions` 字典中，並以端點作為鍵來指定函式。
`defaults`	包含此規則預設值的字典。請參閱上面的範例，了解預設值如何運作。
`subdomain`	指定子網域規則，以防正在使用子網域比對。如果未指定，則假設為預設子網域。
`**options`	要轉發到底層 `Rule` 物件的選項。Werkzeug 的變更是方法選項的處理方式。methods 是此規則應限制使用的方法列表（`GET`、`POST` 等）。預設情況下，規則僅監聽 `GET`（和隱含的 `HEAD`）。從 Flask 0.6 開始，`OPTIONS` 會隱含地新增並由標準請求處理來處理。它們必須指定為關鍵字參數。

視圖函式選項¶

對於內部使用，視圖函式可以附加一些屬性，以自訂視圖函式通常無法控制的行為。可以選擇性地提供以下屬性，以覆寫 add_url_rule() 或一般行為的某些預設值

__name__：函式的名稱預設用作端點。如果明確提供了端點，則會使用此值。此外，預設情況下，這將以藍圖的名稱作為前綴，而藍圖的名稱無法從函式本身自訂。
methods：如果在新增 URL 規則時未提供方法，Flask 將在視圖函式物件本身上尋找是否存在 methods 屬性。如果存在，它將從那裡提取方法的資訊。
provide_automatic_options：如果設定了此屬性，Flask 將強制啟用或停用 HTTP OPTIONS 回應的自動實作。當使用想要在每個視圖的基礎上自訂 OPTIONS 回應的裝飾器時，這會很有用。
required_methods：如果設定了此屬性，即使方法在 route() 呼叫中被明確覆寫，Flask 也始終會在註冊 URL 規則時新增這些方法。

完整範例

def index():
    if request.method == 'OPTIONS':
        # custom options handling here
        ...
    return 'Hello World!'
index.provide_automatic_options = False
index.methods = ['GET', 'OPTIONS']

app.add_url_rule('/', index)

變更日誌

版本新增自 0.8: 新增了 provide_automatic_options 功能。

命令列介面¶

class flask.cli.FlaskGroup(add_default_commands=True, create_app=None, add_version_option=True, load_dotenv=True, set_debug_flag=True, **extra)¶

特殊的 AppGroup 群組子類別，支援從設定的 Flask 應用程式載入更多命令。通常開發人員不必與此類別介接，但對於某些非常進階的使用案例來說，建立此類別的實例是有意義的。請參閱自訂腳本。

參數:

add_default_commands (bool) – 如果為 True，則會新增預設的 run 和 shell 命令。
add_version_option (bool) – 新增 --version 選項。
create_app (t.Callable[..., Flask] | None) – 選用回呼，會將腳本資訊傳遞給它，並傳回載入的應用程式。
load_dotenv (bool) – 載入最近的 .env 和 .flaskenv 檔案以設定環境變數。也會將工作目錄變更為包含找到的第一個檔案的目錄。
set_debug_flag (bool) – 設定應用程式的偵錯旗標。
extra (t.Any)

版本變更自 3.1: -e path 優先於預設的 .env 和 .flaskenv 檔案。

變更日誌

版本變更自 2.2: 新增了 -A/--app、--debug/--no-debug、-e/--env-file 選項。

版本變更自 2.2: 在執行 app.cli 命令時，會推送應用程式上下文，因此這些命令不再需要 @with_appcontext。

在 1.0 版本中變更: 如果已安裝，python-dotenv 將用於從 .env 和 .flaskenv 檔案載入環境變數。

get_command(ctx, name)¶

給定上下文和命令名稱，如果存在，則傳回 Command 物件，否則傳回 None。

參數:

ctx (Context)
name (str)

回傳類型:

Command | None

list_commands(ctx)¶

傳回子命令名稱的列表，順序為它們應出現的順序。

參數:: ctx (Context)
回傳類型:: list[str]

make_context(info_name, args, parent=None, **extra)¶

此函式在給定資訊名稱和引數時，將啟動剖析並建立新的 Context。但它不會調用實際的命令回呼。

若要快速自訂使用的上下文類別，而無需覆寫此方法，請設定 context_class 屬性。

參數:

info_name (str | None) – 此調用的資訊名稱。一般而言，這是腳本或命令的最具描述性的名稱。對於頂層腳本，它通常是腳本的名稱，對於下方的命令，它是命令的名稱。
args (list[str]) – 要剖析為字串列表的引數。
parent (Context | None) – 父上下文（如果可用）。
extra (Any) – 轉發到上下文建構子的額外關鍵字引數。

回傳類型:

Context

版本變更自 8.0: 新增了 context_class 屬性。

parse_args(ctx, args)¶

給定上下文和引數列表，此方法會建立剖析器並剖析引數，然後根據需要修改上下文。這是由 make_context() 自動調用的。

參數:

ctx (Context)
args (list[str])

回傳類型:

list[str]

class flask.cli.AppGroup(name=None, commands=None, **attrs)¶

這與一般的 click Group 類似，但它變更了 command() 裝飾器的行為，使其自動將函式包裝在 with_appcontext() 中。

請勿與 FlaskGroup 混淆。

參數:

name (str | None)
commands (MutableMapping[str, Command] | Sequence[Command] | None)
attrs (Any)

command(*args, **kwargs)¶

這與一般的 click.Group 上同名的方法完全相同，但它會將回呼包裝在 with_appcontext() 中，除非透過傳遞 with_appcontext=False 停用它。

參數:

args (Any)
kwargs (Any)

回傳類型:

Callable[[Callable[[…], Any]], Command]

group(*args, **kwargs)¶

這與一般的 click.Group 上同名的方法完全相同，但它預設將群組類別設為 AppGroup。

參數:

args (Any)
kwargs (Any)

回傳類型:

Callable[[Callable[[…], Any]], Group]

class flask.cli.ScriptInfo(app_import_path=None, create_app=None, set_debug_flag=True, load_dotenv_defaults=True)¶

協助處理 Flask 應用程式的 Helper 物件。通常不必與其介接，因為它在分派到 click 時於內部使用。在 Flask 的未來版本中，此物件很可能會扮演更重要的角色。它通常由 FlaskGroup 自動建立，但您也可以手動建立它並將其作為 click 物件傳遞下去。

版本變更自 3.1: 新增了 load_dotenv_defaults 參數和屬性。

參數:

app_import_path (str | None)
create_app (t.Callable[..., Flask] | None)
set_debug_flag (bool)
load_dotenv_defaults (bool)

app_import_path¶: Flask 應用程式的選用匯入路徑。

create_app¶: 選用函式，會將腳本資訊傳遞給它，以建立應用程式的實例。

data: dict[t.Any, t.Any]¶: 包含可以與此腳本資訊關聯的任意資料的字典。

load_dotenv_defaults¶

是否應載入預設的 .flaskenv 和 .env 檔案。

ScriptInfo 不會載入任何內容，這僅供參考，以便在處理期間於其他位置進行載入時使用。

Added in version 3.1.

load_app()¶

載入 Flask 應用程式（如果尚未載入）並傳回它。多次呼叫此函式只會導致傳回已載入的應用程式。

回傳類型:: Flask

flask.cli.load_dotenv(path=None, load_defaults=True)¶

載入 “dotenv” 檔案以設定環境變數。給定的路徑優先於 .env，而 .env 優先於 .flaskenv。在載入和合併這些檔案後，只有當金鑰尚未在 os.environ 中設定時，才會設定值。

如果未安裝 python-dotenv，則此操作無效。

參數:

path (str | PathLike[str] | None) – 載入此位置的檔案。
load_defaults (bool) – 搜尋並載入預設的 .flaskenv 和 .env 檔案。

Returns:

True 如果至少載入一個環境變數。

回傳類型:

版本 3.1 變更: 新增了 load_defaults 參數。給定的路徑優先於預設檔案。

變更日誌

版本 2.0 變更: 目前目錄不會變更為載入檔案的位置。

版本 2.0 變更: 載入 env 檔案時，預設編碼設定為 UTF-8。

版本 1.1.0 變更: 當未安裝 python-dotenv 或給定的路徑不是檔案時，傳回 False。

在 1.0 版本中新增。

flask.cli.with_appcontext(f)¶

包裝一個回呼函式，以確保它在腳本的應用程式內容中執行。

在 app.cli 或 blueprint.cli 下註冊的自訂命令（及其選項）將始終具有可用的應用程式內容，在這種情況下不需要此裝飾器。

變更日誌

版本 2.2 變更: 應用程式內容對於子命令以及裝飾的回呼函式都處於活動狀態。應用程式內容始終可用於 app.cli 命令和參數回呼函式。

參數:: f (F)
回傳類型:: F

flask.cli.pass_script_info(f)¶

標記一個函式，以便將 ScriptInfo 的實例作為第一個引數傳遞給 click 回呼函式。

參數:: f (t.Callable[te.Concatenate[T, P], R])
回傳類型:: t.Callable[P, R]

flask.cli.run_command = <Command run>¶

執行本地開發伺服器。

此伺服器僅用於開發目的。它不提供生產 WSGI 伺服器的穩定性、安全性或效能。

預設情況下，重載器和偵錯器已啟用 ‘–debug’ 選項。

參數:

args (Any)
kwargs (Any)

回傳類型:

flask.cli.shell_command = <Command shell>¶

在給定的 Flask 應用程式的上下文中執行互動式 Python shell。應用程式將根據其配置填充此 shell 的預設命名空間。

這對於執行少量管理程式碼非常有用，而無需手動配置應用程式。

參數:

args (Any)
kwargs (Any)

回傳類型: