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_matching
和static_host
参数。1.0 版新增: 添加了
subdomain_matching
参数。现在需要手动启用子域匹配。设置SERVER_NAME
不会隐式启用它。0.11 版新增: 添加了 root_path 参数。
0.8 版新增: 添加了 instance_path 和 instance_relative_config 参数。
0.7 版新增: 添加了 static_url_path、static_folder 和 template_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
移出。
- add_template_filter(f, name=None)¶
注册自定义模板过滤器。与
template_filter()
装饰器的工作方式完全相同。
- add_template_global(f, name=None)¶
注册自定义模板全局函数。与
template_global()
装饰器的工作方式完全相同。变更日志
0.10 版新增。
- add_template_test(f, name=None)¶
注册自定义模板测试。与
template_test()
装饰器的工作方式完全相同。变更日志
0.10 版新增。
- 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
属性,则在未传递参数时使用该属性作为默认值。
- 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 版中的新增功能。
- 返回类型:
- app_ctx_globals_class¶
_AppCtxGlobals
的别名
- async_to_sync(func)¶
返回一个将运行协程函数的同步函数。
result = app.async_to_sync(func)(*args, **kwargs)
覆盖此方法以更改应用程序将异步代码转换为同步可调用方式。
变更日志
2.0 版中的新增功能。
- auto_find_instance_path()¶
如果未向应用程序类的构造函数提供实例路径,则尝试查找该路径。它基本上会计算一个名为
instance
的文件夹的路径,该文件夹位于主文件或包旁边。变更日志
0.8 版中的新增功能。
- 返回类型:
- 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
命令中使用这些命令。
- 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
- 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(): ...
- ensure_sync(func)¶
确保函数对 WSGI 工作进程是同步的。普通
def
函数按原样返回。将async def
函数包装起来以运行并等待响应。覆盖此方法以更改应用程序运行异步视图的方式。
变更日志
2.0 版中的新增功能。
- 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
类的子类。
- extensions: dict[str, t.Any]¶
扩展可以存储应用程序特定状态的地方。例如,扩展可以存储数据库引擎和类似内容。
键必须与扩展模块的名称匹配。例如,对于 flask_foo 中的“Flask-Foo”扩展,键将是
'foo'
。变更日志
0.7 版中的新增功能。
- 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 版中的新增功能。
- handle_exception(e)¶
处理未关联错误处理程序的异常,或从错误处理程序引发的异常。这始终导致 500
InternalServerError
。始终发送
got_request_exception
信号。如果
PROPAGATE_EXCEPTIONS
为True
,例如在调试模式中,将重新引发错误,以便调试器可以显示它。否则,将记录原始异常,并返回InternalServerError
。如果为
InternalServerError
或500
注册了错误处理程序,则将使用该处理程序。为了保持一致性,处理程序始终会收到InternalServerError
。原始未处理异常可用作e.original_exception
。变更日志
在 1.1.0 版本中更改:始终将
InternalServerError
实例传递给处理程序,将original_exception
设置为未处理错误。在 1.1.0 版本中更改:即使在没有处理程序时,
after_request
函数和其他最终处理也会针对默认 500 响应完成。0.3 版新增。
- 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
中的每个函数都使用error
、endpoint
和values
调用。如果某个函数返回None
或引发BuildError
,则跳过该函数。否则,其返回值将由url_for
返回。
- 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 版中的新增功能。
- 属性 jinja_env: 环境¶
用于加载模板的 Jinja 环境。
首次访问此属性时会创建环境。之后更改
jinja_options
将不起作用。
- jinja_environment¶
环境
的别名
- 属性 jinja_loader: BaseLoader | 无¶
此对象的模板的 Jinja 加载器。如果已设置,默认情况下,这是一个类
jinja2.loaders.FileSystemLoader
到template_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¶
- 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 版中的新增功能。
- make_default_options_response()¶
此方法用于创建默认
OPTIONS
响应。可以通过子类化更改此方法,以更改OPTIONS
响应的默认行为。变更日志
0.7 版中的新增功能。
- 返回类型:
- make_response(rv)¶
将视图函数的返回值转换为
response_class
实例。- 参数:
rv (ft.ResponseReturnValue) –
视图函数的返回值。视图函数必须返回一个响应。返回
None
,或视图在不返回的情况下结束,是不允许的。以下类型允许用于view_rv
str
使用编码为 UTF-8 的字符串作为主体创建一个响应对象。
字节
使用字节作为主体创建一个响应对象。
字典
在返回之前将被 jsonify 的字典。
列表
在返回之前将被 jsonify 的列表。
生成器
或迭代器
返回
str
或bytes
以作为响应进行流式传输的生成器。元组
可以是
(body, status, headers)
、(body, status)
或(body, headers)
,其中body
是此处允许的任何其他类型,status
是字符串或整数,headers
是字典或(key, value)
元组的列表。如果body
是response_class
实例,status
将覆盖退出值,headers
将被扩展。response_class
对象将保持不变地返回。
- 其他
Response
类 对象被强制转换为
response_class
。callable()
该函数被调用为 WSGI 应用程序。结果用于创建响应对象。
- 返回类型:
变更日志
在版本 2.2 中更改: 生成器将被转换为流响应。列表将被转换为 JSON 响应。
在版本 1.1 中更改: 字典将被转换为 JSON 响应。
在版本 0.9 中更改: 以前元组被解释为响应对象的论据。
- make_shell_context()¶
返回此应用程序的交互式 shell 的 shell 上下文。这将运行所有已注册的 shell 上下文处理器。
变更日志
0.11 版本中的新增功能。
- property name: str¶
应用程序的名称。这通常是导入名称,不同之处在于如果导入名称是 main,则会从运行文件猜测。当 Flask 需要应用程序的名称时,此名称用作显示名称。它可以设置和覆盖以更改值。
变更日志
0.8 版中的新增功能。
- open_instance_resource(resource, mode='rb')¶
从应用程序的实例文件夹 (
instance_path
) 打开资源。否则像open_resource()
一样。实例资源也可以打开进行写入。
- open_resource(resource, mode='rb')¶
打开相对于
root_path
的资源文件以进行读取。例如,如果文件
schema.sql
位于定义Flask
应用程序的文件app.py
旁边,则可以使用以下命令打开它with app.open_resource("schema.sql") as f: conn.executescript(f.read())
请注意,这是 Flask 类中同名方法的副本。
- permanent_session_lifetime¶
用于设置永久会话的过期日期的
timedelta
。默认值为 31 天,这使得永久会话大约持续一个月。此属性还可以使用配置项
PERMANENT_SESSION_LIFETIME
从配置中进行配置。默认为timedelta(days=31)
- 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
的一个实例。- 返回类型:
- redirect(location, code=302)¶
创建一个重定向响应对象。
这是由
flask.redirect()
调用的,也可以直接调用。变更日志
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_context(environ)¶
创建一个表示 WSGI 环境的
RequestContext
。使用with
块来推送上下文,这将使request
指向此请求。请参见 请求上下文。
通常情况下,您不应该在自己的代码中调用此方法。在处理请求时,
wsgi_app()
会自动推送请求上下文。使用test_request_context()
来创建环境和上下文,而不是使用此方法。- 参数:
environ (WSGIEnvironment) – WSGI 环境
- 返回类型:
- root_path¶
文件系统上包的绝对路径。用于查找包中包含的资源。
- route(rule, **options)¶
装饰视图函数,以便使用给定的 URL 规则和选项对其进行注册。调用
add_url_rule()
,它包含有关实现的更多详细信息。@app.route("/") def index(): return "Hello, World!"
请参阅 URL 路由注册。
如果未传递
endpoint
参数,则路由的端点名称默认为视图函数的名称。methods
参数默认为["GET"]
。HEAD
和OPTIONS
会自动添加。
- run(host=None, port=None, debug=None, load_dotenv=True, **options)¶
在本地开发服务器上运行应用程序。
不要在生产环境中使用
run()
。它不打算满足生产服务器的安全性和性能要求。相反,请参阅 部署到生产环境 以获取 WSGI 服务器建议。如果设置了
debug
标志,服务器将自动重新加载代码更改,并在发生异常时显示调试器。如果您想在调试模式下运行应用程序,但禁用交互式调试器上的代码执行,您可以将
use_evalex=False
作为参数传递。这将使调试器的回溯屏幕保持活动状态,但禁用代码执行。不建议将此函数用于具有自动重新加载的开发,因为这很不受支持。相反,您应该使用 flask 命令行脚本的
run
支持。请记住
除非处于调试模式,否则 Flask 将使用通用错误页面抑制任何服务器错误。因此,要在不重新加载代码的情况下启用交互式调试器,您必须使用
debug=True
和use_reloader=False
调用run()
。将use_debugger
设置为True
而不在调试模式下不会捕获任何异常,因为没有任何异常可以捕获。- 参数:
host (str | None) – 要侦听的主机名。将其设置为
'0.0.0.0'
以使服务器在外部也可访问。默认为'127.0.0.1'
或SERVER_NAME
配置变量中的主机(如果存在)。port (int | None) – Web 服务器的端口。默认为
5000
或SERVER_NAME
配置变量中定义的端口(如果存在)。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 版新增。
- send_static_file(filename)¶
用于从
static_folder
提供文件的视图函数。如果设置了static_folder
,则会自动在static_url_path
注册此视图的路由。请注意,这是 Flask 类中同名方法的副本。
变更日志
0.5 版新增。
- 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) –
- 返回类型:
- 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]
- template_global(name=None)¶
用于注册自定义模板全局函数的装饰器。你可以为全局函数指定一个名称,否则将使用函数名称。示例
@app.template_global() def double(n): return 2 * n
变更日志
0.10 版新增。
- 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 版新增。
- test_cli_runner(**kwargs)¶
创建一个 CLI 运行器来测试 CLI 命令。参见 使用 CLI 运行器运行命令。
返回
test_cli_runner_class
的实例,默认情况下为FlaskCliRunner
。Flask 应用程序对象作为第一个参数传递。变更日志
1.0 版中的新增功能。
- 参数:
kwargs (t.Any) –
- 返回类型:
- 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) –
- 返回类型:
- 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_SCHEME
、subdomain
、SERVER_NAME
和APPLICATION_ROOT
构建。subdomain – 要附加到
SERVER_NAME
的子域名。url_scheme – 要代替
PREFERRED_URL_SCHEME
使用的方案。data – 请求正文,可以是字符串,也可以是表单键值对的字典。
json – 如果提供,则将其序列化为 JSON 并作为
data
传递。还将content_type
的默认值设为application/json
。args (Any) – 传递给
EnvironBuilder
的其他位置参数。kwargs (Any) – 传递给
EnvironBuilder
的其他关键字参数。
- 返回类型:
- 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 版中的新增功能。
- update_template_context(context)¶
使用一些常用变量更新模板上下文。这会将 request、session、config 和 g 注入模板上下文,以及模板上下文处理器想要注入的所有内容。请注意,从 Flask 0.6 开始,如果上下文处理器决定返回具有相同键的值,则不会覆盖上下文中原始值。
- url_build_error_handlers: list[t.Callable[[Exception, str, dict[str, t.Any]], str]]¶
handle_url_build_error()
在url_for()
引发BuildError
时由其调用的函数列表。每个函数都使用error
、endpoint
和values
进行调用。如果某个函数返回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_ROOT
和PREFERRED_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
。
- 返回类型:
变更日志
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_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=<对象 对象>)¶
- 参数:
- add_app_template_filter(f, name=None)¶
注册一个模板过滤器,可在应用程序呈现的任何模板中使用。其工作原理类似于
app_template_filter()
装饰器。等同于Flask.add_template_filter()
。
- add_app_template_global(f, name=None)¶
注册一个模板全局变量,可在应用程序呈现的任何模板中使用。其工作原理类似于
app_template_global()
装饰器。等同于Flask.add_template_global()
。变更日志
0.10 版新增。
- add_app_template_test(f, name=None)¶
注册一个模板测试,可在应用程序呈现的任何模板中使用。其工作原理类似于
app_template_test()
装饰器。等同于Flask.add_template_test()
。变更日志
0.10 版新增。
- add_url_rule(rule, endpoint=None, view_func=None, provide_automatic_options=None, **options)¶
使用蓝图注册 URL 规则。有关完整文档,请参阅
Flask.add_url_rule()
。URL 规则添加了蓝图的 URL 前缀。与
url_for()
一起使用的端点名称添加了蓝图的名称前缀。
- 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()
。
- app_template_filter(name=None)¶
注册模板过滤器,可在应用程序呈现的任何模板中使用。等同于
Flask.template_filter()
。
- app_template_global(name=None)¶
注册模板全局,可在应用程序呈现的任何模板中使用。等同于
Flask.template_global()
。变更日志
0.10 版新增。
- app_template_test(name=None)¶
注册模板测试,可在应用程序呈现的任何模板中使用。等同于
Flask.template_test()
。变更日志
0.10 版新增。
- 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
- endpoint(endpoint)¶
装饰一个视图函数,为其注册给定的端点。如果在没有
view_func
的情况下使用add_url_rule()
添加规则时使用。app.add_url_rule("/ex", endpoint="example") @app.endpoint("example") def example(): ...
- 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
类的子类。
- 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 版中的新增功能。
- 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()
对象的实例,该实例稍后将传递给注册回调函数。子类可以覆盖此项以返回设置状态的子类。- 参数:
- 返回类型:
- open_resource(resource, mode='rb')¶
打开
root_path
相对于读取的资源文件。例如,如果文件
schema.sql
位于定义Flask
应用程序的文件app.py
旁边,则可以使用以下命令打开它with app.open_resource("schema.sql") as f: conn.executescript(f.read())
请注意,这是 Flask 类中同名方法的副本。
- patch(rule, **options)¶
使用
methods=["PATCH"]
变更日志
2.0 版中的新增功能。
- post(rule, **options)¶
使用
methods=["POST"]
变更日志
2.0 版中的新增功能。
- put(rule, **options)¶
使用
methods=["PUT"]
变更日志
2.0 版中的新增功能。
- 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"]
。HEAD
和OPTIONS
会自动添加。
- send_static_file(filename)¶
用于从
static_folder
提供文件的视图函数。如果设置了static_folder
,则会自动在此视图的static_url_path
注册一个路由。请注意,这是 Flask 类中同名方法的副本。
变更日志
0.5 版新增。
- 属性 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()
装饰器。此数据结构是内部的。不应直接修改它,并且其格式可能会随时更改。
- 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()
装饰器。此数据结构是内部的。不应直接修改它,并且其格式可能会随时更改。
传入请求数据¶
- class flask.Request(environ, populate_request=True, shallow=False)¶
Flask 中默认使用的请求对象。记住匹配的端点和视图参数。
最终成为
request
的内容。如果你想替换使用的请求对象,你可以对此进行子类化,并将request_class
设置为你的子类。请求对象是
Request
的子类,并提供 Werkzeug 定义的所有属性以及一些 Flask 特定的属性。- property accept_charsets: CharsetAccept¶
此客户端支持的字符集列表,作为
CharsetAccept
对象。
- 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
以指示允许哪些方法。
- 类方法 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 | 无¶
当前蓝图的已注册名称。
如果端点不属于蓝图,或者 URL 匹配失败或尚未执行,则此项为
无
。这并不一定与创建蓝图时使用的名称相匹配。它可能已嵌套,或使用不同的名称注册。
- 属性 缓存控制: RequestCacheControl¶
用于传入缓存控制标头的
RequestCacheControl
对象。
- 关闭()¶
关闭此请求对象的关联资源。这将显式关闭所有文件句柄。你也可以在 with 语句中使用请求对象,它将自动关闭请求对象。
变更日志
0.9 版中的新增功能。
- 返回类型:
无
- 内容编码¶
Content-Encoding 实体标头字段用作媒体类型的修饰符。如果存在,其值表示已对实体正文应用了哪些其他内容编码,因此必须应用哪些解码机制才能获取 Content-Type 标头字段引用的媒体类型。
变更日志
0.9 版中的新增功能。
- 内容 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¶
- 属性 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
中的每个值都是 WerkzeugFileStorage
对象。它基本上像你从 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。
- get_data(cache=True, as_text=False, parse_form_data=False)¶
这会将客户端的缓冲输入数据读入一个字节对象。默认情况下,这是缓存的,但可以通过将cache设置为False来更改此行为。
通常情况下,在不首先检查内容长度的情况下调用此方法是不明智的,因为客户端可能会发送几十兆字节或更多数据,从而导致服务器出现内存问题。
请注意,如果表单数据已经过解析,则此方法不会返回任何内容,因为表单数据解析不会像此方法那样缓存数据。要隐式调用表单数据解析函数,请将parse_form_data设置为True。完成后,如果表单解析器处理数据,此方法的返回值将为空字符串。通常情况下,这没有必要,因为如果缓存了整个数据(这是默认设置),表单解析器将使用缓存的数据解析表单数据。在任何情况下,在调用此方法之前,请务必先检查内容长度,以避免耗尽服务器内存。
如果as_text设置为True,返回值将是解码后的字符串。
变更日志
0.9 版中的新增功能。
- get_json(force=False, silent=False, cache=True)¶
将
data
作为 JSON 解析。如果 mimetype 未指示 JSON(application/json,请参阅
is_json
),或解析失败,则调用on_json_loading_failed()
,并使用其返回值作为返回值。默认情况下,这会引发 415 不支持的媒体类型响应。- 参数:
- 返回类型:
Any | None
变更日志
在版本 2.3 中更改: 引发 415 错误,而不是 400。
在版本 2.1 中更改: 如果内容类型不正确,则引发 400 错误。
- headers¶
随请求一起接收到的标头。
- property host: str¶
向其发出请求的主机名,包括非标准端口(如果存在)。使用
trusted_hosts
验证。
- 属性 if_modified_since: datetime | None¶
解析后的 If-Modified-Since 标头作为 datetime 对象。
变更日志
在版本 2.0 中更改:datetime 对象支持时区。
- 属性 if_unmodified_since: datetime | None¶
解析后的 If-Unmodified-Since 标头作为 datetime 对象。
变更日志
在版本 2.0 中更改:datetime 对象支持时区。
- input_stream¶
原始 WSGI 输入流,没有任何安全检查。
使用此功能很危险。它不会防止无限流或读取超过
content_length
或max_content_length
。请改用
stream
。
- is_multiprocess¶
如果应用程序由生成多个进程的 WSGI 服务器提供服务,则为 True 的布尔值。
- is_multithread¶
如果应用程序由多线程 WSGI 服务器提供服务,则为 True 的布尔值。
- is_run_once¶
如果应用程序在进程生命周期中仅执行一次,则为 True 的布尔值。例如,CGI 就是这种情况,但不能保证仅执行一次。
- 属性 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 版中的新增功能。
- 返回类型:
- max_form_memory_size: int | None = None¶
最大表单字段大小。这会转发到表单数据解析函数 (
parse_form_data()
)。当设置并访问form
或files
属性,并且内存中的 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¶
- 属性 pragma: HeaderSet¶
Pragma 通用标头字段用于包含可能适用于请求/响应链中任何接收者的特定于实现的指令。所有 pragma 指令都指定协议视点的可选行为;但是,某些系统可能要求行为与指令一致。
- referrer¶
Referer[sic] 请求标头字段允许客户端为服务器指定从中获取 Request-URI 的资源的地址 (URI)(“referrer”,尽管标头字段拼写错误)。
- remote_addr¶
发送请求的客户端的地址。
- remote_user¶
如果服务器支持用户身份验证,并且脚本受保护,则此属性包含用户已通过身份验证的用户名。
- routing_exception: HTTPException | None = None¶
如果匹配 URL 失败,这是将作为请求处理的一部分引发/已引发的异常。这通常是
NotFound
异常或类似内容。
- scheme¶
请求使用的协议的 URL 方案,例如
https
或wss
。
- server¶
服务器的地址。对于 Unix 套接字,
(host, port)
,(path, None)
,或如果未知,则为None
。
- property stream: IO[bytes]¶
WSGI 输入流,带有安全检查。此流只能使用一次。
使用
get_data()
以字节或文本形式获取完整数据。data
属性将仅在它们不表示表单数据时包含完整的字节。在这种情况下,form
属性将包含已解析的表单数据。与
input_stream
不同,此流可以防止无限流或读取超过content_length
或max_content_length
的内容。如果设置了
max_content_length
,如果设置了wsgi.input_terminated
,则可以在流上强制执行它。否则,将返回一个空流。如果在底层流耗尽之前达到限制(例如文件太大或无限流),则无法安全地读取流的剩余内容。根据服务器处理此问题的方式,客户端可能会显示“连接重置”故障,而不是看到 413 响应。
变更日志
在版本 2.3 中更改: 预先检查
max_content_length
,并在读取时检查。在版本 0.9 中更改: 即使首先访问了表单解析,流也始终设置(但可能会被消耗)。
- trusted_hosts: list[str] | None = None¶
处理请求时的有效主机名。默认情况下,所有主机都是受信任的,这意味着无论客户端所说的主机是什么,都将被接受。
由于
Host
和X-Forwarded-Host
标头可以被恶意客户端设置为任何值,因此建议设置此属性或在代理中实现类似的验证(如果应用程序在代理后面运行)。变更日志
0.9 版中的新增功能。
- 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
子类,以从字符串中解析数据。
- 属性 values: CombinedMultiDict[str, str]¶
werkzeug.datastructures.CombinedMultiDict
,可合并args
和form
。对于 GET 请求,仅存在
args
,不存在form
。变更日志
2.0 版中已更改:对于 GET 请求,仅存在
args
,不存在form
。
响应对象¶
- 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 通用头字段用于指定请求/响应链中的所有缓存机制都必须遵守的指令。
- call_on_close(func)¶
将函数添加到内部函数列表中,该列表应作为关闭响应的一部分被调用。自 0.7 起,此函数还返回传递的函数,以便可以将其用作装饰器。
变更日志
0.6 版中的新增内容。
- close()¶
如果可能,关闭包装的响应。你也可以在 with 语句中使用该对象,它会自动关闭它。
变更日志
0.9 版新增: 现在可以在 with 语句中使用。
- 返回类型:
无
- content_encoding¶
Content-Encoding 实体标头字段用作媒体类型的修饰符。如果存在,其值表示已对实体正文应用了哪些其他内容编码,因此必须应用哪些解码机制才能获取 Content-Type 标头字段引用的媒体类型。
- 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_status = 200¶
如果未提供,则为默认状态。
- delete_cookie(key, path='/', domain=None, secure=False, httponly=False, samesite=None)¶
删除一个 cookie。如果 key 不存在,则静默失败。
- 直接传递¶
将响应主体直接作为 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)
如果您希望在主调度程序中对响应进行后处理并使用子类提供的功能,这将特别有用。
请记住,如果可能,这将就地修改响应对象!
- freeze()¶
使响应对象准备好进行 pickle 序列化。执行以下操作
将响应缓冲到列表中,忽略
implicity_sequence_conversion
和direct_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,以强制进行缓冲。
- 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 版中的新增功能。
- get_etag()¶
以
(etag, is_weak)
形式返回一个元组。如果没有 ETag,返回值为(None, None)
。
- get_json(force=False, silent=False)¶
将
data
解析为 JSON。在测试期间很有用。如果 mimetype 没有指示 JSON (application/json,请参见
is_json
),则返回None
。与
Request.get_json()
不同,结果不会被缓存。
- 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 版中的新增内容。
- implicit_sequence_conversion = True¶
如果设置为 False,则访问响应对象上的属性不会尝试使用响应迭代器并将其转换为列表。
变更日志
0.6.2 版本新增: 该属性之前称为 implicit_seqence_conversion。(注意拼写错误)。如果你确实使用了此功能,则必须根据名称更改调整你的代码。
- property is_streamed: bool¶
如果响应已流式传输(响应不是具有长度信息的 iterable),则此属性为 True。在这种情况下,流式传输意味着没有关于迭代次数的信息。如果将生成器传递给响应对象,则通常为 True。
在应用某种不应该对流式传输响应进行的后置筛选之前,这对于检查非常有用。
- iter_encoded()¶
迭代使用响应编码编码的响应。如果响应对象被调用为 WSGI 应用程序,则此方法的返回值将用作应用程序迭代器,除非已激活
direct_passthrough
。
- 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,则此方法不起作用。
为了在处理范围请求时获得最佳性能,建议您的响应数据对象实现 seekable、seek 和 tell 方法,如
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 版中的新增内容。
- 返回类型:
无
- property max_cookie_size: int¶
MAX_COOKIE_SIZE
配置键的只读视图。请参阅 Werkzeug 文档中的
max_cookie_size
。
- 属性 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 对象支持时区。
- set_cookie(key, value='', max_age=None, expires=None, path='/', domain=None, secure=False, httponly=False, samesite=None)¶
设置 cookie。
如果 cookie 头的大小超过
max_cookie_size
,则会发出警告,但仍会设置该头。- 参数:
key (str) – 要设置的 cookie 的键(名称)。
value (str) – cookie 的值。
max_age (timedelta | int | None) – 应为秒数,或 None(默认值),如果 cookie 应仅持续到客户端的浏览器会话。
expires (str | datetime | int | float | None) – 应为 datetime 对象或 UNIX 时间戳。
path (str | None) – 将 cookie 限制到给定的路径,默认情况下它将跨越整个域。
domain (str | None) – 如果你想设置跨域 cookie。例如,
domain="example.com"
将设置一个可由域www.example.com
、foo.example.com
等读取的 cookie。否则,cookie 将只能由设置它的域读取。安全 (bool) – 如果
True
,则 Cookie 仅可通过 HTTPS 访问。仅限 HTTP (bool) – 禁止 JavaScript 访问 Cookie。
同站 (str | 无) – 将 Cookie 的范围限制为仅附加到“同站”请求。
- 返回类型:
无
- set_data(value)¶
将新字符串设置为响应。该值必须是字符串或字节。如果设置了字符串,则将其编码为响应的字符集(默认情况下为 utf-8)。
变更日志
0.9 版中的新增功能。
- property stream: ResponseStream¶
响应可迭代对象作为仅写流。
- 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
中的属性和方法。我们建议仅对字典进行子类化并添加该 mixinclass 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 版中的新增功能。
- get_cookie_domain(app)¶
会话 cookie 上
Domain
参数的值。如果没有设置,浏览器将仅向其设置 cookie 的确切域发送 cookie。否则,它们也将将其发送到给定值的任何子域。使用
SESSION_COOKIE_DOMAIN
配置。变更日志
在 2.3 版中更改:默认情况下未设置,不会回退到
SERVER_NAME
。
- get_cookie_httponly(app)¶
如果会话 cookie 应为 httponly,则返回 True。当前仅返回
SESSION_COOKIE_HTTPONLY
配置变量的值。
- get_cookie_name(app)¶
会话 cookie 的名称。使用 ``app.config[“SESSION_COOKIE_NAME”]``。
- get_cookie_path(app)¶
返回 cookie 应有效的路径。默认实现使用
SESSION_COOKIE_PATH
配置变量中的值(如果已设置),并回退到APPLICATION_ROOT
或使用/
(如果为None
)。
- get_cookie_samesite(app)¶
如果 cookie 应使用
SameSite
属性,则返回'Strict'
或'Lax'
。当前仅返回SESSION_COOKIE_SAMESITE
设置的值。
- get_cookie_secure(app)¶
如果 cookie 应该是安全的,则返回 True。这当前仅返回
SESSION_COOKIE_SECURE
设置的值。
- get_expiration_time(app, session)¶
一个帮助程序方法,如果会话链接到浏览器会话,则返回会话的到期日期,否则返回
None
。默认实现返回现在 + 在应用程序上配置的永久会话生命周期。- 参数:
app (Flask) –
session (SessionMixin) –
- 返回类型:
datetime | None
- is_null_session(obj)¶
检查给定的对象是否为 null 会话。不会要求保存 null 会话。
默认情况下,这会检查对象是否为
null_session_class
的实例。
- make_null_session(app)¶
创建一个 null 会话,如果由于配置错误而无法加载真正的会话支持,则该会话充当替换对象。这主要有助于用户体验,因为 null 会话的任务仍然是支持查找而不会抱怨,但修改会以有用的错误消息来回答失败的原因。
默认情况下,这会创建一个
null_session_class
实例。- 参数:
app (Flask) –
- 返回类型:
- 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
,则跳过此方法。- 参数:
app (Flask) –
session (SessionMixin) –
response (Response) –
- 返回类型:
无
- should_set_cookie(app, session)¶
会话后端使用此方法来确定是否应该为该响应的会话 Cookie 设置
Set-Cookie
标头。如果会话已修改,则设置 Cookie。如果会话是永久的,并且SESSION_REFRESH_EACH_REQUEST
配置为 true,则始终设置 Cookie。如果会话已删除,则通常跳过此检查。
变更日志
0.11 版本中的新增功能。
- 参数:
app (Flask) –
session (SessionMixin) –
- 返回类型:
- 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
,则跳过此方法。- 参数:
app (Flask) –
session (SessionMixin) –
response (Response) –
- 返回类型:
无
- serializer = <flask.json.tag.TaggedJSONSerializer object>¶
有效负载的 Python 序列化器。默认值是紧凑的 JSON 派生序列化器,支持一些额外的 Python 类型,例如 datetime 对象或元组。
- session_class¶
- class flask.sessions.SecureCookieSession(initial=None)¶
基于签名 cookie 的会话的基类。
此会话后端将设置
modified
和accessed
属性。它无法可靠地跟踪会话是新的(相对于空的),因此new
仍然硬编码为False
。- 参数:
initial (t.Any) –
- accessed = False¶
标头,允许缓存代理为不同的用户缓存不同的页面。
- get(key, default=None)¶
如果 key 在字典中,则返回 key 的值,否则返回 default。
- modified = False¶
当数据发生更改时,此项将设为
True
。仅跟踪会话字典本身;如果会话包含可变数据(例如嵌套字典),则在修改该数据时必须手动将其设为True
。仅当此项为True
时,会话 Cookie 才会写入响应。
- 类 flask.sessions.NullSession(initial=None)¶
如果会话不可用,则用于生成更友好的错误消息的类。仍将允许只读访问空会话,但在设置时会失败。
- 参数:
initial (t.Any) –
- pop(k[, d]) v, 删除指定的键并返回相应的值。 ¶
如果找不到该键,则返回给定的默认值;否则,引发 KeyError。
- popitem(*args, **kwargs)¶
删除并返回一个 (key, value) 对,作为 2 元组。
对以 LIFO(后进先出)顺序返回。如果字典为空,则引发 KeyError。
- setdefault(*args, **kwargs)¶
如果 key 不在字典中,则插入 key,其值为 default。
如果 key 在字典中,则返回 key 的值,否则返回 default。
- 类 flask.sessions.SessionMixin¶
使用会话属性扩展基本词典。
- accessed = True¶
某些实现可以检测会话数据何时被读取或写入,并在发生这种情况时设置此项。mixin 默认值硬编码为
True
。
- modified = True¶
某些实现可以检测会话的更改,并在发生这种情况时设置此项。mixin 默认值硬编码为
True
。
注意
PERMANENT_SESSION_LIFETIME
配置可以是整数或 timedelta
。 permanent_session_lifetime
属性始终是 timedelta
。
测试客户端¶
- class flask.testing.FlaskClient(*args, **kwargs)¶
它的工作原理与常规 Werkzeug 测试客户端类似,但了解 Flask 的上下文,以便将请求上下文的清理推迟到
with
块结束时。有关如何使用此类的常规信息,请参阅werkzeug.test.Client
。变更日志
0.12 版中已更改:app.test_client() 包含预设的默认环境,可以在 client.environ_base 中 app.test_client() 对象实例化后进行设置。
基本用法在 Testing Flask Applications 章节中概述。
- 参数:
args (t.Any) –
kwargs (t.Any) –
- open(*args, buffered=False, follow_redirects=False, **kwargs)¶
根据给定的参数生成 environ 字典,使用它向应用程序发出请求,并返回响应。
- 参数:
- 返回类型:
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()
相同的参数,这些参数直接传递。- 参数:
- 返回类型:
测试 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 应用程序。
应用程序全局变量¶
要从一个函数共享仅对一个请求有效的 data,全局变量是不够的,因为它会在线程环境中中断。Flask 为你提供了一个特殊对象,确保它仅对活动请求有效,并且会为每个请求返回不同的值。简而言之:它会执行正确操作,就像它对 request
和 session
所做的那样。
- 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()
。变更日志
0.10 版新增。
- pop(name, default=<object object>)¶
按名称获取并删除属性。类似于
dict.pop()
。变更日志
0.11 版本中的新增功能。
- setdefault(name, default=None)¶
如果属性存在,则获取其值,否则设置并返回一个默认值。类似于
dict.setdefault()
。变更日志
0.11 版本中的新增功能。
有用的函数和类¶
- flask.current_app¶
处理当前请求的应用程序的代理。这对于无需导入即可访问应用程序或无法导入应用程序(例如在使用应用程序工厂模式或在蓝图和扩展中)时非常有用。
仅在推送 应用程序上下文 时才可用。这在请求和 CLI 命令期间自动发生。可以使用
app_context()
手动控制它。这是一个代理。有关更多信息,请参见 代理说明。
- flask.has_request_context()¶
如果你有代码想要测试请求上下文是否存在,可以使用此函数。例如,如果请求对象可用,你可能希望利用请求信息,但如果请求对象不可用,则静默失败。
class User(db.Model): def __init__(self, username, remote_addr=None): self.username = username if remote_addr is None and has_request_context(): remote_addr = request.remote_addr self.remote_addr = remote_addr
或者,你还可以测试任何上下文绑定对象(例如
request
或g
)的真值class User(db.Model): def __init__(self, username, remote_addr=None): self.username = username if remote_addr is None and request: remote_addr = request.remote_addr self.remote_addr = remote_addr
变更日志
0.7 版中的新增功能。
- 返回类型:
- 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 版中的新增功能。
- 返回类型:
- 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
。
- 返回类型:
变更日志
在 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()
。- 参数:
- 返回类型:
变更日志
2.2 版中的新增功能: 如果可用,则调用
current_app.aborter
,而不是始终使用 Werkzeug 的默认abort
。
- flask.redirect(location, code=302, Response=None)¶
创建一个重定向响应对象。
如果
current_app
可用,它将使用其redirect()
方法,否则它将使用werkzeug.utils.redirect()
。- 参数:
- 返回类型:
变更日志
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'
在内部,此函数执行以下操作
如果没有传递参数,它将创建一个新的响应参数
如果传递了一个参数,则使用它调用
flask.Flask.make_response()
。如果传递了多个参数,则将参数作为元组传递给
flask.Flask.make_response()
函数。
变更日志
0.6 版中的新增内容。
- 参数:
args (t.Any) –
- 返回类型:
- flask.after_this_request(f)¶
在此请求之后执行函数。这对于修改响应对象很有用。该函数传递响应对象,并且必须返回相同或新的响应对象。
示例
@app.route('/') def index(): @after_this_request def add_header(response): response.headers['X-Foo'] = 'Parachute' return response return 'Hello World!'
如果视图函数以外的函数想要修改响应,则此函数更有用。例如,考虑一个装饰器,它希望添加一些标头,而无需将返回值转换为响应对象。
变更日志
0.9 版中的新增功能。
- 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
。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_fp
或attachment_filename
传递文件名。在版本 0.12 中更改: 在 MIME 检测中,
attachment_filename
优于filename
。在版本 0.9 中更改:
cache_timeout
默认为Flask.get_send_file_max_age()
。在版本 0.7 中更改: 由于不可靠,已移除对类文件对象的 MIME 猜测和 etag 支持。如果您能够,请传递文件名,否则自己附加 etag。
在版本 0.5 中更改: 添加了
add_etags
、cache_timeout
和conditional
参数。默认行为是添加 etag。在版本 0.2 中新增。
- flask.send_from_directory(directory, path, **kwargs)¶
使用
send_file()
从目录中发送文件。@app.route("/uploads/<path:name>") def download_file(name): return send_from_directory( app.config['UPLOAD_FOLDER'], name, as_attachment=True )
这是一个从文件夹(如静态文件或上传文件)安全提供文件的方法。使用
safe_join()
确保来自客户端的路径不会被恶意构造为指向指定目录之外。如果最终路径未指向现有常规文件,则会引发 404
NotFound
错误。- 参数:
directory (os.PathLike[str] | str) –
path
必须位于其下方的目录,相对于当前应用程序的根路径。path (os.PathLike[str] | str) – 要发送的文件的路径,相对于
directory
。kwargs (t.Any) – 传递给
send_file()
的参数。
- 返回类型:
变更日志
2.0 版中已更改:
path
替换了filename
参数。在 2.0 版中新增: 将实现移至 Werkzeug。现在这是一个包装器,用于传递一些特定于 Flask 的参数。
0.5 版新增。
消息闪烁¶
- flask.flash(message, category='message')¶
将消息闪现到下一个请求。为了从会话中移除闪现的消息并向用户显示,模板必须调用
get_flashed_messages()
。变更日志
在版本 0.3 中更改:添加了 category 参数。
- flask.get_flashed_messages(with_categories=False, category_filter=())¶
从会话中提取所有闪现的消息并返回它们。在同一请求中对该函数的进一步调用将返回相同的消息。默认情况下,仅返回消息,但当 with_categories 设置为
True
时,返回值将是形式为(category, message)
的元组列表。通过在 category_filter 中提供那些类别,将闪现的消息过滤到一个或多个类别。这允许在单独的 html 块中呈现类别。 with_categories 和 category_filter 参数是不同的
with_categories 控制是否将类别与消息文本一起返回(
True
给出一个元组,而False
仅给出消息文本)。category_filter 将消息筛选为仅匹配提供的类别的消息。
请参阅 消息闪烁 以获取示例。
变更日志
在版本 0.9 中更改:category_filter 参数已添加。
在版本 0.3 中更改:with_categories 参数已添加。
JSON 支持¶
默认情况下,Flask 使用 Python 的内置 json
模块来处理 JSON。可以通过将不同的提供程序分配给 flask.Flask.json_provider_class
或 flask.Flask.json
来更改 JSON 实现。如果应用程序上下文处于活动状态,flask.json
提供的函数将使用 app.json
上的方法。
Jinja 的 |tojson
过滤器配置为使用应用程序的 JSON 提供程序。该过滤器用 |safe
标记输出。使用它在 HTML <script>
标记内呈现数据。
<script>
const names = {{ names|tojson }};
renderChart(names, {{ axis_data|tojson }});
</script>
- flask.json.jsonify(*args, **kwargs)¶
将给定的参数序列化为 JSON,并返回一个 MIME 类型为
application/json
的Response
对象。从视图返回的字典或列表将自动转换为 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()
。变更日志
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()
。- 参数:
- 返回类型:
无
变更日志
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()
。变更日志
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()
。变更日志
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。
- dump(obj, fp, **kwargs)¶
将数据序列化为 JSON 并写入文件。
- loads(s, **kwargs)¶
将数据反序列化为 JSON。
- load(fp, **kwargs)¶
将从文件读取的数据反序列化为 JSON。
- class flask.json.provider.DefaultJSONProvider(app)¶
使用 Python 的内置
json
库提供 JSON 操作。序列化以下附加数据类型datetime.datetime
和datetime.date
序列化为 RFC 822 字符串。这与 HTTP 日期格式相同。uuid.UUID
序列化为字符串。dataclasses.dataclass
传递给dataclasses.asdict()
。Markup
(或任何具有__html__
方法的对象)将调用__html__
方法以获取字符串。
- 参数:
app (App) –
- static default(o)¶
将此函数应用于
json.dumps()
无法序列化的任何对象。它应返回一个有效的 JSON 类型或引发TypeError
。
- 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()
。从default
、ensure_ascii
和sort_keys
属性设置一些参数默认值。- 参数:
obj (Any) – 要序列化的数据。
kwargs (Any) – 传递给
json.dumps()
。
- 返回类型:
- loads(s, **kwargs)¶
从字符串或字节中反序列化数据为 JSON。
- 参数:
kwargs (Any) – 传递给
json.loads()
。
- 返回类型:
标记的 JSON¶
非标准 JSON 类型的无损序列化的紧凑表示形式。 SecureCookieSessionInterface
使用此形式序列化会话数据,但它可能在其他地方有用。它可以扩展以支持其他类型。
- class flask.json.tag.TaggedJSONSerializer¶
使用标签系统紧凑表示不是 JSON 类型的对象的序列化器。作为中间序列化器传递给
itsdangerous.Serializer
。支持以下额外类型
- default_tags = [<class 'flask.json.tag.TagDict'>, <class 'flask.json.tag.PassDict'>, <class 'flask.json.tag.TagTuple'>, <class 'flask.json.tag.PassList'>, <class 'flask.json.tag.TagBytes'>, <class 'flask.json.tag.TagMarkup'>, <class 'flask.json.tag.TagUUID'>, <class 'flask.json.tag.TagDateTime'>]¶
创建序列化器时要绑定的标签类。可以使用
register()
稍后添加其他标签。
- register(tag_class, force=False, index=None)¶
向此序列化器注册一个新标签。
- class flask.json.tag.JSONTag(serializer)¶
为
TaggedJSONSerializer
定义类型标签的基本类。- 参数:
serializer (TaggedJSONSerializer) –
我们来看一个添加对 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)¶
使用给定的上下文按名称渲染模板。
- flask.render_template_string(source, **context)¶
使用给定的上下文从给定的源字符串呈现模板。
- flask.stream_template(template_name_or_list, **context)¶
使用给定的上下文以流的形式呈现按名称指定的模板。这会返回一个字符串迭代器,可以用作视图的流响应。
- 参数:
- 返回类型:
变更日志
2.2 版中的新增功能。
- flask.stream_template_string(source, **context)¶
使用给定的上下文以流的形式从给定的源字符串呈现模板。这会返回一个字符串迭代器,可以用作视图的流响应。
变更日志
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 中新增。
配置¶
- 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。
- 参数:
- from_envvar(variable_name, silent=False)¶
从指向配置文件的环境变量加载配置。这基本上只是此代码行的一个快捷方式,带有更友好的错误消息
app.config.from_pyfile(os.environ['YOURAPPLICATION_SETTINGS'])
- 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)
- 参数:
- 返回:
True
如果文件加载成功。- 返回类型:
变更日志
在版本 2.3 中更改: 添加了
text
参数。2.0 版中的新增功能。
- from_mapping(mapping=无, **kwargs)¶
更新配置,类似于
update()
,忽略非大写键的项。变更日志
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()
进行基于类的配置的示例。
- from_prefixed_env(prefix='FLASK', *, loads=<function loads>)¶
加载以
FLASK_
开头的任何环境变量,从环境键中删除前缀以获取配置键。值通过加载函数传递,以尝试将它们转换为比字符串更具体的类型。键按
sorted()
顺序加载。默认加载函数尝试将值解析为任何有效的 JSON 类型,包括字典和列表。
可以通过使用双下划线 (
__
) 分隔键来设置嵌套字典中的特定项。如果中间键不存在,它将被初始化为空字典。- 参数:
prefix (str) – 加载以此前缀开头、用下划线 (
_
) 分隔的环境变量。loads (Callable[[str], Any]) – 将每个字符串值传递给此函数,并将返回值用作配置值。如果引发任何错误,则忽略该错误,并且该值仍然是字符串。默认值为
json.loads()
。
- 返回类型:
变更日志
2.1 版中的新增内容。
- from_pyfile(filename, silent=False)¶
使用 Python 文件更新配置中的值。此函数的行为就像使用
from_object()
函数将文件导入为模块一样。- 参数:
- 返回:
True
如果文件加载成功。- 返回类型:
变更日志
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' }
当配置选项直接映射到函数或类构造函数中的关键字参数时,这通常很有用。
- 参数:
- 返回类型:
变更日志
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 版中的新增功能。
有用的内部¶
- class flask.ctx.RequestContext(app, environ, request=None, session=None)¶
请求上下文包含每个请求的信息。Flask 应用程序在请求开始时创建并推送它,然后在请求结束时将其弹出。它将为提供的 WSGI 环境创建 URL 适配器和请求对象。
不要尝试直接使用此类,而是使用
test_request_context()
和request_context()
来创建此对象。当请求上下文被弹出时,它将对应用程序上注册的所有函数进行评估以执行销毁 (
teardown_request()
)。请求上下文在请求结束时自动弹出。使用交互式调试器时,上下文将被还原,因此仍然可以访问
request
。类似地,测试客户端可以在请求结束后保留上下文。但是,销毁函数可能已经关闭了一些资源,例如数据库连接。- 参数:
app (Flask) –
environ (WSGIEnvironment) –
request (Request | None) –
session (SessionMixin | None) –
- copy()¶
使用相同的请求对象创建此请求上下文的副本。这可用于将请求上下文移动到不同的 greenlet。因为实际的请求对象相同,所以这不能用于将请求上下文移动到不同的线程,除非对请求对象的访问被锁定。
变更日志
在版本 1.1 中更改:使用当前会话对象,而不是重新加载原始数据。这可以防止 flask.session 指向过时的对象。
0.10 版新增。
- 返回类型:
- match_request()¶
可以由子类覆盖以挂接到请求匹配。
- 返回类型:
无
- pop(exc=<object object>)¶
弹出请求上下文并通过执行此操作取消其绑定。这还将触发由
teardown_request()
装饰器注册的函数的执行。变更日志
在版本 0.9 中更改:添加了 exc 参数。
- 参数:
exc (BaseException | None) –
- 返回类型:
无
- flask.globals.request_ctx¶
当前的
RequestContext
。如果请求上下文未处于活动状态,则访问此代理上的属性将引发RuntimeError
。这是一个内部对象,对于 Flask 处理请求至关重要。在大多数情况下,不需要访问它。您很可能需要
request
和session
。
- class flask.ctx.AppContext(app)¶
应用程序上下文包含应用程序特定的信息。如果尚未处于活动状态,则在每个请求开始时都会创建并推送应用程序上下文。在运行 CLI 命令时也会推送应用程序上下文。
- 参数:
app (Flask) –
- pop(exc=<object object>)¶
弹出应用程序上下文。
- 参数:
exc (BaseException | None) –
- 返回类型:
无
- push()¶
将应用程序上下文绑定到当前上下文。
- 返回类型:
无
- flask.globals.app_ctx¶
当前
AppContext
。如果应用程序上下文未处于活动状态,则访问此代理上的属性将引发RuntimeError
。这是一个内部对象,对于 Flask 处理请求至关重要。在大多数情况下,不需要访问它。您很可能需要
current_app
和g
。
- class flask.blueprints.BlueprintSetupState(blueprint, app, options, first_registration)¶
用于向应用程序注册蓝图的临时持有者对象。此类的实例由
make_setup_state()
方法创建,并随后传递给所有注册回调函数。- add_url_rule(rule, endpoint=None, view_func=None, **options)¶
一个帮助程序方法,用于向应用程序注册规则(以及可选的视图函数)。端点自动加上蓝图的名称前缀。
- 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¶
此视图注册的方法。使用与
route
和add_url_rule
相同的默认值(["GET", "HEAD", "OPTIONS"]
)。
- class flask.views.MethodView¶
将请求方法分派到相应的实例方法。例如,如果你实现了一个
get
方法,它将用于处理GET
请求。这对于定义 REST API 很有用。
methods
会根据类中定义的方法自动设置。请参阅 基于类的视图 了解更多指南。
class CounterAPI(MethodView): def get(self): return str(session.get("counter", 0)) def post(self): session["counter"] = session.get("counter", 0) + 1 return redirect(url_for("counter")) app.add_url_rule( "/counter", view_func=CounterAPI.as_view("counter") )
- dispatch_request(**kwargs)¶
实际视图函数行为。子类必须覆盖此函数并返回有效的响应。URL 规则中的任何变量都作为关键字参数传递。
- 参数:
kwargs (t.Any) –
- 返回类型:
ft.ResponseReturnValue
URL 路由注册¶
通常有三种方法可以为路由系统定义规则
你可以使用
flask.Flask.route()
装饰器。你可以使用
flask.Flask.add_url_rule()
函数。你可以直接访问底层的 Werkzeug 路由系统,它以
flask.Flask.url_map
形式公开。
路由中的可变部分可以使用尖括号指定(/user/<username>
)。默认情况下,URL 中的可变部分接受任何不带斜杠的字符串,但也可以使用 <converter:name>
指定不同的转换器。
可变部分作为关键字参数传递给视图函数。
可以使用以下转换器
string |
接受任何不带斜杠的文本(默认值) |
int |
接受整数 |
float |
类似于 int,但用于浮点值 |
path |
类似于默认值,但还接受斜杠 |
any |
匹配提供的其中一项 |
uuid |
接受 UUID 字符串 |
可以使用 flask.Flask.url_map
定义自定义转换器。
以下是一些示例
@app.route('/')
def index():
pass
@app.route('/<username>')
def show_user(username):
pass
@app.route('/post/<int:post_id>')
def show_post(post_id):
pass
需要注意的一个重要细节是 Flask 如何处理尾部斜杠。其目的是保持每个 URL 的唯一性,因此适用以下规则
如果规则以斜杠结尾,而用户在请求时未带斜杠,则会自动将用户重定向到附加了尾部斜杠的同一页面。
如果规则未以尾部斜杠结尾,而用户请求的页面带有尾部斜杠,则会引发 404 未找到错误。
这与 Web 服务器处理静态文件的方式一致。这也使得可以安全地使用相对链接目标。
还可以为同一函数定义多个规则。但是,它们必须是唯一的。还可以指定默认值。例如,这里有一个接受可选页面的 URL 的定义
@app.route('/users/', defaults={'page': 1})
@app.route('/users/page/<int:page>')
def show_users(page):
pass
这指定 /users/
将成为第一页的 URL,而 /users/page/N
将成为第 N
页的 URL。
如果 URL 包含默认值,则会使用 301 重定向将其重定向到更简单的形式。在上述示例中,/users/page/1
将重定向到 /users/
。如果你的路由处理 GET
和 POST
请求,请确保默认路由仅处理 GET
,因为重定向无法保留表单数据。
@app.route('/region/', defaults={'id': 1})
@app.route('/region/<int:id>', methods=['GET', 'POST'])
def region(id):
pass
以下是 route()
和 add_url_rule()
接受的参数。唯一的区别是,对于 route 参数,视图函数是使用装饰器定义的,而不是使用 view_func 参数。
rule |
URL 规则(字符串形式) |
endpoint |
已注册 URL 规则的端点。如果未明确声明,Flask 本身假定视图函数的名称就是端点的名称。 |
view_func |
在向提供的端点提供请求时要调用的函数。如果未提供此函数,则可以通过将函数存储在 |
默认值 |
此规则的默认值词典。请参阅上面的示例,了解默认值的工作原理。 |
子域 |
如果使用子域匹配,则指定子域的规则。如果未指定,则假定为默认子域。 |
**选项 |
要转发到底层 |
视图函数选项¶
对于内部使用,视图函数可以附加一些属性以自定义视图函数通常无法控制的行为。可以按选择提供以下属性,以覆盖 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。
- make_context(info_name, args, parent=None, **extra)¶
当给定信息名称和参数时,此函数将启动解析并创建一个新的
Context
。但它不会调用实际的命令回调。要快速自定义所使用的上下文类而不覆盖此方法,请设置
context_class
属性。- 参数:
- 返回类型:
版本 8.0 中已更改: 添加了
context_class
属性。
- class flask.cli.AppGroup(name=None, commands=None, **attrs)¶
这与常规点击
Group
类似,但它改变了command()
装饰器的行为,以便它自动将函数包装在with_appcontext()
中。不要与
FlaskGroup
混淆。- 参数:
- command(*args, **kwargs)¶
这与常规
click.Group
上的同名方法完全相同,但它将回调包装在with_appcontext()
中,除非通过传递with_appcontext=False
禁用它。
- 类 flask.cli.ScriptInfo(app_import_path=无, create_app=无, set_debug_flag=真)¶
处理 Flask 应用程序的帮助器对象。通常不需要与之交互,因为它在内部用于分派到 click。在 Flask 的未来版本中,此对象很可能将发挥更大的作用。通常,它由
FlaskGroup
自动创建,但您也可以手动创建它并将其作为 click 对象传递。- app_import_path¶
Flask 应用程序的导入路径(可选)。
- create_app¶
一个可选函数,将脚本信息传递给它以创建应用程序实例。
- flask.cli.load_dotenv(path=None)¶
按优先级加载“dotenv”文件以设置环境变量。
如果已设置环境变量,则不会覆盖它,因此列表中较早的文件优先于较晚的文件。
如果未安装 python-dotenv,则此方法无效。
变更日志
在版本 2.0 中更改: 当前目录不会更改为加载的文件的位置。
在版本 2.0 中更改: 加载环境文件时,将默认编码设置为 UTF-8。
在版本 1.1.0 中更改: 当未安装 python-dotenv 或给定路径不是文件时,返回
False
。1.0 版中的新增功能。
- flask.cli.with_appcontext(f)¶
包装回调,以确保它在脚本的应用程序上下文中执行。
在
app.cli
或blueprint.cli
下注册的自定义命令(及其选项)始终具有可用的应用程序上下文,在这种情况下不需要此装饰器。变更日志
在版本 2.2 中更改: 应用程序上下文对子命令和装饰的回调均处于活动状态。应用程序上下文始终可用于
app.cli
命令和参数回调。- 参数:
f (F) –
- 返回类型:
F
- flask.cli.pass_script_info(f)¶
标记一个函数,以便将
ScriptInfo
的实例作为第一个参数传递给 click 回调。- 参数:
f (t.Callable[te.Concatenate[T, P], R]) –
- 返回类型:
t.Callable[P, R]
- flask.cli.run_command = <Command run>¶
运行本地开发服务器。
此服务器仅用于开发目的。它不提供生产 WSGI 服务器的稳定性、安全性或性能。
默认情况下,重新加载器和调试器通过“–debug”选项启用。