API

文档的此部分涵盖 Flask 的所有接口。对于 Flask 依赖于外部库的部分,我们在此处记录最重要的部分并提供指向规范文档的链接。

应用程序对象

class flask.Flask(import_name, static_url_path=None, static_folder='static', static_host=None, host_matching=False, subdomain_matching=False, template_folder='templates', instance_path=None, instance_relative_config=False, root_path=None)

flask 对象实现了 WSGI 应用程序,并充当中心对象。它被传递应用程序的模块或包的名称。创建后,它将充当视图函数、URL 规则、模板配置等的中心注册表。

包的名称用于根据包内部或模块所在的文件夹解析资源,具体取决于包参数解析为实际 python 包(带有 __init__.py 文件的文件夹)还是标准模块(仅 .py 文件)。

有关资源加载的更多信息,请参阅 open_resource()

通常,您在主模块或包的 __init__.py 文件中创建 Flask 实例,如下所示

from flask import Flask
app = Flask(__name__)

关于第一个参数

第一个参数的目的是让 Flask 了解哪些内容属于您的应用程序。此名称用于在文件系统上查找资源,可供扩展使用以改进调试信息,还有更多用途。

因此,您在那里提供的内容非常重要。如果您使用的是单个模块,则 __name__ 始终是正确的值。但是,如果您使用的是一个包,通常建议在那里硬编码包的名称。

例如,如果您的应用程序在 yourapplication/app.py 中定义,则应使用以下两个版本之一创建它

app = Flask('yourapplication')
app = Flask(__name__.split('.')[0])

为什么?由于查找资源的方式,该应用程序甚至可以使用 __name__ 正常工作。但是,它会让调试变得更加困难。某些扩展可以根据应用程序的导入名称进行假设。例如,Flask-SQLAlchemy 扩展将在调试模式下查找触发 SQL 查询的应用程序中的代码。如果导入名称未正确设置,则该调试信息将丢失。(例如,它只会选取 yourapplication.app 中的 SQL 查询,而不会选取 yourapplication.views.frontend 中的 SQL 查询)

变更日志

1.0 版新增: 添加了 host_matchingstatic_host 参数。

0.11 版新增: 添加了 root_path 参数。

0.8 版新增: 添加了 instance_pathinstance_relative_config 参数。

0.7 版新增: 添加了 static_url_pathstatic_foldertemplate_folder 参数。

参数:
  • import_name (str) – 应用程序包的名称

  • static_url_path (str | None) – 可用于为 Web 上的静态文件指定不同的路径。默认为 static_folder 文件夹的名称。

  • static_folder (str | os.PathLike[str] | None) – 在 static_url_path 提供服务的静态文件的文件夹。相对于应用程序 root_path 或绝对路径。默认为 'static'

  • static_host (str | None) – 添加静态路由时要使用的主机。默认为 None。在使用 host_matching=True 且配置了 static_folder 时需要。

  • host_matching (bool) – 设置 url_map.host_matching 属性。默认为 False。

  • subdomain_matching (bool) – 匹配路由时考虑相对于 SERVER_NAME 的子域。默认为 False。

  • template_folder (str | os.PathLike[str] | None) – 包含应用程序应使用的模板的文件夹。默认为应用程序根路径中的 'templates' 文件夹。

  • instance_path (str | None) – 应用程序的备用实例路径。默认情况下,假定包或模块旁边的 'instance' 文件夹是实例路径。

  • instance_relative_config (bool) – 如果设置为 True,则加载配置的相对文件名假定相对于实例路径,而不是应用程序根目录。

  • root_path (str | None) – 应用程序文件的根路径。仅当无法自动检测到该路径时才应手动设置,例如对于命名空间包。

aborter

make_aborter() 创建的 aborter_class 实例。 flask.abort() 调用此实例来引发 HTTP 错误,也可以直接调用此实例。

变更日志

版本 2.2 中的新增内容: 从调用此对象的 flask.abort 移出。

aborter_class

Aborter 的别名

add_template_filter(f, name=None)

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

参数:
  • name (str | None) – 过滤器的可选名称,否则将使用函数名称。

  • f (Callable[[...], Any]) –

返回类型:

add_template_global(f, name=None)

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

变更日志

0.10 版新增。

参数:
  • name (str | None) – 全局函数的可选名称,否则将使用函数名称。

  • f (Callable[[...], Any]) –

返回类型:

add_template_test(f, name=None)

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

变更日志

0.10 版新增。

参数:
  • name (str | None) – 测试的可选名称,否则将使用函数名称。

  • f (Callable[[...], bool]) –

返回类型:

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 对象的额外选项。

返回类型:

after_request(f)

注册一个函数,以便在对该对象执行每次请求后运行。

使用响应对象调用该函数,并且必须返回一个响应对象。这允许函数在发送响应之前修改或替换响应。

如果一个函数引发异常,则不会调用任何剩余的 after_request 函数。因此,这不应用于必须执行的操作,例如关闭资源。为此,请使用 teardown_request()

这在应用程序和蓝图对象中都可用。当在应用程序中使用时,它会在每次请求后执行。当在蓝图中使用时,它会在蓝图处理的每次请求后执行。要使用蓝图注册并在每次请求后执行,请使用 Blueprint.after_app_request()

参数:

f (T_after_request) –

返回类型:

T_after_request

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

一个数据结构,用于在每个请求结束时调用函数,格式为 {scope: [functions]}scope 键是函数处于活动状态的蓝图的名称,或 None(表示所有请求)。

要注册函数,请使用 after_request() 装饰器。

此数据结构是内部的。不应直接修改它,并且其格式可能会随时更改。

app_context()

创建 AppContext。用作 with 块来推送上下文,这将使 current_app 指向此应用程序。

在处理请求时,以及在运行 CLI 命令时,RequestContext.push() 会自动推送应用程序上下文。在这些情况之外,使用此方法手动创建上下文。

with app.app_context():
    init_db()

请参阅 应用程序上下文

变更日志

0.9 版中的新增功能。

返回类型:

AppContext

app_ctx_globals_class

_AppCtxGlobals 的别名

async_to_sync(func)

返回一个将运行协程函数的同步函数。

result = app.async_to_sync(func)(*args, **kwargs)

覆盖此方法以更改应用程序将异步代码转换为同步可调用方式。

变更日志

2.0 版中的新增功能。

参数:

func (Callable[[...], Coroutine[Any, Any, Any]]) –

返回类型:

Callable[[…], Any]

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

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

一种在每个请求开始时调用的函数数据结构,格式为 {scope: [functions]}scope 键是函数所针对的蓝图名称,或 None(针对所有请求)。

要注册函数,请使用 before_request() 装饰器。

此数据结构是内部的。不应直接修改它,并且其格式可能会随时更改。

blueprints: dict[str, Blueprint]

将已注册的蓝图名称映射到蓝图对象。该字典保留了注册蓝图的顺序。蓝图可以注册多次,此字典不会跟踪它们被附加的频率。

变更日志

0.7 版中的新增功能。

cli: click.Group

用于为该对象注册 CLI 命令的 Click 命令组。一旦发现应用程序并注册蓝图,就可以从 flask 命令中使用这些命令。

config

作为 Config 的配置字典。它的行为完全像一个常规字典,但支持使用其他方法从文件中加载配置。

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

create_jinja_environment()

基于 jinja_options 和应用程序的各种与 Jinja 相关的函数创建 Jinja 环境。在此之后更改 jinja_options 不会产生任何效果。还会向环境中添加与 Flask 相关的全局变量和过滤器。

变更日志

在版本 0.11 中更改:Environment.auto_reload 根据 TEMPLATES_AUTO_RELOAD 配置选项进行设置。

0.5 版新增。

返回类型:

环境

create_url_adapter(request)

为给定的请求创建 URL 适配器。URL 适配器在请求上下文尚未设置时创建,因此请求会显式传递。

变更日志

在版本 1.0 中更改:SERVER_NAME 不再隐式启用子域匹配。请改用 subdomain_matching

0.9 版中已更改:当为应用程序上下文创建 URL 适配器时,现在也可以在没有请求对象的情况下调用它。

0.6 版中的新增内容。

参数:

request (Request | None) –

返回类型:

MapAdapter | None

property debug: bool

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

在生产环境中部署时,不要启用调试模式。

默认值:False

delete(rule, **options)

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

变更日志

2.0 版中的新增功能。

参数:
  • rule (str) –

  • options (Any) –

返回类型:

Callable[[T_route], T_route]

dispatch_request()

执行请求分派。匹配 URL 并返回视图或错误处理程序的返回值。这不必是响应对象。要将返回值转换为正确的响应对象,请调用 make_response()

变更日志

在版本 0.7 中更改:不再执行异常处理,此代码已移至新的 full_dispatch_request()

返回类型:

ft.ResponseReturnValue

do_teardown_appcontext(exc=<object object>)

在应用程序上下文弹出之前立即调用。

处理请求时,将在请求上下文之后弹出应用程序上下文。请参阅 do_teardown_request()

这将调用所有使用 teardown_appcontext() 修饰的函数。然后发送 appcontext_tearing_down 信号。

这由 AppContext.pop() 调用。

变更日志

0.9 版中的新增功能。

参数:

exc (BaseException | None) –

返回类型:

do_teardown_request(exc=<object object>)

在分派请求并返回响应后,在请求上下文弹出之前立即调用。

这将调用所有使用 teardown_request() 修饰的函数,以及在蓝图处理请求时调用 Blueprint.teardown_request()。最后,发送 request_tearing_down 信号。

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

参数:

exc (BaseException | None) – 分发请求时引发的未处理异常。如果未传递,则从当前异常信息中检测。传递给每个清理函数。

返回类型:

变更日志

0.9 版本中已更改: 添加了 exc 参数。

endpoint(endpoint)

装饰视图函数以使用给定端点注册它。如果在没有 view_func 的情况下使用 add_url_rule() 添加规则,则使用此项。

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

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

endpoint (str) – 与视图函数关联的端点名称。

返回类型:

Callable[[F], F]

ensure_sync(func)

确保函数对 WSGI 工作进程是同步的。普通 def 函数按原样返回。将 async def 函数包装起来以运行并等待响应。

覆盖此方法以更改应用程序运行异步视图的方式。

变更日志

2.0 版中的新增功能。

参数:

func (Callable[[...], Any]) –

返回类型:

Callable[[…], Any]

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() 装饰器。

此数据结构是内部的。不应直接修改它,并且其格式可能会随时更改。

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]

extensions: dict[str, t.Any]

扩展可以存储应用程序特定状态的地方。例如,扩展可以存储数据库引擎和类似内容。

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

变更日志

0.7 版中的新增功能。

full_dispatch_request()

分派请求,并在其之上执行请求预处理和后处理,以及 HTTP 异常捕获和错误处理。

变更日志

0.7 版中的新增功能。

返回类型:

响应

get(rule, **options)

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

变更日志

2.0 版中的新增功能。

参数:
  • rule (str) –

  • options (Any) –

返回类型:

Callable[[T_route], T_route]

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

handle_exception(e)

处理未关联错误处理程序的异常,或从错误处理程序引发的异常。这始终导致 500 InternalServerError

始终发送 got_request_exception 信号。

如果 PROPAGATE_EXCEPTIONSTrue,例如在调试模式中,将重新引发错误,以便调试器可以显示它。否则,将记录原始异常,并返回 InternalServerError

如果为 InternalServerError500 注册了错误处理程序,则将使用该处理程序。为了保持一致性,处理程序始终会收到 InternalServerError。原始未处理异常可用作 e.original_exception

变更日志

在 1.1.0 版本中更改:始终将 InternalServerError 实例传递给处理程序,将 original_exception 设置为未处理错误。

在 1.1.0 版本中更改:即使在没有处理程序时,after_request 函数和其他最终处理也会针对默认 500 响应完成。

0.3 版新增。

参数:

e (Exception) –

返回类型:

响应

handle_http_exception(e)

处理 HTTP 异常。默认情况下,这将调用已注册的错误处理程序,并回退为将异常作为响应返回。

变更日志

1.0.3 版本中已更改: RoutingException,在路由期间用于斜杠重定向等操作,不会传递给错误处理程序。

1.0 版本中已更改: 异常按代码 MRO 查找,因此 HTTPException 子类可以使用基本 HTTPException 的通用处理程序进行处理。

0.3 版新增。

参数:

e (HTTPException) –

返回类型:

HTTPException | ft.ResponseReturnValue

handle_url_build_error(error, endpoint, values)

如果引发 BuildError,则由 url_for() 调用。如果此函数返回一个值,则该值将由 url_for 返回,否则将重新引发该错误。

url_build_error_handlers 中的每个函数都使用 errorendpointvalues 调用。如果某个函数返回 None 或引发 BuildError,则跳过该函数。否则,其返回值将由 url_for 返回。

参数:
  • error (BuildError) – 正在处理的活动 BuildError

  • endpoint (str) – 正在构建的端点。

  • values (dict[str, Any]) – 传递给 url_for 的关键字参数。

返回类型:

str

handle_user_exception(e)

每当发生应处理的异常时,都会调用此方法。一种特殊情况是 HTTPException,它会转发到 handle_http_exception() 方法。此函数将返回一个响应值或使用相同的回溯重新引发异常。

变更日志

在 1.0 版本中更改:从请求数据(如 form)引发的键错误在调试模式下显示错误的键,而不是通用的错误请求消息。

0.7 版中的新增功能。

参数:

e (Exception) –

返回类型:

HTTPException | ft.ResponseReturnValue

property has_static_folder: bool

True 如果 static_folder 已设置。

变更日志

0.5 版新增。

import_name

此对象所属的包或模块的名称。一旦由构造函数设置,请不要更改此名称。

inject_url_defaults(endpoint, values)

将给定端点的 URL 默认值直接注入到传递的值字典中。这在内部使用,并在构建 URL 时自动调用。

变更日志

0.7 版中的新增功能。

参数:
返回类型:

instance_path

保存实例文件夹的路径。

变更日志

0.8 版中的新增功能。

iter_blueprints()

按注册顺序迭代所有蓝图。

变更日志

0.11 版本中的新增功能。

返回类型:

t.ValuesView[Blueprint]

属性 jinja_env: 环境

用于加载模板的 Jinja 环境。

首次访问此属性时会创建环境。之后更改 jinja_options 将不起作用。

jinja_environment

环境 的别名

属性 jinja_loader: BaseLoader |

此对象的模板的 Jinja 加载器。如果已设置,默认情况下,这是一个类 jinja2.loaders.FileSystemLoadertemplate_folder

变更日志

0.5 版新增。

jinja_options: 字典[字符串, t.Any] = {}

create_jinja_environment() 中传递给 Jinja 环境的选项。在创建环境(访问 jinja_env)后更改这些选项将不起作用。

变更日志

在版本 1.1.0 中更改:这是一个 字典,而不是 不可变字典,以便更轻松地进行配置。

json: JSONProvider

提供对 JSON 方法的访问。当应用程序上下文处于活动状态时,flask.json 中的函数将调用此提供程序上的方法。用于处理 JSON 请求和响应。

json_provider_class 的实例。可以通过在子类中更改该属性,或之后分配给此属性来自定义。

默认值 DefaultJSONProvider 使用 Python 的内置 json 库。不同的提供程序可以使用不同的 JSON 库。

变更日志

2.2 版中的新增功能。

json_provider_class

DefaultJSONProvider 的别名

log_exception(exc_info)

记录异常。如果禁用了调试,并且在调用处理程序之前,handle_exception() 会调用此方法。默认实现将异常作为错误记录在 logger 上。

变更日志

0.8 版中的新增功能。

参数:

exc_info (tuple[type, BaseException, TracebackType] | tuple[None, None, None]) –

返回类型:

property logger: Logger

应用程序的标准 Python Logger,其名称与 name 相同。

在调试模式下,记录器的 level 将设置为 DEBUG

如果没有配置任何处理程序,则会添加一个默认处理程序。有关更多信息,请参阅 Logging

变更日志

在 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 版中的新增功能。

返回类型:

中止

make_config(instance_relative=False)

Flask 构造函数用于创建 config 属性。 instance_relative 参数从 Flask 构造函数中传入(在此处命名为 instance_relative_config),并指示 config 是否应相对于实例路径或应用程序的根路径。

变更日志

0.8 版中的新增功能。

参数:

instance_relative (bool) –

返回类型:

配置

make_default_options_response()

此方法用于创建默认 OPTIONS 响应。可以通过子类化更改此方法,以更改 OPTIONS 响应的默认行为。

变更日志

0.7 版中的新增功能。

返回类型:

响应

make_response(rv)

将视图函数的返回值转换为 response_class 实例。

参数:

rv (ft.ResponseReturnValue) –

视图函数的返回值。视图函数必须返回一个响应。返回 None,或视图在不返回的情况下结束,是不允许的。以下类型允许用于 view_rv

str

使用编码为 UTF-8 的字符串作为主体创建一个响应对象。

字节

使用字节作为主体创建一个响应对象。

字典

在返回之前将被 jsonify 的字典。

列表

在返回之前将被 jsonify 的列表。

生成器迭代器

返回 strbytes 以作为响应进行流式传输的生成器。

元组

可以是 (body, status, headers)(body, status)(body, headers),其中 body 是此处允许的任何其他类型,status 是字符串或整数,headers 是字典或 (key, value) 元组的列表。如果 bodyresponse_class 实例,status 将覆盖退出值,headers 将被扩展。

response_class

对象将保持不变地返回。

其他 Response

对象被强制转换为 response_class

callable()

该函数被调用为 WSGI 应用程序。结果用于创建响应对象。

返回类型:

响应

变更日志

在版本 2.2 中更改: 生成器将被转换为流响应。列表将被转换为 JSON 响应。

在版本 1.1 中更改: 字典将被转换为 JSON 响应。

在版本 0.9 中更改: 以前元组被解释为响应对象的论据。

make_shell_context()

返回此应用程序的交互式 shell 的 shell 上下文。这将运行所有已注册的 shell 上下文处理器。

变更日志

0.11 版本中的新增功能。

返回类型:

dict[str, Any]

property name: str

应用程序的名称。这通常是导入名称,不同之处在于如果导入名称是 main,则会从运行文件猜测。当 Flask 需要应用程序的名称时,此名称用作显示名称。它可以设置和覆盖以更改值。

变更日志

0.8 版中的新增功能。

open_instance_resource(resource, mode='rb')

从应用程序的实例文件夹 (instance_path) 打开资源。否则像 open_resource() 一样。实例资源也可以打开进行写入。

参数:
  • 资源 (str) – 资源的名称。要访问子文件夹中的资源,请使用正斜杠作为分隔符。

  • 模式 (str) – 资源文件打开模式,默认值为“rb”。

返回类型:

IO

open_resource(resource, mode='rb')

打开相对于 root_path 的资源文件以进行读取。

例如,如果文件 schema.sql 位于定义 Flask 应用程序的文件 app.py 旁边,则可以使用以下命令打开它

with app.open_resource("schema.sql") as f:
    conn.executescript(f.read())
参数:
  • 资源 (str) – 相对于 root_path 的资源路径。

  • 模式 (str) – 以此模式打开文件。仅支持读取,有效值为“r”(或“rt”)和“rb”。

返回类型:

IO

请注意,这是 Flask 类中同名方法的副本。

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]

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 的一个实例。

返回类型:

响应

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() 回调中访问。

返回类型:

变更日志

2.0.1 版中已更改: 可以使用 name 选项来更改蓝图注册时的(前缀点)名称。这允许同一个蓝图使用 url_for 的唯一名称多次注册。

0.7 版中的新增功能。

register_error_handler(code_or_exception, f)

替代错误附加函数,用于 errorhandler() 装饰器,该装饰器更适合于非装饰器用法。

变更日志

0.7 版中的新增功能。

参数:
返回类型:

request_class

别名 Request

request_context(environ)

创建一个表示 WSGI 环境的 RequestContext。使用 with 块来推送上下文,这将使 request 指向此请求。

请参见 请求上下文

通常情况下,您不应该在自己的代码中调用此方法。在处理请求时,wsgi_app() 会自动推送请求上下文。使用 test_request_context() 来创建环境和上下文,而不是使用此方法。

参数:

environ (WSGIEnvironment) – WSGI 环境

返回类型:

RequestContext

response_class

Response 的别名

root_path

文件系统上包的绝对路径。用于查找包中包含的资源。

route(rule, **options)

装饰视图函数,以便使用给定的 URL 规则和选项对其进行注册。调用 add_url_rule(),它包含有关实现的更多详细信息。

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

请参阅 URL 路由注册

如果未传递 endpoint 参数,则路由的端点名称默认为视图函数的名称。

methods 参数默认为 ["GET"]HEADOPTIONS 会自动添加。

参数:
  • rule (str) – URL 规则字符串。

  • options (Any) – 传递给 Rule 对象的额外选项。

返回类型:

Callable[[T_route], T_route]

run(host=None, port=None, debug=None, load_dotenv=True, **options)

在本地开发服务器上运行应用程序。

不要在生产环境中使用 run()。它不打算满足生产服务器的安全性和性能要求。相反,请参阅 部署到生产环境 以获取 WSGI 服务器建议。

如果设置了 debug 标志,服务器将自动重新加载代码更改,并在发生异常时显示调试器。

如果您想在调试模式下运行应用程序,但禁用交互式调试器上的代码执行,您可以将 use_evalex=False 作为参数传递。这将使调试器的回溯屏幕保持活动状态,但禁用代码执行。

不建议将此函数用于具有自动重新加载的开发,因为这很不受支持。相反,您应该使用 flask 命令行脚本的 run 支持。

请记住

除非处于调试模式,否则 Flask 将使用通用错误页面抑制任何服务器错误。因此,要在不重新加载代码的情况下启用交互式调试器,您必须使用 debug=Trueuse_reloader=False 调用 run()。将 use_debugger 设置为 True 而不在调试模式下不会捕获任何异常,因为没有任何异常可以捕获。

参数:
  • host (str | None) – 要侦听的主机名。将其设置为 '0.0.0.0' 以使服务器在外部也可访问。默认为 '127.0.0.1'SERVER_NAME 配置变量中的主机(如果存在)。

  • port (int | None) – Web 服务器的端口。默认为 5000SERVER_NAME 配置变量中定义的端口(如果存在)。

  • debug (bool | None) – 如果给定,启用或禁用调试模式。请参阅 debug

  • load_dotenv (bool) – 加载最近的 .env.flaskenv 文件以设置环境变量。还会将工作目录更改为包含找到的第一个文件的目录。

  • options (Any) – 要转发给底层 Werkzeug 服务器的选项。有关更多信息,请参阅 werkzeug.serving.run_simple()

返回类型:

变更日志

版本 1.0 中已更改: 如果已安装,python-dotenv 将用于从 .env.flaskenv 文件加载环境变量。

FLASK_DEBUG 环境变量将覆盖 debug

默认情况下启用多线程模式。

版本 0.10 中已更改: 现在从 SERVER_NAME 变量中选择默认端口。

secret_key

如果设置了密钥,加密组件可以使用它来对 cookie 和其他内容进行签名。例如,当您想使用安全 cookie 时,请将其设置为一个复杂的随机值。

此属性还可以通过配置使用 SECRET_KEY 配置键进行配置。默认为 None

select_jinja_autoescape(filename)

如果给定模板名称的自动转义应处于活动状态,则返回 True。如果未给定模板名称,则返回 True

变更日志

在版本 2.2 中更改:现在默认情况下为 .svg 文件启用自动转义。

0.5 版新增。

参数:

filename (str) –

返回类型:

bool

send_static_file(filename)

用于从 static_folder 提供文件的视图函数。如果设置了 static_folder,则会自动在 static_url_path 注册此视图的路由。

请注意,这是 Flask 类中同名方法的副本。

变更日志

0.5 版新增。

参数:

filename (str) –

返回类型:

响应

session_interface: SessionInterface = <flask.sessions.SecureCookieSessionInterface object>

要使用的会话接口。默认情况下,此处使用 SecureCookieSessionInterface 的实例。

变更日志

0.8 版中的新增功能。

shell_context_processor(f)

注册一个 shell 上下文处理器函数。

变更日志

0.11 版本中的新增功能。

参数:

f (T_shell_context_processor) –

返回类型:

T_shell_context_processor

shell_context_processors: list[ft.ShellContextProcessorCallable]

当创建 shell 上下文时应运行的 shell 上下文处理器函数列表。

变更日志

0.11 版本中的新增功能。

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())时,在应用程序上下文变为非活动状态之前,将调用 teardown 函数。由于请求上下文通常还管理应用程序上下文,因此在弹出请求上下文时也会调用它。

如果由于未处理的异常而调用 teardown 函数,则会向其传递一个错误对象。如果注册了 errorhandler(),它将处理异常,而 teardown 不会接收它。

Teardown 函数必须避免引发异常。如果它们执行可能失败的代码,则必须用 try/except 块包围该代码并记录任何错误。

将忽略 teardown 函数的返回值。

变更日志

0.9 版中的新增功能。

参数:

f (T_teardown) –

返回类型:

T_teardown

teardown_appcontext_funcs: list[ft.TeardownCallable]

在销毁应用程序上下文时调用的函数列表。由于应用程序上下文在请求结束时也会被销毁,因此这是存储断开数据库连接的代码的地方。

变更日志

0.9 版中的新增功能。

teardown_request(f)

注册一个函数,以便在弹出请求上下文时调用。通常,这发生在每个请求的末尾,但也可以在测试期间手动推送上下文。

with app.test_request_context():
    ...

with 块退出(或调用 ctx.pop()),在请求上下文变为非活动状态之前,将调用关闭函数。

如果由于未处理的异常而调用 teardown 函数,则会向其传递一个错误对象。如果注册了 errorhandler(),它将处理异常,而 teardown 不会接收它。

Teardown 函数必须避免引发异常。如果它们执行可能失败的代码,则必须用 try/except 块包围该代码并记录任何错误。

将忽略 teardown 函数的返回值。

这在应用和蓝图对象上都可用。当在应用上使用时,这将在每个请求后执行。当在蓝图上使用时,这将在蓝图处理的每个请求后执行。要使用蓝图注册并在每个请求后执行,请使用 Blueprint.teardown_app_request()

参数:

f (T_teardown) –

返回类型:

T_teardown

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() 装饰器。

此数据结构是内部的。不应直接修改它,并且其格式可能会随时更改。

template_filter(name=None)

用于注册自定义模板过滤器的装饰器。你可以为过滤器指定一个名称,否则将使用函数名称。示例

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

name (str | None) – 过滤器的可选名称,否则将使用函数名称。

返回类型:

Callable[[T_template_filter], T_template_filter]

template_folder

相对于 root_path 的模板文件夹的路径,以添加到模板加载器中。如果不需要添加模板,则为 None

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(**kwargs)

创建一个 CLI 运行器来测试 CLI 命令。参见 使用 CLI 运行器运行命令

返回 test_cli_runner_class 的实例,默认情况下为 FlaskCliRunner。Flask 应用程序对象作为第一个参数传递。

变更日志

1.0 版中的新增功能。

参数:

kwargs (t.Any) –

返回类型:

FlaskCliRunner

test_cli_runner_class: type[FlaskCliRunner] | None = None

CliRunner 子类,默认情况下为 FlaskCliRunner,由 test_cli_runner() 使用。它的 __init__ 方法应将 Flask 应用程序对象作为第一个参数。

变更日志

1.0 版中的新增功能。

test_client(use_cookies=True, **kwargs)

为该应用程序创建一个测试客户端。有关单元测试的信息,请转到 测试 Flask 应用程序

请注意,如果你正在测试应用程序代码中的断言或异常,你必须设置 app.testing = True 才能使异常传播到测试客户端。否则,异常将由应用程序处理(测试客户端不可见),并且 AssertionError 或其他异常的唯一指示是对测试客户端的 500 状态代码响应。请参阅 testing 属性。例如

app.testing = True
client = app.test_client()

测试客户端可以在 with 块中使用,以将关闭上下文推迟到 with 块结束时。如果你想访问上下文本地变量以进行测试,这将非常有用

with app.test_client() as c:
    rv = c.get('/?vodka=42')
    assert request.args['vodka'] == '42'

此外,你可以传递可选关键字参数,然后将它们传递给应用程序的 test_client_class 构造函数。例如

from flask.testing import FlaskClient

class CustomClient(FlaskClient):
    def __init__(self, *args, **kwargs):
        self._authentication = kwargs.pop("authentication")
        super(CustomClient,self).__init__( *args, **kwargs)

app.test_client_class = CustomClient
client = app.test_client(authentication='Basic ....')

请参阅 FlaskClient 了解更多信息。

变更日志

在 0.11 版本中更改:添加 **kwargs 以支持将其他关键字参数传递给 test_client_class 的构造函数。

在 0.7 版本中新增:添加了 use_cookies 参数,以及通过设置 test_client_class 属性来覆盖要使用的客户端的功能。

0.4 版中已更改:为客户端添加了对 with 块用法的支持。

参数:
  • use_cookies (bool) –

  • kwargs (t.Any) –

返回类型:

FlaskClient

test_client_class: type[FlaskClient] | None = None

test_client() 方法创建此测试客户端类的实例。默认为 FlaskClient

变更日志

0.7 版中的新增功能。

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_SCHEMEsubdomainSERVER_NAMEAPPLICATION_ROOT 构建。

  • subdomain – 要附加到 SERVER_NAME 的子域名。

  • url_scheme – 要代替 PREFERRED_URL_SCHEME 使用的方案。

  • data – 请求正文,可以是字符串,也可以是表单键值对的字典。

  • json – 如果提供,则将其序列化为 JSON 并作为 data 传递。还将 content_type 的默认值设为 application/json

  • args (Any) – 传递给 EnvironBuilder 的其他位置参数。

  • kwargs (Any) – 传递给 EnvironBuilder 的其他关键字参数。

返回类型:

RequestContext

testing

测试标志。将其设置为 True 以启用 Flask 扩展的测试模式(将来可能还包括 Flask 本身)。例如,这可能会激活具有额外运行时成本的测试帮助器,默认情况下不应启用这些帮助器。

如果已启用此标志,并且 PROPAGATE_EXCEPTIONS 未更改为默认值,则会隐式启用此标志。

此属性还可以使用 TESTING 配置键从配置中进行配置。默认为 False

trap_http_exception(e)

检查是否应捕获 HTTP 异常。默认情况下,对于所有异常,这将返回 False,但如果 TRAP_BAD_REQUEST_ERRORS 设置为 True,则对于错误请求密钥错误除外。如果 TRAP_HTTP_EXCEPTIONS 设置为 True,则它还将返回 True

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

变更日志

在 1.0 版中更改:在调试模式下,默认情况下不会捕获错误请求。

0.8 版中的新增功能。

参数:

e (Exception) –

返回类型:

bool

update_template_context(context)

使用一些常用变量更新模板上下文。这会将 request、session、config 和 g 注入模板上下文,以及模板上下文处理器想要注入的所有内容。请注意,从 Flask 0.6 开始,如果上下文处理器决定返回具有相同键的值,则不会覆盖上下文中原始值。

参数:

context (dict[str, Any]) – 上下文作为字典,在其中更新以添加额外的变量。

返回类型:

url_build_error_handlers: list[t.Callable[[Exception, str, dict[str, t.Any]], str]]

handle_url_build_error()url_for() 引发 BuildError 时由其调用的函数列表。每个函数都使用 errorendpointvalues 进行调用。如果某个函数返回 None 或引发 BuildError,则会跳过该函数。否则,其返回值将由 url_for 返回。

变更日志

0.9 版中的新增功能。

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

一个数据结构,其中包含在生成 URL 时调用以修改关键字参数的函数,格式为 {scope: [functions]}scope 键是函数处于活动状态的蓝图的名称,或所有请求的 None

要注册函数,请使用 url_defaults() 装饰器。

此数据结构是内部的。不应直接修改它,并且其格式可能会随时更改。

url_defaults(f)

应用程序所有视图函数的 URL 默认值的回调函数。它使用端点和值进行调用,并且应该更新就地传递的值。

这在应用程序和蓝图对象上都可用。在应用程序上使用时,它将针对每个请求进行调用。在蓝图上使用时,它将针对蓝图处理的请求进行调用。要使用蓝图注册并影响每个请求,请使用 Blueprint.app_url_defaults()

参数:

f (T_url_defaults) –

返回类型:

T_url_defaults

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

使用给定的值生成到给定端点的 URL。

这由 flask.url_for() 调用,也可以直接调用。

端点是 URL 规则的名称,通常使用 @app.route() 添加,并且通常与视图函数同名。在 Blueprint 中定义的路由会将蓝图名称(用 . 分隔)添加到端点前。

在某些情况下,例如电子邮件消息中,您希望 URL 包含方案和域,例如 https://example.com/hello。当不在活动请求中时,URL 默认情况下将为外部,但这需要设置 SERVER_NAME,以便 Flask 知道要使用哪个域。 APPLICATION_ROOTPREFERRED_URL_SCHEME 也应根据需要进行配置。此配置仅在不在活动请求中时使用。

可以使用 url_defaults() 为函数添加装饰,以便在生成 URL 之前修改关键字参数。

如果生成失败,例如由于未知端点或不正确的值,则会调用应用程序的 handle_url_build_error() 方法。如果该方法返回一个字符串,则返回该字符串,否则会引发 BuildError

参数:
  • endpoint (str) – 与要生成的 URL 关联的端点名称。如果以 . 开头,则将使用当前蓝图名称(如果存在)。

  • _anchor (str | None) – 如果给出,则将此内容作为 #anchor 追加到 URL。

  • _method (str | None) – 如果给出,则为端点生成与此方法关联的 URL。

  • _scheme (str | None) – 如果给出,则 URL 将具有此方案(如果它是外部的)。

  • _external (bool | None) – 如果给出,则优先将 URL 设置为内部 (False) 或要求它为外部 (True)。外部 URL 包括方案和域。当不在活动请求中时,URL 默认情况下为外部。

  • values (Any) – 用于 URL 规则的可变部分的值。未知的键将附加为查询字符串参数,如 ?a=b&c=d

返回类型:

str

变更日志

2.2 版中的新增功能:flask.url_for(调用此方法)中移动。

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

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

用于调用以修改传递到视图函数的关键字参数的数据结构,格式为 {scope: [functions]}scope 键是函数处于活动状态的蓝图的名称,或 None(表示所有请求)。

要注册函数,请使用 url_value_preprocessor() 装饰器。

此数据结构是内部的。不应直接修改它,并且其格式可能会随时更改。

view_functions: dict[str, ft.RouteCallable]

将端点名称映射到视图函数的字典。

要注册视图函数,请使用 route() 装饰器。

此数据结构是内部的。不应直接修改它,并且其格式可能会随时更改。

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]

蓝图对象

flask.蓝图(名称, 导入名称, 静态文件夹=无, 静态 URL 路径=无, 模板文件夹=无, URL 前缀=无, 子域=无, URL 默认值=无, 根路径=无, cli_group=<对象 对象>)
参数:
  • 名称 (str) –

  • 导入名称 (str) –

  • 静态文件夹 (str | os.PathLike[str] | ) –

  • 静态 URL 路径 (str | ) –

  • 模板文件夹 (str | os.PathLike[str] | ) –

  • URL 前缀 (str | ) –

  • 子域 (str | ) –

  • URL 默认值 (dict[str, t.Any] | ) –

  • root_path (str | None) –

  • cli_group (str | None) –

add_app_template_filter(f, name=None)

注册一个模板过滤器,可在应用程序呈现的任何模板中使用。其工作原理类似于 app_template_filter() 装饰器。等同于 Flask.add_template_filter()

参数:
  • name (str | None) – 过滤器的可选名称,否则将使用函数名称。

  • f (Callable[[...], Any]) –

返回类型:

add_app_template_global(f, name=None)

注册一个模板全局变量,可在应用程序呈现的任何模板中使用。其工作原理类似于 app_template_global() 装饰器。等同于 Flask.add_template_global()

变更日志

0.10 版新增。

参数:
  • name (str | None) – 全局变量的可选名称,否则将使用函数名称。

  • f (Callable[[...], Any]) –

返回类型:

add_app_template_test(f, name=None)

注册一个模板测试,可在应用程序呈现的任何模板中使用。其工作原理类似于 app_template_test() 装饰器。等同于 Flask.add_template_test()

变更日志

0.10 版新增。

参数:
  • name (str | None) – 测试的可选名称,否则将使用函数名称。

  • f (Callable[[...], bool]) –

返回类型:

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

返回类型:

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

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

一个数据结构,用于在每个请求结束时调用函数,格式为 {scope: [functions]}scope 键是函数处于活动状态的蓝图的名称,或 None(表示所有请求)。

要注册函数,请使用 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

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

一种在每个请求开始时调用的函数数据结构,格式为 {scope: [functions]}scope 键是函数所针对的蓝图名称,或 None(针对所有请求)。

要注册一个函数,请使用 before_request() 装饰器。

此数据结构是内部的。不应直接修改它,并且其格式可能会随时更改。

cli: click.Group

用于为该对象注册 CLI 命令的 Click 命令组。一旦发现应用程序并注册蓝图,就可以从 flask 命令中使用这些命令。

context_processor(f)

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

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

参数:

f (T_template_context_processor) –

返回类型:

T_template_context_processor

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]

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() 装饰器。

此数据结构是内部的。不应直接修改它,并且其格式可能会随时更改。

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]

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

property has_static_folder: bool

True 如果 static_folder 已设置。

变更日志

0.5 版新增。

import_name

此对象所属的包或模块的名称。一旦由构造函数设置,请不要更改此名称。

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

open_resource(resource, mode='rb')

打开 root_path 相对于读取的资源文件。

例如,如果文件 schema.sql 位于定义 Flask 应用程序的文件 app.py 旁边,则可以使用以下命令打开它

with app.open_resource("schema.sql") as f:
    conn.executescript(f.read())
参数:
  • resource (str) – 相对于 root_path 的资源路径。

  • 模式 (str) – 以此模式打开文件。仅支持读取,有效值为“r”(或“rt”)和“rb”。

返回类型:

IO

请注意,这是 Flask 类中同名方法的副本。

patch(rule, **options)

使用 methods=["PATCH"]

变更日志

2.0 版中的新增功能。

参数:
  • rule (str) –

  • options (Any) –

返回类型:

Callable[[T_route], T_route]

post(rule, **options)

使用 methods=["POST"]

变更日志

2.0 版中的新增功能。

参数:
  • rule (str) –

  • options (Any) –

返回类型:

Callable[[T_route], T_route]

put(rule, **options)

使用 methods=["PUT"]

变更日志

2.0 版中的新增功能。

参数:
  • rule (str) –

  • options (Any) –

返回类型:

Callable[[T_route], T_route]

record(func)

注册一个在蓝图在应用程序上注册时调用的函数。此函数以 make_setup_state() 方法返回的状态作为参数被调用。

参数:

func (Callable[[BlueprintSetupState], None]) –

返回类型:

record_once(func)

record() 类似,但将函数包装在另一个函数中,以确保该函数仅被调用一次。如果蓝图在应用程序上第二次注册,则不会调用传递的函数。

参数:

func (Callable[[BlueprintSetupState], None]) –

返回类型:

register(app, options)

Flask.register_blueprint() 调用,以使用应用程序注册在蓝图上注册的所有视图和回调。创建一个 BlueprintSetupState 并使用它调用每个 record() 回调。

参数:
  • app (App) – 此蓝图正在注册到的应用程序。

  • options (dict[str, t.Any]) – 从 register_blueprint() 转发的关键字参数。

返回类型:

变更日志

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

  • options (Any) –

返回类型:

register_error_handler(code_or_exception, f)

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

变更日志

0.7 版中的新增功能。

参数:
返回类型:

root_path

文件系统上包的绝对路径。用于查找包中包含的资源。

route(rule, **options)

装饰视图函数以使用给定的 URL 规则和选项注册它。调用 add_url_rule(),它有关于实现的更多详细信息。

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

请参阅 URL 路由注册

如果未传递 endpoint 参数,则路由的端点名称默认为视图函数的名称。

methods 参数默认为 ["GET"]HEADOPTIONS 会自动添加。

参数:
  • rule (str) – URL 规则字符串。

  • options (Any) – 传递给 Rule 对象的额外选项。

返回类型:

Callable[[T_route], T_route]

send_static_file(filename)

用于从 static_folder 提供文件的视图函数。如果设置了 static_folder,则会自动在此视图的 static_url_path 注册一个路由。

请注意,这是 Flask 类中同名方法的副本。

变更日志

0.5 版新增。

参数:

filename (str) –

返回类型:

响应

属性 static_folder: str | None

已配置的静态文件夹的绝对路径。如果未设置静态文件夹,则为 None

属性 static_url_path: str | None

静态路由可访问的 URL 前缀。

如果在 init 期间未配置,则从 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(),它将处理异常,而关闭不会接收它。

Teardown 函数必须避免引发异常。如果它们执行可能失败的代码,则必须用 try/except 块包围该代码并记录任何错误。

将忽略 teardown 函数的返回值。

这在应用和蓝图对象上都可用。当在应用上使用时,这将在每个请求后执行。当在蓝图上使用时,这将在蓝图处理的每个请求后执行。要使用蓝图注册并在每个请求后执行,请使用 Blueprint.teardown_app_request()

参数:

f (T_teardown) –

返回类型:

T_teardown

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() 装饰器。

此数据结构是内部的。不应直接修改它,并且其格式可能会随时更改。

template_folder

模板文件夹的路径,相对于 root_path,以添加到模板加载器中。如果不需要添加模板,则为 None

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

一个数据结构,其中包含在生成 URL 时调用以修改关键字参数的函数,格式为 {scope: [functions]}scope 键是函数处于活动状态的蓝图的名称,或所有请求的 None

要注册函数,请使用 url_defaults() 装饰器。

此数据结构是内部的。不应直接修改它,并且其格式可能会随时更改。

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

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

用于调用以修改传递到视图函数的关键字参数的数据结构,格式为 {scope: [functions]}scope 键是函数处于活动状态的蓝图的名称,或 None(表示所有请求)。

要注册函数,请使用 url_value_preprocessor() 装饰器。

此数据结构是内部的。不应直接修改它,并且其格式可能会随时更改。

view_functions: dict[str, ft.RouteCallable]

将端点名称映射到视图函数的字典。

要注册视图函数,请使用 route() 装饰器。

此数据结构是内部的。不应直接修改它,并且其格式可能会随时更改。

传入请求数据

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

Flask 中默认使用的请求对象。记住匹配的端点和视图参数。

最终成为 request 的内容。如果你想替换使用的请求对象,你可以对此进行子类化,并将 request_class 设置为你的子类。

请求对象是 Request 的子类,并提供 Werkzeug 定义的所有属性以及一些 Flask 特定的属性。

参数:
  • environ (WSGIEnvironment) –

  • populate_request (<bool) –

  • shallow (<bool) –

property accept_charsets: CharsetAccept

此客户端支持的字符集列表,作为 CharsetAccept 对象。

property accept_encodings: Accept

此客户端接受的编码列表。HTTP 术语中的编码是压缩编码,例如 gzip。对于字符集,请查看 accept_charset

property accept_languages: LanguageAccept

此客户端接受的语言列表,作为 LanguageAccept 对象。

property accept_mimetypes: MIMEAccept

此客户端支持的 MIME 类型列表,作为 MIMEAccept 对象。

access_control_request_headers

与预检请求一起发送,以指示将与跨域请求一起发送哪些标头。在响应中设置 access_control_allow_headers 以指示允许哪些标头。

access_control_request_method

与预检请求一起发送,以指示将为跨域请求使用哪种方法。在响应中设置 access_control_allow_methods 以指示允许哪些方法。

property access_route: list[str]

如果存在已转发的标头,则这是从客户端 IP 到最后一个代理服务器的所有 IP 地址的列表。

类方法 application(f)

将函数装饰为响应器,将请求作为最后一个参数接受。这与 responder() 装饰器类似,但函数将请求对象作为最后一个参数传递,并且请求对象将自动关闭

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

从 Werkzeug 0.14 开始,HTTP 异常会自动捕获并转换为响应,而不是失败。

参数:

f (t.Callable[[请求], WSGIApplication]) – 要装饰的 WSGI 可调用对象

返回:

一个新的 WSGI 可调用对象

返回类型:

WSGIApplication

属性 args: MultiDict[str, str]

已解析的 URL 参数(URL 中问号后面的部分)。

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

变更日志

在版本 2.3 中更改:无效的字节保持百分比编码。

属性 授权: 授权 |

授权 标头解析为 授权 对象。如果标头不存在,则为

变更日志

在版本 2.3 中更改:授权 不再是 dict。对于使用令牌而非参数的认证方案,添加了 令牌 属性。

属性 基本网址: str

网址 相同,但没有查询字符串。

属性 蓝图: str |

当前蓝图的已注册名称。

如果端点不属于蓝图,或者 URL 匹配失败或尚未执行,则此项为

这并不一定与创建蓝图时使用的名称相匹配。它可能已嵌套,或使用不同的名称注册。

属性 蓝图: 列表[字符串]

当前蓝图向上通过父蓝图注册的名称。

如果没有当前蓝图或 URL 匹配失败,则此项将为空列表。

变更日志

2.0.1 版本中的新增功能。

属性 缓存控制: RequestCacheControl

用于传入缓存控制标头的 RequestCacheControl 对象。

关闭()

关闭此请求对象的关联资源。这将显式关闭所有文件句柄。你也可以在 with 语句中使用请求对象,它将自动关闭请求对象。

变更日志

0.9 版中的新增功能。

返回类型:

内容编码

Content-Encoding 实体标头字段用作媒体类型的修饰符。如果存在,其值表示已对实体正文应用了哪些其他内容编码,因此必须应用哪些解码机制才能获取 Content-Type 标头字段引用的媒体类型。

变更日志

0.9 版中的新增功能。

属性 内容长度: 整数 |

Content-Length 实体标头字段表示实体正文的大小(以字节为单位),或者对于 HEAD 方法,表示如果请求是 GET,则会发送的实体正文的大小。

内容 MD5

Content-MD5 实体标头字段(如 RFC 1864 中所定义)是实体正文的 MD5 摘要,目的是提供实体正文的端到端消息完整性检查 (MIC)。(注意:MIC 适用于检测实体正文在传输过程中的意外修改,但不能防御恶意攻击。)

变更日志

0.9 版中的新增功能。

content_type

Content-Type 实体头字段表示发送给接收者的实体正文的媒体类型,或者在 HEAD 方法的情况下,表示如果请求是 GET,将发送的媒体类型。

属性 cookies: ImmutableMultiDict[str, str]

一个 dict,其中包含随请求传输的所有 cookie 的内容。

属性 data: bytes

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

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

date

Date 通用头字段表示生成消息的日期和时间,与 RFC 822 中的 orig-date 具有相同的语义。

变更日志

在版本 2.0 中更改:datetime 对象支持时区。

dict_storage_class

ImmutableMultiDict 的别名

属性 endpoint: str | None

与请求 URL 匹配的端点。

如果匹配失败或尚未执行,这将为 None

这与 view_args 结合使用,可用于重建相同的 URL 或修改后的 URL。

environ: WSGIEnvironment

包含 HTTP 标头和来自 WSGI 服务器的信息的 WSGI 环境。

属性 files: ImmutableMultiDict[str, FileStorage]

MultiDict 对象包含所有已上传的文件。 files 中的每个键都是 <input type="file" name=""> 中的名称。 files 中的每个值都是 Werkzeug FileStorage 对象。

它基本上像你从 Python 中了解的标准文件对象一样,不同之处在于它还具有 save() 函数,该函数可以将文件存储在文件系统上。

请注意, files 仅在请求方法为 POST、PUT 或 PATCH 且发布到请求的 <form> 具有 enctype="multipart/form-data" 时才包含数据。否则,它将为空。

有关所用数据结构的更多详细信息,请参阅 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),它允许创建 multipart 请求、支持 cookie 等。

它接受与 EnvironBuilder 相同的选项。

变更日志

0.5 版中已更改: 此方法现在接受与 EnvironBuilder 相同的参数。因此,environ 参数现在称为 environ_overrides

返回:

请求对象

参数:
  • args (Any) –

  • kwargs (Any) –

返回类型:

请求

property full_path: str

请求的路径,包括查询字符串。

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

这会将客户端的缓冲输入数据读入一个字节对象。默认情况下,这是缓存的,但可以通过将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 不支持的媒体类型响应。

参数:
  • force (bool) – 忽略 mimetype,并始终尝试解析 JSON。

  • silent (bool) – 不显示 mimetype 和解析错误,并返回 None

  • cache (bool) – 存储解析的 JSON,以供后续调用返回。

返回类型:

Any | None

变更日志

在版本 2.3 中更改: 引发 415 错误,而不是 400。

在版本 2.1 中更改: 如果内容类型不正确,则引发 400 错误。

headers

随请求一起接收到的标头。

property host: str

向其发出请求的主机名,包括非标准端口(如果存在)。使用 trusted_hosts 验证。

属性 host_url: str

仅请求 URL 方案和主机。

属性 if_match: ETags

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

返回类型:

ETags

属性 if_modified_since: datetime | None

解析后的 If-Modified-Since 标头作为 datetime 对象。

变更日志

在版本 2.0 中更改:datetime 对象支持时区。

属性 if_none_match: ETags

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

返回类型:

ETags

属性 if_range: IfRange

解析后的 If-Range 标头。

变更日志

2.0 版本中已更改:IfRange.date 具有时区感知。

0.7 版中的新增功能。

属性 if_unmodified_since: datetime | None

解析后的 If-Unmodified-Since 标头作为 datetime 对象。

变更日志

在版本 2.0 中更改:datetime 对象支持时区。

input_stream

原始 WSGI 输入流,没有任何安全检查。

使用此功能很危险。它不会防止无限流或读取超过 content_lengthmax_content_length

请改用 stream

property is_json: bool

检查 mimetype 是否指示 JSON 数据,即 application/jsonapplication/*+json

is_multiprocess

如果应用程序由生成多个进程的 WSGI 服务器提供服务,则为 True 的布尔值。

is_multithread

如果应用程序由多线程 WSGI 服务器提供服务,则为 True 的布尔值。

is_run_once

如果应用程序在进程生命周期中仅执行一次,则为 True 的布尔值。例如,CGI 就是这种情况,但不能保证仅执行一次。

property is_secure: bool

如果请求是通过安全协议(HTTPS 或 WSS)发出的,则为 True

属性 json: Any | None

如果 mimetype 指示 JSON(application/json,请参阅 is_json),则解析 JSON 数据。

使用默认参数调用 get_json()

如果请求内容类型不是 application/json,这会引发 415 不受支持的媒体类型错误。

变更日志

在版本 2.3 中更改: 引发 415 错误,而不是 400。

在版本 2.1 中更改: 如果内容类型不正确,则引发 400 错误。

list_storage_class

ImmutableList 的别名

make_form_data_parser()

创建表单数据解析器。使用一些参数实例化 form_data_parser_class

变更日志

0.8 版中的新增功能。

返回类型:

FormDataParser

属性 max_content_length: int | None

只读视图 MAX_CONTENT_LENGTH 配置键。

max_form_memory_size: int | None = None

最大表单字段大小。这会转发到表单数据解析函数 (parse_form_data())。当设置并访问 formfiles 属性,并且内存中的 POST 数据比指定值长时,会引发 RequestEntityTooLarge 异常。

变更日志

0.5 版新增。

max_form_parts = 1000

要解析的最大 multipart 部分数,传递给 form_data_parser_class。解析具有超过此部分数的表单数据将引发 RequestEntityTooLarge

变更日志

2.2.3 版中的新增功能。

max_forwards

Max-Forwards 请求头字段提供了一种机制,使用 TRACE 和 OPTIONS 方法来限制可以将请求转发到下一个入站服务器的代理或网关的数量。

method

请求所用的方法,例如 GET

property mimetype: str

类似于 content_type,但没有参数(例如,没有字符集、类型等),并且始终是小写。例如,如果内容类型是 text/HTML; charset=utf-8,则 mimetype 将是 'text/html'

property mimetype_params: dict[str, str]

mimetype 参数作为 dict。例如,如果内容类型是 text/html; charset=utf-8,则参数将是 {'charset': 'utf-8'}

on_json_loading_failed(e)

如果 get_json() 失败且未静默,则调用此方法。

如果此方法返回一个值,则将其用作 get_json() 的返回值。默认实现引发 BadRequest

参数:

e (ValueError | None) – 如果解析失败,则这是异常。如果内容类型不是 application/json,则它将为 None

返回类型:

任何

变更日志

在版本 2.3 中更改: 引发 415 错误,而不是 400。

origin

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

parameter_storage_class

ImmutableMultiDict 的别名

path

root_path 之后的 URL 的路径部分。这是用于在应用程序内路由的路径。

属性 pragma: HeaderSet

Pragma 通用标头字段用于包含可能适用于请求/响应链中任何接收者的特定于实现的指令。所有 pragma 指令都指定协议视点的可选行为;但是,某些系统可能要求行为与指令一致。

query_string

URL 中“?”之后的这部分。这是原始值,对于已解析的值,请使用 args

属性 range: Range | None

已解析的 Range 标头。

变更日志

0.7 版中的新增功能。

返回类型:

范围

referrer

Referer[sic] 请求标头字段允许客户端为服务器指定从中获取 Request-URI 的资源的地址 (URI)(“referrer”,尽管标头字段拼写错误)。

remote_addr

发送请求的客户端的地址。

remote_user

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

root_path

应用程序挂载在其下的前缀,没有尾随斜杠。 path 在此之后。

property root_url: str

请求 URL 方案、主机和根路径。这是应用程序被访问的根目录。

routing_exception: HTTPException | None = None

如果匹配 URL 失败,这是将作为请求处理的一部分引发/已引发的异常。这通常是 NotFound 异常或类似内容。

scheme

请求使用的协议的 URL 方案,例如 httpswss

property script_root: str

别名,用于 self.root_pathenviron["SCRIPT_ROOT"] 没有尾随斜杠。

server

服务器的地址。对于 Unix 套接字,(host, port)(path, None),或如果未知,则为 None

shallow: bool

在创建请求对象时设置。如果 True,从请求正文读取将导致 RuntimeException。有助于防止中间件修改流。

property stream: IO[bytes]

WSGI 输入流,带有安全检查。此流只能使用一次。

使用 get_data() 以字节或文本形式获取完整数据。data 属性将仅在它们不表示表单数据时包含完整的字节。在这种情况下,form 属性将包含已解析的表单数据。

input_stream 不同,此流可以防止无限流或读取超过 content_lengthmax_content_length 的内容。

如果设置了 max_content_length,如果设置了 wsgi.input_terminated,则可以在流上强制执行它。否则,将返回一个空流。

如果在底层流耗尽之前达到限制(例如文件太大或无限流),则无法安全地读取流的剩余内容。根据服务器处理此问题的方式,客户端可能会显示“连接重置”故障,而不是看到 413 响应。

变更日志

在版本 2.3 中更改: 预先检查 max_content_length,并在读取时检查。

在版本 0.9 中更改: 即使首先访问了表单解析,流也始终设置(但可能会被消耗)。

trusted_hosts: list[str] | None = None

处理请求时的有效主机名。默认情况下,所有主机都是受信任的,这意味着无论客户端所说的主机是什么,都将被接受。

由于 HostX-Forwarded-Host 标头可以被恶意客户端设置为任何值,因此建议设置此属性或在代理中实现类似的验证(如果应用程序在代理后面运行)。

变更日志

0.9 版中的新增功能。

property url: str

包含方案、主机、根路径、路径和查询字符串的完整请求 URL。

属性 url_root: str

root_url 的别名。具有方案、主机和根路径的 URL。例如,https://example.com/app/

url_rule: Rule | None = None

与请求匹配的内部 URL 规则。这有助于检查在请求前/后处理程序中允许哪些 URL 方法(request.url_rule.methods)等。不过,如果请求的方法对于 URL 规则无效,有效列表将出现在 routing_exception.valid_methods 中(Werkzeug 异常 MethodNotAllowed 的属性),因为请求从未在内部绑定。

变更日志

0.6 版中的新增内容。

属性 user_agent: UserAgent

用户代理。使用 user_agent.string 获取标头值。将 user_agent_class 设置为 UserAgent 的子类,以提供其他属性或其他扩展数据的解析。

变更日志

2.1 版中已更改:已移除内置解析器。将 user_agent_class 设置为 UserAgent 子类,以从字符串中解析数据。

user_agent_class

别名 UserAgent

属性 values: CombinedMultiDict[str, str]

werkzeug.datastructures.CombinedMultiDict,可合并 argsform

对于 GET 请求,仅存在 args,不存在 form

变更日志

2.0 版中已更改:对于 GET 请求,仅存在 args,不存在 form

view_args: dict[str, t.Any] | None = None

与请求匹配的视图参数的字典。如果在匹配时发生异常,这将为 None

property want_form_data_parsed: bool

True 如果请求方法携带内容。默认情况下,如果发送 Content-Type,则为 true。

变更日志

0.8 版中的新增功能。

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

参数:
accept_ranges

Accept-Ranges 标头。即使名称表明支持多个值,它也必须仅为一个字符串标记。

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

参数:
返回类型:

age

Age 响应头字段传达了发送方对从源服务器生成响应(或其重新验证)以来所经过时间的估计。

Age 值为非负十进制整数,表示以秒为单位的时间。

property allow: HeaderSet

Allow 实体头字段列出了由 Request-URI 标识的资源支持的方法集。此字段的目的是严格通知接收者与资源关联的有效方法。405(方法不允许)响应中必须存在 Allow 头字段。

autocorrect_location_header = False

如果重定向 Location 头是相对 URL,则将其设为绝对 URL,包括方案和域。

变更日志

版本 2.1 中已更改: 默认情况下禁用此功能,因此响应将发送相对重定向。

0.8 版中的新增功能。

automatically_set_content_length = True

如果可能,此响应对象是否应自动设置 content-length 头?默认情况下为 true。

变更日志

0.8 版中的新增功能。

属性 cache_control: ResponseCacheControl

Cache-Control 通用头字段用于指定请求/响应链中的所有缓存机制都必须遵守的指令。

calculate_content_length()

如果可用,则返回内容长度,否则返回 None

返回类型:

int | None

call_on_close(func)

将函数添加到内部函数列表中,该列表应作为关闭响应的一部分被调用。自 0.7 起,此函数还返回传递的函数,以便可以将其用作装饰器。

变更日志

0.6 版中的新增内容。

参数:

func (Callable[[], Any]) –

返回类型:

Callable[[], Any]

close()

如果可能,关闭包装的响应。你也可以在 with 语句中使用该对象,它会自动关闭它。

变更日志

0.9 版新增: 现在可以在 with 语句中使用。

返回类型:

content_encoding

Content-Encoding 实体标头字段用作媒体类型的修饰符。如果存在,其值表示已对实体正文应用了哪些其他内容编码,因此必须应用哪些解码机制才能获取 Content-Type 标头字段引用的媒体类型。

属性 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 适用于检测实体正文在传输过程中的意外修改,但不能防御恶意攻击。)

属性 content_range: ContentRange

Content-Range 标题作为 ContentRange 对象。即使未设置标题,也可以使用。

变更日志

0.7 版中的新增功能。

属性 content_security_policy: ContentSecurityPolicy

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

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

属性 content_security_policy_report_only: ContentSecurityPolicy

Content-Security-policy-report-only 标头作为 ContentSecurityPolicy 对象。即使未设置标头,也可以使用。

Content-Security-Policy-Report-Only 标头添加了一个未强制执行但会报告的 CSP 策略,从而有助于检测某些类型的攻击。

content_type

Content-Type 实体头字段表示发送给接收者的实体正文的媒体类型,或者在 HEAD 方法的情况下,表示如果请求是 GET,将发送的媒体类型。

cross_origin_embedder_policy

防止文档加载任何未明确授予文档权限的跨域资源。值必须是 werkzeug.http.COEP 枚举的成员。

cross_origin_opener_policy

允许控制与跨域文档共享浏览上下文组。值必须是 werkzeug.http.COOP 枚举的成员。

属性 data: bytes | str

调用 get_data()set_data() 的描述符。

date

Date 通用头字段表示生成消息的日期和时间,与 RFC 822 中的 orig-date 具有相同的语义。

变更日志

在版本 2.0 中更改:datetime 对象支持时区。

default_mimetype: str | None = 'text/html'

如果未提供,则为默认 mimetype。

default_status = 200

如果未提供,则为默认状态。

删除一个 cookie。如果 key 不存在,则静默失败。

参数:
  • key (str) – 要删除的 cookie 的键(名称)。

  • 路径 (str | ) – 如果应删除的 Cookie 限制在某个路径,则必须在此处定义该路径。

  • (str | ) – 如果应删除的 Cookie 限制在某个域,则必须在此处定义该域。

  • 安全 (bool) – 如果 True,则 Cookie 仅可通过 HTTPS 访问。

  • 仅限 HTTP (bool) – 禁止 JavaScript 访问 Cookie。

  • 同站 (str | ) – 将 Cookie 的范围限制为仅附加到“同站”请求。

返回类型:

直接传递

将响应主体直接作为 WSGI 可迭代对象传递。当主体是二进制文件或其他字节迭代器时,可以使用此方法来跳过一些不必要的检查。使用 send_file(),而不是手动设置此项。

过期

Expires 实体标头字段给出了响应被视为过时的日期/时间。过时的缓存条目通常不会由缓存返回。

变更日志

在版本 2.0 中更改:datetime 对象支持时区。

类方法 强制类型(响应, 环境=)

强制 WSGI 响应为当前类型的响应对象。Werkzeug 会在许多情况下在内部使用 Response,例如异常。如果您对异常调用 get_response(),您将获得一个常规 Response 对象,即使您使用的是自定义子类。

此方法可以强制执行给定的响应类型,如果提供了环境,它还将任意 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_conversiondirect_passthrough

  • 设置 Content-Length 标头。

  • 生成 ETag 标头(如果尚未设置)。

变更日志

在版本 2.1 中更改:删除了 no_etag 参数。

在版本 2.0 中更改:始终添加 ETag 标头。

在版本 0.6 中更改:设置 Content-Length 标头。

返回类型:

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)

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

如果请求方法是 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 以来,位置和内容位置标头中的 IRI 已得到妥善处理。

此外,从 0.6 开始,Werkzeug 将尝试在能够自行弄清楚的情况下设置内容长度。如果响应可迭代对象中的所有字符串已编码且可迭代对象已缓冲,则会出现这种情况。

参数:

environ (WSGIEnvironment) – 请求的 WSGI 环境。

返回:

返回一个新的 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/jsonapplication/*+json

property is_sequence: bool

如果迭代器已缓冲,则此属性将为 True。如果响应属性是列表或元组,则响应对象将认为迭代器已缓冲。

变更日志

0.6 版中的新增内容。

property is_streamed: bool

如果响应已流式传输(响应不是具有长度信息的 iterable),则此属性为 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 响应标头字段用于将接收者重定向到请求 URI 以外的位置,以完成请求或识别新资源。

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

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

如果请求或环境中的请求方法不是 GET 或 HEAD,则此方法不起作用。

为了在处理范围请求时获得最佳性能,建议您的响应数据对象实现 seekableseektell 方法,如 io.IOBase 所述。由 wrap_file() 返回的对象自动实现这些方法。

它不会移除响应的主体,因为这是 __call__() 函数自动为我们执行的操作。

返回自身,以便您可以执行 return resp.make_conditional(req),但会就地修改对象。

参数:
  • request_or_environ (WSGIEnvironment | Request) – 要用于使响应有条件地依赖于它的请求对象或 WSGI 环境。

  • accept_ranges (bool | str) – 此参数决定 Accept-Ranges 标头的值。如果 False(默认值),则不会设置标头。如果 True,则会将其设置为 "bytes"。如果它是一个字符串,则会使用此值。

  • complete_length (int | None) – 仅在有效的范围请求中使用。它将设置 Content-Range 完成长度值,并计算 Content-Length 实际值。此参数对于成功完成范围请求是必需的。

引发:

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

返回类型:

响应

变更日志

在版本 2.0 中更改: 如果长度为 0,则会跳过范围处理,而不是引发 416 范围无法满足错误。

make_sequence()

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

变更日志

0.6 版中的新增内容。

返回类型:

MAX_COOKIE_SIZE 配置键的只读视图。

请参阅 Werkzeug 文档中的 max_cookie_size

属性 mimetype: str | None

mimetype(不含字符集等的内容类型)

属性 mimetype_params: dict[str, str]

mimetype 参数作为 dict。例如,如果内容类型是 text/html; charset=utf-8,则参数将是 {'charset': 'utf-8'}

变更日志

0.5 版新增。

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

作为 WSGI 可迭代对象发送的响应正文。字符串或字节列表表示固定长度的响应,任何其他可迭代对象都是流式响应。字符串会编码为 UTF-8 字节。

不要将其设置为普通字符串或字节,这会导致发送响应非常低效,因为它会一次迭代一个字节。

属性 retry_after: datetime | None

Retry-After 响应头字段可与 503(服务不可用)响应一起使用,以指示服务预计对请求客户端不可用的时长。

到期时间或日期(以秒为单位)。

变更日志

在版本 2.0 中更改:datetime 对象支持时区。

设置 cookie。

如果 cookie 头的大小超过 max_cookie_size,则会发出警告,但仍会设置该头。

参数:
  • key (str) – 要设置的 cookie 的键(名称)。

  • value (str) – cookie 的值。

  • max_age (timedelta | int | None) – 应为秒数,或 None(默认值),如果 cookie 应仅持续到客户端的浏览器会话。

  • expires (str | datetime | int | float | None) – 应为 datetime 对象或 UNIX 时间戳。

  • path (str | None) – 将 cookie 限制到给定的路径,默认情况下它将跨越整个域。

  • domain (str | None) – 如果你想设置跨域 cookie。例如,domain="example.com" 将设置一个可由域 www.example.comfoo.example.com 等读取的 cookie。否则,cookie 将只能由设置它的域读取。

  • 安全 (bool) – 如果 True,则 Cookie 仅可通过 HTTPS 访问。

  • 仅限 HTTP (bool) – 禁止 JavaScript 访问 Cookie。

  • 同站 (str | ) – 将 Cookie 的范围限制为仅附加到“同站”请求。

返回类型:

set_data(value)

将新字符串设置为响应。该值必须是字符串或字节。如果设置了字符串,则将其编码为响应的字符集(默认情况下为 utf-8)。

变更日志

0.9 版中的新增功能。

参数:

value (bytes | str) –

返回类型:

set_etag(etag, weak=False)

设置 etag,如果之前有一个,则覆盖旧的 etag。

参数:
返回类型:

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

变更日志

在版本 2.3 中更改:可以将此属性分配给以设置标头。可以分配一个列表以设置多个标头值。使用 del 取消设置标头。

在版本 2.3 中更改:WWWAuthenticate 不再是 dict。添加了 token 属性,用于使用令牌而非参数进行身份验证的挑战。

会话

如果您已设置 Flask.secret_key(或从 SECRET_KEY 配置),则可以在 Flask 应用程序中使用会话。会话可以记住从一个请求到另一个请求的信息。Flask 执行此操作的方式是使用签名 cookie。用户可以查看会话内容,但除非他们知道密钥,否则无法修改它,因此请务必将其设置为复杂且无法猜测的内容。

要访问当前会话,可以使用 session 对象

class flask.session

会话对象的工作方式与普通 dict 非常类似,不同之处在于它会跟踪修改。

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

以下属性很有趣

new

True 如果会话是新的,False 否则。

modified

True 如果会话对象检测到修改。请注意,不会自动拾取可变结构上的修改,在这种情况下,您必须自己明确将属性设置为 True。这是一个示例

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

如果设置为 True,会话将持续 permanent_session_lifetime 秒。默认值为 31 天。如果设置为 False(这是默认值),当用户关闭浏览器时,会话将被删除。

会话接口

变更日志

0.8 版中的新增功能。

会话接口提供了一种简单的方法来替换 Flask 正在使用的会话实现。

class flask.sessions.SessionInterface

您必须实现的基本接口,以便替换使用 werkzeug 的 securecookie 实现的默认会话接口。您必须实现的唯一方法是 open_session()save_session(),其他方法具有您无需更改的有用默认值。

open_session() 方法返回的会话对象必须提供类似于字典的接口以及 SessionMixin 中的属性和方法。我们建议仅对字典进行子类化并添加该 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 版中的新增功能。

会话 cookie 上 Domain 参数的值。如果没有设置,浏览器将仅向其设置 cookie 的确切域发送 cookie。否则,它们也将将其发送到给定值的任何子域。

使用 SESSION_COOKIE_DOMAIN 配置。

变更日志

在 2.3 版中更改:默认情况下未设置,不会回退到 SERVER_NAME

参数:

app (Flask) –

返回类型:

str | None

如果会话 cookie 应为 httponly,则返回 True。当前仅返回 SESSION_COOKIE_HTTPONLY 配置变量的值。

参数:

app (Flask) –

返回类型:

bool

会话 cookie 的名称。使用 ``app.config[“SESSION_COOKIE_NAME”]``。

参数:

app (Flask) –

返回类型:

str

返回 cookie 应有效的路径。默认实现使用 SESSION_COOKIE_PATH 配置变量中的值(如果已设置),并回退到 APPLICATION_ROOT 或使用 /(如果为 None)。

参数:

app (Flask) –

返回类型:

str

如果 cookie 应使用 SameSite 属性,则返回 'Strict''Lax'。当前仅返回 SESSION_COOKIE_SAMESITE 设置的值。

参数:

app (Flask) –

返回类型:

str | None

如果 cookie 应该是安全的,则返回 True。这当前仅返回 SESSION_COOKIE_SECURE 设置的值。

参数:

app (Flask) –

返回类型:

bool

get_expiration_time(app, session)

一个帮助程序方法,如果会话链接到浏览器会话,则返回会话的到期日期,否则返回 None。默认实现返回现在 + 在应用程序上配置的永久会话生命周期。

参数:
返回类型:

datetime | None

is_null_session(obj)

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

默认情况下,这会检查对象是否为 null_session_class 的实例。

参数:

obj (object) –

返回类型:

bool

make_null_session(app)

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

默认情况下,这会创建一个 null_session_class 实例。

参数:

app (Flask) –

返回类型:

NullSession

null_session_class

make_null_session() 将在此处查找在请求空会话时应创建的类。同样,is_null_session() 方法将针对此类型执行类型检查。

NullSession 的别名

open_session(app, request)

在每个请求的开头调用此方法,在推送请求上下文后,在匹配 URL 之前。

此方法必须返回一个实现类字典接口以及SessionMixin 接口的对象。

此方法将返回None以指示加载以某种方式失败,但不是立即错误。在这种情况下,请求上下文将回退到使用make_null_session()

参数:
返回类型:

SessionMixin | None

pickle_based = False

指示会话接口是否基于 pickle 的标志。Flask 扩展可以使用此标志来决定如何处理会话对象。

变更日志

0.10 版新增。

save_session(app, session, response)

在生成响应后、删除请求上下文之前,在每个请求的末尾调用此方法。如果 is_null_session() 返回 True,则跳过此方法。

参数:
返回类型:

会话后端使用此方法来确定是否应该为该响应的会话 Cookie 设置 Set-Cookie 标头。如果会话已修改,则设置 Cookie。如果会话是永久的,并且 SESSION_REFRESH_EACH_REQUEST 配置为 true,则始终设置 Cookie。

如果会话已删除,则通常跳过此检查。

变更日志

0.11 版本中的新增功能。

参数:
返回类型:

bool

class flask.sessions.SecureCookieSessionInterface

默认会话接口,通过 itsdangerous 模块将会话存储在已签名的 Cookie 中。

static digest_method(string=b'', *, usedforsecurity=True)

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

key_derivation = 'hmac'

itsdangerous 支持的关键派生的名称。默认值为 hmac。

open_session(app, request)

在每个请求的开头调用此方法,在推送请求上下文后,在匹配 URL 之前。

此方法必须返回一个实现类字典接口以及SessionMixin 接口的对象。

这将返回 None 以指示加载以某种方式失败,但不是立即错误。在这种情况下,请求上下文将回退到使用 make_null_session()

参数:
返回类型:

SecureCookieSession | None

salt = 'cookie-session'

应在基于 cookie 的会话签名的密钥上应用的盐。

save_session(app, session, response)

在生成响应后,在删除请求上下文之前,在每个请求的末尾调用此方法。如果 is_null_session() 返回 True,则跳过此方法。

参数:
返回类型:

serializer = <flask.json.tag.TaggedJSONSerializer object>

有效负载的 Python 序列化器。默认值是紧凑的 JSON 派生序列化器,支持一些额外的 Python 类型,例如 datetime 对象或元组。

session_class

SecureCookieSession 的别名

class flask.sessions.SecureCookieSession(initial=None)

基于签名 cookie 的会话的基类。

此会话后端将设置 modifiedaccessed 属性。它无法可靠地跟踪会话是新的(相对于空的),因此 new 仍然硬编码为 False

参数:

initial (t.Any) –

accessed = False

标头,允许缓存代理为不同的用户缓存不同的页面。

get(key, default=None)

如果 key 在字典中,则返回 key 的值,否则返回 default。

参数:
  • key (str) –

  • default (Any) –

返回类型:

任何

modified = False

当数据发生更改时,此项将设为 True。仅跟踪会话字典本身;如果会话包含可变数据(例如嵌套字典),则在修改该数据时必须手动将其设为 True。仅当此项为 True 时,会话 Cookie 才会写入响应。

setdefault(key, default=None)

如果 key 不在字典中,则插入 key,其值为 default。

如果 key 在字典中,则返回 key 的值,否则返回 default。

参数:
  • key (str) –

  • default (Any) –

返回类型:

任何

flask.sessions.NullSession(initial=None)

如果会话不可用,则用于生成更友好的错误消息的类。仍将允许只读访问空会话,但在设置时会失败。

参数:

initial (t.Any) –

clear() None.  D 中删除所有项目。
参数:
  • args (Any) –

  • kwargs (Any) –

返回类型:

NoReturn

pop(k[, d]) v, 删除指定的键并返回相应的值。

如果找不到该键,则返回给定的默认值;否则,引发 KeyError。

参数:
  • args (Any) –

  • kwargs (Any) –

返回类型:

NoReturn

popitem(*args, **kwargs)

删除并返回一个 (key, value) 对,作为 2 元组。

对以 LIFO(后进先出)顺序返回。如果字典为空,则引发 KeyError。

参数:
  • args (Any) –

  • kwargs (Any) –

返回类型:

NoReturn

setdefault(*args, **kwargs)

如果 key 不在字典中,则插入 key,其值为 default。

如果 key 在字典中,则返回 key 的值,否则返回 default。

参数:
  • args (Any) –

  • kwargs (Any) –

返回类型:

NoReturn

update([E, ]**F) None.  dict/iterable E F 更新 D

如果 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) –

返回类型:

NoReturn

flask.sessions.SessionMixin

使用会话属性扩展基本词典。

accessed = True

某些实现可以检测会话数据何时被读取或写入,并在发生这种情况时设置此项。mixin 默认值硬编码为 True

modified = True

某些实现可以检测会话的更改,并在发生这种情况时设置此项。mixin 默认值硬编码为 True

property permanent: bool

这反映了字典中的 '_permanent' 键。

注意

PERMANENT_SESSION_LIFETIME 配置可以是整数或 timedeltapermanent_session_lifetime 属性始终是 timedelta

测试客户端

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

它的工作原理与常规 Werkzeug 测试客户端类似,但了解 Flask 的上下文,以便将请求上下文的清理推迟到 with 块结束时。有关如何使用此类的常规信息,请参阅 werkzeug.test.Client

变更日志

0.12 版中已更改:app.test_client() 包含预设的默认环境,可以在 client.environ_baseapp.test_client() 对象实例化后进行设置。

基本用法在 Testing Flask Applications 章节中概述。

参数:
  • args (t.Any) –

  • kwargs (t.Any) –

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

根据给定的参数生成 environ 字典,使用它向应用程序发出请求,并返回响应。

参数:
  • args (t.Any) – 传递给 EnvironBuilder 以创建请求的 environ。如果传递了一个单独的参数,它可以是现有的 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 参数。

session_transaction(*args, **kwargs)

当与 with 语句结合使用时,这将打开一个会话事务。这可用于修改测试客户端使用的会话。一旦离开 with 块,会话就会被存储回。

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

在内部,这是通过一个临时的测试请求上下文实现的,并且由于会话处理可能依赖于请求变量,因此此函数接受与 test_request_context() 相同的参数,这些参数直接传递。

参数:
  • args (Any) –

  • kwargs (Any) –

返回类型:

Iterator[SessionMixin]

测试 CLI 运行器

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

用于测试 Flask 应用程序的 CLI 命令的 CliRunner。通常使用 test_cli_runner() 创建。请参阅 使用 CLI Runner 运行命令

参数:
  • app (Flask) –

  • kwargs (t.Any) –

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

在隔离环境中调用 CLI 命令。请参阅 CliRunner.invoke 以获取完整的函数文档。请参阅 使用 CLI Runner 运行命令 以获取示例。

如果未提供 obj 参数,则传递 ScriptInfo 的实例,该实例知道如何加载正在测试的 Flask 应用程序。

参数:
  • cli (Any) – 要调用的命令对象。默认为应用程序的 cli 组。

  • args (Any) – 用于调用命令的字符串列表。

  • kwargs (Any) –

返回:

一个 Result 对象。

返回类型:

任何

应用程序全局变量

要从一个函数共享仅对一个请求有效的 data,全局变量是不够的,因为它会在线程环境中中断。Flask 为你提供了一个特殊对象,确保它仅对活动请求有效,并且会为每个请求返回不同的值。简而言之:它会执行正确操作,就像它对 requestsession 所做的那样。

flask.g

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

这是一个在请求期间存储资源的好地方。例如,before_request 函数可以从会话 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=<object object>)

按名称获取并删除属性。类似于 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

或者,你还可以测试任何上下文绑定对象(例如 requestg)的真值

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 将具有此方案(如果它是外部的)。

  • _external (bool | None) – 如果给出,则优先将 URL 设置为内部 (False) 或要求它为外部 (True)。外部 URL 包括方案和域。当不在活动请求中时,URL 默认情况下为外部。

  • values (Any) – 用于 URL 规则的可变部分的值。未知的键将附加为查询字符串参数,如 ?a=b&c=d

返回类型:

str

变更日志

在 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) – 传递给异常。

返回类型:

NoReturn

变更日志

2.2 版中的新增功能: 如果可用,则调用 current_app.aborter,而不是始终使用 Werkzeug 的默认 abort

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

创建一个重定向响应对象。

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

参数:
  • location (str) – 要重定向到的 URL。

  • code (int) – 重定向的状态代码。

  • 响应 (type[Response] | None) – 要使用的响应类。当 current_app 处于活动状态时不使用,它使用 app.response_class

返回类型:

响应

变更日志

2.2 版新增: 如果可用,调用 current_app.redirect,而不是始终使用 Werkzeug 的默认 redirect

flask.make_response(*args)

有时需要在视图中设置其他标头。由于视图不必返回响应对象,但可以返回一个由 Flask 本身转换为响应对象的值,因此向其中添加标头变得很棘手。可以调用此函数而不是使用返回,您将获得一个响应对象,可用于附加标头。

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

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'

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

变更日志

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 ( | (int | t.Callable[[str | ], int | ])) – 客户端应缓存文件的时间(以秒为单位)。如果设置,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 参数。它可以是一个字符串,用于代替生成一个字符串。

在 2.0 版中更改: 传递继承自 TextIOBase 的类文件对象将引发 ValueError,而不是发送空文件。

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

在 1.1 版中更改: filename 可以是 PathLike 对象。

在 1.1 版中更改: 传递 BytesIO 对象支持范围请求。

在版本 1.0.3 中更改: 文件名使用 ASCII 编码,而不是 Latin-1,以与 WSGI 服务器更广泛地兼容。

在版本 1.0 中更改: 支持 UTF-8 文件名,如 RFC 2231 中所述。

在版本 0.12 中更改: 不再从文件对象自动推断文件名。如果您想使用自动 MIME 和 etag 支持,请通过 filename_or_fpattachment_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_etagscache_timeoutconditional 参数。默认行为是添加 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' 表示警告。但是,任何类型的字符串都可以用作类别。

返回类型:

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

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

通过在 category_filter 中提供那些类别,将闪现的消息过滤到一个或多个类别。这允许在单独的 html 块中呈现类别。 with_categoriescategory_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_classflask.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,并返回一个 MIME 类型为 application/jsonResponse 对象。从视图返回的字典或列表将自动转换为 JSON 响应,无需调用此方法。

这需要一个活动请求或应用程序上下文,并调用 app.json.response()

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

可以给出位置参数或关键字参数,但不能同时给出。如果未给出任何参数,则序列化 None

参数:
  • args (t.Any) – 要序列化的单个值,或要作为要序列化的列表处理的多个值。

  • kwargs (t.Any) – 视为要序列化的字典。

返回类型:

响应

变更日志

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

返回类型:

str

变更日志

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

返回类型:

变更日志

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 中更改: 在 Flask 2.3 中将删除 app 参数。

在版本 2.0 中更改: 在 Flask 2.1 中将删除 encoding。文件必须为文本模式或带有 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 库。

返回类型:

str

dump(obj, fp, **kwargs)

将数据序列化为 JSON 并写入文件。

参数:
  • obj (Any) – 要序列化的数据。

  • fp (IO[str]) – 用于写入文本的已打开文件。应使用 UTF-8 编码成为有效的 JSON。

  • kwargs (Any) – 可以传递给底层 JSON 库。

返回类型:

loads(s, **kwargs)

将数据反序列化为 JSON。

参数:
  • s (str | bytes) – 文本或 UTF-8 字节。

  • kwargs (Any) – 可以传递给底层 JSON 库。

返回类型:

任何

load(fp, **kwargs)

将从文件读取的数据反序列化为 JSON。

参数:
  • fp (IO) – 用于读取文本或 UTF-8 字节的文件。

  • kwargs (Any) – 可以传递给底层 JSON 库。

返回类型:

任何

response(*args, **kwargs)

将给定参数序列化为 JSON,并返回具有 application/json mimetype 的 Response 对象。

jsonify() 函数为当前应用程序调用此方法。

可以给出位置参数或关键字参数,但不能同时给出。如果未给出任何参数,则序列化 None

参数:
  • args (t.Any) – 要序列化的单个值,或要作为要序列化的列表处理的多个值。

  • kwargs (t.Any) – 视为要序列化的字典。

返回类型:

响应

class flask.json.provider.DefaultJSONProvider(app)

使用 Python 的内置 json 库提供 JSON 操作。序列化以下附加数据类型

参数:

app (App) –

static default(o)

将此函数应用于 json.dumps() 无法序列化的任何对象。它应返回一个有效的 JSON 类型或引发 TypeError

参数:

o (Any) –

返回类型:

任何

ensure_ascii = True

使用转义序列替换非 ASCII 字符。这可能与某些客户端更兼容,但可以禁用以提高性能和大小。

sort_keys = True

对任何已序列化的字典中的键进行排序。这可能对某些缓存情况有用,但可以禁用以提高性能。启用后,键必须全部为字符串,在排序前不会对其进行转换。

compact: bool | None = None

如果 True,或在调试模式外为 None,则 response() 输出不会添加缩进、换行符或空格。如果 False,或在调试模式中为 None,它将使用非紧凑表示形式。

mimetype = 'application/json'

response() 中设置的 MIME 类型。

dumps(obj, **kwargs)

将数据序列化为 JSON 字符串。

关键字参数传递给 json.dumps()。从 defaultensure_asciisort_keys 属性设置一些参数默认值。

参数:
返回类型:

str

loads(s, **kwargs)

从字符串或字节中反序列化数据为 JSON。

参数:
返回类型:

任何

response(*args, **kwargs)

将给定的参数序列化为 JSON,并返回一个包含它的 Response 对象。响应 mimetype 将为 “application/json”,可以使用 mimetype 更改。

如果 compactFalse 或启用调试模式,输出将被格式化为更易于阅读。

可以给出位置参数或关键字参数,但不能同时给出。如果未给出任何参数,则序列化 None

参数:
  • args (t.Any) – 要序列化的单个值,或要作为要序列化的列表处理的多个值。

  • kwargs (t.Any) – 视为要序列化的字典。

返回类型:

响应

标记的 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() 稍后添加其他标签。

dumps(value)

标记值并将其转储为紧凑的 JSON 字符串。

参数:

value (Any) –

返回类型:

str

loads(value)

从 JSON 字符串加载数据并反序列化任何标记对象。

参数:

value (str) –

返回类型:

任何

register(tag_class, force=False, index=None)

向此序列化器注册一个新标签。

参数:
  • tag_class (type[JSONTag]) – 要注册的标签类。将使用此序列化器实例对其进行实例化。

  • force (bool) – 覆盖现有标签。如果为 false(默认),则引发 KeyError

  • index (int | None) – 在标签顺序中插入新标签的索引。当新标签是现有标签的特例时很有用。如果 None(默认),则将标签追加到顺序的末尾。

引发:

KeyError – 如果标签键已注册且 force 不为 true。

返回类型:

tag(value)

必要时将值转换为标记表示形式。

参数:

value (Any) –

返回类型:

任何

untag(value)

将标记表示形式转换回原始类型。

参数:

value (dict[str, Any]) –

返回类型:

任何

class flask.json.tag.JSONTag(serializer)

TaggedJSONSerializer 定义类型标签的基本类。

参数:

serializer (TaggedJSONSerializer) –

check(value)

检查给定值是否应由该标签标记。

参数:

value (Any) –

返回类型:

bool

key: str = ''

用于标记序列化对象的标签。如果为空,则此标签仅用作标记期间的中间步骤。

tag(value)

将值转换为有效的 JSON 类型,并在其周围添加标签结构。

参数:

value (Any) –

返回类型:

dict[str, Any]

to_json(value)

将 Python 对象转换为有效的 JSON 类型的对象。标签将在稍后添加。

参数:

value (Any) –

返回类型:

任何

to_python(value)

将 JSON 表示转换回正确的类型。标签将已被移除。

参数:

value (Any) –

返回类型:

任何

我们来看一个添加对 OrderedDict 支持的示例。字典在 JSON 中没有顺序,因此为了处理此问题,我们将把项目转储为 [key, value] 对的列表。子类化 JSONTag 并为其提供新键 'od' 以标识类型。会话序列化器首先处理字典,因此将新标签插入到顺序的前面,因为 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) – 可在模板中使用的变量。

返回类型:

str

flask.render_template_string(source, **context)

使用给定的上下文从给定的源字符串呈现模板。

参数:
  • source (str) – 要呈现的模板的源代码。

  • context (Any) – 可在模板中使用的变量。

返回类型:

str

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 如果文件加载成功。

返回类型:

bool

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) – 如果文件不存在,则忽略该文件。

  • 文本 (布尔值) – 以文本或二进制模式打开文件。

返回:

True 如果文件加载成功。

返回类型:

bool

变更日志

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

2.0 版中的新增功能。

from_mapping(mapping=, **kwargs)

更新配置,类似于 update(),忽略非大写键的项。

返回:

始终返回 True

参数:
返回类型:

bool

变更日志

0.11 版本中的新增功能。

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) – 导入名称或对象

返回类型:

from_prefixed_env(prefix='FLASK', *, loads=<function loads>)

加载以 FLASK_ 开头的任何环境变量,从环境键中删除前缀以获取配置键。值通过加载函数传递,以尝试将它们转换为比字符串更具体的类型。

键按 sorted() 顺序加载。

默认加载函数尝试将值解析为任何有效的 JSON 类型,包括字典和列表。

可以通过使用双下划线 (__) 分隔键来设置嵌套字典中的特定项。如果中间键不存在,它将被初始化为空字典。

参数:
  • prefix (str) – 加载以此前缀开头、用下划线 (_) 分隔的环境变量。

  • loads (Callable[[str], Any]) – 将每个字符串值传递给此函数,并将返回值用作配置值。如果引发任何错误,则忽略该错误,并且该值仍然是字符串。默认值为 json.loads()

返回类型:

bool

变更日志

2.1 版中的新增内容。

from_pyfile(filename, silent=False)

使用 Python 文件更新配置中的值。此函数的行为就像使用 from_object() 函数将文件导入为模块一样。

参数:
  • filename (str | PathLike[str]) – 配置的文件名。这可以是绝对文件名,也可以是相对于根路径的文件名。

  • silent (bool) – 如果希望在文件缺失时静默失败,则设置为 True

返回:

True 如果文件加载成功。

返回类型:

bool

变更日志

0.7 版中的新增内容: silent 参数。

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)

当服务器上启动响应时,请求上下文就会消失。这样做是为了提高效率,并降低遇到编写不当的 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 版中的新增功能。

参数:

generator_or_function (Iterator | Callable[[...], Iterator]) –

返回类型:

迭代器

有用的内部

class flask.ctx.RequestContext(app, environ, request=None, session=None)

请求上下文包含每个请求的信息。Flask 应用程序在请求开始时创建并推送它,然后在请求结束时将其弹出。它将为提供的 WSGI 环境创建 URL 适配器和请求对象。

不要尝试直接使用此类,而是使用 test_request_context()request_context() 来创建此对象。

当请求上下文被弹出时,它将对应用程序上注册的所有函数进行评估以执行销毁 (teardown_request())。

请求上下文在请求结束时自动弹出。使用交互式调试器时,上下文将被还原,因此仍然可以访问 request。类似地,测试客户端可以在请求结束后保留上下文。但是,销毁函数可能已经关闭了一些资源,例如数据库连接。

参数:
copy()

使用相同的请求对象创建此请求上下文的副本。这可用于将请求上下文移动到不同的 greenlet。因为实际的请求对象相同,所以这不能用于将请求上下文移动到不同的线程,除非对请求对象的访问被锁定。

变更日志

在版本 1.1 中更改:使用当前会话对象,而不是重新加载原始数据。这可以防止 flask.session 指向过时的对象。

0.10 版新增。

返回类型:

RequestContext

match_request()

可以由子类覆盖以挂接到请求匹配。

返回类型:

pop(exc=<object object>)

弹出请求上下文并通过执行此操作取消其绑定。这还将触发由 teardown_request() 装饰器注册的函数的执行。

变更日志

在版本 0.9 中更改:添加了 exc 参数。

参数:

exc (BaseException | None) –

返回类型:

flask.globals.request_ctx

当前的 RequestContext。如果请求上下文未处于活动状态,则访问此代理上的属性将引发 RuntimeError

这是一个内部对象,对于 Flask 处理请求至关重要。在大多数情况下,不需要访问它。您很可能需要 requestsession

class flask.ctx.AppContext(app)

应用程序上下文包含应用程序特定的信息。如果尚未处于活动状态,则在每个请求开始时都会创建并推送应用程序上下文。在运行 CLI 命令时也会推送应用程序上下文。

参数:

app (Flask) –

pop(exc=<object object>)

弹出应用程序上下文。

参数:

exc (BaseException | None) –

返回类型:

push()

将应用程序上下文绑定到当前上下文。

返回类型:

flask.globals.app_ctx

当前 AppContext。如果应用程序上下文未处于活动状态,则访问此代理上的属性将引发 RuntimeError

这是一个内部对象,对于 Flask 处理请求至关重要。在大多数情况下,不需要访问它。您很可能需要 current_appg

class flask.blueprints.BlueprintSetupState(blueprint, app, options, first_registration)

用于向应用程序注册蓝图的临时持有者对象。此类的实例由 make_setup_state() 方法创建,并随后传递给所有注册回调函数。

参数:
  • blueprint (Blueprint) –

  • app (App) –

  • options (t.Any) –

  • first_registration (bool) –

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

一个帮助程序方法,用于向应用程序注册规则(以及可选的视图函数)。端点自动加上蓝图的名称前缀。

参数:
  • rule (str) –

  • endpoint (str | None) –

  • view_func (ft.RouteCallable | None) –

  • options (t.Any) –

返回类型:

app

当前应用程序的引用

blueprint

创建此设置状态的蓝图的引用。

first_registration

由于蓝图可以多次向应用程序注册,并且并非所有内容都希望在其中多次注册,因此可以使用此属性来确定蓝图是否已在过去注册。

options

一个字典,其中包含传递给 register_blueprint() 方法的所有选项。

subdomain

蓝图应该为此激活的子域名,否则为 None

url_defaults

一个字典,其中包含 URL 默认值,这些默认值会添加到蓝图定义的每个 URL 中。

url_prefix

应用于蓝图中定义的所有 URL 的前缀。

信号

信号由 Blinker 库提供。有关简介,请参阅 Signals

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 上存储请求全局数据。

类方法 as_view(名称, *类参数, **类关键字参数)

将类转换为可为路由注册的视图函数。

默认情况下,生成的视图将为每个请求创建视图类的实例,并调用其 dispatch_request() 方法。如果视图类将 init_every_request 设置为 False,则每个请求将使用相同的实例。

除了 名称 外,传递给此方法的所有其他参数都将转发到视图类 __init__ 方法。

变更日志

在版本 2.2 中更改:添加了 init_every_request 类属性。

参数:
  • 名称 (str) –

  • 类参数 (t.Any) –

  • 类关键字参数 (t.Any) –

返回类型:

ft.RouteCallable

装饰器: ClassVar[列表[可调用[[F], F]]] = []

要应用于生成的视图函数的装饰器列表,按顺序排列。请记住,@装饰器 语法从下到上应用,因此列表中的第一个装饰器将是底层装饰器。

变更日志

0.8 版中的新增功能。

dispatch_request()

实际视图函数行为。子类必须覆盖此函数并返回有效的响应。URL 规则中的任何变量都作为关键字参数传递。

返回类型:

ft.ResponseReturnValue

init_every_request: ClassVar[bool] = True

默认情况下,为每个请求创建此视图类的实例。如果视图子类将此项设置为 False,则对每个请求使用相同的实例。

单个实例效率更高,尤其是在初始化期间完成复杂设置时。但是,在 self 上存储数据在请求之间不再安全,而应使用 g

变更日志

2.2 版中的新增功能。

methods: ClassVar[Collection[str] | None] = None

此视图注册的方法。使用与 routeadd_url_rule 相同的默认值(["GET", "HEAD", "OPTIONS"])。

provide_automatic_options: ClassVar[bool | None] = None

控制 OPTIONS 方法是否自动处理。默认情况下使用与 routeadd_url_rule 相同的默认值(True)。

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 路由注册

通常有三种方法可以为路由系统定义规则

  1. 你可以使用 flask.Flask.route() 装饰器。

  2. 你可以使用 flask.Flask.add_url_rule() 函数。

  3. 你可以直接访问底层的 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 的唯一性,因此适用以下规则

  1. 如果规则以斜杠结尾,而用户在请求时未带斜杠,则会自动将用户重定向到附加了尾部斜杠的同一页面。

  2. 如果规则未以尾部斜杠结尾,而用户请求的页面带有尾部斜杠,则会引发 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/。如果你的路由处理 GETPOST 请求,请确保默认路由仅处理 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 字典中(以端点作为键)来稍后指定该函数。

默认值

此规则的默认值词典。请参阅上面的示例,了解默认值的工作原理。

子域

如果使用子域匹配,则指定子域的规则。如果未指定,则假定为默认子域。

**选项

要转发到底层 Rule 对象的选项。Werkzeug 的更改处理方法选项。methods 是此规则应限于的方法列表 (GETPOST 等)。默认情况下,规则只侦听 GET(隐式地侦听 HEAD)。从 Flask 0.6 开始,OPTIONS 由标准请求处理隐式添加并处理。它们必须指定为关键字参数。

视图函数选项

对于内部使用,视图函数可以附加一些属性以自定义视图函数通常无法控制的行为。可以按选择提供以下属性,以覆盖 add_url_rule() 的一些默认值或一般行为

  • __name__:默认情况下,函数的名称用作端点。如果明确提供端点,则使用此值。此外,这将默认情况下以蓝图的名称为前缀,而无法从函数本身自定义。

  • methods:如果在添加 URL 规则时未提供 methods,Flask 将在视图函数对象本身上查找是否存在 methods 属性。如果存在,它将从中提取方法的信息。

  • provide_automatic_options:如果设置此属性,Flask 将强制启用或禁用 HTTP OPTIONS 响应的自动实现。当使用想要在每个视图的基础上自定义 OPTIONS 响应的装饰器时,这非常有用。

  • required_methods:如果设置此属性,Flask 将在注册 URL 规则时始终添加这些方法,即使在 route() 调用中显式覆盖了这些方法。

完整示例

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)

支持从配置的 Flask 应用程序加载更多命令的 AppGroup 组的特殊子类。通常情况下,开发人员不必与该类进行交互,但有一些非常高级的用例,对于这些用例,创建该类的实例是有意义的。请参阅 自定义脚本

参数:
  • 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) –

变更日志

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

参数:
返回类型:

Command | None

list_commands(ctx)

返回子命令名称列表,按应显示的顺序排列。

参数:

ctx (Context) –

返回类型:

list[str]

make_context(info_name, args, parent=None, **extra)

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

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

参数:
  • info_name (str | None) – 此调用的信息名称。通常这是脚本或命令的最具描述性的名称。对于顶级脚本,它通常是脚本的名称,对于其下的命令,它是命令的名称。

  • args (list[str]) – 要解析为字符串列表的参数。

  • parent (Context | None) – 可用的父上下文(如果存在)。

  • extra (Any) – 转发到上下文构造函数的其他关键字参数。

返回类型:

Context

版本 8.0 中已更改: 添加了 context_class 属性。

parse_args(ctx, args)

给定上下文和参数列表,这将创建解析器并解析参数,然后根据需要修改上下文。这由 make_context() 自动调用。

参数:
返回类型:

list[str]

class flask.cli.AppGroup(name=None, commands=None, **attrs)

这与常规点击 Group 类似,但它改变了 command() 装饰器的行为,以便它自动将函数包装在 with_appcontext() 中。

不要与 FlaskGroup 混淆。

参数:
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]

flask.cli.ScriptInfo(app_import_path=, create_app=, set_debug_flag=)

处理 Flask 应用程序的帮助器对象。通常不需要与之交互,因为它在内部用于分派到 click。在 Flask 的未来版本中,此对象很可能将发挥更大的作用。通常,它由 FlaskGroup 自动创建,但您也可以手动创建它并将其作为 click 对象传递。

参数:
  • app_import_path (str | ) –

  • create_app (t.Callable[..., Flask] | ) –

  • set_debug_flag (bool) –

app_import_path

Flask 应用程序的导入路径(可选)。

create_app

一个可选函数,将脚本信息传递给它以创建应用程序实例。

data: dict[t.Any, t.Any]

一个字典,其中包含可与此脚本信息关联的任意数据。

load_app()

加载 Flask 应用(如果尚未加载)并返回它。多次调用此方法只会返回已加载的应用。

返回类型:

Flask

flask.cli.load_dotenv(path=None)

按优先级加载“dotenv”文件以设置环境变量。

如果已设置环境变量,则不会覆盖它,因此列表中较早的文件优先于较晚的文件。

如果未安装 python-dotenv,则此方法无效。

参数:

path (str | PathLike[str] | None) – 加载此位置的文件,而不是进行搜索。

返回:

True,如果加载了文件。

返回类型:

bool

变更日志

在版本 2.0 中更改: 当前目录不会更改为加载的文件的位置。

在版本 2.0 中更改: 加载环境文件时,将默认编码设置为 UTF-8。

在版本 1.1.0 中更改: 当未安装 python-dotenv 或给定路径不是文件时,返回 False

1.0 版中的新增功能。

flask.cli.with_appcontext(f)

包装回调,以确保它在脚本的应用程序上下文中执行。

app.cliblueprint.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) –

返回类型:

任何