欢迎来到Flask¶

“micro”是什么意思？¶

对我来说,microframework 中的“micro”并不仅仅意味着框架的简单性和轻量性，还意 味着明显的复杂度限制和用框架所写出的应用的大小。即使只用一个python文件构成 一个应用也是事实。为了变得平易近人和简洁，一个microframwork会选择牺牲一些 可能对于大型或者更加复杂的应用来说必不可少的功能。

例如，flask使用内部的本地线程对象从而使你不用为了线程安全而在一个请求中来回 的在方法和方法之间传递对象。虽然这是一个简单的方法并且节省了你很多的时间， 但是它可能也会在非常大的应用中引发一些问题因为这些本地线程对象可能会在同一 线程的任何地方发生变化。

Flask 提供了一些工具来处理着这种方法的缺点，但是它更多的只是一种理论对于更 大的应用来说，因为理论上本地县城对象会在同一线程的任何地方被修改。

Flask也是基于配置的，也就是说许多东西会被预先配置。比如说，按照惯例，模板和 静态文件会在应用程序的python资源树下的子目录中。

Flask被称为”microframework”的主要原因是保持核心简单和可扩展性的理念。没有 数据库抽象层，没有表单验证以及其他的任何已经存在的可以处理它的不同库。但是 flask知道扩展的概念。这样你就可以在你的应用程序中添加这些功能，如果它被引用 的话。目前已经有对象关系映射器，表单验证，上传处理，各种开放认证技术等等之类 的扩展。

然而flask并没有许多的代码，并且它基于一个非常坚固的基础，这样它就可以非常容 易的去适应大型的应用。如果你有兴趣，请查阅 搞大了？！ 章节。

如果你对flask的设计原则感到好奇，请转向 Design Decisions in Flask 章节。

一个框架和一个例子¶

Flask 并不仅仅是一个微型框架；它同时也是一个例子。基于Flask，会有一系列的博 文来阐述如何创建一个框架。Flask自己就是一种在现有库的基础上实现一个框架的方 式。不像大部分的其他微型框架，Flask不会试着实现它自己的任何东西，它直接使用 已经存在的代码。

Web开发是危险的¶

我并不是在开玩笑。好吧，也许有一小点。如果你写一个web应用，你可能允许用户注册 ，并且允许他们在你的服务器上留下数据。用户把数据委托给了你。即使你是唯一可能 在你的应用中留下数据的用户，你也会希望那些数据安全的存储起来。

不幸的是，有很多中方法去损害一个Web应用程序的安全性。Flask可以防止一种现代Web 应用中最常见的安全问题：cross-site scripting(XSS).除非你故意的把不安全的HTML 标记为安全的，Flask和潜在的Jinja2模板引擎会把你覆盖掉。但是引发安全问题的方式 还有很多。

这篇文档是要提醒你注意Web开发中需要注意安全问题的方面。这些安全忧患中的一些远 远比人所想到的复杂的多，我们有时候会低估了一个漏洞会被利用的可能性，直到一个聪 明的攻击者指出一种方式来溢出我们的应用。

别以为你的应用程序还没有重要到吸引攻击者的程度， 依靠这种攻击方式，可能会有一些 自动机器人在想方设法在你的数据库中填入垃圾邮件，恶意软件的链接，等等。

Python 3的状态¶

目前Python社区正处在一个提高库对Python编程语言的新的迭代过程的支持。不幸的是， Python3 中还有一些问题，像缺少对Python3应该采用哪种WSGI方式的决策。这些问题有 部分原因是Python中的未经审核的变化；一部分原因是每个人都希望参与推动WSGI标准的 野心。

正因为如此，我们推荐不要使用Python3来开发任何Web应用直到WSGI的问题得到解决。 你会发现一部分框架和Web库宣称支持 Python3，但是它们的支持是基于Python3和 Python3.1中过时的WSGI实现，而这个实现很有可能在不久的将来会发生改变。

一旦WSGI的问题得到解决，Werkzeug和Flask将会立刻移植到Python3，并且我们会 提供一些有用的提示来把现存的应用更新到 Python3.在那之前，我们强烈推荐在 开发过程中使用激活的Python3 警告python2.6和2.7，以及Unicode文字的 __future__ 功能。

virtualenv¶

当你拥有shell访问权限时，virtualenv 可能是你在开发以及生产环境中想要使用的。

Virtualenv解决了什么问题？如果你像我一样喜欢Python，你可能会不仅想要在基于 Flask的Web应用，还包括一些其他的应用中使用它。但是，你拥有的项目越多，你用 不同的版本的Python工作的可能性越大，或者至少是不同版本的Python库。面对现实 吧；库很经常的破坏向后兼容性，而且想要任何大型的（正经的）应用零依赖是不可 能的。那么当你的两个或多个项目有依赖性冲突的话，你要怎么做？

Virtualenv来救援！它从根本上实现了多种并排式的python安装。它实际上并没有安 装Python的单独的副本，但它确实提供了一种巧妙的方式，让不同的项目环境中分离 出来。

那么让我们来看看Virtualenv是如何工作的！

如果你是在Mac OS X 或者Linux下，那么下面的两条命令将会适合你:

$ sudo easy_install virtualenv

或者更好的:

$ sudo pip install virtualenv

任意一个都可以在你的系统中安装virtualenv。它甚至可能在你的包管理中。如果你使用 的是Ubuntu，尝试:

$ sudo apt-get install python-virtualenv

如果你在Windows平台上并没有 easy_install 命令，你首先必须安装它。查阅 Windows 平台下的 easy_install 章节来获得更多如何做的信息。一旦你安装了它， 运行上述的命令，记得去掉 sudo 前缀。

一旦你装上了virtualenv，请调出shell然后创建你自己的环境变量。我通常会创建 一个包含 env 文件夹的项目文件夹：

$ mkdir myproject
$ cd myproject
$ virtualenv env
New python executable in env/bin/python
Installing setuptools............done.

现在，无论何时你想在一个项目上工作，你只需要激活相应的环境。在OS X和Linux上 ，执行以下操作：

$ . env/bin/activate

(注意脚本名称和点号之间的空格。该点意味着这个脚本应该运行在当前shell的上下文。 如果这条命令不能在你的shell中正常工作，请试着把点号替换为 source)

如果你是一个Windows用户，下面的命令是为你准备的:

$ env\scripts\activate

无论哪种方式，现在你应该正在使用你的virtualenv（看看你的shell提示已经更改到 显示virtualenv）

现在你可以键入下面的命令来激活你virtualenv中的Flask:

$ easy_install Flask

几秒钟后就准备好了。

安装到系统全局¶

这样也可以，但是我确实不推荐它。只需以root权限运行 easy_install

$ sudo easy_install Flask

(Windows平台下，在管理员Shell下运行,不要 sudo ).

生活在边缘¶

如果你想要使用最新版本的Flask，有两种方法：你可以使用 easy_insall 拉出开发版本， 或者让它来操作一个git检索。无论哪种方式，推荐你使用virtualenv。

在一个新的Virtualenv中获得git检索,并运行在在开发模式下

$ git clone http://github.com/mitsuhiko/flask.git
Initialized empty Git repository in ~/dev/flask/.git/
$ cd flask
$ virtualenv env
$ . env/bin/activate
New python executable in env/bin/python
Installing setuptools............done.
$ python setup.py develop
...
Finished processing dependencies for Flask

这将引入依赖关系和激活Git的头作为在Virtualenv中当前的版本。然后你只需 要 git pull origin 来获得最新的版本。

如果你不想用git来得到最新的开发版，可以改用下面的命令:

$ mkdir flask
$ cd flask
$ virtualenv env
$ . env/bin/activate
New python executable in env/bin/python
Installing setuptools............done.
$ easy_install Flask==dev
...
Finished processing dependencies for Flask==dev

Windows 平台下的 easy_install¶

在windows上，安装 easy_install 是有一点的复杂因为在Windows上比在类Unix系统上 有一些轻微的不同的规则，但是它并不难。最简单的安装方式是下载 ez_setup.py 文件 然后运行它。运行它最简单的方式是进入到你的下载目录中，然后双击这个文件。

接着，添加 easy_install 命令和其他Python脚本到命令行搜索路径，方法为：添加你 python安装目录中的Scripts文件夹到环境变量 PATH 中。添加方法:右键桌面的“我的电脑” 图标或者开始菜单中的“计算机”，然后选在“属性”。之后，在Vista和Win7下，单击“高级系统 设置”；在WinXP下，单击“高级”选项。然后，单击“环境变量”按钮，双击“系统变量”中的“path”变量。 在那里添加你的Python解释器的 Scripts文件夹；确保你使用分号将它与现有的值隔开。 假设你在使用默认路径的Python2.6，加入下面的值

;C:\Python26\Scripts

这样就完成了。要检查它是否正常工作，打开命令提示符然后执行 easy_install.如果在Vista 或者Win7下你只有用户控制权限，它应该会要求你获得管理员权限。

一个最小的应用¶

一个最小的Flask应用程序看起来像是这样:

from flask import Flask
app = Flask(__name__)

@app.route('/')
def hello_world():
    return "Hello World!"

if __name__ == '__main__':
    app.run()

把它存为 hello.py 或其它相似的文件名，然后用python解释器运行这个文件. 请确保你的程序名不是叫做 flask.py ,因为这样会和Flask本身发生冲突.

$ python hello.py
 * Running on http://127.0.0.1:5000/

把浏览器指向 http://127.0.0.1:5000/, 你将看到 你的 hello world的问候.

那么这段代码到底做了什么?

1. 首先我们导入了 Flask 类.这个类的一个实例将会是我们的 WSGI程序.
2. 接下来我实们来例化这个类.我们把模块/包的名字传给它,这样Flask就会知道它 将要到哪里寻找模板，静态文件之类的东西.
3. 然后我们使用 route() 装饰器告诉Flask哪个网址将会触发 我们的函数.
4. 这个函数还有一个作用是为特定的函数生成网址，并返回我们想要显示在用户浏 览器的信息.
5. 最后我们用 run() 函数来运行本地服务器以及我们的应用. if __name__ == '__main__': 确保了服务器只会在直接用Python解释器执行 该脚本的时候运行,而不会在导入模块的时候运行.

要停止服务器，按 Ctrl+C.

app.run(host='0.0.0.0')

调试模式¶

虽然 run() 方法很适于启动一个本地的测试服务器, 但是你每次修改代码后都得重启它.这样显然不好,Flask当然可以做得更好. 如果你开启服务器的debug支持,那么每次代码更改后服务器都会自动重启， 如果出现问题的话，还会提供给你一个有用的调试器.

有两种方法来开启debug模式.你可以在application对象上设置标志位

app.debug = True
app.run()

或者作为run方法的一个参数传入

app.run(debug=True)

两者均有完全相同的效果.

运行中的调试器的截图:

路由¶

正如你看到的，route() 装饰器用于绑定一个函数到一个网址. 但是它不仅仅只有这些!你可以构造动态的网址并给函数附加多个规则.

这里是一些例子

@app.route('/')
def index():
    return 'Index Page'

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

@app.route('/user/<username>')
def show_user_profile(username):
    # show the user profile for that user
    pass

@app.route('/post/<int:post_id>')
def show_post(post_id):
    # show the post with the given id, the id is an integer
    pass

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

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

>>> from flask import Flask, url_for
>>> app = Flask(__name__)
>>> @app.route('/')
... def index(): pass
...
>>> @app.route('/login')
... def login(): pass
...
>>> @app.route('/user/<username>')
... def profile(username): pass
...
>>> with app.test_request_context():
...  print url_for('index')
...  print url_for('login')
...  print url_for('login', next='/')
...  print url_for('profile', username='John Doe')
...
/
/login
/login?next=/
/user/John%20Doe

@app.route('/login', methods=['GET', 'POST'])
def login():
    if request.method == 'POST':
        do_the_login()
    else:
        show_the_login_form()

静态文件¶

动态的web应用程序也需要静态文件.这往往是CSS和JavaScript文件的来源.理想情况 下你的web服务器配置好了为你服务它们，但在开发过程中Flask也可以为你做这些. 只需要在你的包或者模块旁边里创建一个名为 static 的文件夹，它将可以通过 /static 来访问.

要生成这部分的网址，使用特殊的 'static' 网址名字

url_for('static', filename='style.css')

这个文件将位于文件系统的 static/style.css 位置.

模板渲染¶

从Python生成HTML不好玩也相当麻烦,因为你必须自己做HTML转义以保证应用 程序的安全.因为这个原因，Flask自动为您配置了 Jinja2 模板引擎.

你可以使用 render_template() 来渲染模板.所有您需要做的 是提供模板的名字，以及你想要作为参数传给模板引擎的变量.这里是一个如 和渲染模板的简单例子:

from flask import render_template

@app.route('/hello/')
@app.route('/hello/<name>')
def hello(name=None):
    return render_template('hello.html', name=name)

Flask将会在 templates 文件夹下查找模板.因此如果你的应用程序是一个 模块，这个文件夹在那个模块的旁边，或者如果它实际上是一个包含在您的 包里面的包:

案例 一: 一个模块

/application.py
/templates
    /hello.html

案例 二: 一个包:

/application
    /__init__.py
    /templates
        /hello.html

作为模板来讲你可以充分利用Jinja2模板的威力.前往 文档的 模版 章节或者 Jinja2 模板文档 查看更多信息.

这里是一个模版的例子:

<!doctype html>
<title>Hello from Flask</title>
{% if name %}
  <h1>Hello {{ name }}!</h1>
{% else %}
  <h1>Hello World!</h1>
{% endif %}

在模板内部你可以访问 request, session 和 g [1] 对象,以及 get_flashed_messages() 函数.

当使用继承的时候模板显得特别有用.如果你想了解继承是如何工作的，请查看 Template Inheritance 模式文档.基本上模板继承可以使得特定元素在 每个页面上都显示(比如header,navigation和footer).

自动转义默认是开启的，所以如果名字中包含HTML将被自动转义.如果你信任一个 变量并知道它是安全的(例如来自于一个把wiki标记转换为HTML格式的模板),你可以 使用类 Markup 或者 模板中的 |safe 标签，来标记它是 安全的. 前往Jinja2文档查看更多的例子.

这里就 Markup 类如何工作有一个简单的介绍:

>>> from flask import Markup
>>> Markup('<strong>Hello %s!</strong>') % '<blink>hacker</blink>'
Markup(u'<strong>Hello &lt;blink&gt;hacker&lt;/blink&gt;!</strong>')
>>> Markup.escape('<blink>hacker</blink>')
Markup(u'&lt;blink&gt;hacker&lt;/blink&gt;')
>>> Markup('<em>Marked up</em> &raquo; HTML').striptags()
u'Marked up \xbb HTML'

访问 Request 数据¶

对web应用程序来说最重要的就是对客户端发送到服务器端的数据做出响应.在 Flask中这个信息由一个全局的 request 对象提供.如果你 有一些Python的经验，你可能会奇怪这个对象怎么可能是全局的，并且Flask 怎么还能依然线程安全. 答案是局部上下文.

from flask import request

with app.test_request_context('/hello', method='POST'):
    # now you can do something with the request until the
    # end of the with block, such as basic assertions:
    assert request.path == '/hello'
    assert request.method == 'POST'

from flask import request

with app.request_context(environ):
    assert request.method == 'POST'

from flask import request

@app.route('/login', methods=['POST', 'GET'])
def login():
    error = None
    if request.method == 'POST':
        if valid_login(request.form['username'],
                       request.form['password']):
            return log_the_user_in(request.form['username'])
        else:
            error = 'Invalid username/password'
    # this is executed if the request method was GET or the
    # credentials were invalid

searchword = request.args.get('q', '')

from flask import request

@app.route('/upload', methods=['GET', 'POST'])
def upload_file():
    if request.method == 'POST':
        f = request.files['the_file']
        f.save('/var/www/uploads/uploaded_file.txt')
    ...

from flask import request
from werkzeug import secure_filename

@app.route('/upload', methods=['GET', 'POST'])
def upload_file():
    if request.method == 'POST':
        f = request.files['the_file']
        f.save('/var/www/uploads/' + secure_filename(f.filename))
    ...

跳转和错误¶

把一个用户跳转到某个地方去你可以使用 redirect() 函数,提前 中断一个请求并返回错误码，你可以使用 abort() 函数.这里有 一个它们是如何工作的例子:

from flask import abort, redirect, url_for

@app.route('/')
def index():
    return redirect(url_for('login'))

@app.route('/login')
def login():
    abort(401)
    this_is_never_executed()

这是一个相当没有意义的例子，因为用户将会从首页跳转到一个它不能访问的页面 (401意味着禁止访问),但它展示了它们是如何工作的.

默认每个错误码将会显示一个黑白错误信息的页面.如果你想定制错误页面，你可以 使用:meth:~flask.Flask.errorhandler 装饰器:

from flask import render_template

@app.errorhandler(404)
def page_not_found(error):
    return render_template('page_not_found.html'), 404

注意 render_template() 调用后的 404 .它告诉Flask这个页 面的状态码是404，代表没有找到的意思.默认的状态码是200，它的意思是: 一切 顺利.

会话¶

除了request对象外，还有一个对象叫做:class:~flask.session 允许你在不同请求 之间储存特定用户信息.这是在cookies基础上实现的并对cookies进行了加密.这意味 着用户可以查看你的cookie的内容，但不能修改它.除非它知道签名的密钥.

要使用会话你需要设置一个密钥.这是会话工作的一个例子:

from flask import Flask, session, redirect, url_for, escape, request

app = Flask(__name__)

@app.route('/')
def index():
    if 'username' in session:
        return 'Logged in as %s' % escape(session['username'])
    return 'You are not logged in'

@app.route('/login', methods=['GET', 'POST'])
def login():
    if request.method == 'POST':
        session['username'] = request.form['username']
        return redirect(url_for('index'))
    return '''
        <form action="" method="post">
            <p><input type=text name=username>
            <p><input type=submit value=Login>
        </form>
    '''

@app.route('/logout')
def logout():
    # remove the username from the session if its there
    session.pop('username', None)
    return redirect(url_for('index'))

# set the secret key.  keep this really secret:
app.secret_key = 'A0Zr98j/3yX R~XHH!jmN]LWX/,?RT'

这里提到了 escape() 函数，如果你没有使用模板引擎可以用它 来做转义(就像这个例子).

>>> import os
>>> os.urandom(24)
'\xfd{H\xe5<\x95\xf9\xe3\x96.5\xd1\x01O<!\xd5\xa2\xa0\x9fR"\xa1\xa8'

消息闪烁¶

良好的应用程序和用户界面都是基于反馈.如果用户得不到足够的反馈，它可能 最终会憎恨这个应用程序.Flask提供了一个简单的方法来给用户反馈，通过它的 消息闪烁系统.这个消息闪烁系统使得可以在一个request结束时记录一条消息, 然后在下一个request(仅能在这个request)中访问它.通常结合模板的布局来 做这件事.

要闪烁一条消息使用 flash() 方法，获得消息使用 get_flashed_messages(),这个方法也能在模板中使用. 查看 Message Flashing 获得更完整的示例.

日志记录¶

有时你可能会遇到一种情况，你要处理的数据应该是正确的，但实际上却不是. 比如你有一些客户端代码发送HTTP请求到服务器，它明显变形了.这可能是因为 用户对数据的加工，或者客户端代码故障.大多数时候，在这种情况下回复 400 Bad Request 就可以了,但在一些情况下不这么做，并且代码还得继续 工作下去.

然而你想把一些不对劲的事情记录下来.这时日志记录就派上用场了.从Flask 0.3 开始一个日志记录器已经预先为您配置好了.

这里有一些日志调用的例子:

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

附带的 logger 是一个标准的日志类 Logger, 因此可以前往官方标准库文档查看更新信息.

WSGI 中间件集成¶

如果你想添加一个WSGI中间件到你的应用程序，你可以封装内部的WSGI应用. 例如你如果享用Werkzeug包中的一个中间件来处理lighttpd的一些bug,你可以 这样做:

from werkzeug.contrib.fixers import LighttpdCGIRootFix
app.wsgi_app = LighttpdCGIRootFix(app.wsgi_app)

Jinja安装¶

Flask默认的Jinja配置为：

• .html, .htm, .xml, .xhtml 文件默认开启自动转义
• 模版文件可以通过 {% autoescaping %} 标签来选择是否开启自动转义
• Flask在Jinja2的模版中增加了一些全局变量和辅助方法，它们的值是默认的。

标准上下文¶

Jinja2的模版默认存在以下全局变量：

config

当前的configuration对象 (flask.config)

New in version 0.6.

request

当前的request对象 (flask.request)

session

当前的session对象 (flask.session)

g

用来保存一个request的全局变量（译者：不同的请求有不同的全局变量，g保存的是当前请求的全局变量） (flask.g)

url_for()

flask.url_for() 函数

get_flashed_messages()

flask.get_flashed_messages() 函数

{% from '_helpers.html' import my_macro with context %}

标准过滤器¶

Jinja2含有如下过滤器（包含了Jinja2模版引擎自带的）：

tojson()

这个函数是用来将对象转换成JSON格式。如果你要实时的生成JavaScript，那么这个功能是非常实用的。 要注意不能在 script 标签里面进行转义。所以如果你想在 script 标签里面使用这个函数，要确保用 |safe 来关闭自动转义：

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

|tojson 过滤器会自动转义前置的斜杠。

控制自动转义¶

自动转义就是自动帮你将特殊的字符替换成转义符号。HTML（或者XML， XHTML）的特殊字符有 &, >, <, ", ' 。因为这些字符在文档中有它自己特殊的含义，所以如果你想在文章中使用这些符号，必须将它替换成转义符号。如果不这样做，不仅用户使用不了这些符号，还会导致安全问题。(更多 Cross-Site Scripting (XSS))

但是有时候你需要在模版中禁用自动转义。如果你想直接将HTML插入页面，比如将markdown语言转换成HTML，那么你就需要这样做了。

有3种方法可以关闭自动转义：

• 在Python文件中进行转义。先在 Markup 对象中进行转义，然后将它传送给模版。一般推荐使用这个方式。
• 在模版文件中进行转义。通过 |safe 过滤器来表示字符串是安全的({{ myvariable|safe }})
• 暂时禁用全局的自动转义功能。

要想在模版中禁用全局自动转义功能，可以用 {% autoescaping %} 语句块:

{% autoescaping false %}
        <p>autoescaping is disableed here
        <p>{{ will_not_be_escaped }}
{% endautoescape %}

在这么做的时候，要语句块中使用到的变量非常小心。

引入过滤器¶

如果你想在Jinja2中引入你自己的过滤器，有2种方法可以做到。你可以把他们放在某个应用的 jinja_env 对象里面或者用 template_filter() 装饰器。

下面的两个例子都把对象的元素颠倒过来

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

def reverse_filter(s):
    return s[::-1]
app.jinja_env.filters['reverse'] = reverse_filter

在装饰器里，如果你想用函数的名字来做装饰器的名字，那么装饰器参数可以省略。

上下文处理器¶

Flask中的上下文处理器是为了把新的变量自动插入到模版的上下文。上下文处理器在模版被呈现之前运行，它可以把新的值插入到模版中。上下文处理器是一个返回一个字典的函数。字典的键名和键值会与模版中想对应的变量的进行合并

@app.context_processor
def inject_user():
        return dict(user=g.user)

上面的上下文处理器在模版创建了一个 user 的变量，它的值是 g.user 。这个例子不是很实用，因为 g 变量在模版中总是可以访问的，但是它展示了上下文处理器的使用方法。

要先有应用程序¶

首先，我们需要一个应用程序来进行测试；我们将使用 教程 作为我们的测试项目。如果你还没有的话，你可以在 示例项目 里获取代码。

测试骨架¶

为了测试这个项目，我们要新增一个模块 (flaskr_tests.py) 。 且在那里建立一个 unittest 的骨架:

import os
import flaskr
import unittest
import tempfile

class FlaskrTestCase(unittest.TestCase):

    def setUp(self):
        self.db_fd, flaskr.app.config['DATABASE'] = tempfile.mkstemp()
        flaskr.app.config['TESTING'] = True
        self.app = flaskr.app.test_client()
        flaskr.init_db()

    def tearDown(self):
        os.close(self.db_fd)
        os.unlink(flaskr.app.config['DATABASE'])

if __name__ == '__main__':
    unittest.main()

在 setUp() 方法内的代码会建立一个新的测试客户端并且初始化一个新的数据库。此方法会在测试方法执行前先被调用。为了在测试结束删除建立的数据库，我们选择在 tearDown() 方法内关闭并删除这个数据库文件。此外，在准备过程中配置标记将被激活。他的作用是在处理请求时禁用错误捕捉以便于你能在针对应用程序做测试时得到更详细的错误报告。

该测试客户端会提供一个简易的应用程序交互界面。我们可以通过它向应用程序触发测试请求， 测试客户端则会一手掌控所有信息。

由于SQLite3是一个基于文件系统的数据库形式，所以我们可以十分容易地使用临时文件的形式来建立一个临时的数据库并对其进行初始化。方法 mkstemp() 为我们做了两件事： 他返回了一个低级别的文件句柄和一个随机的文件名，后者就是我们使用的数据库文件名。我们只要保持有 db_fd 我们就能使用 os.close() 方法来关闭该文件。

如果我们现在运行测试套件，我们应该可以看到如下的输出结果:

$ python flaskr_tests.py

----------------------------------------------------------------------
Ran 0 tests in 0.000s

OK

尽管这个测试程序没有执行任何的实际测试，但是从这里我们可以看到我们的flaskr程序没有语法错误，否则在引入应用程序类库时就会抛出异常不再执行了。

处女测¶

现在是时候来测试应用程序的功能了。我们现在确认一下如果我们访问应用程序的根节点 (/)，应用程序应显示 “No entries here so far” 。我们在类里添加了一个新的方法来实现这个功能，如下:

class FlaskrTestCase(unittest.TestCase):

    def setUp(self):
        self.db_fd, flaskr.app.config['DATABASE'] = tempfile.mkstemp()
        self.app = flaskr.app.test_client()
        flaskr.init_db()

    def tearDown(self):
        os.close(self.db_fd)
        os.unlink(flaskr.DATABASE)

    def test_empty_db(self):
        rv = self.app.get('/')
        assert 'No entries here so far' in rv.data

注意我们的测试方法是以 test 开头的；这会让 unittest 模块自动将此方法作为测试方法来执行。

通过使用 self.app.get 我们可以把一个HTTP GET 请求通过给定的路径发送到应用程序。返回值是一个 response_class 对象。 我们现在可以用 data 属性来对应用程序进行核查。对应这个例子，我们需要核查 'No entries here so far' 是输出结果的一部分。

再将它执行一次你应该可以看到一次成功的测试结果:

$ python flaskr_tests.py
.
----------------------------------------------------------------------
Ran 1 test in 0.034s

OK

日志的输入输出¶

关于这个应用程序，其绝大部分功能是供给管理员使用的，所以我们需要一个途径来记录应用程序运行。为了达到这个目的，我们向登录和登出页面发送了一些带有表单数据（用户名和密码）的请求。由于登录登出请求会跳转页面，所以我们告诉客户端要它 follow_redirects （跟踪跳转）。

在你的 FlaskrTestCase 类里添加如下两个方法:

def login(self, username, password):
    return self.app.post('/login', data=dict(
        username=username,
        password=password
    ), follow_redirects=True)

def logout(self):
    return self.app.get('/logout', follow_redirects=True)

现在，我们就可以很方便的通过检查日志查看是否有非法登录的情况。在类里添加一个新的测试方法:

def test_login_logout(self):
    rv = self.login('admin', 'default')
    assert 'You were logged in' in rv.data
    rv = self.logout()
    assert 'You were logged out' in rv.data
    rv = self.login('adminx', 'default')
    assert 'Invalid username' in rv.data
    rv = self.login('admin', 'defaultx')
    assert 'Invalid password' in rv.data

测试添加功能¶

我们同时还需要测试添加消息的功能是否正常。再添加一个新的测试方法，像这样:

def test_messages(self):
    self.login('admin', 'default')
    rv = self.app.post('/add', data=dict(
        title='<Hello>',
        text='<strong>HTML</strong> allowed here'
    ), follow_redirects=True)
    assert 'No entries here so far' not in rv.data
    assert '&lt;Hello&gt;' in rv.data
    assert '<strong>HTML</strong> allowed here' in rv.data

这里，我们测试了HTML语法只能在内容里使用，而标题里不行。结果和预想的一样。

运行测试我们应该可以得到三条通过的测试结果:

$ python flaskr_tests.py
...
----------------------------------------------------------------------
Ran 3 tests in 0.332s

OK

对于那些更复杂的注入带有头和状态代码的测试，你可以在Flask的源码包里找到`MiniTwit Example`_ 项目，里面有更多更大型的测试用例。

其他测试技巧¶

除了使用上述的测试客户端意外，还可以通过使用方法 test_request_context() ，将其和 with 语句组合可以产生一个临时的请求上下文。通过此功能你可以像在视图功能里一样访问这些类 request,:class:~flask.g 和 session 。这里有一个使用此方法的完整例子:

app = flask.Flask(__name__)

with app.test_request_context('/?name=Peter'):
    assert flask.request.path == '/'
    assert flask.request.args['name'] == 'Peter'

所有其他上下文约束的对象都可以使用相同的方法。

如果你想要在不同的配置环境下测试应用程序，看起来好像没有什么好办法，可以考虑切换到应用程序工厂模式，(可查阅 应用程序的工厂模式).

注意不管你是否使用测试请求上下文，方法 before_request() 在方法:meth:~flask.Flask.after_request 被执行之前不一定会被执行。然而方法:meth:~flask.Flask.teardown_request 在测试方法离开 with 语块时一定会被执行。 如果你确实希望方法 before_request() 也被执行的话, 你需要自行调用:meth:~flask.Flask.preprocess_request 方法:

app = flask.Flask(__name__)

with app.test_request_context('/?name=Peter'):
    app.preprocess_request()
    ...

在打开数据库连接或做类似的工作时，这一步就显得十分必要。这取决于你是如何设计你的应用程序的。

保持现场¶

有时候我们需要触发一个常规的请求后将上下文现场保持一个较长的时间，以便于触发更多的内部检查。 有了 Flask 0.4 或以上版本，通过使用方法 test_client() 并加上 with 语块就可以做到了:

app = flask.Flask(__name__)

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

如果你使用了方法 test_client() 但是没有加上 with 语块, assert 语句会报错。这是因为这里的 request 不可用 (因为此操作在实际请求之外).不管如何, 记住任何 after_request() 方法在此时已经执行，所以你的数据库连接和其他所有操作可能已经被关闭了。

报错邮件¶

如果应用程序以生产模式运行（通常在服务器上你会这么做)，在默认情况下你不会看见任何的日志信息。 这是为什么呢？因为Flask是一个零配置框架，而如果没有配置的话，框架又应该把日志文件放到哪里去 呢？依靠假设并不是一个很好的方法，因为总是会存在各种不同的可能，也许那个我们假设放置日志的地方 用户并没有权限访问。另外，对于大多数小型的应用程序来说也不会有人去关注他的日志。

实际上，我可以向你保证即使你为你的程序配置了放置错误信息的日志文件，你也永远不会去查看他，除非 当你的用户向你报告了一个事件而你需要去排查错误的时候。你所需要的只是，当异常第二次发生时接收到 一封报警邮件，然后你在针对其中的情况进行处理。

Flask使用了python内置的日志系统，并且他会在你需要是向你发生关于异常的邮件。这里是一个关于如何 配置Flask的日志以向你发送异常邮件的例子:

ADMINS = ['yourname@example.com']
if not app.debug:
    import logging
    from logging.handlers import SMTPHandler
    mail_handler = SMTPHandler('127.0.0.1',
                               'server-error@example.com',
                               ADMINS, 'YourApplication Failed')
    mail_handler.setLevel(logging.ERROR)
    app.logger.addHandler(mail_handler)

这是如何操作的呢？我们创建了一个新的类 SMTPHandler ，他 将通过 127.0.0.1 的邮件服务器向所有的 ADMINS 用户发送标题为“YourApplication Failed” 邮件，并且将发件地址配置为 server-error@example.com 。此外，我们还提供了对 需要证书的邮件服务器的支持，关于这部分的文档，请查看 SMTPHandler 。

邮件处理器只会发送异常和错误的信息，因为我们并不希望通过邮件获取警告信息或其他一些处理过程中 产生的没有用的日志。

当你在产品中使用它们的时候，请务必查看 日志格式 以使得报错邮件中包含更多的信息。这 些信息将为你解决很多的烦恼。

日志文件¶

即使你已经有了报错邮件，你可能仍然希望能够查看到警告信息。为了排查问题，尽可能的保存更多的 信息不失为一个好主意。请注意，Flask的系统核心本身并不会去记录任何警告信息，因此编写记录那 些看起来不对劲的地方的代码将是你的责任。

这里提供了几个处理类，但对于基本的记录错误日志而言他们并不是总是那么的有用。而其中最值得我们 注意的是以下几项:

• FileHandler - 将日志信息写入文件系统中
• RotatingFileHandler - 将日志信息写入文件系统中，并且 当日志达到一定数量时会滚动记录最新的信息。
• NTEventLogHandler - 将日志发送到windows系统的日 志事件中。如果你的系统部署在windows环境中，那么这正是你想要的。
• SysLogHandler - 将日志发送到UNIX的系统日志中。

一旦你选择了你的日志处理类，你就可以向上文中配置SMTP处理类一样的来配置它们，唯一需要注意的 是使用更低级别的设置（我这里使用的是 WARNING ）:

if not app.debug:
    import logging
    from logging.handlers import TheHandlerYouWant
    file_handler = TheHandlerYouWant(...)
    file_handler.setLevel(logging.WARNING)
    app.logger.addHandler(file_handler)

日志格式¶

在默认情况下，处理器只会将日志信息写入文件或是用邮件发送给你。而日志应该记录更多的信息，你必须 配置你的日志，使它能够让你更方便的知道发生了什么样的错误，以及更重要的是告诉你哪里发生了错误。

格式处理器（formatter）可以让你获取格式化的字符串。你需要知道是日志的连接是自动进行的，你不需要 将它包含在格式处理器的格式化字符串中。

这里有几个例子：

from logging import Formatter
mail_handler.setFormatter(Formatter('''
Message type:       %(levelname)s
Location:           %(pathname)s:%(lineno)d
Module:             %(module)s
Function:           %(funcName)s
Time:               %(asctime)s

Message:

%(message)s
'''))

from logging import Formatter
file_handler.setFormatter(Formatter(
    '%(asctime)s %(levelname)s: %(message)s '
    '[in %(pathname)s:%(lineno)d]'
))

其他代码库¶

目前为止，我们只配置了你的程序自身的日志。而其他的代码库同样可以需要记录日志。比如，SQLAlchemy 使用了很多日志。使用 logging 包可以一次性的配置所有的日志，当我并不推荐那样做。因为当 多个程序在同一个Python解释器上运行是，你将无法单独的对他们进行配置。

相对的，我推荐你只对你所关注的日志进行配置，通过 getLogger() 方法获取 所有的日志处理器，并通过迭代获取他们:

from logging import getLogger
loggers = [app.logger, getLogger('sqlalchemy'),
           getLogger('otherlibrary')]
for logger in loggers:
    logger.addHandler(mail_handler)
    logger.addHandler(file_handler)

基本配置¶

config 实际上继承于字典（dictionary）类型，所以你可以像操作任何字典那样配置它：

app = Flask(__name__)
app.config['DEBUG'] = True

配置好的配置参数值也被包含在 Flask 对象中，你可以像这样读取、更改这些配置值：

app.debug = True

一次更新多个配置值，你可以使用 dict.update() 方法：

app.config.update(
    DEBUG=True,
    SECRET_KEY='...'
)

内置配置参数¶

以下配置参数是Flask中默认包含的：

使用配置文件¶

Configuration becomes more useful if you can configure from a file, and ideally that file would be outside of the actual application package so that you can install the package with distribute (Deploying with Distribute) and still modify that file afterwards.

So a common pattern is this:

app = Flask(__name__)
app.config.from_object('yourapplication.default_settings')
app.config.from_envvar('YOURAPPLICATION_SETTINGS')

This first loads the configuration from the yourapplication.default_settings module and then overrides the values with the contents of the file the YOURAPPLICATION_SETTINGS environment variable points to. This environment variable can be set on Linux or OS X with the export command in the shell before starting the server:

$ export YOURAPPLICATION_SETTINGS=/path/to/settings.cfg
$ python run-app.py
 * Running on http://127.0.0.1:5000/
 * Restarting with reloader...

On Windows systems use the set builtin instead:

>set YOURAPPLICATION_SETTINGS=\path\to\settings.cfg

The configuration files themselves are actual Python files. Only values in uppercase are actually stored in the config object later on. So make sure to use uppercase letters for your config keys.

Here is an example configuration file:

DEBUG = False
SECRET_KEY = '?\xbf,\xb4\x8d\xa3"<\x9c\xb0@\x0f5\xab,w\xee\x8d$0\x13\x8b83'

Make sure to load the configuration very early on so that extensions have the ability to access the configuration when starting up. There are other methods on the config object as well to load from individual files. For a complete reference, read the Config object’s documentation.

最佳配置实践¶

The downside with the approach mentioned earlier is that it makes testing a little harder. There is no one 100% solution for this problem in general, but there are a couple of things you can do to improve that experience:

1. create your application in a function and register blueprints on it. That way you can create multiple instances of your application with different configurations attached which makes unittesting a lot easier. You can use this to pass in configuration as needed.
2. Do not write code that needs the configuration at import time. If you limit yourself to request-only accesses to the configuration you can reconfigure the object later on as needed.

开发 / 产品¶

Most applications need more than one configuration. There will at least be a separate configuration for a production server and one used during development. The easiest way to handle this is to use a default configuration that is always loaded and part of version control, and a separate configuration that overrides the values as necessary as mentioned in the example above:

app = Flask(__name__)
app.config.from_object('yourapplication.default_settings')
app.config.from_envvar('YOURAPPLICATION_SETTINGS')

Then you just have to add a separate config.py file and export YOURAPPLICATION_SETTINGS=/path/to/config.py and you are done. However there are alternative ways as well. For example you could use imports or subclassing.

What is very popular in the Django world is to make the import explicit in the config file by adding an from yourapplication.default_settings import * to the top of the file and then overriding the changes by hand. You could also inspect an environment variable like YOURAPPLICATION_MODE and set that to production, development etc and import different hardcoded files based on that.

An interesting pattern is also to use classes and inheritance for configuration:

class Config(object):
    DEBUG = False
    TESTING = False
    DATABASE_URI = 'sqlite://:memory:'

class ProductionConfig(Config):
    DATABASE_URI = 'mysql://user@localhost/foo'

class DevelopmentConfig(Config):
    DEBUG = True

class TestingConfig(Config):
    TESTING = True

开启这个配置你需要调用 from_object() ：

app.config.from_object('configmodule.ProductionConfig')

There are many different ways and it’s up to you how you want to manage your configuration files. However here a list of good recommendations:

• keep a default configuration in version control. Either populate the config with this default configuration or import it in your own configuration files before overriding values.
• use an environment variable to switch between the configurations. This can be done from outside the Python interpreter and makes development and deployment much easier because you can quickly and easily switch between different configs without having to touch the code at all. If you are working often on different projects you can even create your own script for sourcing that activates a virtualenv and exports the development configuration for you.
• Use a tool like fabric in production to push code and configurations separately to the production server(s). For some details about how to do that, head over to the Deploying with Fabric pattern.

Subscribing to Signals¶

To subscribe to a signal, you can use the connect() method of a signal. The first argument is the function that should be called when the signal is emitted, the optional second argument specifies a sender. To unsubscribe from a signal, you can use the disconnect() method.

For all core Flask signals, the sender is the application that issued the signal. When you subscribe to a signal, be sure to also provide a sender unless you really want to listen for signals of all applications. This is especially true if you are developing an extension.

Here for example a helper context manager that can be used to figure out in a unittest which templates were rendered and what variables were passed to the template:

from flask import template_rendered
from contextlib import contextmanager

@contextmanager
def captured_templates(app):
    recorded = []
    def record(sender, template, context):
        recorded.append((template, context))
    template_rendered.connect(record, app)
    try:
        yield recorded
    finally:
        template_rendered.disconnect(record, app)

This can now easily be paired with a test client:

with captured_templates(app) as templates:
    rv = app.test_client().get('/')
    assert rv.status_code == 200
    assert len(templates) == 1
    template, context = templates[0]
    assert template.name == 'index.html'
    assert len(context['items']) == 10

All the template rendering in the code issued by the application app in the body of the with block will now be recorded in the templates variable. Whenever a template is rendered, the template object as well as context are appended to it.

Additionally there is a convenient helper method (connected_to()). that allows you to temporarily subscribe a function to a signal with is a context manager on its own. Because the return value of the context manager cannot be specified that way one has to pass the list in as argument:

from flask import template_rendered

def captured_templates(app, recorded):
    def record(sender, template, context):
        recorded.append((template, context))
    return template_rendered.connected_to(record, app)

The example above would then look like this:

templates = []
with captured_templates(app, templates):
    ...
    template, context = templates[0]

Creating Signals¶

If you want to use signals in your own application, you can use the blinker library directly. The most common use case are named signals in a custom Namespace.. This is what is recommended most of the time:

from blinker import Namespace
my_signals = Namespace()

Now you can create new signals like this:

model_saved = my_signals.signal('model-saved')

The name for the signal here makes it unique and also simplifies debugging. You can access the name of the signal with the name attribute.

Sending Signals¶

If you want to emit a signal, you can do so by calling the send() method. It accepts a sender as first argument and optionally some keyword arguments that are forwarded to the signal subscribers:

class Model(object):
    ...

    def save(self):
        model_saved.send(self)

Try to always pick a good sender. If you have a class that is emitting a signal, pass self as sender. If you emitting a signal from a random function, you can pass current_app._get_current_object() as sender.

Decorator Based Signal Subscriptions¶

With Blinker 1.1 you can also easily subscribe to signals by using the new connect_via() decorator:

from flask import template_rendered

@template_rendered.connect_via(app)
def when_template_rendered(sender, template, context):
    print 'Template %s is rendered with %s' % (template.name, context)

Core Signals¶

The following signals exist in Flask:

flask.template_rendered

This signal is sent when a template was successfully rendered. The signal is invoked with the instance of the template as template and the context as dictionary (named context).

Example subscriber:

def log_template_renders(sender, template, context):
    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.request_started

This signal is sent before any request processing started but when the request context was set up. Because the request context is already bound, the subscriber can access the request with the standard global proxies such as request.

Example subscriber:

def log_request(sender):
    sender.logger.debug('Request context is set up')

from flask import request_started
request_started.connect(log_request, app)

flask.request_finished

This signal is sent right before the response is sent to the client. It is passed the response to be sent named response.

Example subscriber:

def log_response(sender, response):
    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

This signal is sent when an exception happens during request processing. It is sent before the standard exception handling kicks in and even in debug mode, where no exception handling happens. The exception itself is passed to the subscriber as exception.

Example subscriber:

def log_exception(sender, exception):
    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

This signal is sent when the request is tearing down. This is always called, even if an exception is caused. Currently functions listening to this signal are called after the regular teardown handlers, but this is not something you can rely on.

Example subscriber:

def close_db_connection(sender):
    session.close()

from flask import request_tearing_down
request_tearing_down.connect(close_db_connection, app)

Basic Principle¶

Consider you have a function that loads a list of objects from the database and renders into a template:

@app.route('/users/')
def show_users(page):
    users = User.query.all()
    return render_template('users.html', users=users)

This is simple and flexible, but if you want to provide this view in a generic fashion that can be adapted to other models and templates as well you might want more flexibility. This is where pluggable class based views come into place. As the first step to convert this into a class based view you would do this:

from flask.views import View

class ShowUsers(View):

    def dispatch_request(self):
        users = User.query.all()
        return render_template('users.html', objects=users)

app.add_url_rule('/users/', ShowUsers.as_view('show_users'))

As you can see what you have to do is to create a subclass of flask.views.View and implement dispatch_request(). Then we have to convert that class into an actual view function by using the as_view() class method. The string you pass to that function is the name of the endpoint that view will then have. But this by itself is not helpful, so let’s refactor the code a bit:

from flask.views import View

class ListView(View):

    def get_template_name(self):
        raise NotImplementedError()

    def render_template(self, context):
        return render_template(self.get_template_name(), **context)

    def dispatch_request(self):
        context = {'objects': self.get_objects()}
        return self.render_template(context)

class UserView(ListView):

    def get_template_name(self):
        return 'users.html'

    def get_objects(self):
        return User.query.all()

This of course is not that helpful for such a small example, but it’s good enough to explain the basic principle. When you have a class based view the question comes up what self points to. The way this works is that whenever the request is dispatched a new instance of the class is created and the dispatch_request() method is called with the parameters from the URL rule. The class itself is instanciated with the parameters passed to the as_view() function. For instance you can write a class like this:

class RenderTemplateView(View):
    def __init__(self, template_name):
        self.template_name = template_name
    def dispatch_request(self):
        return render_template(self.template_name)

And then you can register it like this:

app.add_url_rule('/about', view_func=RenderTemplateView.as_view(
    'about_page', template_name='about.html'))

Method Hints¶

Pluggable views are attached to the application like a regular function by either using route() or better add_url_rule(). That however also means that you would have to provide the names of the HTTP methods the view supports when you attach this. In order to move that information to the class you can provide a methods attribute that has this information:

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

    def dispatch_request(self):
        if request.method == 'POST':
            ...
        ...

app.add_url_rule('/myview', view_func=MyView.as_view('myview'))

Method Based Dispatching¶

For RESTful APIs it’s especially helpful to execute a different function for each HTTP method. With the flask.views.MethodView you can easily do that. Each HTTP method maps to a function with the same name (just in lowercase):

from flask.views import MethodView

class UserAPI(MethodView):

    def get(self):
        users = User.query.all()
        ...

    def post(self):
        user = User.from_form_data(request.form)
        ...

app.add_url_rule('/users/', view_func=UserAPI.as_view('users'))

That way you also don’t have to provide the methods attribute. It’s automatically set based on the methods defined in the class.

Diving into Context Locals¶

Say you have a utility function that returns the URL the user should be redirected to. Imagine it would always redirect to the URL’s next parameter or the HTTP referrer or the index page:

from flask import request, url_for

def redirect_url():
    return request.args.get('next') or \
           request.referrer or \
           url_for('index')

As you can see, it accesses the request object. If you try to run this from a plain Python shell, this is the exception you will see:

>>> redirect_url()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'NoneType' object has no attribute 'request'

That makes a lot of sense because we currently do not have a request we could access. So we have to make a request and bind it to the current context. The test_request_context method can create us a RequestContext:

>>> ctx = app.test_request_context('/?next=http://example.com/')

This context can be used in two ways. Either with the with statement or by calling the push() and pop() methods:

>>> ctx.push()

From that point onwards you can work with the request object:

>>> redirect_url()
u'http://example.com/'

Until you call pop:

>>> ctx.pop()

Because the request context is internally maintained as a stack you can push and pop multiple times. This is very handy to implement things like internal redirects.

For more information of how to utilize the request context from the interactive Python shell, head over to the Working with the Shell chapter.

How the Context Works¶

If you look into how the Flask WSGI application internally works, you will find a piece of code that looks very much like this:

def wsgi_app(self, environ):
    with self.request_context(environ):
        try:
            response = self.full_dispatch_request()
        except Exception, e:
            response = self.make_response(self.handle_exception(e))
        return response(environ, start_response)

The method request_context() returns a new RequestContext object and uses it in combination with the with statement to bind the context. Everything that is called from the same thread from this point onwards until the end of the with statement will have access to the request globals (flask.request and others).

The request context internally works like a stack: The topmost level on the stack is the current active request. push() adds the context to the stack on the very top, pop() removes it from the stack again. On popping the application’s teardown_request() functions are also executed.

Callbacks and Errors¶

What happens if an error occurs in Flask during request processing? This particular behavior changed in 0.7 because we wanted to make it easier to understand what is actually happening. The new behavior is quite simple:

1. Before each request, before_request() functions are executed. If one of these functions return a response, the other functions are no longer called. In any case however the return value is treated as a replacement for the view’s return value.
2. If the before_request() functions did not return a response, the regular request handling kicks in and the view function that was matched has the chance to return a response.
3. The return value of the view is then converted into an actual response object and handed over to the after_request() functions which have the chance to replace it or modify it in place.
4. At the end of the request the teardown_request() functions are executed. This always happens, even in case of an unhandled exception down the road.

Now what happens on errors? In production mode if an exception is not caught, the 500 internal server handler is called. In development mode however the exception is not further processed and bubbles up to the WSGI server. That way things like the interactive debugger can provide helpful debug information.

An important change in 0.7 is that the internal server error is now no longer post processed by the after request callbacks and after request callbacks are no longer guaranteed to be executed. This way the internal dispatching code looks cleaner and is easier to customize and understand.

The new teardown functions are supposed to be used as a replacement for things that absolutely need to happen at the end of request.

Teardown Callbacks¶

The teardown callbacks are special callbacks in that they are executed at at different point. Strictly speaking they are independent of the actual request handling as they are bound to the lifecycle of the RequestContext object. When the request context is popped, the teardown_request() functions are called.

This is important to know if the life of the request context is prolonged by using the test client in a with statement of when using the request context from the command line:

with app.test_client() as client:
    resp = client.get('/foo')
    # the teardown functions are still not called at that point
    # even though the response ended and you have the response
    # object in your hand

# only when the code reaches this point the teardown functions
# are called.  Alternatively the same thing happens if another
# request was triggered from the test client

It’s easy to see the behavior from the command line:

>>> app = Flask(__name__)
>>> @app.teardown_request
... def teardown_request(exception=None):
...     print 'this runs after request'
...
>>> ctx = app.test_request_context()
>>> ctx.push()
>>> ctx.pop()
this runs after request
>>>

Notes On Proxies¶

Some of the objects provided by Flask are proxies to other objects. The reason behind this is that these proxies are shared between threads and they have to dispatch to the actual object bound to a thread behind the scenes as necessary.

Most of the time you don’t have to care about that, but there are some exceptions where it is good to know that this object is an actual proxy:

• The proxy objects do not fake their inherited types, so if you want to perform actual instance checks, you have to do that on the instance that is being proxied (see _get_current_object below).
• if the object reference is important (so for example for sending Signals 信号)

If you need to get access to the underlying object that is proxied, you can use the _get_current_object() method:

app = current_app._get_current_object()
my_signal.send(app)

Context Preservation on Error¶

If an error occurs or not, at the end of the request the request context is popped and all data associated with it is destroyed. During development however that can be problematic as you might want to have the information around for a longer time in case an exception occurred. In Flask 0.6 and earlier in debug mode, if an exception occurred, the request context was not popped so that the interactive debugger can still provide you with important information.

Starting with Flask 0.7 you have finer control over that behavior by setting the PRESERVE_CONTEXT_ON_EXCEPTION configuration variable. By default it’s linked to the setting of DEBUG. If the application is in debug mode the context is preserved, in production mode it’s not.

Do not force activate PRESERVE_CONTEXT_ON_EXCEPTION in production mode as it will cause your application to leak memory on exceptions. However it can be useful during development to get the same error preserving behavior as in development mode when attempting to debug an error that only occurs under production settings.

Why Blueprints?¶

Blueprints in Flask are intended for these cases:

• Factor an application into a set of blueprints. This is ideal for larger applications; a project could instantiate an application object, initialize several extensions, and register a collection of blueprints.
• Register a blueprint on an application at a URL prefix and/or subdomain. Parameters in the URL prefix/subdomain become common view arguments (with defaults) across all view functions in the blueprint.
• Register a blueprint multiple times on an application with different URL rules.
• Provide template filters, static files, templates, and other utilities through blueprints. A blueprint does not have to implement applications or view functions.
• Register a blueprint on an application for any of these cases when initializing a Flask extension.

A blueprint in Flask is not a pluggable app because it is not actually an application – it’s a set of operations which can be registered on an application, even multiple times. Why not have multiple application objects? You can do that (see 应用程序的派遣), but your applications will have separate configs and will be managed at the WSGI layer.

Blueprints instead provide separation at the Flask level, share application config, and can change an application object as necessary with being registered. The downside is that you cannot unregister a blueprint once application without having to destroy the whole application object.

The Concept of Blueprints¶

The basic concept of blueprints is that they record operations to execute when registered on an application. Flask associates view functions with blueprints when dispatching requests and generating URLs from one endpoint to another.

My First Blueprint¶

This is what a very basic blueprint looks like. In this case we want to implement a blueprint that does simple rendering of static templates:

from flask import Blueprint, render_template, abort
from jinja2 import TemplateNotFound

simple_page = Blueprint('simple_page', __name__)

@simple_page.route('/', defaults={'page': 'index'})
@simple_page.route('/<page>')
def show(page):
    try:
        return render_template('pages/%s.html' % page)
    except TemplateNotFound:
        abort(404)

When you bind a function with the help of the @simple_page.route decorator the blueprint will record the intention of registering the function show on the application when it’s later registered. Additionally it will prefix the endpoint of the function with the name of the blueprint which was given to the Blueprint constructor (in this case also simple_page).

Registering Blueprints¶

So how do you register that blueprint? Like this:

from flask import Flask
from yourapplication.simple_page import simple_page

app = Flask(__name__)
app.register_blueprint(simple_page)

If you check the rules registered on the application, you will find these:

[<Rule '/static/<filename>' (HEAD, OPTIONS, GET) -> static>,
 <Rule '/<page>' (HEAD, OPTIONS, GET) -> simple_page.show>,
 <Rule '/' (HEAD, OPTIONS, GET) -> simple_page.show>]

The first one is obviously from the application ifself for the static files. The other two are for the show function of the simple_page blueprint. As you can see, they are also prefixed with the name of the blueprint and separated by a dot (.).

Blueprints however can also be mounted at different locations:

app.register_blueprint(simple_page, url_prefix='/pages')

And sure enough, these are the generated rules:

[<Rule '/static/<filename>' (HEAD, OPTIONS, GET) -> static>,
 <Rule '/pages/<page>' (HEAD, OPTIONS, GET) -> simple_page.show>,
 <Rule '/pages/' (HEAD, OPTIONS, GET) -> simple_page.show>]

On top of that you can register blueprints multiple times though not every blueprint might respond properly to that. In fact it depends on how the blueprint is implemented if it can be mounted more than once.

Blueprint Resources¶

Blueprints can provide resources as well. Sometimes you might want to introduce a blueprint only for the resources it provides.

>>> simple_page.root_path
'/Users/username/TestProject/yourapplication'

with simple_page.open_resource('static/style.css') as f:
    code = f.read()

admin = Blueprint('admin', __name__, static_folder='static')

url_for('admin.static', filename='style.css')

admin = Blueprint('admin', __name__, template_folder='templates')

Building URLs¶

If you want to link from one page to another you can use the url_for() function just like you normally would do just that you prefix the URL endpoint with the name of the blueprint and a dot (.):

url_for('admin.index')

Additionally if you are in a view function of a blueprint or a rendered template and you want to link to another endpoint of the same blueprint, you can use relative redirects by prefixing the endpoint with a dot only:

url_for('.index')

This will link to admin.index for instance in case the current request was dispatched to any other admin blueprint endpoint.

Creating a Request Context¶

The easiest way to create a proper request context from the shell is by using the test_request_context method which creates us a RequestContext:

>>> ctx = app.test_request_context()

Normally you would use the with statement to make this request object active, but in the shell it’s easier to use the push() and pop() methods by hand:

>>> ctx.push()

From that point onwards you can work with the request object until you call pop:

>>> ctx.pop()

Firing Before/After Request¶

By just creating a request context, you still don’t have run the code that is normally run before a request. This might result in your database being unavailable if you are connecting to the database in a before-request callback or the current user not being stored on the g object etc.

This however can easily be done yourself. Just call preprocess_request():

>>> ctx = app.test_request_context()
>>> ctx.push()
>>> app.preprocess_request()

Keep in mind that the preprocess_request() function might return a response object, in that case just ignore it.

To shutdown a request, you need to trick a bit before the after request functions (triggered by process_response()) operate on a response object:

>>> app.process_response(app.response_class())
<Response 0 bytes [200 OK]>
>>> ctx.pop()

The functions registered as teardown_request() are automatically called when the context is popped. So this is the perfect place to automatically tear down resources that were needed by the request context (such as database connections).

Further Improving the Shell Experience¶

If you like the idea of experimenting in a shell, create yourself a module with stuff you want to star import into your interactive session. There you could also define some more helper methods for common things such as initializing the database, dropping tables etc.

Just put them into a module (like shelltools and import from there):

>>> from shelltools import *