快速上手

迫不及待要开始了么?本文会给你好好介绍如何上手 Flask 。 这里假定你已经安装好了 Flask ,否则请先阅读《 安装 》。

一个最小的应用

最小Flask应用程序如下所示:

from flask import Flask
app = Flask(__name__)

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

那么,这段代码做了什么?

  1. 首先我们导入了 Flask 类。该类的实例将会成为我们的 WSGI 应用。
  2. 接着我们创建一个该类的实例。第一个参数是应用模块或者包的名称。如果你使用 一个单一模块(就像本例),那么应当使用 __name__ ,因为名称会根据这个 模块是按应用方式使用还是作为一个模块导入而发生变化(可能是 ‘__main__’ , 也可能是实际导入的名称)。这个参数是必需的,这样 Flask 才能知道在哪里可以 找到模板和静态文件等东西。更多内容详见 Flask 文档。
  3. 然后我们使用 route() 装饰器来告诉 Flask 什么样的 URL可以触发函数 。
  4. 函数名称被用于生成相关联的 URL 。函数最后返回想要在用户浏览器中显示的信息。

把它保存为 hello.py 或其他类似名称。请不要使用 flask.py 作为应用名称,这会与 Flask 本身发生冲突。

可以使用 flask 命令或者 python 的 -m 开关来运行这个应用。在 运行应用之前,需要在终端里导出 FLASK_APP 环境变量:

$ export FLASK_APP=hello.py
$ flask run
 * Running on http://127.0.0.1:5000/

如果您在Windows上,环境变量语法取决于命令行解释器。在命令提示下::

C:\path\to\app>set FLASK_APP=hello.py

在PowerShell上:

PS C:\path\to\app> $env:FLASK_APP = "hello.py"

或者你可以使用 python -m flask ::

$ export FLASK_APP=hello.py
$ python -m flask run
 * Running on http://127.0.0.1:5000/

这将启动一个非常简单的内置服务器,这对于测试来说已经足够了,但是 用于生产可能是不够的。关于部署的有关内容参见《 部署方式 》。

现在在浏览器中打开 http://127.0.0.1:5000/ ,应该 可以看到 Hello World! 字样。

外部可见的服务器

如果运行服务器,你会发现服务器只能从你自己的计算机访问,而不能从网络中的任何其他计算机访问。这是默认设置,因为在调试模式下,应用程序的用户可以在您的计算机上执行任意的python代码。

如果禁用了调试器或信任网络上的用户,你可以简单修改调用run()的方式使你的服务器公开可用。

$ flask run --host=0.0.0.0

这会让你的操作系统监听所有公共IP。

如果服务器不能启动,该怎么办

假如运行 python -m flask 命令失败或者 flask 命令不存在,那么可能会有多种原因导致失败。首先应该检查错误信息。

旧版Flask

早于0.11的Flask版本使用不同的方法启动应用程序。简而言之,简单的说就是 flask 和 python -m flask 命令都无法使用。在这种情况有 两个选择:一是升级 Flask 到更新的版本,二是参阅《 开发服务器 》,学习其他启动服务器的方法。

导入名称无效

这个 FLASK_APP 环境变量是要导入的模块的名称, 运行 flask run 命令就会导入这个模块。 如果该模块的名称不正确,您将在启动时收到导入错误。如果调试模式打开的情况下,会在运行到应用开始的时候出现导入错误。出错信息会告诉你尝试导入哪个模块时出错,为什么会出错。

最常见的原因是打字错误,或者因为你没有真正创建一个 app 对象。

调试模式

(只需要记录出错信息和追踪堆栈?参见 应用错误处理 )

虽然 flask 命令很适合启动本地开发服务器,但每次对代码进行更改后,都必须手动重新启动它。这样不是很方便, Flask 可以做得更好。如果启用调试支持,服务器将在代码更改时自动重新加载,如果出现问题,它还将为您提供一个有用的调试器。

想要启用所有开发功能(包括调试模式),可以在运行服务器之前导出 FLASK_ENV 环境变量并将其设置为 development

$ export FLASK_ENV=development
$ flask run

(在Windows上,需要使用 set 而不是 export

这样可以实现以下功能:

  1. 激活调试器
  2. 启动自动重新加载
  3. 在flask应用程序上启用调试模式。

还可以通过导出 FLASK_DEBUG=1 来单独控制调试模式的开关。

开发服务器 文档中还有更多的参数说明。

注意

虽然交互调试器不能在分布环境下工作(这使得它基本不可能用于生产环境),但是 它允许执行任意代码,这样会成为一个重大安全隐患。因此, 绝对不能在生产环境 中使用调试器 。

运行的调试器的屏幕截图:

screenshot of debugger in action

有关使用调试器的详细信息,请参见 Werkzeug documentation .

是否考虑使用另一个调试器?请参阅 使用调试器 。

路由

现代Web应用都使用有意义的URL,这样有易于人们辨识记忆。用户都喜欢可以不访问索引页就可以直接访问想要的那个页面。

使用 route() 装饰器来把函数绑定到对应的 URL:

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

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

但是能做的不仅仅是这些!你可以使URL的某些部分成为动态的,并将多个规则附加到一个函数。

变量规则

通过把 URL 的一部分标记为 <variable_name> 就可以在 URL 中添加变量。标记的部分会作为关键字参数传递给函数。通过使用 <converter:variable_name> ,可以选择性的加上一个转换器,为变量指定规则。请看下面的例子:

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

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

@app.route('/path/<path:subpath>')
def show_subpath(subpath):
    # show the subpath after /path/
    return 'Subpath %s' % subpath

转换器类型:

string (默认)接受没有斜线的任何文本
int 接受正整数
float 接受正浮点值
path 类似 string ,但可以包含斜杠
uuid 接受UUID字符串

唯一的URL/重定向行为

以下两条规则的不同之处在于是否使用尾部的斜杠。:

@app.route('/projects/')
def projects():
    return 'The project page'

@app.route('/about')
def about():
    return 'The about page'

projects 的 URL 是中规中举的,尾部有一个斜杠,看起来就如同一个文件夹。访问一个没有斜杠结尾的 URL 时 Flask 会自动进行重定向,帮你在尾部加上一个斜杠。

about 的 URL 没有尾部斜杠,因此其行为表现与一个文件类似。如果访问这个 URL 时添加了尾部斜杠就会得到一个 404 错误。这样可以保持 URL 唯一,并帮助 搜索引擎避免重复索引同一页面。

URL构建

url_for() 函数用于构建指定函数的 URL。它把函数名称作为第一个参数。它可以接受任意个关键字参数,每个关键字参数对应 URL 中的变量。未知变量 将添加到 URL 中作为查询参数。

为什么要使用URL反转函数生成URL,而非在模板中硬编码?

  1. 反转通常比硬编码URL更具描述性。
  2. 你可以只在一个地方改变 URL ,而不用到处乱找。
  3. URL 创建会为你处理特殊字符的转义和 Unicode 数据,比较直观。
  4. 生成的路径总是绝对的,可以避免相对路径产生副作用。
  5. 如果你的应用是放在 URL 根路径之外的地方(如在 /myapplication 中,不在 / 中), url_for() 会为你妥善处理。

例如,这里我们使用 test_request_context() 方法来尝试使用 url_for() 。 test_request_context() 告诉 Flask 正在处理一个请求,而实际上也许我们正处在交互 Python shell 之中, 并没有真正的请求。参见 本地环境 。

from flask import Flask, url_for

app = Flask(__name__)

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

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

@app.route('/user/<username>')
def profile(username):
    return '{}\'s profile'.format(username)

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

HTTP方法

Web应用程序在访问URL时使用不同的HTTP方法。在使用flask时,应该熟悉HTTP方法。默认情况下,一个路由只回应 GET 请求。可以使用 route() 装饰器的 methods 参数来处理不同的 HTTP 方法:

from flask import request

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

如果当前使用了 GET 方法, Flask 会自动添加 HEAD 方法支持,并且同时还会 按照 HTTP RFC 来处理 HEAD 请求。同样, OPTIONS 也会自动实现。

静态文件

动态Web应用程序还需要静态文件。通常是css和javascript文件。理想情况下,你的Web服务器已经配置好了为你提供静态文件服务,但在开发期间,Flask也可以这样做。只要在你的包或模块旁边创建一个名为 static 的文件夹就行了。 静态文件位于应用的 /static 中。

使用特定的 'static' 端点就可以生成相应的 URL

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 文件夹内寻找模板。因此,如果你的应用是一个模块, 那么模板文件夹应该在模块旁边;如果是一个包,那么就应该在包里面:

情形1: 一个模板:

/application.py
/templates
    /hello.html

情形2: 一个包:

/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 %}

在模板内部可以和访问 get_flashed_messages() 函数一样访问 request 、 session 和 g [1] 对象。

模板继承让模板用起来相当顺手。如果你想知道它是如何工作的,其工作原理参见 模板继承 方案文档。简单的说,模板继承可以使每个页面的特定元素(如页头、导航和页尾) 保持一致。

自动转义默认是开启的。因此,如果 name 包含 HTML ,那么会被自动转义。如果你可以 信任某个变量,且知道它是安全的 HTML (例如变量来自一个把 wiki 标记转换为 HTML 的模块),那么可以使用 Markup 类把它标记为安全的,或者在模板 中使用 |safe 过滤器。更多例子参见 Jinja 2 文档。

这下面 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'

在 0.5 版更改: 自动转义不再在所有的模板中启用。下列扩展名的模板会触发自动转义:.html, .htm, .xml, .xhtml。从字符串加载的模板会禁用自动转义。

Changelog
[1]不确定什么是 g 对象?它是某个可以根据需要储存信息的 东西。更多信息参见 g 对象的文档和 使用 SQLite 3 文档。

访问请求数据

对于 web 应用来说对客户端向服务器发送的数据作出响应很重要。在 Flask 中由全局 对象 request 来提供请求信息。如果你有一些 Python 基础,那么 可能会奇怪:既然这个对象是全局的,怎么还能保持线程安全?答案是本地环境:

环境局部变量

内幕消息

如果你想了解工作原理和如何使用局部环境进行测试,那么请阅读本节, 否则可以跳过本节。

某些对象在 Flask 中是全局对象,但不是通常意义下的全局对象。这些对象实际上是 特定环境下局部对象的代理。虽然很拗口,但还是很容易理解的。

设想现在处于处理线程的环境中。一个请求传入,服务器决定生成一个新线程(或者别的什么东西,这个底层的东西能够处理包括线程在内的并发系统)。当 Flask 开始其内部请求处理时会把当前线程作为活动环境,并把当前应用和 WSGI 环境绑定到这个环境(线程)上。它以一种聪明的方式使得一个应用可以在不中断的情况下调用另一个应用上。

这对你意味着什么?基本上你可以完全不必理会。这个只有在做类似单元测试时才有用。在测试时会遇到由于没有请求对象而导致依赖于请求的代码会突然崩溃的情况。解决方案是自己创建一个请求对象并绑定到环境。最简单的单元测试解决方案是使用 test_request_context() 环境管理器。通过使用 with 声明可以绑定一个测试请求,以便于交互。例如:

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'

另一种可能性是将整个WSGi环境传递给 request_context() 方法:

from flask import request

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

请求对象

API章节对请求对象做了详尽阐述(参见request),因此这里不会赘述。此处宽泛介绍一些最常用的操作。首先从Flask模块里导入它:

from flask import request

通过使用 method 属性可以操作当前请求方法,通过使用 form 属性处理表单数据(在 POST 或者 PUT 请求中传输的数据)。以下是使用上述两个属性的例子:

@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'
    # the code below is executed if the request method
    # was GET or the credentials were invalid
    return render_template('login.html', error=error)

当 form 属性中不存在这个键时会发生什么?会引发一个 KeyError 的异常。 如果你不像捕捉一个标准错误一样捕捉 KeyError,那么会显示一个 HTTP 400 Bad Request 错误页面。因此,多数情况下你不必处理这个问题。

你可以使用args 属性来访问在URL中提交的参数( ?key=value ):

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

我们建议使用 get 或通过捕捉 KeyError 来访问 URL 参数。因为在这种情况下,用户可能会更改URL导致一个400错误的请求页面,这样会影响用户体验。

要获得请求对象的方法和属性的完整列表,请参阅Request文档。

文件上传

你可以用flask轻松处理上传的文件。只要确保不要忘记在HTM里设置 enctype="multipart/form-data" 属性,否则浏览器根本不会发送文件。

已上传的文件被储存在内存或文件系统的临时位置。你可以通过请求对象 files 属性来访问上传的文件。每个上传的文件都储存在这个字典型属性中。这个属性基本和标准 Python file 对象一样,另外多出一个用于把上传文件保存到服务器的文件系统中的 save() 方法。下面是一个简单的例子,演示了它的工作原理:

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')
    ...

如果想要知道文件上传之前其在客户端系统中的名称,可以使用 filename 属性。但是请记住,这个值是可以伪造的,所以永远不要相信这个值。如果想要把客户端的文件名作为服务器上的文件名,可以通过 Werkzeug 提供的 secure_filename() 函数:

from flask import request
from werkzeug.utils 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))
    ...

要获得更好的示例,请参见 上传文件 方案。

Cookies

可以使用 cookies 属性来访问 cookies 。可以使用响应对象的 set_cookie 方法来设置 cookies 。请求对象的 cookies 属性是一个包含了客户端传输的所有 cookies 的字典。在 Flask 中,如果使用会话,那么就不要直接使用 cookies ,请参考会话一节。

读取cookie::

from flask import request

@app.route('/')
def index():
    username = request.cookies.get('username')
    # use cookies.get(key) instead of cookies[key] to not get a
    # KeyError if the cookie is missing.

存储cookie::

from flask import make_response

@app.route('/')
def index():
    resp = make_response(render_template(...))
    resp.set_cookie('username', 'the username')
    return resp

请注意, cookies 是设置在响应对象上。通常只是从视图函数返回字符串,Flask 会把它们转换为响应对象。如果你想显式地转换,那么可以使用 make_response() 函数,然后再修改它。

使用延迟的请求回调方案可以在没有响应对象的情况下设置一个 cookie 。

有关此信息,请参见 :about-responses。

重定向和错误

使用 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 表示禁止访问)。但是上例可以说明重定向和出错跳出是如何工作的。

默认情况下,每个错误代码都会显示一个黑白错误页。如果要自定义错误页,可以使用 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 ,这表示页面对应的出错代码是 404 ,即页面不存在。默认为 200 表示:一切正常。

详见 错误处理 。

关于响应

视图函数的返回值将自动转换为一个响应对象。如果返回值是一个字符串,则将其转换为一个包含作为响应体的字符串、一个 200 OK 出错代码和一个 text/html 类型的响应对象。以下是转换的规则:

  1. 如果返回的是一个合法的响应对象,它会从视图直接返回。
  2. 如果返回的是一个字符串,响应对象会用字串符数据和默认参数创建。
  3. 如果返回的是一个元组,那么元组中的元素可以提供额外的信息。这样的元组应当由 (response, status, headers) 或者 (response, headers) 组成,并且至少包含一个元素。 status 的值会重载状态代码, headers可以是一个列表或字典,作为额外的消息标头值。
  4. 如果以上都不是,那么 Flask 会假定返回值是一个有效的 WSGI 应用并把它转换为 一个响应对象。

如果要在视图中获取响应对象的结果,可以使用make_response函数。

比如你有这样一个视图:

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

你只需要把返回值表达式传递给make_response,获取响应对象并修改它,然后返回它:

@app.errorhandler(404)
def not_found(error):
    resp = make_response(render_template('error.html'), 404)
    resp.headers['X-Something'] = 'A value'
    return resp

会话

除了请求对象,还有一个名为 session 的对象,允许你在不同请求之间储存信息。这个对象相当于用密钥签名加密的 cookie ,即用户可以查看你的 cookie ,但是如果没有密钥就无法修改它。

要使用会话,你必须设置一个密钥。以下是会话的工作方式:

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

app = Flask(__name__)

# Set the secret key to some random bytes. Keep this really secret!
app.secret_key = b'_5#y2L"F4Q8z\n\xec]/'

@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 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 it's there
    session.pop('username', None)
    return redirect(url_for('index'))

这里用到的 escape() 是用来转义的。如果不使用模板引擎就可以像上例一样使用这个函数来转义。

如何生成好的密钥

一个好的密钥应当有足够的随机性。 操作系统可以有多种方式基于密码随机生成器来生成随机数据。使用下面的命令可以快捷的为 Flask.secret_key ( 或者 SECRET_KEY )生成值:

$ python -c 'import os; print(os.urandom(16))'
b'_5#y2L"F4Q8z\n\xec]/'

使用基于cookie的会话需要注意:Flask 会取出会话对象中的值,把值序列化后储存到 cookie 中。在打开 cookie 的情况下,如果需要查找某个值,但是这个值在请求中没有持续储存的话,那么不会得到一个明确的出错信息。请检查页面响应中的 cookie 的大小是否与网络浏览器所支持的大小一致。

除了默认的客户端的会话之外,还有许多 Flask 扩展支持服务端会话。

信息闪现

好的应用程序和用户界面都有良好的反馈。如果用户没有得到足够的反馈,他们可能最终会讨厌这个应用程序。flask通过闪现系统提供了一种非常简单的向用户提供反馈的方式。闪现系统的基本工作原理是在请求结束时记录一个消息,提供且只提供给下一个请求使用。通常通过一个布局模板来展现闪现的消息。

使用flash() 可以闪现一个消息。在模板中,使用 get_flashed_messages() 来操作消息。完整的例子参见 消息闪现 。

日志记录

0.3 新版功能.

Changelog

有时候你会遇到这样的情况,你处理的数据本应该是正确的,但实际上不是。例如因为用户篡改了数据或客户端代码出错而导致一个客户端代码向服务器发送了明显错误的 HTTP 请求。多数时候在类似情况下,返回 400 Bad Request 就没事了,但是有时候不能这么做,并且要让代码继续运行。

你可能还想记录下发生了什么问题。这时候日志记录就派上了用场。从Flask0.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 Logger 类, 更多信息详见官方的 <https://docs.python.org/library/logging.html>

更多内容请参阅 应用错误处理 。

集成 WSGI中间件

如果要在应用程序中添加WSGI中间件,可以封装内部的WSGI应用程序。例如,如果您想使用Werkzeug包中的一个中间软件来解决LightTPD中的bug,可以这样做:

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

使用Flask扩展

扩展是帮助完成公共任务的包。例如 Flask-SQLAlchemy 为在 Flask 中轻松使用 SQLAlchemy 提供支持。

更多关于 Flask 扩展的内容请参阅 扩展 。

部署到Web服务器

准备好部署新的flask应用程序了吗?请移步 部署方式 。