API ¶

变更日志

在 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 的生成器，将作为响应进行流式传输。
tuple: 可以是 (body, status, headers)、(body, status) 或 (body, headers)，其中 body 是此处允许的任何其他类型，status 是字符串或整数，headers 是字典或 (key, value) 元组的列表。如果 body 是 response_class 实例，则 status 会覆盖退出值，并且 headers 会被扩展。
response_class: 对象保持不变地返回。
其他 Response 类: 对象被强制转换为 response_class。
callable(): 该函数作为 WSGI 应用程序调用。结果用于创建响应对象。

返回类型:

变更日志

在 2.2 版本中变更：生成器将转换为流式响应。列表将转换为 JSON 响应。

在 1.1 版本中变更：字典将转换为 JSON 响应。

在 0.9 版本中变更：以前，元组被解释为响应对象的参数。

preprocess_request()¶

在请求分发之前调用。调用在应用程序和当前蓝图（如果有）中注册的 url_value_preprocessors。然后调用在应用程序和蓝图中注册的 before_request_funcs。

如果任何 before_request() 处理程序返回非 None 值，则该值将像视图的返回值一样处理，并且进一步的请求处理将停止。

返回类型:: ft.ResponseReturnValue | None

process_response(response)¶

可以被覆盖，以便在响应对象发送到 WSGI 服务器之前对其进行修改。默认情况下，这将调用所有 after_request() 装饰的函数。

变更日志

在 0.5 版本中变更：从 Flask 0.5 开始，为请求后执行注册的函数以注册的相反顺序调用。

参数:: response (Response) – response_class 对象。
返回值:: 一个新的响应对象或相同的对象，必须是 response_class 的实例。
返回类型:: 响应

do_teardown_request(exc=_sentinel)¶

在请求分发和响应返回之后，在请求上下文弹出之前立即调用。

这将调用所有用 teardown_request() 和 Blueprint.teardown_request() 装饰的函数（如果蓝图处理了请求）。最后，发送 request_tearing_down 信号。

这由 RequestContext.pop() 调用，在测试期间可能会延迟以保持对资源的访问。

参数:: exc (BaseException | None) – 分发请求时引发的未处理异常。如果未传递，则从当前异常信息中检测到。传递给每个 teardown 函数。
返回类型:: None

变更日志

在 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 – 用于替代 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)

这样你仍然拥有原始的应用对象，并且可以继续调用它的方法。

变更日志

在版本 0.7 中变更: 请求和应用上下文的拆卸事件即使在发生未处理的错误时也会被调用。其他事件可能不会被调用，具体取决于分发期间发生错误的时间。请参阅回调和错误。

参数:

environ (WSGIEnvironment) – 一个 WSGI 环境。
start_response (StartResponse) – 一个可调用对象，接受状态码、标头列表和可选的异常上下文以启动响应。

返回类型:

cabc.Iterable[bytes]

aborter_class¶: 别名：Aborter

add_template_filter(f, name=None)¶

注册自定义模板过滤器。其工作方式与 template_filter() 装饰器完全相同。

参数:

name (str | None) – 过滤器的可选名称，否则将使用函数名称。
f (Callable[[...], Any])

返回类型:

None

add_template_global(f, name=None)¶

注册自定义模板全局函数。其工作方式与 template_global() 装饰器完全相同。

变更日志

在版本 0.10 中添加。

参数:

name (str | None) – 全局函数的可选名称，否则将使用函数名称。
f (Callable[[...], Any])

返回类型:

None

add_template_test(f, name=None)¶

注册自定义模板测试。其工作方式与 template_test() 装饰器完全相同。

变更日志

在版本 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)¶

注册一个函数，以便在每个请求之前运行。

例如，这可以用于打开数据库连接，或从会话中加载已登录用户。

@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)¶

注册一个模板上下文处理器函数。这些函数在渲染模板之前运行。返回的字典的键将作为模板中可用的变量添加。

这在应用和蓝图对象上都可用。在应用上使用时，这将为每个渲染的模板调用。在蓝图上使用时，这将为从蓝图视图渲染的模板调用。要在蓝图上注册并影响每个模板，请使用 Blueprint.app_context_processor()。

参数:: f (T_template_context_processor)
返回类型:: T_template_context_processor

create_global_jinja_loader()¶

创建 Jinja2 环境的加载器。可用于仅覆盖加载器并保持其余部分不变。不鼓励覆盖此函数。相反，应该覆盖 jinja_loader() 函数。

全局加载器在应用程序和各个蓝图的加载器之间进行调度。

变更日志

在 0.7 版本中添加。

返回类型:: DispatchingJinjaLoader

property debug: bool¶

是否启用调试模式。当使用 flask run 启动开发服务器时，将为未处理的异常显示交互式调试器，并且当代码更改时服务器将重新加载。这映射到 DEBUG 配置键。如果设置得太晚，它可能无法按预期运行。

在生产环境中部署时，请勿启用调试模式。

默认值: False

delete(rule, **options)¶

带有 methods=["DELETE"] 的 route() 的快捷方式。

变更日志

在 2.0 版本中添加。

参数:

rule (str)
options (Any)

返回类型:

Callable[[T_route], T_route]

endpoint(endpoint)¶

装饰视图函数以将其注册到给定的端点。如果在没有 view_func 的情况下使用 add_url_rule() 添加了规则，则可以使用此方法。

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)¶

带有 methods=["GET"] 的 route() 的快捷方式。

变更日志

在 2.0 版本中添加。

参数:

rule (str)
options (Any)

返回类型:

Callable[[T_route], T_route]

handle_url_build_error(error, endpoint, values)¶

如果引发了 BuildError，则由 url_for() 调用。如果此方法返回一个值，它将由 url_for 返回，否则将重新引发错误。

将使用 error、endpoint 和 values 调用 url_build_error_handlers 中的每个函数。如果函数返回 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 构建时自动调用。

变更日志

在 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 使用不同的格式。不会删除任何处理程序，并且仅在尚未配置任何处理程序时才添加处理程序。

在 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），并指示配置应相对于实例路径还是应用程序的根路径。

变更日志

版本 0.8 中新增。

参数:: instance_relative (bool)
返回类型:: Config

property name: str¶: 应用的名称。这通常是导入名称，但如果导入名称是 main，则会从运行文件中猜测。此名称在 Flask 需要应用名称时用作显示名称。可以设置和覆盖此名称以更改其值。

变更日志

版本 0.8 中新增。

patch(rule, **options)¶

带有 methods=["PATCH"] 的 route() 的快捷方式。

变更日志

在 2.0 版本中添加。

参数:

rule (str)
options (Any)

返回类型:

Callable[[T_route], T_route]

permanent_session_lifetime¶

一个 timedelta，用于设置永久会话的过期日期。默认值为 31 天，这使得永久会话大约可以存活一个月。

此属性也可以通过配置中的 PERMANENT_SESSION_LIFETIME 配置键进行配置。默认为 timedelta(days=31)

post(rule, **options)¶

带有 methods=["POST"] 的 route() 的快捷方式。

变更日志

在 2.0 版本中添加。

参数:

rule (str)
options (Any)

返回类型:

Callable[[T_route], T_route]

put(rule, **options)¶

带有 methods=["PUT"] 的 route() 的快捷方式。

变更日志

在 2.0 版本中添加。

参数:

rule (str)
options (Any)

返回类型:

Callable[[T_route], T_route]

redirect(location, code=302)¶

创建重定向响应对象。

这由 flask.redirect() 调用，也可以直接调用。

参数:

location (str) – 要重定向到的 URL。
code (int) – 重定向的状态码。

返回类型:

BaseResponse

变更日志

在 2.2 版本中新增: 从调用此方法的 flask.redirect 移动而来。

register_blueprint(blueprint, **options)¶

在应用程序上注册一个 Blueprint。传递给此方法的关键字参数将覆盖蓝图上设置的默认值。

在应用程序的 blueprints 中记录蓝图后，调用蓝图的 register() 方法。

参数:

blueprint (Blueprint) – 要注册的蓝图。
url_prefix – 蓝图路由将以此为前缀。
subdomain – 蓝图路由将匹配此子域名。
url_defaults – 蓝图路由将对视图参数使用这些默认值。
options (t.Any) – 额外的关键字参数将传递给 BlueprintSetupState。它们可以在 record() 回调中访问。

返回类型:

None

变更日志

在 2.0.1 版本中更改: name 选项可用于更改蓝图注册时使用的（前缀点号的）名称。这允许同一个蓝图使用唯一的名称多次注册，以便用于 url_for。

在 0.7 版本中添加。

register_error_handler(code_or_exception, f)¶

替代错误附加函数，用于 errorhandler() 装饰器，对于非装饰器用法，它更直接易用。

变更日志

在 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。

变更日志

在 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，则拆卸处理程序将不会传递错误。

变更日志

在版本 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

变更日志

在版本 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

变更日志

在版本 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。

变更日志

在 0.7 版本中添加。

testing¶

测试标志。将此设置为 True 以启用 Flask 扩展的测试模式（将来可能也包括 Flask 本身）。例如，这可能会激活具有额外运行时开销的测试助手，这些助手默认情况下不应启用。

如果启用此项，并且 PROPAGATE_EXCEPTIONS 未从默认值更改，则会隐式启用此项。

此属性也可以通过配置中的 TESTING 配置键进行配置。默认为 False。

trap_http_exception(e)¶

检查是否应捕获 HTTP 异常。默认情况下，对于除错误请求键错误之外的所有异常，如果 TRAP_BAD_REQUEST_ERRORS 设置为 True，则这将返回 False。如果 TRAP_HTTP_EXCEPTIONS 设置为 True，它也会返回 True。

对于视图函数引发的所有 HTTP 异常，都会调用此方法。如果它对任何异常返回 True，则不会调用此异常的错误处理程序，并且它会在回溯中显示为常规异常。这有助于调试隐式引发的 HTTP 异常。

变更日志

在 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¶: 由 make_aborter() 创建的 aborter_class 的实例。这由 flask.abort() 调用以引发 HTTP 错误，也可以直接调用。

变更日志

在 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]¶: 将注册的蓝图名称映射到蓝图对象。该字典保留蓝图注册的顺序。蓝图可以多次注册，此字典不跟踪它们附加的频率。

变更日志

在 0.7 版本中添加。

extensions: dict[str, t.Any]¶

扩展可以存储应用程序特定状态的位置。例如，扩展可以在此处存储数据库引擎和类似内容。

键必须与扩展模块的名称匹配。例如，对于 flask_foo 中的 “Flask-Foo” 扩展，键将为 'foo'。

变更日志

在 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 缓存值（如果未传递）。

默认情况下，这会从 current_app 的配置中返回 SEND_FILE_MAX_AGE_DEFAULT。这默认为 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()。

变更日志

在版本 0.10 中添加。

参数:

name (str | None) – 全局变量的可选名称，否则将使用函数名称。
f (Callable[[...], Any])

返回类型:

None

add_app_template_test(f, name=None)¶

注册一个模板测试，在应用程序渲染的任何模板中都可用。其工作方式类似于 app_template_test() 装饰器。等效于 Flask.add_template_test()。

变更日志

在版本 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()。

变更日志

在版本 0.10 中添加。

参数:: name (str | None) – 全局变量的可选名称，否则将使用函数名称。
返回类型:: Callable[[T_template_global], T_template_global]

app_template_test(name=None)¶

注册一个模板测试，在应用程序渲染的任何模板中都可用。等效于 Flask.template_test()。

变更日志

在版本 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)¶

注册一个函数，以便在每个请求之前运行。

例如，这可以用于打开数据库连接，或从会话中加载已登录用户。

@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)¶

注册一个模板上下文处理器函数。这些函数在渲染模板之前运行。返回的字典的键将作为模板中可用的变量添加。

这在应用和蓝图对象上都可用。在应用上使用时，这将为每个渲染的模板调用。在蓝图上使用时，这将为从蓝图视图渲染的模板调用。要在蓝图上注册并影响每个模板，请使用 Blueprint.app_context_processor()。

参数:: f (T_template_context_processor)
返回类型:: T_template_context_processor

delete(rule, **options)¶

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

变更日志

在 2.0 版本中添加。

参数:

rule (str)
options (Any)

返回类型:

Callable[[T_route], T_route]

endpoint(endpoint)¶

装饰视图函数，以注册给定的端点。如果添加规则时没有使用 view_func，则使用 add_url_rule()。

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)¶

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

变更日志

在 2.0 版本中添加。

参数:

rule (str)
options (Any)

返回类型:

Callable[[T_route], T_route]

property has_static_folder: bool¶: 如果设置了 static_folder，则为 True。

变更日志

版本 0.5 中新增。

property 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() 的快捷方式。

变更日志

在 2.0 版本中添加。

参数:

rule (str)
options (Any)

返回类型:

Callable[[T_route], T_route]

post(rule, **options)¶

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

变更日志

在 2.0 版本中添加。

参数:

rule (str)
options (Any)

返回类型:

Callable[[T_route], T_route]

put(rule, **options)¶

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

变更日志

在 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 版本更改: 嵌套蓝图以其点状名称注册。这允许同名的不同蓝图嵌套在不同的位置。

在 2.0.1 版本中更改: name 选项可用于更改蓝图注册时使用的（前缀点号的）名称。这允许同一个蓝图使用唯一的名称多次注册，以便用于 url_for。

register_blueprint(blueprint, **options)¶

在此蓝图上注册 Blueprint。传递给此方法的关键字参数将覆盖蓝图上设置的默认值。

变更日志

在 2.0.1 版本中更改: name 选项可用于更改蓝图注册时使用的（前缀点号的）名称。这允许同一个蓝图使用唯一的名称多次注册，以便用于 url_for。

在 2.0 版本中添加。

参数:

blueprint (Blueprint)
options (Any)

返回类型:

None

register_error_handler(code_or_exception, f)¶

errorhandler() 装饰器的替代错误附加函数，对于非装饰器用法，使用起来更直接。

变更日志

在 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]

property static_folder: str | None¶: 配置的静态文件夹的绝对路径。如果未设置静态文件夹，则为 None。

property 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 异常或类似异常。

property max_content_length: int | None¶

在此请求期间将读取的最大字节数。如果超过此限制，则会引发 413 RequestEntityTooLarge 错误。如果设置为 None，则在 Flask 应用程序级别不强制执行任何限制。但是，如果它是 None 并且请求没有 Content-Length 标头，并且 WSGI 服务器未指示它终止流，则不会读取任何数据以避免无限流。

每个请求默认为 MAX_CONTENT_LENGTH 配置，默认为 None。可以在特定 request 上设置它，以将限制应用于该特定视图。应根据应用程序或视图的特定需求适当设置此值。

3.1 版本更改: 这可以按请求设置。

变更日志

0.6 版本更改: 这可以通过 Flask 配置进行配置。

property max_form_memory_size: int | None¶

在 multipart/form-data 正文中，任何非文件表单字段的最大大小（以字节为单位）。如果超过此限制，则会引发 413 RequestEntityTooLarge 错误。如果设置为 None，则在 Flask 应用程序级别不强制执行任何限制。

每个请求默认为 MAX_FORM_MEMORY_SIZE 配置，默认为 500_000。可以在特定 request 上设置它，以将限制应用于该特定视图。应根据应用程序或视图的特定需求适当设置此值。

3.1 版本更改: 这可以通过 Flask 配置进行配置。

property max_form_parts: int | None¶

在 multipart/form-data 正文中可能存在的最大字段数。如果超过此限制，则会引发 413 RequestEntityTooLarge 错误。如果设置为 None，则在 Flask 应用程序级别不强制执行任何限制。

每个请求默认为 MAX_FORM_PARTS 配置，默认为 1_000。可以在特定 request 上设置它，以将限制应用于该特定视图。应根据应用程序或视图的特定需求适当设置此值。

3.1 版本更改: 这可以通过 Flask 配置进行配置。

property 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。
返回类型:: 任何

变更日志

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]¶: 如果存在 forwarded 标头，则这是一个列表，其中包含从客户端 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 可调用对象
返回值:: 一个新的 WSGI 可调用对象
返回类型:: WSGIApplication

property args: MultiDict[str, str]¶

解析后的 URL 参数（URL 中问号后面的部分）。

默认情况下，此函数返回 ImmutableMultiDict。可以通过将 parameter_storage_class 设置为不同的类型来更改此行为。如果表单数据的顺序很重要，则可能需要这样做。

变更日志

2.3 版本变更: 无效字节保持百分比编码。

property authorization: Authorization | None¶: Authorization 标头被解析为 Authorization 对象。如果标头不存在，则为 None。

变更日志

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]¶: 一个 dict，其中包含随请求传输的所有 Cookie 的内容。

property data: bytes¶

从 stream 读取的原始数据。如果请求表示表单数据，则为空。

要获取原始数据，即使它表示表单数据，请使用 get_data()。

date¶: Date 通用标头字段表示消息的原始日期和时间，其语义与 RFC 822 中的 orig-date 相同。

变更日志

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 属性中。

变更日志

0.9 版本变更: 在 Werkzeug 0.9 之前，这仅包含 POST 和 PUT 请求的表单数据。

form_data_parser_class¶: FormDataParser 的别名

classmethod from_values(*args, **kwargs)¶

基于提供的值创建一个新的请求对象。如果给定 environ，则会从中填充缺失的值。当您需要模拟来自 URL 的请求时，此方法对于小型脚本很有用。不要将此方法用于单元测试，有一个功能齐全的客户端对象 (Client) 允许创建多部分请求，支持 Cookie 等。

这接受与 EnvironBuilder 相同的选项。

变更日志

0.5 版本变更: 此方法现在接受与 EnvironBuilder 相同的参数。因此，environ 参数现在称为 environ_overrides。

返回值:

请求对象

参数:

args (Any)
kwargs (Any)

返回类型:

Request

property full_path: str¶: 请求的路径，包括查询字符串。

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

这会将来自客户端的缓冲传入数据读取到一个 bytes 对象中。默认情况下，这是缓存的，但可以通过将 cache 设置为 False 来更改此行为。

通常，在不首先检查内容长度的情况下调用此方法是一个坏主意，因为客户端可能会发送数十兆字节或更多的数据，从而导致服务器上的内存问题。

请注意，如果已解析表单数据，则此方法将不会返回任何内容，因为表单数据解析不会像此方法那样缓存数据。要隐式调用表单数据解析函数，请将 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 Unsupported Media Type 响应。

参数:

force (bool) – 忽略 mimetype 并始终尝试解析 JSON。
silent (bool) – 静默处理 mimetype 和解析错误，并返回 None。
cache (bool) – 存储已解析的 JSON，以便在后续调用中返回。

返回类型:

Any | None

变更日志

2.3 版本变更: 引发 415 错误而不是 400 错误。

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 对象。

变更日志

2.0 版本变更: datetime 对象是时区感知的。

property if_none_match: ETags¶

包含 If-None-Match 标头中所有 etag 的对象。

返回类型:: ETags

property if_range: IfRange¶: 解析后的 If-Range 标头。

变更日志

在 2.0 版本中变更: IfRange.date 是时区感知的。

在 0.7 版本中添加。

property if_unmodified_since: datetime | None¶: 解析后的 If-Unmodified-Since 标头，为 datetime 对象。

变更日志

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 错误。

变更日志

2.3 版本变更: 引发 415 错误而不是 400 错误。

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，但不包含参数（例如，不包含 charset，type 等），并且始终为小写。例如，如果内容类型为 text/HTML; charset=utf-8，则 mimetype 将为 'text/html'。

property mimetype_params: dict[str, str]¶: mimetype 参数，以 dict 形式表示。例如，如果内容类型为 text/html; charset=utf-8，则 params 将为 {'charset': 'utf-8'}。

origin¶: 请求的来源主机。在响应中设置 access_control_allow_origin 以指示允许哪些来源。

parameter_storage_class¶: ImmutableMultiDict 的别名

property pragma: HeaderSet¶: Pragma 通用标头字段用于包含特定于实现的指令，这些指令可能适用于请求/响应链上的任何接收者。所有 pragma 指令都从协议的角度指定可选行为；但是，某些系统可能要求行为与指令一致。

property range: Range | None¶

解析后的 Range 标头。

变更日志

在 0.7 版本中添加。

返回类型:: Range

referrer¶: Referer[原文如此] 请求标头字段允许客户端为服务器的利益指定从中获取 Request-URI 的资源地址 (URI)（“referrer”，尽管标头字段拼写错误）。

remote_user¶: 如果服务器支持用户身份验证，并且脚本受到保护，则此属性包含用户已通过身份验证的用户名。

property root_url: str¶: 请求 URL 协议、主机和根路径。这是访问应用程序的根路径。

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，包含协议、主机、根路径、路径和查询字符串。

property url_root: str¶: 别名为 root_url。包含协议、主机和根路径的 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¶: 包含 HTTP 标头和来自 WSGI 服务器信息的 WSGI 环境。

shallow: bool¶: 创建请求对象时设置。如果为 True，则从请求体读取将导致 RuntimeException。用于防止中间件修改流。

method¶: 请求使用的方法，例如 GET。

scheme¶: 请求使用的协议的 URL 协议方案，例如 https 或 wss。

server¶: 服务器的地址。 (host, port)，Unix 套接字的 (path, None)，或者如果未知，则为 None。

root_path¶: 应用程序挂载在其下的前缀，不带尾部斜杠。 path 在此之后。

path¶: URL 中 root_path 之后的部分。这是用于应用程序内路由的路径。

query_string¶: URL 中“？”之后的部分。这是原始值，使用 args 获取解析后的值。

headers¶: 随请求接收的标头。

remote_addr¶: 发送请求的客户端地址。

flask.request¶

要访问传入的请求数据，您可以使用全局 request 对象。 Flask 为您解析传入的请求数据，并通过该全局对象使您可以访问它。在内部，如果您在多线程环境中，Flask 会确保您始终获得活动线程的正确数据。

这是一个代理。有关更多信息，请参见代理说明。

请求对象是 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' 是常见的。

变更日志

在 0.7 版本中添加。

property access_control_allow_credentials: bool¶: 浏览器是否可以将凭据共享给 JavaScript 代码。作为预检请求的一部分，它指示是否可以在跨域请求中使用凭据。

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，则为其添加 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 中新增。

property 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 标头字段引用的媒体类型，必须应用哪些解码机制。

property content_language: HeaderSet¶: Content-Language 实体标头字段描述了封闭实体的预期受众的自然语言。请注意，这可能不等同于实体主体中使用的所有语言。

content_length¶: Content-Length 实体标头字段指示实体主体的尺寸，以发送给接收者的八位字节的十进制数表示，或者在 HEAD 方法的情况下，指示如果请求是 GET 请求，则将发送的实体主体的尺寸。

content_location¶: 当封闭在消息中的实体可以从与请求资源的 URI 分离的位置访问时，可以使用 Content-Location 实体标头字段来提供该实体的资源位置。

content_md5¶: Content-MD5 实体标头字段（在 RFC 1864 中定义）是实体主体的 MD5 摘要，用于提供实体主体的端到端消息完整性检查 (MIC)。（注意：MIC 适用于检测实体主体在传输过程中的意外修改，但不能防止恶意攻击。）

property content_range: ContentRange¶: Content-Range 标头作为 ContentRange 对象。即使未设置标头也可用。

变更日志

在 0.7 版本中添加。

property content_security_policy: ContentSecurityPolicy¶

Content-Security-Policy 标头作为 ContentSecurityPolicy 对象。即使未设置标头也可用。

Content-Security-Policy 标头添加了额外的安全层，以帮助检测和缓解某些类型的攻击。

property 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 枚举的成员。

property data: bytes | str¶: 一个描述符，调用 get_data() 和 set_data()。

date¶: Date 通用标头字段表示消息的原始日期和时间，其语义与 RFC 822 中的 orig-date 相同。

变更日志

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 实体标头字段给出了响应被视为陈旧后的日期/时间。陈旧的缓存条目通常可能不会被缓存返回。

变更日志

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 环境对象。

返回值:

一个响应对象。

返回类型:

freeze()¶

使响应对象准备好进行 pickle 处理。执行以下操作

将响应缓冲到列表中，忽略 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 以强制执行缓冲。

返回值:

一个响应对象。

返回类型:

get_app_iter(environ)¶

返回给定 environ 的应用程序迭代器。根据请求方法和当前状态代码，返回值可能是空响应，而不是来自响应的响应。

如果请求方法是 HEAD 或状态代码在 HTTP 规范要求空响应的范围内，则返回空的可迭代对象。

变更日志

版本 0.6 中新增。

参数:: environ (WSGIEnvironment) – 请求的 WSGI 环境。
返回值:: 一个响应迭代器。
返回类型:: 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 起，位置和 content-location 标头中的 IRI 得到正确处理。

同样从 0.6 开始，Werkzeug 将尝试设置内容长度，如果它能够自行计算出来。如果响应可迭代对象中的所有字符串都已编码并且可迭代对象已缓冲，则会发生这种情况。

参数:: environ (WSGIEnvironment) – 请求的 WSGI 环境。
返回值:: 返回一个新的 Headers 对象。
返回类型:: Headers

get_wsgi_response(environ)¶

以元组形式返回最终的 WSGI 响应。元组中的第一项是应用程序迭代器，第二项是状态，第三项是标头列表。返回的响应是专门为给定环境创建的。例如，如果 WSGI 环境中的请求方法是 'HEAD'，则响应将为空，并且仅存在标头和状态代码。

变更日志

版本 0.6 中新增。

参数:: environ (WSGIEnvironment) – 请求的 WSGI 环境。
返回值:: 一个 (app_iter, status, headers) 元组。
返回类型:: tuple[t.Iterable[bytes], str, list[tuple[str, str]]]

implicit_sequence_conversion = True¶: 如果设置为 False，则访问响应对象上的属性将不会尝试使用响应迭代器并将其转换为列表。

变更日志

在版本 0.6.2 中添加: 该属性以前称为 implicit_seqence_conversion。（注意拼写错误）。如果您确实使用了此功能，则必须使您的代码适应名称更改。

property is_json: bool¶: 检查 mimetype 是否指示 JSON 数据，包括 application/json 或 application/*+json。

property is_sequence: bool¶: 如果迭代器被缓冲，则此属性将为 True。如果响应属性是列表或元组，则响应对象将认为迭代器已被缓冲。

变更日志

版本 0.6 中新增。

property is_streamed: bool¶

如果响应是流式传输的（响应不是具有长度信息的可迭代对象），则此属性为 True。在这种情况下，流式传输意味着没有关于迭代次数的信息。如果将生成器传递给响应对象，则通常为 True。

这对于在应用某些不应针对流式响应发生的后置过滤之前进行检查非常有用。

iter_encoded()¶

迭代使用响应编码编码的响应。如果将响应对象作为 WSGI 应用程序调用，则除非激活 direct_passthrough，否则此方法的返回值将用作应用程序迭代器。

返回类型:: Iterator[bytes]

property json: Any | None¶

如果 mimetype 指示 JSON（application/json，请参阅 is_json），则为已解析的 JSON 数据。

使用默认参数调用 get_json()。

last_modified¶: Last-Modified 实体标头字段指示原始服务器认为变体上次修改的日期和时间。

变更日志

2.0 版本变更: datetime 对象是时区感知的。

location¶: Location 响应标头字段用于将接收者重定向到 Request-URI 以外的位置，以完成请求或标识新资源。

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

使响应有条件地响应请求。如果已为响应定义了 etag，则此方法效果最佳。可以使用 add_etag 方法来执行此操作。如果在没有 etag 的情况下调用，则仅设置 date 标头。

如果请求或 environ 中的请求方法不是 GET 或 HEAD，则此方法不执行任何操作。

为了在处理范围请求时获得最佳性能，建议您的响应数据对象实现 seekable、seek 和 tell 方法，如 io.IOBase 所述。 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) – 仅在有效的 Range 请求中使用。它将设置 Content-Range 完整长度值并计算 Content-Length 的实际值。此参数对于成功完成 Range 请求是必需的。

Raises:

RequestedRangeNotSatisfiable 如果 Range 标头无法解析或满足。

返回类型:

变更日志

Changed in version 2.0: 版本 2.0 中的变更：如果长度为 0，则跳过 Range 处理，而不是引发 416 Range Not Satisfiable 错误。

make_sequence()¶

将响应迭代器转换为列表。默认情况下，如果需要，这将自动发生。如果禁用 implicit_sequence_conversion，则不会自动调用此方法，并且某些属性可能会引发异常。这也会编码所有项。

变更日志

版本 0.6 中新增。

返回类型:: None

property mimetype: str | None¶: MIME 类型 (不包含字符集等的内容类型)。

property mimetype_params: dict[str, str]¶: mimetype 参数，以 dict 形式表示。例如，如果内容类型为 text/html; charset=utf-8，则 params 将为 {'charset': 'utf-8'}。

变更日志

版本 0.5 中新增。

property retry_after: datetime | None¶

Retry-After 响应标头字段可以与 503 (服务不可用) 响应一起使用，以指示服务预计不可用多久。

到期前的秒数或日期。

变更日志

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) – 应该是秒数，或者如果 Cookie 应该仅在客户端浏览器会话期间持续存在，则为 None (默认值)。
expires (str | datetime | int | float | None) – 应该是 datetime 对象或 UNIX 时间戳。
path (str | None) – 将 Cookie 限制为给定的路径，默认情况下它将跨越整个域。
domain (str | None) – 如果要设置跨域 Cookie。例如，domain="example.com" 将设置一个 Cookie，该 Cookie 可由域 www.example.com, foo.example.com 等读取。否则，Cookie 只能由设置它的域读取。
secure (bool) – 如果为 True，则 Cookie 仅通过 HTTPS 可用。
httponly (bool) – 禁止 JavaScript 访问 Cookie。
samesite (str | None) – 将 Cookie 的范围限制为仅附加到“同站点”请求。
partitioned (bool) – 如果为 True，则 Cookie 将被分区。

返回类型:

None

Changed in version 3.1: 版本 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: 版本 2.3 中的变更：此属性可以被赋值以设置标头。可以分配列表以设置多个标头值。使用 del 取消设置标头。

Changed in version 2.3: 版本 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: 版本 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¶

会话对象的工作方式与普通字典非常相似，不同之处在于它会跟踪修改。

这是一个代理。有关更多信息，请参见代理说明。

以下属性很有趣

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 的 securecookie 实现。您唯一需要实现的方法是 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() 将在此处查找在请求空会话时应创建的类。同样，is_null_session() 方法将对此类型执行类型检查。

别名：NullSession

pickle_based = False¶: 一个标志，指示会话接口是否基于 pickle。 Flask 扩展可以使用此标志来决定如何处理会话对象。

变更日志

在版本 0.10 中添加。

make_null_session(app)¶

创建一个空会话，如果由于配置错误而无法加载真正的会话支持，则该会话充当替换对象。这主要有助于用户体验，因为空会话的任务仍然是支持查找而不会抱怨，但修改会以关于哪里失败的有用错误消息来响应。

默认情况下，这将创建 null_session_class 的实例。

参数:: app (Flask)
返回类型:: NullSession

is_null_session(obj)¶

检查给定对象是否为空会话。空会话不会被要求保存。

默认情况下，这将检查对象是否为 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: 版本 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 应该是分区 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 模块将 session 存储在签名的 cookie 中。

salt = 'cookie-session'¶: 盐值，应该在密钥之上应用，用于签名基于 cookie 的会话。

static digest_method(string=b'')¶

用于签名的哈希函数。默认值为 sha1。

参数:: string (bytes)
返回类型:: 任何

key_derivation = 'hmac'¶: itsdangerous 支持的密钥派生名称。默认值为 hmac。

serializer = <flask.json.tag.TaggedJSONSerializer object>¶: 用于 payload 的 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 的基类。

此会话后端将设置 modified 和 accessed 属性。它无法可靠地跟踪会话是新的（相对于空的），因此 new 仍然硬编码为 False。

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

modified = False¶: 当数据更改时，此值设置为 True。仅跟踪会话字典本身；如果会话包含可变数据（例如嵌套字典），则在修改该数据时必须手动将其设置为 True。仅当此值为 True 时，会话 cookie 才会写入响应。

accessed = False¶: 标头，允许缓存代理为不同的用户缓存不同的页面。

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 元组。

键值对以 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。

变更日志

在 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

变更日志

在 2.1 版本中变更：移除 as_tuple 参数。

在 2.0 版本中变更：调用 response.close() 时，请求输入流将关闭。重定向的输入流将自动关闭。

在 0.5 版本中变更：如果在 data 参数的字典中将字典作为文件提供，则内容类型必须称为 content_type 而不是 mimetype。此更改是为了与 werkzeug.FileWrapper 保持一致性而进行的。

在 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)

返回值:

一个 Result 对象。

返回类型:

Result

应用程序全局变量¶

为了在不同函数之间共享仅对一个请求有效的数据，全局变量是不够好的，因为它会在线程环境中崩溃。Flask 为您提供了一个特殊对象，以确保它仅对活动请求有效，并且每个请求将返回不同的值。简而言之：它做了正确的事情，就像它对 request 和 session 所做的那样。

flask.g¶

一个命名空间对象，可以在应用程序上下文期间存储数据。这是 Flask.app_ctx_globals_class 的实例，默认值为 ctx._AppCtxGlobals。

这是在请求期间存储资源的好地方。例如，before_request 函数可以从 session id 加载用户对象，然后设置 g.user 以在视图函数中使用。

这是一个代理。有关更多信息，请参见代理说明。

变更日志

在 0.10 版本中变更：绑定到应用程序上下文而不是请求上下文。

class flask.ctx._AppCtxGlobals¶

一个普通对象。用作在应用程序上下文期间存储数据的命名空间。

创建应用程序上下文会自动创建此对象，该对象作为 g 代理提供。

'key' in g: 检查属性是否存在。

变更日志

在版本 0.10 中添加。

iter(g): 返回属性名称的迭代器。

变更日志

在版本 0.10 中添加。

get(name, default=None)¶

按名称或默认值获取属性。类似于 dict.get()。

参数:

name (str) – 要获取的属性的名称。
default (Any | None) – 如果属性不存在，则返回的值。

返回类型:

变更日志

在版本 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¶

当前请求所处理的应用的代理。这在无需导入应用的情况下访问应用非常有用，或者在应用无法导入时（例如使用应用工厂模式或在蓝图和扩展中）。

仅当应用上下文被推送时，此功能才可用。这在请求和 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

变更日志

在 0.7 版本中添加。

返回类型:: bool

flask.copy_current_request_context(f)¶

一个辅助函数，用于装饰一个函数以保留当前的请求上下文。这在使用 greenlet 时非常有用。装饰函数的那一刻，会创建一个请求上下文的副本，然后在调用该函数时推送该副本。当前会话也包含在复制的请求上下文中。

示例

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'

变更日志

在版本 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 和域。当不在活动请求中时，URL 默认情况下是外部的。
values (Any) – 用于 URL 规则的可变部分的值。未知的键将作为查询字符串参数附加，例如 ?a=b&c=d。

返回类型:

变更日志

版本变更于 2.2: 调用 current_app.url_for，允许应用覆盖此行为。

版本变更于 0.10: 添加了 _scheme 参数。

版本变更于 0.9: 添加了 _anchor 和 _method 参数。

版本变更于 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) – 传递给异常。

返回类型:

变更日志

版本新增于 2.2: 如果 current_app 可用，则调用 current_app.aborter，而不是始终使用 Werkzeug 的默认 abort。

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

创建重定向响应对象。

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

参数:

location (str) – 要重定向到的 URL。
code (int) – 重定向的状态码。
Response (type[Response] | None) – 要使用的响应类。当 current_app 处于活动状态时，不使用此参数，而是使用 app.response_class。

返回类型:

变更日志

版本新增于 2.2: 如果 current_app 可用，则调用 current_app.redirect，而不是始终使用 Werkzeug 的默认 redirect。

flask.make_response(*args)¶

有时需要在视图中设置额外的标头。因为视图不必返回响应对象，而是可以返回一个值，该值由 Flask 本身转换为响应对象，因此向其添加标头会变得棘手。可以调用此函数来代替使用 return，你将获得一个响应对象，你可以使用该对象来附加标头。

如果视图看起来像这样，并且你想添加一个新的标头

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 = make_response(render_template('not_found.html'), 404)

此函数的另一个用例是将视图函数的返回值强制转换为响应，这对于视图装饰器很有帮助

response = make_response(view_function())
response.headers['X-Parachutes'] = 'parachutes are cool'

在内部，此函数执行以下操作

如果没有传递任何参数，它会创建一个新的响应参数
如果传递了一个参数，则使用该参数调用 flask.Flask.make_response()。
如果传递了多个参数，则这些参数作为元组传递给 flask.Flask.make_response() 函数。

变更日志

版本 0.6 中新增。

参数:: args (t.Any)
返回类型:: 响应

flask.after_this_request(f)¶

在此请求之后执行一个函数。这对于修改响应对象很有用。该函数被传递响应对象，并且必须返回相同或新的响应对象。

示例

@app.route('/')
def index():
    @after_this_request
    def add_header(response):
        response.headers['X-Foo'] = 'Parachute'
        return response
    return 'Hello World!'

如果视图函数以外的函数想要修改响应，这会更有用。例如，考虑一个想要添加一些标头而不将返回值转换为响应对象的装饰器。

变更日志

版本 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 的内置包装器。或者，如果 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) – 启用基于请求标头的条件和范围响应。需要传递文件路径和 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 以优先进行条件缓存。

返回类型:

变更日志

版本变更于 2.0: download_name 替换了 attachment_filename 参数。如果 as_attachment=False，则使用 Content-Disposition: inline 传递它。

版本变更于 2.0: max_age 替换了 cache_timeout 参数。conditional 默认启用，并且未设置 max_age。

版本变更于 2.0: etag 替换了 add_etags 参数。它可以是一个字符串，用于代替生成一个 ETag。

版本变更于 2.0: 传递继承自 TextIOBase 的类文件对象将引发 ValueError，而不是发送空文件。

版本新增于 2.0: 将实现移动到 Werkzeug。现在这是一个包装器，用于传递一些 Flask 特定的参数。

版本变更于 1.1: filename 可以是 PathLike 对象。

版本变更于 1.1: 传递 BytesIO 对象支持范围请求。

版本变更于 1.0.3: 文件名使用 ASCII 而不是 Latin-1 编码，以获得与 WSGI 服务器更广泛的兼容性。

版本变更于 1.0: 支持 RFC 2231 中指定的 UTF-8 文件名。

版本变更于 0.12: 文件名不再从文件对象自动推断。如果你想使用自动 MIME 和 etag 支持，请通过 filename_or_fp 或 attachment_filename 传递文件名。

版本变更于 0.12: 对于 MIME 检测，attachment_filename 优先于 filename。

版本变更于 0.9: cache_timeout 默认为 Flask.get_send_file_max_age() 的返回值。

版本变更于 0.7: 移除了对类文件对象的 MIME 猜测和 etag 支持，因为它不可靠。如果可以，请传递文件名，否则请自行附加 etag。

版本变更于 0.5: 添加了 add_etags、cache_timeout 和 conditional 参数。默认行为是添加 etag。

版本新增于 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() 的参数。

返回类型:

变更日志

版本变更于 2.0: path 替换了 filename 参数。

版本新增于 2.0: 将实现移动到 Werkzeug。现在这是一个包装器，用于传递一些 Flask 特定的参数。

版本 0.5 中新增。

消息闪现¶

flask.flash(message, category='message')¶

向下一个请求闪现消息。为了从会话中删除闪现消息并将其显示给用户，模板必须调用 get_flashed_messages()。

变更日志

版本变更于 0.3: 添加了 category 参数。

参数:

message (str) – 要闪现的消息。
category (str) – 消息的类别。建议使用以下值：'message' 用于任何类型的消息，'error' 用于错误，'info' 用于信息消息，'warning' 用于警告。但是，任何类型的字符串都可以用作类别。

返回类型:

None

flask.get_flashed_messages(with_categories=False, category_filter=())¶

从会话中拉取所有闪现消息并返回它们。在同一请求中进一步调用此函数将返回相同的消息。默认情况下，仅返回消息，但当 with_categories 设置为 True 时，返回值将是一个元组列表，形式为 (category, message)。

通过在 category_filter 中提供类别，将闪现消息过滤为一个或多个类别。这允许在单独的 html 块中呈现类别。with_categories 和 category_filter 参数是不同的

with_categories 控制是否将类别与消息文本一起返回（True 返回一个元组，其中 False 仅返回消息文本）。
category_filter 将消息过滤为仅与提供的类别匹配的消息。

有关示例，请参见消息闪现。

变更日志

版本变更于 0.9: 添加了 category_filter 参数。

版本变更于 0.3: 添加了 with_categories 参数。

参数:

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，并返回一个 Response 对象，其 mimetype 为 application/json。从视图返回的 dict 或 list 将自动转换为 JSON 响应，而无需调用此函数。

这需要一个活动的请求或应用上下文，并调用 app.json.response()。

在调试模式下，输出会使用缩进进行格式化，以便于阅读。这也可以由提供程序控制。

可以给定位置参数或关键字参数，但不能同时给定两者。如果没有给定参数，则序列化 None。

参数:

args (t.Any) – 要序列化的单个值，或要视为列表进行序列化的多个值。
kwargs (t.Any) – 视为要序列化的 dict。

返回类型:

变更日志

在 2.2 版本中变更: 调用 current_app.json.response，允许应用覆盖此行为。

在 2.0.2 版本中变更: decimal.Decimal 通过转换为字符串来支持。

在 0.11 版本中变更: 添加了对序列化顶层数组的支持。这在旧版本的浏览器中是一个安全风险。请参阅 JSON 安全性。

版本新增于 0.2。

flask.json.dumps(obj, **kwargs)¶

将数据序列化为 JSON。

如果 current_app 可用，它将使用其 app.json.dumps() 方法，否则将使用 json.dumps()。

参数:

obj (Any) – 要序列化的数据。
kwargs (Any) – 传递给 dumps 实现的参数。

返回类型:

变更日志

在 2.3 版本中变更: 移除了 app 参数。

在 2.2 版本中变更: 调用 current_app.json.dumps，允许应用覆盖此行为。

在 2.0.2 版本中变更: decimal.Decimal 通过转换为字符串来支持。

在 2.0 版本中变更: encoding 将在 Flask 2.1 中移除。

在 1.0.3 版本中变更: 可以直接传递 app，而无需应用上下文进行配置。

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

变更日志

在 2.3 版本中变更: 移除了 app 参数。

在 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 实现的参数。

返回类型:

变更日志

在 2.3 版本中变更: 移除了 app 参数。

在 2.2 版本中变更: 调用 current_app.json.loads，允许应用覆盖此行为。

在 2.0 版本中变更: encoding 将在 Flask 2.1 中移除。数据必须是字符串或 UTF-8 字节。

在 1.0.3 版本中变更: 可以直接传递 app，而无需应用上下文进行配置。

flask.json.load(fp, **kwargs)¶

从文件中读取 JSON 并反序列化数据。

如果 current_app 可用，它将使用其 app.json.load() 方法，否则将使用 json.load()。

参数:

fp (IO) – 为读取文本或 UTF-8 字节而打开的文件。
kwargs (Any) – 传递给 load 实现的参数。

返回类型:

变更日志

在 2.3 版本中变更: 移除了 app 参数。

在 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，并返回一个 Response 对象，其 mimetype 为 application/json。

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¶: 对任何序列化的 dict 中的键进行排序。这可能对某些缓存情况很有用，但可以禁用以获得更好的性能。启用后，键都必须是字符串，排序前不会进行转换。

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 使用此方法来序列化会话数据，但它在其他地方也可能很有用。它可以扩展以支持其他类型。

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 的支持。Dict 在 JSON 中没有顺序，因此为了处理这种情况，我们将项目转储为 [key, value] 对的列表。为 JSONTag 创建子类，并为其提供新键 ' od' 以标识类型。会话序列化程序首先处理 dict，因此将新标记插入到顺序的前面，因为 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。

返回值:

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。

返回值:

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) – 以文本或二进制模式打开文件。

返回值:

True 如果文件已成功加载。

返回类型:

变更日志

在 2.3 版本中更改: 添加了 text 参数。

在 2.0 版本中添加。

from_mapping(mapping=None, **kwargs)¶

像 update() 一样更新配置，忽略非大写键的项目。

返回值:

始终返回 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 指向过期的对象。

在版本 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)¶

一个辅助方法，用于向应用注册路由规则（以及可选的视图函数）。端点会自动添加 Blueprint 的名称作为前缀。

参数:

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'

变更日志

在版本 0.10 中添加。

flask.appcontext_popped¶: 当应用上下文被弹出时，会发送此信号。发送者是应用。这通常与 appcontext_tearing_down 信号一致。

变更日志

在版本 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)

变更日志

在版本 0.10 中添加。

基于类的视图¶

变更日志

在 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 未找到错误。

这与 Web 服务器处理静态文件的方式一致。这也使得安全地使用相对链接目标成为可能。

您还可以为同一函数定义多个规则。但是，它们必须是唯一的。也可以指定默认值。例如，以下是接受可选页面的 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__：函数的名称默认用作端点。如果显式提供了端点，则使用此值。此外，默认情况下，这将以 Blueprint 的名称作为前缀，这是无法从函数本身自定义的。
methods：如果在添加 URL 规则时未提供 methods，则 Flask 将在视图函数对象本身上查找是否存在 methods 属性。如果存在，它将从那里提取 methods 的信息。
provide_automatic_options：如果设置了此属性，Flask 将强制启用或禁用 HTTP OPTIONS 响应的自动实现。当使用想要在每个视图的基础上自定义 OPTIONS 响应的装饰器时，这可能很有用。
required_methods：如果设置了此属性，即使在 route() 调用中显式覆盖了 methods，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)¶

此函数在给定 info 名称和参数时，将启动解析并创建一个新的 Context。但它不会调用实际的命令回调。

要快速自定义使用的上下文类，而无需覆盖此方法，请设置 context_class 属性。

参数:

info_name (str | None) – 此调用的 info 名称。通常，这是脚本或命令最具描述性的名称。对于顶层脚本，通常是脚本的名称；对于下级命令，则是命令的名称。
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 应用程序的辅助对象。通常不需要与之交互，因为它在分发到 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 文件。

返回值:

如果加载了至少一个环境变量，则返回 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)

返回类型: