API

本部分文档涵盖了Flask的所有接口。对于Flask依赖于外部库的部分，我们在这里记录最重要的部分，并提供规范文档的链接。

应用程序对象

class flask.Flask(import_name, static_path=None, static_url_path=None, static_folder='static', 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而不是yourapplication.views.frontend中选择SQL查询）

版本0.7中的新功能：添加了static_url_path，static_folder和template_folder参数。

版本0.8中的新功能：添加了instance_path和instance_relative_config参数。

版本0.11中的新功能：添加了root_path参数。

参数：
  • import_name - 应用程序包的名称
  • static_url_path - 可用于为网络上的静态文件指定不同的路径。默认为static_folder文件夹的名称。
  • static_folder - 应在static_url_path上提供的静态文件的文件夹。默认为应用程序根路径中的'static'文件夹。
  • template_folder - 包含应用程序应使用的模板的文件夹。默认为应用程序根路径中的'templates'文件夹。
  • instance_path - 应用程序的替代实例路径。默认情况下，包或模块旁边的文件夹'instance'被假定为实例路径。
  • instance_relative_config - 如果设置为True，则加载配置的相对文件名假定为相对于实例路径而不是应用程序根。
  • root_path - 默认情况下，Flask会自动计算应用程序根目录的路径。在某些情况下，这不能实现（例如，如果包是Python 3命名空间包），并且需要手动定义。
add_template_filter(f, name=None)

注册自定义模板过滤器。与template_filter()装饰器完全一样。

参数：name - 过滤器的可选名称，否则将使用函数名称。
add_template_global(f, name=None)

注册自定义模板全局函数。与template_global()装饰器完全一样。

版本0.10中的新功能。

参数：name - 全局函数的可选名称，否则将使用函数名称。
add_template_test(f, name=None)

注册自定义模板测试。与template_test()装饰器完全一样。

版本0.10中的新功能。

参数：name - 测试的可选名称，否则将使用函数名称。
add_url_rule(rule, endpoint=None, view_func=None, **options)

连接网址规则。与route()装饰器完全一样。如果提供了view_func，它将被注册到端点。

基本上这个例子：

@app.route('/')
def index():
    pass

相当于以下内容：

def index():
    pass
app.add_url_rule('/', 'index', index)

如果未提供view_func，则需要将端点连接到视图函数，如下所示：

app.view_functions['index'] = index

内部route()调用add_url_rule()，所以如果你想通过子类化定制行为，你只需要改变这个方法。

有关详细信息，请参阅URL Route Registrations。

在版本0.2中更改： view_func参数添加。

在版本0.6中更改： OPTIONS作为方法自动添加。

参数：
  • 规则 - 网址规则为字符串
  • endpoint - 注册的URL规则的端点。Flask本身假定视图函数的名称为endpoint
  • view_func - 向提供的端点提供请求时调用的函数
  • 选项 - 要转发到底层Rule对象的选项。改变Werkzeug是处理方法选项。方法是此规则应限于（GET，POST等）的方法列表。默认情况下，规则只监听GET（和隐式地HEAD）。从Flask 0.6开始，OPTIONS由标准请求处理隐式添加和处理。
after_request(f)

注册要在每个请求后运行的函数。

您的函数必须具有一个参数，response_class的实例，并返回一个新的响应对象或相同（参见process_response()）。

从Flask 0.7开始，如果发生未处理的异常，此函数可能不会在请求结束时执行。

after_request_funcs = None

具有在每个请求后应调用的函数列表的字典。字典的键是此函数处于活动状态的蓝图的名称，None用于所有请求。这可以例如用于关闭数据库连接。要在此处注册函数，请使用after_request()装饰器。

app_context()

仅绑定应用程序。只要应用程序绑定到当前上下文，flask.current_app指向该应用程序。如果需要，在请求上下文被推时自动创建应用程序上下文。

用法示例：

with app.app_context():
    ...

版本0.9中的新功能。

app_ctx_globals_class

用于g实例的类。

自定义类的示例用例：

  1. 在flask上存储任意属性。
  2. 为恳求每个请求的数据库连接器添加一个属性。
  3. 对于意外的属性，返回None，而不是AttributeError。
  4. 如果设置了意外的attr，则引发异常，一个“受控”的瓶子。

在Flask 0.9中，此属性称为request_globals_class，但在0.10中更改为app_ctx_globals_class，因为flask.g对象现在是应用程序上下文作用域。

版本0.10中的新功能。

_AppCtxGlobals的别名

auto_find_instance_path()

尝试找到实例路径，如果它没有提供给应用程序类的构造函数。它将基本计算主文件或包旁边的名为instance的文件夹的路径。

版本0.8中的新功能。

before_first_request(f)

注册要在第一个请求之前运行的应用程序的此实例的函数。

该函数将在没有任何参数的情况下被调用，其返回值被忽略。

版本0.8中的新功能。

before_first_request_funcs = None

应在第一次请求此实例的开始时调用的函数列表。要在此处注册函数，请使用before_first_request()装饰器。

版本0.8中的新功能。

before_request （ f ）

注册在每个请求之前运行的函数。

该函数将被调用时没有任何参数。如果函数返回一个非无值，它被处理，就像它是从视图的返回值，进一步的请求处理停止。

before_request_funcs = None

具有应在请求开始时调用的函数列表的字典。字典的键是此函数处于活动状态的蓝图的名称，None用于所有请求。这可以例如用于打开数据库连接或获取当前登录的用户。要在此处注册函数，请使用before_request()装饰器。

blueprints = None

所有附加的蓝图在字典中的名称。蓝图可以多次附加，因此这本字典不会告诉你它们附加的频率。

版本0.7中的新功能。

cli = None

此应用程序的click命令行上下文。应用程序被发现后，此处注册的命令会显示在flask命令中。默认命令由Flask本身提供，可以覆盖。

这是一个click.Group对象的实例。

config =无

配置字典为Config。这个行为与普通字典完全相同，但支持从文件加载配置的其他方法。

config_class

用于此应用程序的config属性的类。默认为Config。

自定义类的示例用例：

  1. 某些配置选项的默认值。
  2. 通过除键之外的属性访问配置值。

版本0.11中的新功能。

Config的别名

context_processor(f)

注册模板上下文处理器函数。

create_global_jinja_loader()

创建Jinja2环境的装载器。可以用来覆盖加载器，并保持其余的不变。不鼓励重写这个函数。相反，应该重写jinja_loader()函数。

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

版本0.7中的新功能。

create_jinja_environment()

基于jinja_options和select_jinja_autoescape()创建Jinja2环境。从0.7开始，这也在初始化之后添加了Jinja2全局变量和过滤器。覆盖此功能以自定义行为。

版本0.5中的新功能。

根据TEMPLATES_AUTO_RELOAD配置选项更改了版本0.11中的 Environment.auto_reload：

create_url_adapter(request)

为给定请求创建URL适配器。URL适配器在请求上下文尚未设置的点创建，因此请求明确传递。

版本0.6中的新功能。

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

debug

调试标志。将此设置为True可启用应用程序的调试。在调试模式下，当发生未处理的异常时，调试器将启动，并且如果检测到代码的更改，集成服务器将自动重新加载应用程序。

也可以从配置中使用DEBUG配置键配置此属性。默认为False。

default_config = ImmutableDict({'TRAP_HTTP_EXCEPTIONS': False, 'LOGGER_HANDLER_POLICY': 'always', 'PERMANENT_SESSION_LIFETIME': datetime.timedelta(31), 'EXPLAIN_TEMPLATE_LOADING': False, 'TEMPLATES_AUTO_RELOAD': None, 'JSON_AS_ASCII': True, 'SESSION_REFRESH_EACH_REQUEST': True, 'SESSION_COOKIE_PATH': None, 'SESSION_COOKIE_SECURE': False, 'JSON_SORT_KEYS': True, 'TRAP_BAD_REQUEST_ERRORS': False, 'DEBUG': False, 'PREFERRED_URL_SCHEME': 'http', 'SECRET_KEY': None, 'APPLICATION_ROOT': None, 'PRESERVE_CONTEXT_ON_EXCEPTION': None, 'SESSION_COOKIE_DOMAIN': None, 'USE_X_SENDFILE': False, 'LOGGER_NAME': None, 'SERVER_NAME': None, 'SESSION_COOKIE_HTTPONLY': True, 'JSONIFY_MIMETYPE': 'application/json', 'SEND_FILE_MAX_AGE_DEFAULT': datetime.timedelta(0, 43200), 'TESTING': False, 'PROPAGATE_EXCEPTIONS': None, 'SESSION_COOKIE_NAME': 'session', 'JSONIFY_PRETTYPRINT_REGULAR': True, 'MAX_CONTENT_LENGTH': None})

默认配置参数。

dispatch_request()

请求分派。匹配URL并返回视图或错误处理程序的返回值。这不必是一个响应对象。为了将返回值转换为适当的响应对象，请调用make_response()。

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

do_teardown_appcontext(exc=<object object at 0x00000000034936B0>)

当应用程序上下文弹出时调用。这与do_teardown_request()几乎相同，但是对于应用程序上下文。

版本0.9中的新功能。

do_teardown_request(exc=<object object at 0x00000000034936B0>)

在实际请求分派后调用，将调用每个teardown_request()修饰函数。这不是由Flask对象本身实际调用的，而是在弹出请求上下文时触发。这样，我们对测试环境下的某些资源进行了更严格的控制。

在版本0.9中更改：添加了exc参数。以前，这总是使用当前的异常信息。

endpoint(endpoint)

一个装饰器，用于将函数注册为端点。例：

@app.endpoint('example.endpoint')
def example():
    return "example"
参数：endpoint - 端点的名称
error_handler_spec = None

所有注册的错误处理程序的字典。键是None，用于应用程序上的错误处理程序，否则键是蓝图的名称。每个键指向另一个字典，其中键是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

您还可以将函数注册为错误处理程序，而不使用errorhandler()装饰器。以下示例等效于上面的示例：

def page_not_found(error):
    return 'This page does not exist', 404
app.error_handler_spec[None][404] = page_not_found

通过赋值给error_handler_spec来设置错误处理程序是不鼓励的，因为它需要嵌套字典和特殊情况下的任意异常类型。

第一个None指的是活动蓝图。如果错误处理程序应该是应用程序宽度None将被使用。

版本0.7中的新功能：使用register_error_handler()，而不是直接修改error_handler_spec

版本0.7中的新功能：现在还可以注册自定义异常类型，但不一定是HTTPException类的子类。

参数：code - 代码作为处理程序的整数
extensions = None

扩展可以存储应用程序特定状态的地方。例如，这是一个扩展可以存储数据库引擎和类似的东西。对于向后兼容性扩展应该注册如下：

if not hasattr(app, 'extensions'):
    app.extensions = {}
app.extensions['extensionname'] = SomeObject()

密钥必须与扩展模块的名称匹配。例如，在flask_foo中的“Flask-Foo”扩展的情况下，键将是'foo'。

版本0.7中的新功能。

full_dispatch_request()

分派请求，并在其上执行请求pre和postprocessing以及HTTP异常捕获和错误处理。

版本0.7中的新功能。

get_send_file_max_age(filename)

为send_file()函数提供默认cache_timeout。

默认情况下，此函数从current_app的配置返回SEND_FILE_MAX_AGE_DEFAULT。

Static file functions such as send_from_directory() use this function, and send_file() calls this function on current_app when the given cache_timeout is None. 如果在send_file()中给出cache_timeout，则使用该超时；否则，将调用此方法。

这允许子类更改基于文件名发送文件时的行为。例如，要将.js文件的缓存超时设置为60秒：

class MyFlask(flask.Flask):
    def get_send_file_max_age(self, name):
        if name.lower().endswith('.js'):
            return 60
        return flask.Flask.get_send_file_max_age(self, name)

版本0.9中的新功能。

got_first_request

如果应用程序开始处理第一个请求，则此属性设置为True。

版本0.8中的新功能。

handle_exception(e)

当发生未捕获的异常时启动的默认异常处理。在调试模式下，异常将立即重新生成，否则将被记录，并使用500内部服务器错误的处理程序。如果不存在此类处理程序，则显示默认的500内部服务器错误消息。

版本0.3中的新功能。

handle_http_exception(e)

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

版本0.3中的新功能。

handle_url_build_error(error, endpoint, values)

在url_for()上处理BuildError。

handle_user_exception （ e ）

每当发生应该处理的异常时，将调用此方法。特殊情况是HTTPException s，它们由此函数转发到handle_http_exception()方法。此函数将返回响应值或使用相同的追溯重新处理异常。

版本0.7中的新功能。

has_static_folder

如果程序包绑定对象的容器具有用于静态文件的文件夹，则这是True。

版本0.5中的新功能。

init_jinja_globals()

已弃用。用于初始化Jinja2全局变量。

版本0.5中的新功能。

在0.7版中已更改：此方法已弃用0.7。改为替换create_jinja_environment()。

inject_url_defaults(endpoint, values)

将给定端点的URL默认值直接插入到传递的值字典中。这是内部使用，并自动调用URL建设。

版本0.7中的新功能。

instance_path = None

保存实例文件夹的路径。

版本0.8中的新功能。

iter_blueprints()

按照他们注册的顺序迭代所有蓝图。

版本0.11中的新功能。

jinja_env

用于加载模板的Jinja2环境。

jinja_environment

用于Jinja环境的类。

版本0.11中的新功能。

Environment的别名

jinja_loader

这个包的Jinja加载器绑定对象。

版本0.5中的新功能。

jinja_options = ImmutableDict({'extensions': ['jinja2.ext.autoescape', 'jinja2.ext.with_']})

直接传递到Jinja2环境的选项。

json_decoder

要使用的JSON解码器类。默认为JSONDecoder。

版本0.10中的新功能。

JSONDecoder的别名

json_encoder

要使用的JSON编码器类。默认为JSONEncoder。

版本0.10中的新功能。

JSONEncoder的别名

log_exception(exc_info)

记录异常。如果调试被禁用并且恰好在调用处理程序之前，这由handle_exception()调用。默认实现将异常作为错误记录在logger上。

版本0.8中的新功能。

logger

此应用程序的logging.Logger对象。如果应用程序处于调试模式，则默认配置为记录到stderr。这个记录器可以用来（惊喜）日志消息。这里有一些例子：

app.logger.debug('A value for debugging')
app.logger.warning('A warning occurred (%d apples)', 42)
app.logger.error('An error occurred')

版本0.3中的新功能。

logger_name

要使用的记录器的名称。默认情况下，记录器名称是传递给构造函数的包名。

版本0.4中的新功能。

make_config(instance_relative=False)

用于通过Flask构造函数创建配置属性。从Flask的构造函数（名为instance_relative_config）传递instance_relative参数，并指示配置是相对于应用程序的实例路径还是根路径。

版本0.8中的新功能。

make_default_options_response （ ）

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

版本0.7中的新功能。

make_null_session()

创建缺少会话的新实例。代替覆盖此方法，我们建议替换session_interface。

版本0.7中的新功能。

make_response(rv)

将来自视图函数的返回值转换为作为response_class的实例的实际响应对象。

以下类型允许用于rv：

response_class该对象不变地返回
str将使用字符串作为主体创建响应对象
unicode将使用编码为utf-8的字符串作为主体创建响应对象
WSGI函数该函数被称为WSGI应用程序并缓冲为响应对象
tuple以（响应， 状态， 头）或标头）其中响应是此处定义的任何类型，status是字符串或整数， t9> headers是一个列表或带有标题值的字典。
参数：rv - 视图函数的返回值

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

make_shell_context()

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

版本0.11中的新功能。

name

应用程序的名称。这通常是导入名称，区别是如果导入名称是main，则从运行文件中猜测它。当Flask需要应用程序的名称时，此名称将用作显示名称。可以设置和覆盖以更改值。

版本0.8中的新功能。

open_instance_resource(resource, mode='rb')

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

参数：
  • resource - 资源的名称。要访问子文件夹中的资源，请使用正斜杠作为分隔符。
  • mode - 资源文件打开模式，默认为“rb”。
open_resource(resource, mode='rb')

从应用程序的资源文件夹中打开资源。要了解这是如何工作的，请考虑以下文件夹结构：

/myapplication.py
/schema.sql
/static
    /style.css
/templates
    /layout.html
    /index.html

如果要打开schema.sql文件，您将执行以下操作：

with app.open_resource('schema.sql') as f:
    contents = f.read()
    do_something_with(contents)
参数：
  • resource - 资源的名称。要访问子文件夹中的资源，请使用正斜杠作为分隔符。
  • mode - 资源文件打开模式，默认为“rb”。
open_session(request)

创建或打开新会话。默认实现将所有会话数据存储在签名的Cookie中。这需要设置secret_key。代替覆盖此方法，我们建议替换session_interface。

参数：请求 - request_class的实例。
permanent_session_lifetime

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

此属性还可以从配置中配置PERMANENT_SESSION_LIFETIME配置键。默认为timedelta(days=31)

preprocess_request()

在实际请求分派之前调用，并调用每个before_request()修饰函数，不传递任何参数。如果这些函数中的任何一个返回一个值，则它被视为来自视图的返回值，并且进一步的请求处理被停止。

这也会在实际的before_request()函数调用之前触发url_value_processor()函数。

preserve_context_on_exception

返回PRESERVE_CONTEXT_ON_EXCEPTION配置值的值（如果已设置），否则返回合理的默认值。

版本0.7中的新功能。

process_response(response)

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

在版本0.5中更改：自Flask 0.5开始，按照注册的相反顺序调用在请求执行后注册的函数。

参数：响应 - a response_class对象。
返回：新的响应对象或相同，必须是response_class的实例。
propagate_exceptions

返回PROPAGATE_EXCEPTIONS配置值的值（如果已设置），否则返回合理的默认值。

版本0.7中的新功能。

register_blueprint(blueprint, **options)

在应用程序上注册蓝图。有关蓝图的信息，请转到Modular Applications with Blueprints。

蓝图名称作为第一个参数传入。选项作为附加关键字参数传递，并转发到“选项”字典中的蓝图。

参数：
  • 子域 - 为蓝图设置子域
  • url_prefix - 为蓝图上定义的所有网址设置前缀。(url_prefix='/<lang code>')
  • url_defaults - 添加到使用此蓝图定义的每个网址的网址默认值字典
  • static_folder - 在此蓝图中将静态文件夹添加到网址
  • static_url_path - 在此蓝图中为网址添加静态网址路径
  • template_folder - 设置备用模板文件夹
  • root_path - 为此蓝图设置备用根路径

版本0.7中的新功能。

register_error_handler(code_or_exception, f)

将errorhandler()装饰器的替代错误附加功能更简单地用于非装饰器使用。

版本0.7中的新功能。

request_class

用于请求对象的类。有关详细信息，请参阅Request。

Request的别名

request_context(environ)

从给定环境创建RequestContext并将其绑定到当前上下文。这必须与with语句结合使用，因为请求仅在with块的持续时间内绑定到当前上下文。

用法示例：

with app.request_context(environ):
    do_something_with(request)

返回的对象也可以在没有with语句的情况下使用，这对于在shell中工作非常有用。上面的示例执行与此代码完全相同：

ctx = app.request_context(environ)
ctx.push()
try:
    do_something_with(request)
finally:
    ctx.pop()

在版本0.3中更改：添加了对非语句用法和with语句的支持现在传递ctx对象。

参数：environ - 一个WSGI环境
response_class

用于响应对象的类。有关详细信息，请参阅Response。

Response的别名

route(rule, **options)

用于为给定URL规则注册视图函数的装饰器。这样做与add_url_rule()相同，但是用于装饰器使用：

@app.route('/')
def index():
    return 'Hello World'

有关详细信息，请参阅URL Route Registrations。

参数：
  • 规则 - 网址规则为字符串
  • endpoint - 注册的URL规则的端点。Flask本身假定视图函数的名称为endpoint
  • 选项 - 要转发到底层Rule对象的选项。改变Werkzeug是处理方法选项。方法是此规则应限于（GET，POST等）的方法列表。默认情况下，规则只监听GET（和隐式地HEAD）。从Flask 0.6开始，OPTIONS由标准请求处理隐式添加和处理。
run(host=None, port=None, debug=None, **options)

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

不要在生产设置中使用run()。它不打算满足生产服务器的安全性和性能要求。而是，请参阅Deployment Options了解WSGI服务器建议。

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

如果要以调试模式运行应用程序，但禁用交互式调试器上的代码执行，则可以传递use_evalex=False作为参数。这将使调试器的追溯屏幕保持活动，但禁用代码执行。

不建议将此函数用于自动重新加载的开发，因为这是受到严重支持。相反，您应该使用Flask命令行脚本的run支持。

记住

Flask将使用通用错误页抑制任何服务器错误，除非它处于调试模式。因此，只需启用交互式调试器而不重新加载代码，则必须使用debug=True和use_reloader=False调用run()将use_debugger设置为True而不处于调试模式将不会捕获任何异常，因为不会捕获任何异常。

在版本0.10中更改：默认端口现在从SERVER_NAME变量中选取。

参数：
  • host - 要监听的主机名。将此设置为'0.0.0.0'以使服务器也可从外部使用。默认为'127.0.0.1'。
  • port - 网络服务器的端口。默认为5000或在SERVER_NAME配置变量（如果存在）中定义的端口。
  • debug - 如果给定，请启用或禁用调试模式。请参见debug。
  • 选项 - 要转发到基础Werkzeug服务器的选项。有关详细信息，请参阅werkzeug.serving.run_simple()。
save_session(session, response)

如果需要更新，请保存会话。对于默认实现，请检查open_session()。Instead of overriding this method we recommend replacing the session_interface.

参数：
secret_key

如果设置了密钥，加密组件可以使用它来签名cookie和其他东西。例如，当您想要使用安全cookie时，将此设置为复杂的随机值。

也可以使用SECRET_KEY配置键从配置中配置此属性。默认为None。

select_jinja_autoescape(filename)

如果对给定模板名称自动转义处于活动状态，则返回True。如果未给出模板名称，则返回True。

版本0.5中的新功能。

send_file_max_age_default

A timedelta，用作send_file()函数的默认cache_timeout。默认值为12小时。

也可以使用SEND_FILE_MAX_AGE_DEFAULT配置键从配置中配置此属性。此配置变量也可以设置为用作秒的整数值。默认为timedelta(hours=12)

send_static_file(filename)

内部用于将静态文件从静态文件夹发送到浏览器的函数。

版本0.5中的新功能。

安全Cookie将此用作会话Cookie的名称。

此属性也可以从配置中配置SESSION_COOKIE_NAME配置键。默认为'session'

session_interface = <flask.sessions.SecureCookieSessionInterface object at 0x0000000006BD3358>

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

版本0.8中的新功能。

shell_context_processor(f)

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

版本0.11中的新功能。

shell_context_processors = None

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

版本0.11中的新功能。

should_ignore_error(error)

这被调用以确定是否应该忽略错误或不考虑拆卸系统。如果此函数返回True，则拆解处理程序将不会传递错误。

版本0.10中的新功能。

static_folder

配置的静态文件夹的绝对路径。

teardown_appcontext(f)

注册应用程序上下文结束时要调用的函数。当请求上下文被弹出时，这些函数通常也被调用。

例：

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

当在上面的示例中执行ctx.pop()时，在应用上下文从活动上下文的堆栈移动之前调用拆卸功能。如果你在测试中使用这样的结构，这变得相关。

因为一个请求上下文通常也管理一个应用程序上下文，它也会在你弹出请求时被调用上下文。

当由于异常而调用拆卸函数时，它将传递一个错误对象。

忽略拆卸函数的返回值。

版本0.9中的新功能。

teardown_appcontext_funcs = None

当应用程序上下文被销毁时调用的函数列表。因为应用程序的上下文也被删除，如果请求结束，这是存储断开与数据库的代码的地方。

版本0.9中的新功能。

teardown_request(f)

注册要在每个请求结束时运行的函数，而不管是否存在异常。当请求上下文弹出时，即使未执行实际请求，这些函数也会执行。

例：

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

当在上述示例中执行ctx.pop()时，在请求上下文从活动上下文的堆栈移动之前调用拆卸功能。如果你在测试中使用这样的结构，这变得相关。

一般来说，拆卸功能必须采取一切必要的步骤，以避免它们失败。如果他们执行可能失败的代码，它们将不得不通过try / except语句和日志发生错误来包围这些代码的执行。

当调用teardown函数时由于异常，它将传递一个错误对象。

忽略拆卸函数的返回值。

调试注意

在调试模式下，Flask不会立即删除异常请求。相反，它将保持活动，以便交互式调试器仍然可以访问它。此行为可由PRESERVE_CONTEXT_ON_EXCEPTION配置变量控制。

teardown_request_funcs = None

具有在每个请求之后调用的函数列表的字典，即使发生异常。字典的键是此函数处于活动状态的蓝图的名称，None用于所有请求。这些函数不允许修改请求，它们的返回值被忽略。如果在处理请求时发生异常，它会传递到每个teardown_request函数。要在此处注册函数，请使用teardown_request()装饰器。

版本0.7中的新功能。

template_context_processors = None

一个带有函数列表的字典，该函数没有参数调用来填充模板上下文。字典的键是此函数处于活动状态的蓝图的名称，None用于所有请求。每个返回模板上下文更新的字典。要在此处注册函数，请使用context_processor()装饰器。

template_filter(name=None)

用于注册自定义模板过滤器的装饰器。您可以为过滤器指定名称，否则将使用函数名称。例：

@app.template_filter()
def reverse(s):
    return s[::-1]
参数：name - 过滤器的可选名称，否则将使用函数名称。
template_global(name=None)

用于注册自定义模板全局函数的装饰器。您可以为全局函数指定名称，否则将使用函数名称。例：

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

版本0.10中的新功能。

参数：name - 全局函数的可选名称，否则将使用函数名称。
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 - 测试的可选名称，否则将使用函数名称。
test_client(use_cookies=True, **kwargs)

为此应用程序创建测试客户端。有关单元测试转到Testing Flask Applications的信息。

请注意，如果您要在应用代码中测试断言或异常，您必须设置app.testing = True t0 >以便将异常传播到测试客户端。否则，异常将由应用程序处理（对测试客户端不可见），并且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, authentication=None, *args, **kwargs):
        FlaskClient.__init__(*args, **kwargs)
        self._authentication = authentication

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

有关详细信息，请参阅FlaskClient。

在版本0.4中更改：添加了对with对客户端的块使用的支持。

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

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

test_client_class = None

当使用test_client时使用的测试客户端。

版本0.7中的新功能。

test_request_context(*args, **kwargs)

从给定值创建WSGI环境（有关详细信息，请参阅werkzeug.test.EnvironBuilder），此函数接受相同的参数。

testing

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

如果这被启用，并且PROPAGATE_EXCEPTIONS没有从默认值改变，它被隐式地启用。

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

trap_http_exception(e)

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

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

版本0.8中的新功能。

update_template_context(context)

用一些常用的变量更新模板上下文。这将请求，会话，配置和g注入模板上下文以及所有模板上下文处理器要注入。注意，在Flask 0.6中，如果上下文处理器决定返回具有相同键的值，上下文中的原始值将不会被覆盖。

参数：上下文 - 上下文作为一个字典，在现场更新以添加额外的变量。
url_build_error_handlers = None

当url_for()引发BuildError时调用的函数列表。此处注册的每个函数都使用错误，端点和值来调用。如果函数返回None或引发BuildError，则尝试下一个函数。

版本0.9中的新功能。

url_default_functions = None

具有可用作URL值预处理器的函数列表的字典。键None在此用于应用程序宽度的回调，否则键是蓝图的名称。这些函数中的每一个都有机会在URL值的字典用作视图函数的关键字参数之前对其进行修改。对于每个注册的函数，这个函数还应该提供一个url_defaults()函数，它会再次自动添加这些参数。

版本0.7中的新功能。

url_defaults(f)

URL的回调函数默认为应用程序的所有视图函数。它使用端点和值来调用，并且应该更新已传递的值。

url_map = None

此实例的Map。您可以使用它在类创建后但在连接任何路由之前更改路由转换器。例：

from werkzeug.routing import BaseConverter

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

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

用于创建URL规则的规则对象。这由add_url_rule()使用。默认为werkzeug.routing.Rule。

版本0.7中的新功能。

Rule的别名

url_value_preprocessor(f)

将函数注册为应用程序的所有视图函数的URL值预处理器。它在调用视图函数之前调用，可以修改提供的url值。

url_value_preprocessors = None

具有可用作URL值处理器函数的函数列表的字典。每当构建一个URL时，调用这些函数来修改值的字典。键None在此用于应用程序宽度的回调，否则键是蓝图的名称。这些函数中的每一个都有机会修改字典

版本0.7中的新功能。

use_x_sendfile

如果要使用X-Sendfile功能，请启用此功能。请记住，服务器必须支持这一点。这仅影响使用send_file()方法发送的文件。

版本0.2中的新功能。

也可以使用USE_X_SENDFILE配置键从配置中配置此属性。默认为False。

view_functions = None

已注册的所有视图函数的字典。键将是也用于生成URL的函数名，并且值是函数对象本身。要注册视图函数，请使用route()装饰器。

wsgi_app(environ, start_response)

实际的WSGI应用程序。这不是在__ call __中实现的，因此可以应用中间件而不会丢失对类的引用。所以，而不是这样做：

app = MyMiddleware(app)

这是一个更好的主意，做到这一点：

app.wsgi_app = MyMiddleware(app.wsgi_app)

然后你仍然有原始的应用程序对象，并可以继续调用它的方法。

在版本0.7中更改：在错误条件下更改了前后请求回调的行为，并添加了一个新的回调，它将始终在请求结束时执行，而不管发生错误不。请参阅Callbacks and Errors。

参数：
  • environ - 一个WSGI环境
  • start_response - 一个callable接受一个状态码，一个标题列表和一个可选的异常上下文开始响应

Blueprint Objects

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

表示蓝图。蓝图是一个对象，用于记录稍后将使用BlueprintSetupState调用的函数，以注册主应用程序上的函数或其他内容。有关详细信息，请参阅Modular Applications with Blueprints。

版本0.7中的新功能。

add_app_template_filter(f, name=None)

注册自定义模板过滤器，适用范围广。像Flask.add_template_filter()但是是一个蓝图。与app_template_filter()装饰器完全一样。

参数：name - 过滤器的可选名称，否则将使用函数名称。
add_app_template_global(f, name=None)

注册自定义模板全局，可用于应用程序。像Flask.add_template_global()但是是一个蓝图。与app_template_global()装饰器完全一样。

版本0.10中的新功能。

参数：name - 全局的可选名称，否则将使用函数名称。
add_app_template_test(f, name=None)

注册自定义模板测试，可用的应用程序广泛。像Flask.add_template_test()但是是一个蓝图。与app_template_test()装饰器完全一样。

版本0.10中的新功能。

参数：name - 测试的可选名称，否则将使用函数名称。
add_url_rule(rule, endpoint=None, view_func=None, **options)

像Flask.add_url_rule()，但是是一个蓝图。url_for()函数的端点以蓝图的名称为前缀。

after_app_request(f)

像Flask.after_request()，但是是一个蓝图。这样的函数在每个请求之后执行，即使在蓝图外部。

after_request(f)

像Flask.after_request()，但是是一个蓝图。此函数仅在由该蓝图的功能处理的每个请求之后执行。

app_context_processor(f)

像Flask.context_processor()但是是一个蓝图。这样的函数是每个请求执行的，即使在蓝图外部。

app_errorhandler(code)

像Flask.errorhandler()但是是一个蓝图。此处理程序用于所有请求，即使在蓝图外部。

app_template_filter(name=None)

注册自定义模板过滤器，适用范围广。像Flask.template_filter()但是是一个蓝图。

参数：name - 过滤器的可选名称，否则将使用函数名称。
app_template_global(name=None)

注册自定义模板全局，可用于应用程序。像Flask.template_global()但是是一个蓝图。

版本0.10中的新功能。

参数：name - 全局的可选名称，否则将使用函数名称。
app_template_test(name=None)

注册自定义模板测试，可用的应用程序广泛。像Flask.template_test()，但是是一个蓝图。

版本0.10中的新功能。

参数：name - 测试的可选名称，否则将使用函数名称。
app_url_defaults(f)

与url_defaults()相同，但适用范围广。

app_url_value_preprocessor(f)

与url_value_preprocessor()相同，但适用范围广。

before_app_first_request(f)

喜欢Flask.before_first_request()。这样的功能在对应用的第一请求之前执行。

before_app_request(f)

喜欢Flask.before_request()。这样的函数在每个请求之前执行，即使在蓝图外部。

before_request(f)

像Flask.before_request()但是是一个蓝图。此函数仅在由该蓝图的功能处理的每个请求之前执行。

context_processor(f)

像Flask.context_processor()但是是一个蓝图。此函数仅对由蓝图处理的请求执行。

endpoint(endpoint)

像Flask.endpoint()但是是一个蓝图。这不会为端点添加蓝图名称前缀，这必须由此方法的用户显式完成。如果端点前缀为。它将被注册到当前的蓝图，否则它是一个独立于应用程序的端点。

errorhandler(code_or_exception)

注册仅对此蓝图有效的错误处理程序。请注意，路由不会发生在蓝图的本地，因此404的错误处理程序通常不会被蓝图处理，除非它是在视图函数内部引起的。另一个特殊情况是500内部服务器错误，它总是从应用程序查找。

否则作为Flask对象的errorhandler()装饰器。

get_send_file_max_age(filename)

为send_file()函数提供默认cache_timeout。

默认情况下，此函数从current_app的配置返回SEND_FILE_MAX_AGE_DEFAULT。

Static file functions such as send_from_directory() use this function, and send_file() calls this function on current_app when the given cache_timeout is None. 如果在send_file()中给出cache_timeout，则使用该超时；否则，将调用此方法。

这允许子类更改基于文件名发送文件时的行为。例如，要将.js文件的缓存超时设置为60秒：

class MyFlask(flask.Flask):
    def get_send_file_max_age(self, name):
        if name.lower().endswith('.js'):
            return 60
        return flask.Flask.get_send_file_max_age(self, name)

版本0.9中的新功能。

has_static_folder

如果程序包绑定对象的容器具有用于静态文件的文件夹，则这是True。

版本0.5中的新功能。

jinja_loader

这个包的Jinja加载器绑定对象。

版本0.5中的新功能。

make_setup_state(app, options, first_registration=False)

创建BlueprintSetupState()对象的实例，稍后传递到注册回调函数。子类可以覆盖此，以返回设置状态的子类。

open_resource(resource, mode='rb')

从应用程序的资源文件夹中打开资源。要了解这是如何工作的，请考虑以下文件夹结构：

/myapplication.py
/schema.sql
/static
    /style.css
/templates
    /layout.html
    /index.html

如果要打开schema.sql文件，您将执行以下操作：

with app.open_resource('schema.sql') as f:
    contents = f.read()
    do_something_with(contents)
参数：
  • resource - 资源的名称。要访问子文件夹中的资源，请使用正斜杠作为分隔符。
  • mode - 资源文件打开模式，默认为“rb”。
record(func)

注册在应用程序上注册蓝图时调用的函数。此函数使用由make_setup_state()方法返回的状态as参数调用。

record_once(func)

像record()工作，但将函数包装在另一个函数中，这将确保函数只被调用一次。如果第二次在应用程序上注册了蓝图，则不会调用传递的函数。

register(app, options, first_registration=False)

由Flask.register_blueprint()调用以在应用程序上注册蓝图。这可以被覆盖以定制寄存器行为。来自register_blueprint()的关键字参数直接转发到选项字典中的此方法。

register_error_handler(code_or_exception, f)

errorhandler()错误附加函数的非装饰版本类似于Flask对象的register_error_handler()应用程序范围函数，错误处理程序限于此蓝图。

版本0.11中的新功能。

route(rule, **options)

像Flask.route()但是是一个蓝图。url_for()函数的端点以蓝图的名称为前缀。

send_static_file(filename)

内部用于将静态文件从静态文件夹发送到浏览器的函数。

版本0.5中的新功能。

static_folder

配置的静态文件夹的绝对路径。

teardown_app_request(f)

像Flask.teardown_request()但是对于一个蓝图。这样的功能在拆除每个请求时执行，即使在蓝图外部。

teardown_request(f)

像Flask.teardown_request()但是对于一个蓝图。此功能仅在拆除该蓝图功能处理的请求时执行。当请求上下文被弹出时，即使没有执行实际请求时，执行拆卸请求功能。

url_defaults(f)

本蓝图的URL默认回调函数。它使用端点和值来调用，并且应该更新已传递的值。

url_value_preprocessor(f)

将函数注册为此蓝图的URL值预处理器。它在调用视图函数之前调用，可以修改提供的url值。

Incoming Request Data

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

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

它是最终成为request。如果要替换所使用的请求对象，您可以对其进行子类化，并将request_class设置为您的子类。

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

form

A MultiDict与从POST或PUT请求解析的表单数据。请注意，文件上传不会在这里结束，而是在files属性中。

args

A MultiDict与解析的查询字符串的内容。（问号后面的URL中的部分）。

values

A CombinedMultiDict与form和args的内容。

cookies

A dict与所有与请求一起传输的Cookie的内容。

stream

如果传入表单数据未使用已知的mimetype进行编码，则数据将不经修改地存储在此流中以供使用。大多数时候，使用data这将是一个更好的主意，它将把数据作为字符串。流只返回一次数据。

headers

传入请求标头作为像对象的字典。

data

包含传入请求数据作为字符串，以防它与mimetype Flask不处理。

files

A MultiDict与作为POST或PUT请求的一部分上传的文件。每个文件存储为FileStorage对象。它基本上就像一个你从Python知道的标准文件对象，区别在于它还有一个save()函数，可以将文件存储在文件系统上。

environ

基础WSGI环境。

method

当前请求方法（POST，GET等）

path
full_path
script_root
url
base_url
url_root

提供不同的方法来查看当前的IRI。假设您的应用程序正在侦听以下应用程序根目录：

http://www.example.com/myapplication

并且用户请求以下URI：

http://www.example.com/myapplication/%CF%80/page.html?x=y

在这种情况下，上述属性的值如下：

路径u'/π/page.html'
full_pathu'/π/page.html?x=y'
script_rootu'/myapplication'
base_urlu'http://www.example.com/myapplication/π/page.html'
urlu'http://www.example.com/myapplication/π/page.html?x=y'
url_rootu'http://www.example.com/myapplication/'
is_xhr

True如果请求是通过JavaScript XMLHttpRequest触发的。这只适用于支持X-Requested-With头并将其设置为XMLHttpRequest的库。这样做的库是原型，jQuery和Mochikit，可能还有更多。

blueprint

当前蓝图的名称

endpoint

与请求匹配的端点。结合使用view_args可以重建相同或修改的URL。如果匹配时发生异常，则None。

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

解析传入的JSON请求数据并返回。默认情况下，如果mimetype不是application / json，此函数将返回None，但这可以通过force参数覆盖。如果解析失败，请求对象上的on_json_loading_failed()方法将被调用。

参数：
  • force - 如果设置为True，mimetype将被忽略。
  • silent - 如果设置为True，此方法将失败并返回None。
  • 缓存 - 如果设置为True，则在请求中记住解析的JSON数据。
is_json

指示此请求是否为JSON。默认情况下，如果mimetype为application / json或application / * + json，则请求将被视为包含JSON数据。

版本0.11中的新功能。

json

如果mimetype为application / json，则将包含已解析的JSON数据。否则，这将是None。

应该使用get_json()方法。

max_content_length

MAX_CONTENT_LENGTH配置键的只读视图。

module

如果请求已分派到实际模块，则为当前模块的名称。这是已弃用的功能，请改用蓝图。

on_json_loading_failed(e)

如果解析JSON数据失败，则调用。当发生错误时，get_json()使用此方法的返回值。The default implementation just raises a BadRequest exception.

在版本0.10中更改：删除了生成随机JSON响应的错误之前的行为。如果你想要的行为回来，你可以通过子类添加它。

版本0.8中的新功能。

routing_exception = None

如果匹配的URL失败，这是将引发/作为请求处理的一部分引发的异常。这通常是一个NotFound异常或类似的东西。

url_rule = None

与请求匹配的内部网址规则。这可以用于检查前/后处理程序（request.url_rule.methods）等的URL允许哪些方法。

版本0.6中的新功能。

view_args = None

与请求匹配的视图参数的dict。如果匹配时发生异常，则None。

class flask.request

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

这是一个代理。有关详细信息，请参阅Notes On Proxies。

请求对象是Request子类的实例，并提供Werkzeug定义的所有属性。这只是简要概述了最重要的。

Response Objects

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设置为您的子类。

headers

表示响应标头的Headers对象。

status

具有响应状态的字符串。

status_code

响应状态为整数。

data

调用get_data()和set_data()的描述符。这不应该使用，并将最终被弃用。

mimetype

mimetype（没有字符集的内容类型等）

设置Cookie。这些参数与Python标准库中的cookie Morsel对象相同，但它也接受unicode数据。

参数：
  • 键 - 要设置的cookie的键（名称）。
  • value - Cookie的值。
  • max_age - 应为秒数，或无（默认），如果Cookie只应在客户端的浏览器会话持续时间。
  • expires - 应为datetime对象或UNIX时间戳。
  • domain - 如果您要设置跨网域Cookie。例如，domain=".example.com"将设置一个可以被域www.example.com，foo.example.com否则，cookie只能由设置它的域读取。
  • path - 将Cookie限制到给定路径，默认情况下它将跨整个域。

Sessions

如果您设置了Flask.secret_key，您可以在Flask应用程序中使用会话。会话基本上使得可以记住从一个请求到另一个请求的信息。Flask通过使用签名的cookie来做到这一点。因此，用户可以查看会话内容，但不能修改它，除非他们知道秘密密钥，因此请确保将其设置为复杂和不可猜测的东西。

要访问当前会话，您可以使用session对象：

class flask.session

会话对象的工作方式非常类似于普通的dict，区别在于它跟踪修改。

这是一个代理。有关详细信息，请参阅Notes On Proxies。

以下属性很有趣：

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（这是默认值），当用户关闭浏览器时，会话将被删除。

Session Interface

版本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，则返回应用于会话Cookie的Cookie域的有用帮助程序方法。

如果会话cookie应为httponly，则返回True。目前只返回SESSION_COOKIE_HTTPONLY config var的值。

返回Cookie应该有效的路径。The default implementation uses the value from the SESSION_COOKIE_PATH config var if it’s set, and falls back to APPLICATION_ROOT or uses / if it’s None.

如果cookie应该是安全的，则返回True。目前只返回SESSION_COOKIE_SECURE设置的值。

get_expiration_time(app, session)

如果会话连接到浏览器会话，则返回会话的过期日期的帮助方法或None。默认实现返回现在+应用程序上配置的永久会话生存期。

is_null_session(obj)

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

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

make_null_session(app)

如果由于配置错误而无法加载实际会话支持，则创建作为替换对象的空会话。这主要帮助用户体验，因为null会话的工作是仍然支持查找而不抱怨，但修改已回答了一个有用的错误消息的失败。

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

null_session_class

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

NullSession的别名

open_session(app, request)

此方法必须实现，并且必须在加载失败的情况下返回None，因为配置错误或实现类似于接口的字典的会话对象实例+ SessionMixin。

pickle_based = False

一个标志，指示会话接口是否基于pickle。这可以由Flask扩展使用，以决定如何处理会话对象。

版本0.10中的新功能。

save_session(app, session, response)

对于在请求结束时由open_session()返回的实际会话，将调用此方法。这在请求上下文中仍然被调用，所以如果你绝对需要访问请求，你可以这样做。

指示是否应立即设置cookie。这由会话后端使用，以确定他们是否应该发出set-cookie头。默认行为由SESSION_REFRESH_EACH_REQUEST配置变量控制。如果设置为False，则仅当会话被修改时设置cookie，如果设置为True，如果会话是永久性的，则它始终设置。

如果会话被删除，通常会跳过此检查。

版本0.11中的新功能。

class flask.sessions.SecureCookieSessionInterface

通过itsdangerous模块在已签名的Cookie中存储会话的默认会话界面。

static digest_method()

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

key_derivation = 'hmac'

其危险的支持的密钥导出的名称。默认值为hmac。

salt = 'cookie-session'

应该应用在用于签署基于cookie的会话的秘密密钥之上的盐。

serializer = <flask.sessions.TaggedJSONSerializer object at 0x0000000006BC7D30>

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

session_class

SecureCookieSession的别名

class flask.sessions.SecureCookieSession(initial=None)

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

class flask.sessions.NullSession(initial=None)

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

class flask.sessions.SessionMixin

使用Flask扩展和用户对会话期望的访问器扩展基本字典。

modified = True

对于某些后端，这将始终为True，但有些后端将默认为false并检测字典中的更改，只要更改不会在会话中的可变结构上发生。默认的mixin实现只是硬编码True。

new = False

一些会话后端可以告诉您会话是否是新的，但不一定保证。小心使用。默认的mixin实现只是硬编码False。

permanent

这反映了dict中的'_permanent'键。

flask.sessions.session_json_serializer = <flask.sessions.TaggedJSONSerializer object at 0x0000000006BC7D30>

定制的JSON序列化程序，支持在序列化（元组，标记对象，日期时间）时我们认为是理所当然的一些额外的类型。

这个对象提供类似于simplejson的转储和加载方法，但它也标记了通常出现在会话中的某些内置Python对象。目前，在其转储的JSON中支持以下扩展值：

注意

PERMANENT_SESSION_LIFETIME配置键也可以是从Flask 0.8开始的整数。要么自己抓住这个，要么使用应用程序上的permanent_session_lifetime属性，将结果自动转换为整数。

Test Client

class flask.testing.FlaskClient(application, response_wrapper=None, use_cookies=True, allow_subdomain_redirects=False)

像一个常规的Werkzeug测试客户端，但是有一些知识关于Flask如何推迟清除请求上下文堆栈到with体的结束用于with声明。有关如何使用此类的一般信息，请参阅werkzeug.test.Client。

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

session_transaction(*args, **kwargs)

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

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

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

Application Globals

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

flask.g

只要存储在这个任何你想要的。例如，数据库连接或当前登录的用户。

从Flask 0.10开始，这是存储在应用程序上下文，不再请求上下文，这意味着如果只有应用程序上下文绑定，并且还没有请求，它变得可用。当与用于测试的Faking Resources and Context模式组合时，这是特别有用的。

此外，从0.10，你可以使用get()方法来获取属性或None（或第二个参数）如果没有设置。这两个用法现在是等价的：

user = getattr(flask.g, 'user', None)
user = flask.g.get('user', None)

现在还可以使用中的in

从0.11开始，您可以使用pop()和setdefault()，就像在字典中使用它们一样。

这是一个代理。有关详细信息，请参阅Notes On Proxies。

Useful Functions and Classes

flask.current_app

指向处理请求的应用程序。这对于希望支持并行运行多个应用程序的扩展很有用。这是由应用程序上下文，而不是通过请求上下文，所以你可以通过使用app_context()方法更改此代理的值。

这是一个代理。有关详细信息，请参阅Notes On Proxies。

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 like you
        # would otherwise in the view function.
        ...
    gevent.spawn(do_some_work)
    return 'Regular response'

版本0.10中的新功能。

flask.has_app_context()

像has_request_context()工作，但应用程序上下文。您也可以只对current_app对象进行布尔检查。

版本0.9中的新功能。

flask.url_for(endpoint, **values)

使用提供的方法生成指向给定端点的URL。

目标端点未知的变量参数将作为查询参数附加到生成的URL。如果查询参数的值为None，则将跳过整个对。如果蓝图处于活动状态，则可以通过为本地端点添加点（.）来快速引用相同的蓝图，）。

这将引用本地的索引函数到当前蓝图：

url_for('.index')

有关详情，请转到Quickstart。

To integrate applications, Flask has a hook to intercept URL build errors through Flask.url_build_error_handlers. 当当前应用程序没有给定端点和值的URL时，url_for函数会产生BuildError。当current_app调用url_build_error_handlers，如果不是None，它可以返回一个字符串作为url_for（而不是url_for的默认值来引发BuildError异常）或重新引发异常。一个例子：

def external_url_handler(error, endpoint, values):
    "Looks up an external URL when `url_for` cannot build a URL."
    # This is an example of hooking the build_error_handler.
    # Here, lookup_url is some utility function you've built
    # which looks up the endpoint in some external URL registry.
    url = lookup_url(endpoint, **values)
    if url is None:
        # External lookup did not have a URL.
        # Re-raise the BuildError, in context of original traceback.
        exc_type, exc_value, tb = sys.exc_info()
        if exc_value is error:
            raise exc_type, exc_value, tb
        else:
            raise error
    # url_for will use this result, instead of raising BuildError.
    return url

app.url_build_error_handlers.append(external_url_handler)

这里，错误是BuildError的实例，端点和值是传递到url_for 。请注意，这是用于在当前应用程序之外构建URL，而不是用于处理404 NotFound错误。

版本0.10中的新功能：添加了_scheme参数。

版本0.9中的新功能：添加了_anchor和_method参数。

版本0.9中的新功能：在BuildError上调用Flask.handle_build_error()。

参数：
  • endpoint - URL的终点（函数名称）
  • values - URL规则的变量参数
  • _external - 如果设置为True，则会生成绝对URL。服务器地址可以通过SERVER_NAME配置变量更改，默认为localhost。
  • _scheme - 指定所需URL方案的字符串。_external参数必须设置为True或引发ValueError。如果没有请求上下文可用，则默认行为使用与当前请求相同的方案，或来自app configuration的PREFERRED_URL_SCHEME。从Werkzeug 0.10开始，这也可以设置为空字符串来构建协议相对URL。
  • _anchor - 如果提供，则将其添加为网址的锚点。
  • _method - 如果提供，则显式指定HTTP方法。
flask.abort()

当传递代码 - >异常项的dict时，它可以用作可调用，引发异常。如果可调用的第一个参数是一个整数，它将在映射中查找，如果它是一个WSGI应用程序，它将在代理异常中引发。

其余的参数被转发到异常构造函数。

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

返回响应对象（WSGI应用程序），如果调用，将客户端重定向到目标位置。支持的代码为301,302,303,305和307。300不支持，因为它不是一个真正的重定向和304，因为它是一个请求与请求定义If-Modified-Since头的答案。

版本0.6中的新功能：此位置现在可以是使用iri_to_uri()函数编码的Unicode字符串。

版本0.10中的新功能：现在可以传入用于Response对象的类。

参数：
  • location - 应该重定向到的位置。
  • code - 重定向状态代码。默认为302。
  • 响应（类） - 在实例化响应时使用的响应类。如果未指定，默认值为werkzeug.wrappers.Response。
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中的新功能。

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(filename_or_fp, mimetype=None, as_attachment=False, attachment_filename=None, add_etags=True, cache_timeout=None, conditional=False)

将文件的内容发送到客户端。这将使用可用和配置的最有效的方法。默认情况下，它将尝试使用WSGI服务器的file_wrapper支持。或者，您可以将应用程序的use_x_sendfile属性设置为True，以直接发出X-Sendfile标题。但是，这需要支持X-Sendfile的底层Web服务器。

默认情况下，它会尝试猜测你的mimetype，但你也可以明确地提供一个。为了额外的安全，你可能想要发送某些文件作为附件（例如HTML）。mimetype猜测需要提供filename或attachment_filename。

请勿从用户源将文件名传递到此函数；您应该使用send_from_directory()。

版本0.2中的新功能。

版本0.5中的新功能：添加了add_etags，cache_timeout和条件参数。默认行为现在是附加etags。

在版本0.7中更改： mimetype猜测和etag支持文件对象已被弃用，因为它不可靠。如果你能够传递一个文件名，否则自己附上一个etag。此功能将在Flask 1.0中删除

在版本0.9中更改： cache_timeout从无应用程序配置时拉取其默认值。

参数：
  • filename_or_fp - 要在latin-1中发送的文件的文件名。这是相对于root_path如果指定了相对路径。或者，可能会提供文件对象，在这种情况下，X-Sendfile可能无法正常工作，并回退到传统方法。在调用send_file()之前，请确保文件指针位于要发送的数据的开头。
  • mimetype - 文件的mimetype（如果提供），否则自动检测发生。
  • as_attachment – set to True if you want to send this file with a Content-Disposition: attachment header.
  • attachment_filename - 附件的文件名（如果与文件的文件名不同）。
  • add_etags - 设置为False以禁用附加的etag。
  • 条件 - 设置为True以启用条件响应。
  • cache_timeout - 标头的超时秒数。当None（默认值）时，此值由current_app的get_send_file_max_age()设置。
flask.send_from_directory(directory, filename, **options)

使用send_file()发送来自给定目录的文件。这是一种从上传文件夹或类似内容快速显示静态文件的安全方法。

用法示例：

@app.route('/uploads/<path:filename>')
def download_file(filename):
    return send_from_directory(app.config['UPLOAD_FOLDER'],
                               filename, as_attachment=True)

发送文件和性能

强烈建议您在Web服务器中激活X-Sendfile支持（如果没有进行身份验证），告诉网络服务器自己为指定路径提供文件，而不调用Web应用程序改进性能。

版本0.5中的新功能。

参数：
  • 目录 - 存储所有文件的目录。
  • filename - 相对于要下载的目录的文件名。
  • 选项 - 可选的关键字参数，它们直接转发到send_file()。
flask.safe_join(directory, filename)

安全加入目录和文件名。

用法示例：

@app.route('/wiki/<path:filename>')
def wiki_page(filename):
    filename = safe_join(app.config['WIKI_FOLDER'], filename)
    with open(filename, 'rb') as fd:
        content = fd.read()  # Read and process the file content...
参数：
  • 目录 - 基本目录。
  • filename - 相对于该目录的不可信文件名。
上升：

NotFound，如果生成的路径会脱离目录。

flask.escape(s)

将字符串s中的字符＆，，'和“转换为HTML安全序列。如果您需要显示可能在HTML中包含此类字符的文本，请使用此选项。标记返回值作为标记字符串。

class flask.Markup

将字符串标记为可以安全地包含在HTML / XML输出中，而无需转义。这实现了几个框架和Web应用程序使用的__ html __接口。Markup是unicode的直接子类，提供unicode的所有方法，只是它转义传递的参数，并始终返回t5>。

escape函数返回标记对象，因此不会发生双重转义。

Markup类的构造函数可以用于三种不同的事情：当传递一个unicode对象时，假设它传递一个具有HTML表示的对象（有一个__ html __ t3 >方法），否则传递的对象将转换为unicode字符串，然后假定为安全的：

>>> Markup("Hello <em>World</em>!")
Markup(u'Hello <em>World</em>!')
>>> class Foo(object):
...  def __html__(self):
...   return '<a href="#">foo</a>'
...
>>> Markup(Foo())
Markup(u'<a href="#">foo</a>')

如果想要传递的对象始终被视为不安全，您可以使用escape() classmethod创建Markup对象：

>>> Markup.escape("Hello <em>World</em>!")
Markup(u'Hello &lt;em&gt;World&lt;/em&gt;!')

标记字符串上的操作是标记感知的，这意味着所有参数都通过escape()函数传递：

>>> em = Markup("<em>%s</em>")
>>> em % "foo & bar"
Markup(u'<em>foo &amp; bar</em>')
>>> strong = Markup("<strong>%(text)s</strong>")
>>> strong % {'text': '<blink>hacker here</blink>'}
Markup(u'<strong>&lt;blink&gt;hacker here&lt;/blink&gt;</strong>')
>>> Markup("<em>Hello</em> ") + "<foo>"
Markup(u'<em>Hello</em> &lt;foo&gt;')
classmethod escape(s)

逃离字符串。像escape()工作，区别在于Markup的子类会返回正确的子类。

striptags()

将标记取消转义为text_type字符串并剥离所有标记。这也解决了已知的HTML4和XHTML实体。空格被标准化为一：

>>> Markup("Main &raquo;  <em>About</em>").striptags()
u'Main \xbb About'
unescape()

将标记再次解析为text_type字符串。这也解决了已知的HTML4和XHTML实体：

>>> Markup("Main &raquo; <em>About</em>").unescape()
u'Main \xbb <em>About</em>'

Message Flashing

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

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

更改了版本0.3： 类别参数添加。

参数：
  • message - 要闪烁的消息。
  • 类别 - 邮件的类别。The following values are recommended: 'message' for any kind of message, 'error' for errors, 'info' for information messages and 'warning' for warnings. 但是任何类型的字符串都可以用作类别。
flask.get_flashed_messages(with_categories=False, category_filter=[])

从会话中拉取所有已闪烁的消息并返回。在同一请求中对函数的进一步调用将返回相同的消息。默认情况下只返回消息，但是当with_categories设置为True时，返回值将是形式的元组列表， message）。

通过在category_filter中提供这些类别，将闪烁的邮件过滤到一个或多个类别。这允许在单独的html块中渲染类别。with_categories和category_filter参数是不同的：

  • with_categories控制类别是否返回消息文本（True给出元组，False仅显示消息文本）。
  • category_filter将邮件过滤到仅与提供的类别匹配的邮件。

有关示例，请参见Message Flashing。

在版本0.3中已更改： with_categories参数添加。

在版本0.9中更改： category_filter参数添加。

参数：
  • with_categories - 设置为True也可接收类别。
  • category_filter - 限制返回值的类别白名单

JSON Support

Flask使用simplejson来实现JSON。由于simplejson既是标准库又是扩展，Flask会首先尝试simplejson然后回到stdlib json模块。此外，它将委派访问当前应用程序的JSON编码器和解码器，以便于定制。

所以，对于初学者，而不是：

try:
    import simplejson as json
except ImportError:
    import json

你可以这样做：

from flask import json

有关使用示例，请阅读标准库中的json文档。以下扩展名默认应用于stdlib的JSON模块：

  1. datetime对象序列化为 RFC 822字符串。
  2. 任何具有__html__方法（如Markup）的对象都将调用该方法，然后将返回值序列化为字符串。

此json模块的htmlsafe_dumps()函数也可用作Jinja2中的|tojson过滤器。请注意，在script标签中，不得进行转义，因此如果您打算在script标签中使用|safe除非你使用Flask 0.10，这意味着：

<script type=text/javascript>
    doSomethingWith({{ user.username|tojson|safe }});
</script>

自动排序JSON键

可以将配置变量JSON_SORT_KEYS（Configuration Handling）设置为false，以阻止Flask自动排序键。默认情况下，启用排序并在应用程序外部打开上下文排序。

注意，当使用基于内容的HTTP缓存和Python的哈希随机化特性时，禁用密钥排序会导致问题。

flask.json.jsonify(*args, **kwargs)

此函数包装dumps()以添加一些增强功能，使生活更轻松。它使用application / json mimetype将JSON输出转换为Response对象。为了方便，它还将多个参数转换为一个数组或多个关键字参数到一个dict。这意味着jsonify(1,2,3)和jsonify([1,2,3])序列化为[1,2,3]

为了清楚起见，JSON序列化行为与dumps()有以下区别：

  1. 单个参数：直接传递到dumps()。
  2. 多个参数：在传递到dumps()之前转换为数组。
  3. 多个关键字参数：在传递到dumps()之前转换为dict。
  4. args和kwargs：行为未定义并将抛出异常。

用法示例：

from flask import jsonify

@app.route('/_get_current_user')
def get_current_user():
    return jsonify(username=g.user.username,
                   email=g.user.email,
                   id=g.user.id)

这将发送一个JSON响应这样到浏览器：

{
    "username": "admin",
    "email": "admin@localhost",
    "id": 42
}

在版本0.11中更改：添加了对顶层数组序列化的支持。这在古老的浏览器中引入了安全风险。有关详细信息，请参阅JSON Security。

如果未通过X请求： XMLHttpRequest请求此函数的响应，以简化调试，除非JSONIFY_PRETTYPRINT_REGULAR config参数设置为false。压缩（不漂亮）格式化目前意味着在分隔符之后没有缩进和空格。

版本0.2中的新功能。

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

如果堆栈上有应用程序，使用应用程序配置的编码器（json_encoder）将obj序列化为JSON格式str。

此函数可以返回unicode字符串或ascii-only bytestrings默认情况下自动强制为unicode字符串。默认情况下，该行为由JSON_AS_ASCII配置变量控制，并且可以通过simplejson ensure_ascii参数覆盖。

flask.json.dump(obj, fp, **kwargs)

像dumps()但写入文件对象。

flask.json.loads(s, **kwargs)

如果堆栈上有应用程序，请使用应用程序配置的解码器（json_decoder）从字符串s中取消序列化JSON对象。

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

像loads()但从文件对象读取。

class flask.json.JSONEncoder(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

默认的Flask JSON编码器。这个扩展了默认simplejson编码器，它也支持datetime对象，UUID以及Markup对象，它们被序列化为RFC 822 datetime字符串作为HTTP日期格式）。为了支持更多的数据类型，重写default()方法。

default(o)

在子类中实现此方法，以便为o返回可序列化对象，或调用基本实现（提出TypeError）。

例如，要支持任意迭代器，您可以实现默认像这样：

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    return JSONEncoder.default(self, o)
class flask.json.JSONDecoder(object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)

默认的JSON解码器。这个不改变默认simplejson解码器的行为。有关详细信息，请参阅json文档。此解码器不仅用于此模块的加载功能，还用于Request。

Template Rendering

flask.render_template(template_name_or_list, **context)

使用给定的上下文从模板文件夹呈现模板。

参数：
  • template_name_or_list - 要渲染的模板的名称，或具有模板名称的迭代器，第一个现有的模板将被渲染
  • 上下文 - 应该在模板的上下文中提供的变量。
flask.render_template_string(source, **context)

使用给定的上下文从给定的模板源字符串呈现模板。模板变量将被自动转义。

参数：
  • source - 要呈现的模板的源代码
  • 上下文 - 应该在模板的上下文中提供的变量。
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 - 模板的名称
  • attribute - 要访问的宏变量的名称

Configuration

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'

在窗口上使用设置。

参数：
  • root_path - 从中​​读取文件的路径。当应用程序创建配置对象时，这是应用程序的root_path。
  • defaults - 默认值的可选字典
from_envvar(variable_name, silent=False)

从指向配置文件的环境变量加载配置。这基本上只是一个快捷方式，更好的错误消息这行代码：

app.config.from_pyfile(os.environ['YOURAPPLICATION_SETTINGS'])
参数：
  • variable_name - 环境变量的名称
  • silent - 如果您希望丢失文件的静默失败，请设置为True。
返回：

bool。True如果能加载配置，False否则。

from_json(filename, silent=False)

从JSON文件更新配置中的值。This function behaves as if the JSON object was a dictionary and passed to the from_mapping() function.

参数：
  • filename - JSON文件的文件名。这可以是绝对文件名或相对于根路径的文件名。
  • silent - 如果您希望丢失文件的静默失败，请设置为True。

版本0.11中的新功能。

from_mapping(*mapping, **kwargs)

更新配置，如update()忽略具有非上键的项。

版本0.11中的新功能。

from_object(obj)

更新给定对象的值。对象可以是以下两种类型之一：

  • 一个字符串：在这种情况下，将导入具有该名称的对象
  • 实际对象引用：该对象直接使用

对象通常是模块或类。

只是该对象中的大写变量存储在配置中。用法示例：

app.config.from_object('yourapplication.default_config')
from yourapplication import default_config
app.config.from_object(default_config)

您不应使用此功能加载实际配置，而应使用配置默认值。实际的配置应加载from_pyfile()，最好是从不在包中的位置加载，因为该包可能是系统安装的。

参数：obj - 导入名称或对象
from_pyfile(filename, silent=False)

从Python文件更新配置中的值。此函数的行为与使用from_object()函数作为模块导入的文件相同。

参数：
  • filename - 配置的文件名。这可以是绝对文件名或相对于根路径的文件名。
  • silent - 如果您希望丢失文件的静默失败，请设置为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'
}

当配置选项直接映射到函数或类构造函数中的关键字参数时，这通常很有用。

参数：
  • 命名空间 - 配置命名空间
  • 小写 - 指示结果字典的键是否应为小写的标志
  • trim_namespace - 指示结果字典的键是否不应包含命名空间的标志

版本0.11中的新功能。

Extensions

flask.ext

此模块充当Flask扩展的重定向导入模块。它被添加在0.8作为规范方式导入Flask扩展，使我们可以有更多的灵活性如何分配扩展。

如果要使用名为“Flask-Foo”的扩展名，您可以从ext导入它，如下所示：

from flask.ext import foo

版本0.8中的新功能。

Stream Helpers

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

Useful Internals

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

请求上下文包含所有请求相关信息。它在请求开始时创建，并推送到_request_ctx_stack，并在其末尾删除。它将为所提供的WSGI环境创建URL适配器和请求对象。

请不要尝试直接使用此类，而应使用test_request_context()和request_context()创建此对象。

当请求上下文弹出时，它将评估在应用程序上注册的用于拆卸执行的所有函数（teardown_request()）。

请求上下文在请求结束时自动弹出。在调试模式下，如果发生异常，请求上下文将被保留，以便交互式调试器有机会内省数据。对于0.4，这也可以强制用于未失败并且在DEBUG模式之外的请求。通过在WSGI环境中将'flask._preserve_context'设置为True，上下文将不会在请求结束时弹出。这由test_client()用于实现延迟清除功能。

你可能会发现这有助于单元测试，你需要从上下文本地的信息一段时间。确保在这种情况下自己正确地pop()堆栈，否则你的单元测试将泄漏内存。

copy()

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

版本0.10中的新功能。

match_request()

可以被一个子类覆盖以钩入请求的匹配。

pop(exc=<object object>)

弹出请求上下文，并通过这样做解除绑定。这也将触发由teardown_request()装饰器注册的函数的执行。

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

push()

将请求上下文绑定到当前上下文。

flask._request_ctx_stack

内部LocalStack用于实现Flask中使用的所有上下文局部对象。这是一个记录的实例，可以由扩展和应用程序代码使用，但一般不鼓励使用。

以下属性总是存在于堆栈的每个层上：

应用程式
活动Flask应用程序。
url_adapter
用于匹配请求的URL适配器。
请求
当前请求对象。
session
活动会话对象。
g
具有flask.g对象的所有属性的对象。
闪烁
闪存消息的内部缓存。

用法示例：

from flask import _request_ctx_stack

def get_session():
    ctx = _request_ctx_stack.top
    if ctx is not None:
        return ctx.session
class flask.ctx.AppContext(app)

应用程序上下文将应用程序对象隐式绑定到当前线程或greenlet，类似于RequestContext绑定请求信息。如果创建了一个请求上下文，但应用程序不在单个应用程序的顶部，则还会隐式创建应用程序上下文。

pop(exc=<object object>)

弹出应用程序上下文。

push()

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

flask._app_ctx_stack

与请求上下文类似，但只绑定应用程序。这主要是用于存储数据的扩展。

版本0.9中的新功能。

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

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

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

一种帮助方法，用于向应用程序注册规则（以及可选的视图函数）。端点将自动带有蓝图的名称前缀。

app = None

对当前应用程序的引用

blueprint = None

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

first_registration = None

因为蓝图可以与应用程序多次注册，并且并非所有想要多次注册的应用程序，此属性可以用于确定蓝图是否已在过去注册。

options = None

一个包含传递到register_blueprint()方法的所有选项的字典。

subdomain = None

该蓝图应当处于活动状态的子域，None。

url_defaults = None

具有URL默认值的字典，添加到使用蓝图定义的每个URL。

url_prefix = None

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

Signals

版本0.6中的新功能。

signals.signals_available

True如果信号系统可用。这是安装blinker时的情况。

以下信号存在于Flask中：

flask.template_rendered

当成功呈现模板时发送此信号。信号被调用模板的实例作为模板和上下文作为字典（名为上下文）。

订阅者示例：

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

该信号在模板渲染过程之前发送。信号被调用模板的实例作为模板和上下文作为字典（名为上下文）。

订阅者示例：

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

此信号在响应发送到客户端之前立即发送。它通过响应发送命名为响应。

订阅者示例：

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

当在请求处理期间发生异常时，发送此信号。在之前发送标准异常处理，甚至在调试模式下，其中不发生异常处理。异常本身作为异常传递给订阅者。

订阅者示例：

def log_exception(sender, exception, **extra):
    sender.logger.debug('Got exception during processing: %s', exception)

from flask import got_request_exception
got_request_exception.connect(log_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

当应用程序正在闪烁消息时，发送此信号。消息作为消息关键字参数发送，类别发送为类别。

订阅者示例：

recorded = []
def record(sender, message, category, **extra):
    recorded.append((message, category))

from flask import message_flashed
message_flashed.connect(record, app)

版本0.10中的新功能。

class signals.Namespace

如果闪光灯可用，则为blinker.base.Namespace的别名，否则创建伪信号的虚拟类。这个类可用于想要提供与Flask本身相同的备用系统的Flask扩展。

signal(name, doc=None)

如果blinker可用，则为此命名空间创建一个新信号，否则返回一个伪信号，该伪信号具有一个send方法，该方法对所有其他操作（包括连接）都将执行一个RuntimeError。

Class-Based Views

版本0.7中的新功能。

class flask.views.View

使用视图函数的替代方法。子类必须实现dispatch_request()，它使用来自URL路由系统的视图参数调用。如果提供methods，则方法不必显式地传递到add_url_rule()方法：

class MyView(View):
    methods = ['GET']

    def dispatch_request(self, name):
        return 'Hello %s!' % name

app.add_url_rule('/hello/<name>', view_func=MyView.as_view('myview'))

当你想装饰一个可插入的视图时，你必须在创建视图函数时（通过包装as_view()的返回值）或者使用decorators

class SecretView(View):
    methods = ['GET']
    decorators = [superuser_required]

    def dispatch_request(self):
        ...

存储在装饰器列表中的装饰器在创建视图函数时一个接一个地应用。请注意，您可以而不是使用基于类的装饰器，因为那些将装饰视图类，而不是生成的视图函数！

classmethod as_view(name, *class_args, **class_kwargs)

将类转换为可以与路由系统一起使用的实际视图函数。在内部，这将生成一个函数，它将在每个请求上实例化View，并调用dispatch_request()方法。

传递给as_view()的参数被转发到类的构造函数。

decorators = ()

修饰基于类的视图的规范方法是修饰as_view()的返回值。然而，由于这将逻辑的一部分从类声明移动到它被挂接到路由系统的地方。

您可以在此列表中放置一个或多个装饰器，并且每当创建视图函数时，结果都会自动装饰。

版本0.8中的新功能。

dispatch_request()

子类必须重写这个方法来实现实际的视图函数代码。使用来自URL规则的所有参数调用此方法。

methods = None

此视图可以处理的方法列表。

class flask.views.MethodView

像一个常规的基于类的视图，但是分派请求到特定的方法。例如，如果你实现一个名为get()的方法，这意味着你将响应'GET'请求和dispatch_request()此外，自动为您设置options：

class CounterAPI(MethodView):

    def get(self):
        return session.get('counter', 0)

    def post(self):
        session['counter'] = session.get('counter', 0) + 1
        return 'OK'

app.add_url_rule('/counter', view_func=CounterAPI.as_view('counter'))

URL Route Registrations

一般来说，有三种方法来定义路由系统的规则：

  1. 您可以使用flask.Flask.route()装饰器。
  2. 您可以使用flask.Flask.add_url_rule()函数。
  3. 您可以直接访问作为flask.Flask.url_map公开的底层Werkzeug路由系统。

可以使用尖括号（/user/<username>）指定路由中的变量部分。默认情况下，URL中的可变部分接受不带斜杠的任何字符串，但也可以使用<converter:name>指定不同的转换器。

变量部分作为关键字参数传递给视图函数。

提供以下转换器：

string接受任何不带斜杠的文本（默认）
int接受整数
float例如int，但是对于浮点值
路径像默认值，但也接受斜杠
任何匹配所提供的项目之一
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如何处理尾部斜线。其目的是保持每个网址唯一，以便适用以下规则：

  1. 如果规则以斜杠结尾并且用户没有斜杠请求，则用户将自动重定向到带有尾部斜杠的同一页面。
  2. 如果规则不以尾部斜杠结尾，并且用户请求带有尾部斜杠的页面，则会出现404未找到的。

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

您还可以为同一个函数定义多个规则。他们必须是独一无二的。还可以指定默认值。这里例如是接受可选页面的URL的定义：

@app.route('/users/', defaults={'page': 1})
@app.route('/users/page/<int:page>')
def show_users(page):
    pass

这指定/users/将是第一页的网址，而/users/page/N将是第页N的网址。

以下是route()和add_url_rule()接受的参数。唯一的区别是，对于route参数，view函数是使用装饰器而不是view_func参数定义的。

规则URL规则为字符串
端点注册的URL规则的端点。如果没有明确说明，Flask本身假定视图函数的名称是端点的名称。
view_func在向所提供的端点提供请求时调用的函数。如果没有提供，可以稍后通过将端点作为键将其存储在view_functions字典中来指定函数。
默认值具有此规则的默认值的字典。有关默认值如何工作，请参见上面的示例。
子域指定子域匹配在使用中的子域的规则。如果未指定，则假定为缺省子域。
**选项要转发到底层Rule对象的选项。改变Werkzeug是处理方法选项。方法是此规则应限于（GET，POST等）的方法列表。默认情况下，规则只监听GET（和隐式地HEAD）。从Flask 0.6开始，OPTIONS由标准请求处理隐式添加和处理。它们必须指定为关键字参数。

View Function Options

对于内部使用，视图函数可以附加一些属性来定制视图函数通常不能控制的行为。可以选择提供以下属性来覆盖某些默认值：add_url_rule()或一般行为：

  • __ name __：默认情况下，函数的名称用作端点。如果明确提供端点，则使用此值。此外，默认情况下，它将以蓝图的名称为前缀，不能从函数本身定制。
  • 方法：如果添加URL规则时未提供方法，则如果存在方法属性，Flask将查看视图函数对象本身。如果是，它将从那里拉方法的信息。
  • provide_automatic_options：如果设置此属性，Flask将强制启用或禁用HTTP OPTIONS响应的自动实施。在使用想要在每个视图的基础上自定义OPTIONS响应的装饰器时，这可能很有用。
  • required_methods：如果设置了此属性，则即使方法在route()调用中显式覆盖，Flask也将在注册URL规则时添加这些方法。

完整示例：

def index():
    if request.method == 'OPTIONS':
        # custom options handling here
        ...
    return 'Hello World!'
index.provide_automatic_options = False
index.methods = ['GET', 'OPTIONS']

app.add_url_rule('/', index)

版本0.8中的新功能：添加了provide_automatic_options功能。

Command Line Interface

class flask.cli.FlaskGroup(add_default_commands=True, create_app=None, **extra)

支持从配置的Flask应用程序加载更多命令的AppGroup组的特殊子类。通常开发人员不必与这个类接口，但是有一些非常高级的用例，为此创建一个实例是有意义的。

有关为什么有用的信息，请参阅Custom Scripts。

参数：
  • add_default_commands - 如果此值为True，则会添加默认的run和shell命令。
  • create_app - 传递脚本信息的可选回调，并返回加载的应用程序。
class flask.cli.AppGroup(name=None, commands=None, **attrs)

这类似于常规点击Group，但它改变了command()装饰器的行为，使其自动包装with_appcontext()

不要与FlaskGroup混淆。

command(*args, **kwargs)

这个方法和普通的click.Group上的同名方法完全一样，但它在with_appcontext()中包含回调，除非通过传递with_appcontext=False

group(*args, **kwargs)

这与常规click.Group上的同名方法完全相同，但它将组类默认为AppGroup。

class flask.cli.ScriptInfo(app_import_path=None, create_app=None)

帮助对象来处理Flask应用程序。这通常不需要接口，因为它在调度中单击时在内部使用。在Flask的未来版本中，这个对象很可能发挥更大的作用。通常，它由FlaskGroup自动创建，但您也可以手动创建它并将其作为点击对象传递。

app_import_path = None

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

create_app = None

（可选）传递脚本信息以创建应用程序实例的函数。

data = None

具有可与此脚本信息相关联的任意数据的字典。

load_app()

加载Flask应用程序（如果尚未加载）并返回它。调用此多次只会导致已经加载的应用程序返回。

flask.cli.with_appcontext(f)

包装一个回调，以确保它被执行的脚本的应用程序上下文。如果回调直接注册到app.cli对象，则它们将默认包装此函数，除非禁用。

flask.cli.pass_script_info(f)

标记函数，以便将ScriptInfo的实例作为第一个参数传递给单击回调。

flask.cli.run_command = <click.core.Command object at 0x0000000006BACAC8>

为Flask应用程序运行本地开发服务器。

此本地服务器仅推荐用于开发目的，但也可用于简单的内部网部署。默认情况下，它不支持任何类型的并发性以简化调试。这可以使用-with-threads选项更改，这将启用基本的多线程。

如果Flask的调试标志被启用，则默认启用重装器和调试器，否则禁用。

flask.cli.shell_command = <click.core.Command object at 0x0000000006BACB38>

在给定Flask应用程序的上下文中运行交互式Python shell。应用程序将根据其配置填充此shell的默认命名空间。

这对于执行管理代码的小片段很有用，而无需手动配置应用程序。