轻量级Web框架——Flask的新人教程笔记

注：本篇博客只是作为博主的笔记，想要深入学习的同学还是要观看官方教程。

前沿

“微”：核心简单，易于扩展 --> 不包含许多已有库胜任的功能，但支持扩展。 个人理解：相当于提供一系列接口，开发人员可以根据自身需求进行定制；

快速入门

一个最小的应用

from flask import Flask
app = Flask(__name__)

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

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

一般模板和静态文件分别存储在应用 Python 源代码树下的子目录 templates 和 static 里；

WSGI 程序 --> 接口，使开发人员专心开发 Web 程序，而无需关注 HTTP 协议；

route() 装饰器告诉 Flask 什么样的 URL 能触发函数。

run() 函数来让应用运行在本地服务器上；

调试模式

通过设置 debug 决定调试模式；有两种途径来启用调试模式。一种是直接在应用对象上设置:

app.debug = True
app.run()

另一种是作为 run 方法的一个参数传入:

app.run(debug=True)

路由及变量规则

我们可以把一个函数绑定到对应到 URL 上。当然，可以构造含有动态部分的 URL ，也可以在一个函数上附着多个规则；

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

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

要给 URL 添加变量部分，你可以把这些特殊的字段标记为 <variable_name> ， 这个部分将会作为命名参数传递到你的函数。规则可以用 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

唯一 URL / 重定向行为

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

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

第一种情况中，指向 projects 的规范 URL 尾端有一个斜线。这种感觉很像在文件系统中的文件夹。访问一个结尾不带斜线的 URL 会被 Flask 重定向到带斜线的规范 URL 去。然而，第二种情况的 URL 结尾不带斜线，类似 UNIX-like 系统下的文件的路径名。访问结尾带斜线的 URL 会产生一个 404 “Not Found” 错误，

构造 URL

Flask 使用 url_for() 来给指定的函数生成 URL;

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

HTTP 方法

通过 route() 装饰器传递 methods 参数修改路由回应请求，HTTP 方法有，

• GET(默认);
• HEAD;
• PUT;
• POST;
• DELETE;
• OPTIONS.

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

静态文件

Flask 生成静态文件 --> 在包或者模块所在目录中创建一个名为 static 的文件夹，在应用中使用 /static即可访问；给静态文件生成 URL ，使用特殊的 ‘static’ 端点名。

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

这个文件应该存储在文件系统上的 static/style.css 。

模版渲染

render_template() 方法来渲染模板 --> 将模板名和你想作为关键字的参数传入模板的变量。Flask 会在 templates 文件夹里寻找模板如下。

from flask import render_template

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

注：模版是可以继承的。下列扩展名的模板会触发自动转义： .html、 .htm、.xml、.xhtml 。

在 Flask 中，使用全局 request 对象访问进入的请求数据。Flask 处理进入的请求数据并允许你用这个全局对象访问它。如果你工作在多线程环境，Flask 内部保证你总会在当前线程上获取正确的数据，

当前请求的 HTTP 方法可通过 method 属性来访问。通过 :attr:~flask.request.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 异常。 如果不捕获，它会显示一个 HTTP 400 Bad Requset 错误界面。

可以通过 args 属性来访问 URL 中提交的参数 （ ?key=value ） :

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

文件上传

HTML 表单中设置 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 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 的字典。如果你想使用会话，请不要直接使用 Cookies。

读取 cookies:

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.

存储 cookies:

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() 函数然后再进行修改。

重定向和错误

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

默认情况下，错误代码会显示一个黑白的错误页面。如果你要定制错误页面， 可以使用 errorhandler() 装饰器:

from flask import render_template

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

关于响应

视图函数的返回值会被自动转换为一个响应对象。如果返回值是一个字符串， 它被转换为该字符串为主体的、状态码为 200 OK 的 、 MIME 类型是 text/html 的响应对象。Flask 把返回值转换为响应对象的逻辑是这样：

1. 如果返回的是一个合法的响应对象，它会从视图直接返回；
2. 如果返回的是一个字符串，响应对象会用字符串数据和默认参数创建；
3. 如果返回的是一个元组，且元组中的元素可以提供额外的信息。这样的元组必须是 (response, status, 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

注：视图函数返回的响应可以是包含 HTML 的简单字符串，也可以是复杂的表单。

除请求对象之外，还有一个 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 it's 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() 可以在你模板引擎外做转义。官方文档

Convert the characters &, <, >, ‘, and ” in string s to HTML-safe sequences. Use this if you need to display text that might contain such characters in HTML. Marks return value as markup string.

使用基于 cookie 的会话需注意: Flask 会将你放进会话对象的值序列化至 Cookies。如果你发现某些值在请求之间并没有持久存在，然而确实已经启用了 Cookies，但也没有得到明确的错误信息。这时，请检查你的页面响应中的 Cookies 的大小，并与 Web 浏览器所支持的大小对比。（注：我没看懂它想表达什么）

消息闪现

Flask 提供了消息闪现系统，可以简单地给用户反馈。 消息闪现系统通常会在请求结束时记录信息，并在下一个（且仅在下一个）请求中访问记录的信息。展现这些消息通常结合要模板布局。

使用 flash() 方法可以闪现一条消息。要操作消息本身，请使用 get_flashed_messages() 函数，并且在模板中也可以使用。

日志记录

从 Flask 0.3 开始，Flask 就已经预置了日志系统。

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中间件。

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