标签归档:Flask

从HTTP请求-响应循环探索Flask的基本工作方式

本文基于Flask Web开发实战2章《Flask与HTTP》删减改写而来,完整的章节目录请访问本书主页http://helloflask.com/book查看。

本文中所指的示例程序在helloflask仓库的demos/http目录下。

HTTP(Hypertext Transfer Protocol,超文本传输协议)定义了服务器和客户端之间信息交流的格式和传递方式,它是万维网(World Wide Web)中数据交换的基础。在这篇文章中,我们会以HTTP协议定义的请求响应循环流程作为框架,了解Flask处理请求和响应的各种方式。

附注 HTTP的详细定义在RFC 7231~7235中可以看到。RFC(Request For Comment,请求评议)是一系列关于互联网标准和信息的文件,可以将其理解为互联网(Internet)的设计文档。完整的RFC列表可以在这里看到:https://tools.ietf.org/rfc/

本章的示例程序在helloflask仓库的demos/http目录下,你可以通过下面的操作来运行程序:

$ git clone https://github.com/greyli/helloflask
$ cd helloflask
$ pipenv install
$ pipenv shell
$ cd demos/http
$ flask run

请求响应循环

为了更贴近现实,我们以一个真实的URL为例:

http://helloflask.com/hello

当我们在浏览器中的地址栏中输入这个URL,然后按下Enter,稍等片刻,浏览器会显示一个问候页面。这背后到底发生了什么?你一定可以猜想到,这背后也有一个类似我们第1章编写的程序运行着。它负责接收用户的请求,并把对应的内容返回给客户端,显示在用户的浏览器上。事实上,每一个Web应用都包含这种处理模式,即“请求-响应循环(Request-Response Cycle)”:客户端发出请求,服务器处理请求并返回响应,如下图所示:

请求响应循环示意图

请求响应循环示意图

附注 客户端(Client Side)是指用来提供给用户的与服务器通信的各种软件。在本书中,客户端通常指Web浏览器(后面简称浏览器),比如Chrome、Firefox、IE等;服务器端(Server Side)则指为用户提供服务的服务器,也是我们的程序运行的地方。

这是每一个Web程序的基本工作模式,如果再进一步,这个模式又包含着更多的工作单元,

下图展示了一个Flask程序工作的实际流程:

Flask Web程序工作流程

Flask Web程序工作流程

从上图可以看出,HTTP在整个流程中起到了至关重要的作用,它是客户端和服务器端之间沟通的桥梁。

当用户访问一个URL,浏览器便生成对应的HTTP请求,经由互联网发送到对应的Web服务器。Web服务器接收请求,通过WSGI将HTTP格式的请求数据转换成我们的Flask程序能够使用的Python数据。在程序中,Flask根据请求的URL执行对应的视图函数,获取返回值生成响应。响应依次经过WSGI转换生成HTTP响应,再经由Web服务器传递,最终被发出请求的客户端接收。浏览器渲染响应中包含的HTML和CSS代码,并执行JavaScript代码,最终把解析后的页面呈现在用户浏览器的窗口中。

提示 关于WSGI的更多细节,我们会在第16章进行详细介绍。

提示 这里的服务器指的是处理请求和响应的Web服务器,比如我们上一章介绍的开发服务器,而不是指物理层面上的服务器主机。

HTTP请求

URL是一个请求的起源。不论服务器是运行在美国洛杉矶,还是运行在我们自己的电脑上,当我们输入指向服务器所在地址的URL,都会向服务器发送一个HTTP请求。一个标准的URL由很多部分组成,以下面这个URL为例:

http://helloflask.com/hello?name=Grey

这个URL的各个组成部分如下表所示:

信息

说明

http://

协议字符串,指定要使用的协议

helloflask.com

服务器的地址(域名)

/hello?name=Grey

要获取的资源路径(path),类似Unix的文件目录结构

附注 这个URL后面的?name=Grey部分是查询字符串(query string)。URL中的查询字符串用来向指定的资源传递参数。查询字符串从问号?开始,以键值对的形式写出,多个键值对之间使用&分隔。

请求报文

当我们在浏览器中访问这个URL时,随之产生的是一个发向http://helloflask.com所在服务器的请求。请求的实质是发送到服务器上的一些数据,这种浏览器与服务器之间交互的数据被称为报文(message),请求时浏览器发送的数据被称为请求报文(request message),而服务器返回的数据被称为响应报文(response message)。

请求报文由请求的方法、URL、协议版本、首部字段(header)以及内容实体组成。前面的请求产生的请求报文示意如下表所示:

组成说明

请求报文内容

报文首部:请求行(方法、URL、协议)

GET /hello HTTP/1.1

报文首部:各种首部字段

Host: helloflask.com

Connection: keep-alive

Cache-Control: max-age=0

User-Agent: Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.104 Safari/537.36

空行

 

报文主体

name=Grey

如果你想看看真实的HTTP报文,可以在浏览器中向任意一个有效的URL发起请求,然后在浏览器的开发者工具(F12)里的Network标签中看到URL对应资源加载的所有请求列表,点击任一个请求条目即可看到报文信息,下图是使用Chrome访问本地的示例程序的示例:

在Chrome浏览器中查看请求和响应报文

在Chrome浏览器中查看请求和响应报文

报文由报文首部和报文主体组成,两者由空行分隔,请求报文的主体一般为空。如果URL中包含查询字符串,或是提交了表单,那么报文主体将会是查询字符串和表单数据。

HTTP通过方法来区分不同的请求类型。比如,当你直接访问一个页面时,请求的方法是GET;当你在某个页面填写了表单并提交时,请求方法则通常为POST。下表是常见的几种HTTP方法类型:

方法

说明

GET

获取资源

POST

传输数据

PUT

传输文件

DELETE

删除资源

HEAD

获得报文首部

OPTIONS

询问支持的方法

报文首部包含了请求的各种信息和设置,比如客户端的类型,是否设置缓存,语言偏好等等。

附注 HTTP中可用的首部字段列表可以在https://www.iana.org/assignments/message-headers/message-headers.xhtml看到。请求方法的详细列表和说明可以在RFC 7231中看到。

如果运行了示例程序,那么当你在浏览器中访问http://127.0.0.1:5000/hello,开发服务器会在命令行中输出一条记录日志,其中包含请求的主要信息:

127.0.0.1 - - [02/Aug/2017 09:51:37] "GET /hello HTTP/1.1" 200 –

Request对象

现在该让Flask的请求对象request出场了,这个请求对象封装了从客户端发来的请求报文,我们能从它获取请求报文中的所有数据。

注意 请求解析和响应封装实际上大部分是由Werkzeug完成的,Flask子类化Werkzeug的请求(Request)和响应(Response)对象并添加了和程序相关的特定功能。在这里为了方便理解,我们先略过不谈。在第16章,我们会详细了解Flask的工作原理。

和上一节一样,我们先从URL说起。假设请求的URL是http://helloflask.com/hello?name=Grey,当Flask接收到请求后,请求对象会提供多个属性来获取URL的各个部分,常用的属性如下表所示:

属性

path

u’/hello’

full_path

u’/hello?name=Grey’

host

u’helloflask.com’

host_url

u’http://helloflask.com/ ‘

base_url

u’http://helloflask.com/hello ‘

url

u’http://helloflask.com/hello?name=Grey ‘

url_root

u’http://helloflask.com/ ‘

除了URL,请求报文中的其他信息都可以通过request对象提供的属性和方法获取,其中常用的部分如下表所示:

属性/方法

说明

args

Werkzeug的ImmutableMultiDict对象。存储解析后的查询字符串,可通过字典方式获取键值。如果你想获取未解析的原生查询字符串,可以使用query_string属性

blueprint

当前蓝本的名称,关于蓝本的概念在本书第二部分会详细介绍

cookies

一个包含所有随请求提交的cookies的字典

data

包含字符串形式的请求数据

endpoint

与当前请求相匹配的端点值

files

Werkzeug的MultiDict对象,包含所有上传文件,可以使用字典的形式获取文件。使用的键为文件input标签中的name属性值,对应的值为Werkzeug的FileStorage对象,可以调用save()方法并传入保存路径来保存文件

form

Werkzeug的ImmutableMultiDict对象。类似files,包含解析后的表单数据。表单字段值通过input标签的name属性值作为键获取

values

Werkzeug的CombinedMultiDict对象,结合了args和form属性的值

get_data(cache=True, as_text=False, parse_from_data=False)

获取请求中的数据,默认读取为字节字符串(bytestring),将as_text设为True返回值将是解码后的unicode字符串

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

作为JSON解析并返回数据,如果MIME类型不是JSON,返回None(除非force设为True);解析出错则抛出Werkzeug提供的BadRequest异常(如果未开启调试模式,则返回400错误响应,后面会详细介绍),如果silent设为True则返回None;cache设置是否缓存解析后的JSON数据

headers

一个Werkzeug的EnvironHeaders对象,包含首部字段,可以以字典的形式操作

is_json

通过MIME类型判断是否为JSON数据,返回布尔值

json

包含解析后的JSON数据,内部调用get_json(),可通过字典的方式获取键值

method

请求的HTTP方法

referrer

请求发起的源URL,即referer

scheme

请求的URL模式(http或https)

user_agent

用户代理(User Agent,UA),包含了用户的客户端类型,操作系统类型等信息

提示 Werkzeug的MutliDict类是字典的子类,它主要实现了同一个键对应多个值的情况。比如一个文件上传字段可能会接收多个文件。这时就可以通过getlist()方法来获取文件对象列表。而ImmutableMultiDict类继承了MutliDict类,但其值不可更改。具体访问Werkzeug文档相关数据结构章节http://werkzeug.pocoo.org/docs/latest/datastructures/

在我们的示例程序中实现了同样的功能。当你访问http://localhost:5000/hello?name=Grey,页面加载后会显示“Hello, Grey!”。这说明处理这个URL的视图函数从查询字符串中获取了查询参数name的值,如下所示:

from flask import Flask, request

app = Flask(__name__)

@app.route('/hello')
def hello():
    name = request.args.get('name', 'Flask')  # 获取查询参数name的值
    return '<h1>Hello, %s!</h1>' % name  # 插入到返回值中

注意 上面的示例代码包含安全漏洞,在现实中我们要避免直接将用户传入的数据直接作为响应返回,在本章的末尾我们将介绍包括这个漏洞在内的Web常见安全漏洞的具体细节和防范措施。

需要注意的是,和普通的字典类型不同,当我们从request对象中类型为MutliDict或ImmutableMultiDict的属性(比如files、form、args)中直接使用键作为索引获取数据时(比如request.args[‘name’]),如果没有对应的键,那么会返回HTTP 400错误响应(Bad Request,表示请求无效),而不是抛出KeyError异常,如下图所示。为了避免这个错误,我们应该使用get()方法获取数据,如果没有对应的值则返回None;get()方法的第二个参数可以设置默认值,比如requset.args.get(‘name’, ‘Human’)。

400错误响应

400错误响应

提示 如果开启了调试模式,那么会抛出BadRequestKeyError异常并显示对应的错误堆栈信息,而不是常规的400响应。

在Flask中处理请求

URL是指向网络上资源的地址。在Flask中,我们需要让请求的URL匹配对应的视图函数,视图函数返回值就是URL对应的资源。

路由匹配

为了便于将请求分发到对应的视图函数,程序实例中存储了一个路由表(app.url_map),其中定义了URL规则和视图函数的映射关系。当请求发来后,Flask会根据请求报文中的URL(path部分)来尝试与这个表中的所有的URL规则进行匹配,调用匹配成功的视图函数。如果没有找到匹配的URL规则,说明程序中没有处理这个URL的视图函数,Flask会自动返回404错误响应(Not Found,表示资源未找到)。你可以尝试在浏览器中访问http://localhost:5000/nothing,因为我们的程序中没有视图函数负责处理这个URL,所以你会得到404响应,如下图所示:

404错误响应

404错误响应

如果你经常上网,那么肯定会对这个错误代码相当熟悉,它表示请求的资源没有找到。和前面提及的400错误响应一样,这类错误代码被称为HTTP状态码,用来表示响应的状态,具体会在下面详细讨论。

当请求的URL与某个视图函数的URL规则匹配成功时,对应的视图函数就会被调用。使用flask routes命令可以查看程序中定义的所有路由,这个列表由app.url_map解析得到:

$ flask routes
Endpoint  Methods  Rule
--------  -------  -----------------------
hello     GET      /hello
go_back   GET      /goback/<int:age>
hi         GET      /hi
...
static    GET      /static/<path:filename>

在输出的文本中,我们可以看到每个路由对应的端点(Endpoint)、HTTP方法(Methods)和URL规则(Rule),其中static端点是Flask添加的特殊路由,用来访问静态文件,具体我们会在第3章学习。

设置监听的HTTP方法

在上一节通过flask routes命令打印出的路由列表可以看到,每一个路由除了包含URL规则外,还设置了监听的HTTP方法。GET是最常用的HTTP方法,所以视图函数的默认监听的方法类型就是GET,HEAD、OPTIONS方法的请求由Flask处理,而像DELETE、PUT等方法一般不会在程序中实现,在后面我们构建Web API时才会用到这些方法。

我们可以在app.route()装饰器中使用methods参数传入一个包含监听的HTTP方法的可迭代对象。比如,下面的视图函数同时监听GET请求和POST请求:

@app.route('/hello', methods=['GET', 'POST'])
def hello():
    return '<h1>Hello, Flask!</h1>'

当某个请求的方法不符合要求时,请求将无法被正常处理。比如,在提交表单时通常使用POST方法,而如果提交的目标URL对应的视图函数只允许GET方法,这时Flask会自动返回一个405错误响应(Method Not Allowed,表示请求方法不允许),如下图所示:

405错误响应

405错误响应

通过定义方法列表,我们可以为同一个URL规则定义多个视图函数,分别处理不同HTTP方法的请求,我们在本书第二部分构建Web API时会用到这个特性。

3. URL处理

从前面的路由列表中可以看到,除了/hello,这个程序还包含许多URL规则,比如和go_back端点对应的/goback/<int:year>。现在请尝试访问http://localhost:5000/goback/34,在URL中加入一个数字作为时光倒流的年数,你会发现加载后的页面中有通过传入的年数计算出的年份:“Welcome to 1984!”。仔细观察一下,你会发现URL规则中的变量部分有一些特别,<int:year>表示为year变量添加了一个int转换器,Flask在解析这个URL变量时会将其转换为整型。URL中的变量部分默认类型为字符串,但Flask提供了一些转换器可以在URL规则里使用,如下表所示:

转换器

说明

string

不包含斜线的字符串(默认值)

int

整型

float

浮点数

path

包含斜线的字符串。static路由的URL规则中的filename变量就使用了这个转换器

any

匹配一系列给定值中的一个元素

uuid

UUID字符串

转换器通过特定的规则指定,即“<转换器:变量名>”。<int:year>把year的值转换为整数,因此我们可以在视图函数中直接对year变量进行数学计算:

@app.route('goback/<int:year>')
def go_back(year):
    return '<p>Welcome to %d!</p>' % (2018 - year)

默认的行为不仅仅是转换变量类型,还包括URL匹配。在这个例子中,如果不使用转换器,默认year变量会被转换成字符串,为了能够在Python中计算天数,我们就需要使用int()函数将year变量转换成整型。但是如果用户输入的是英文字母,就会出现转换错误,抛出ValueError异常,我们还需要手动验证;使用了转换器后,如果URL中传入的变量不是数字,那么会直接返回404错误响应。比如,你可以尝试访问http://localhost:5000/goback/tang。

在用法上唯一特别的是any转换器,你需要在转换器后添加括号来给出可选值,即“<any(value1, value2, …):变量名>”,比如:

@app.route('/colors/<any(blue, white, red):color>')
def three_colors(color):
    return '<p>Love is patient and kind. Love is not jealous or boastful or proud or rude.</p>'

当你在浏览器中访问http://localhost:5000/colors/<color>时,如果将<color>部分替换为any转换器中设置的可选值以外的任意字符,均会获得404错误响应。

如果你想在any转换器中传入一个预先定义的列表,可以通过格式化字符串的方式(使用%或是format()函数)来构建URL规则字符串,比如:

colors = ['blue', 'white', 'red']

@app.route('/colors/<any(%s):color>' % str(colors)[1:-1])
...

HTTP响应

在Flask程序中,客户端发出的请求触发相应的视图函数,获取返回值会作为响应的主体,最后生成完整的响应,即响应报文。

响应报文

响应报文主要由协议版本、状态码(status code)、原因短语(reason phrase)、响应首部和响应主体组成。以发向localhost:5000/hello的请求为例,服务器生成的响应报文示意如下表所示:

组成说明

响应报文内容

报文首部:状态行(协议、状态码、原因短语)

HTTP/1.1 200 OK

报文首部:各种首部字段

Content-Type: text/html; charset=utf-8

Content-Length: 22

Server: Werkzeug/0.12.2 Python/2.7.13

Date: Thu, 03 Aug 2017 05:05:54 GMT

空行

 

报文主体

<h1>Hello, Human!</h1>

响应报文的首部包含了一些关于响应和服务器的信息,这些内容由Flask生成,而我们在视图函数中返回的内容即为响应报文中的主体内容。浏览器接受到响应后,会把返回的响应主体解析并显示在浏览器窗口上。

HTTP状态码用来表示请求处理的结果,下表是常见的几种状态码和相应的原因短语:

类型

状态码

原因短语(用于解释状态码)

说明

成功

200

OK

请求被正常处理

201

Created

请求被处理,并创建了一个新资源

204

No Content

请求处理成功,但无内容返回

重定向

301

Moved Permanently

永久重定向

302

Found

临时性重定向

304

Not Modified

请求的资源未被修改,重定向到缓存的资源

客户端错误

400

Bad Request

表示请求无效,即请求报文中存在错误

401

Unauthorized

类似403,表示请求的资源需要获取授权信息,在浏览器中会弹出认证弹窗

403

Forbidden

表示请求的资源被服务器拒绝访问

404

Not Found

表示服务器上无法找到请求的资源或URL无效

服务器端错误

500

Internal Server Error

服务器内部发生错误

提示 当关闭调试模式时,即FLASK_ENV使用默认值production,如果程序出错,Flask会自动返回500错误响应;而调试模式下则会显示调试信息和错误堆栈。

附注 响应状态码的详细列表和说明可以在RFC 7231中看到。

在Flask中生成响应

响应在Flask中使用Response对象表示,响应报文中的大部分内容由服务器处理,大多数情况下,我们只负责返回主体内容。

根据我们在请求一节介绍的内容,Flask会先判断是否可以找到与请求URL相匹配的路由,如果没有则返回404响应。如果找到,则调用对应的视图函数,视图函数的返回值构成了响应报文的主体内容,正确返回时状态码默认为200。Flask会调用make_response()方法将视图函数返回值转换为响应对象。

完整的说,视图函数可以返回最多由三个元素组成的元组:响应主体、状态码、首部字段。其中首部字段可以为字典,或是两元素元组组成的列表。

比如,普通的响应可以只包含主体内容:

@app.route('/hello')
def hello():
    ...
    return '<h1>Hello, Flask!</h1>'

默认的状态码为200,下面指定了不同的状态码:

@app.route('/hello')
def hello():
    ...
    return '<h1>Hello, Flask!</h1>', 201

有时你会想附加或修改某个首部字段。比如,要生成状态码为3XX的重定向响应,需要将首部中的Location字段设置为重定向的目标URL:

@app.route('/hello')
def hello():
    ...
    return '', 302, {'Location': 'http://www.example.com'}

现在访问http://localhost:5000/hello,会重定向到http://www.example.com。在多数情况下,除了响应主体,其他部分我们通常只需要使用默认值即可。

重定向

如果你访问http://localhost:5000/hi,你会发现页面加载后地址栏中的URL变为了http://localhost:5000/hello。这种行为被称为重定向(Redirect),你可以理解为网页跳转。在上一节的示例中,状态码为302的重定向响应的主体为空,首部中需要将Location字段设为重定向的目标URL,浏览器接受到重定向响应后会向Location字段中的目标URL发起新的GET请求,整个流程下图所示:

重定向流程示意图

重定向流程示意图

在Web程序中,我们经常需要进行重定向。比如,当某个用户在没有经过认证的情况下访问需要登录后才能访问的资源,程序通常会重定向到登录页面。

对于重定向这一类特殊响应,Flask提供了一些辅助函数。除了像前面那样手动生成302响应,我们可以使用Flask提供的redirect()函数来生成重定向响应,重定向的目标URL作为第一个参数。前面的例子可以简化为:

from flask import Flask, redirect
...
@app.route('/hello')
def hello():
    return redirect('http://www.example.com')

提示 使用redirect()函数时,默认的状态码为302,即临时重定向。如果你想修改状态码,可以在redirect()函数中作为第二个参数或使用code关键字传入。

如果要在程序内重定向到其他视图,那么只需在redirect()函数中使用url_for()函数生成目标URL即可,如下所示:

from flask import Flask, redirect, url_for 

...

@app.route('/hi')
def hi():
    ...
    return redierct(url_for('hello'))  # 重定向到/hello

@app.route('/hello')
def hello():
    ...

错误响应

如果你访问http://localhost:5000/brew/coffee,你会获得一个418错误响应(I’m a teapot),如下图所示:

418错误响应

418错误响应

附注 418错误响应由IETF(Internet Engineering Task Force,互联网工程任务组)在1998年愚人节发布的HTCPCP(Hyper Text Coffee Pot Control Protocol,超文本咖啡壶控制协议)中定义(玩笑),当一个控制茶壶的 HTCPCP 收到 BREW 或 POST 指令要求其煮咖啡时应当回传此错误。

大多数情况下,Flask会自动处理常见的错误响应。HTTP错误对应的异常类在Werkzeug的werkzeug.exceptions模块中定义,抛出这些异常即可返回对应的错误响应。如果你想手动返回错误响应,更方便的方法是使用Flask提供的abort()函数。

在abort()函数中传入状态码即可返回对应的错误响应,下面的视图函数返回404错误响应:

from flask import Flask, abort

...

@app.route('/404')
def not_found():
    abort(404)

提示 abort()函数前不需要使用return语句,但一旦abort()函数被调用,abort()函数之后的代码将不会被执行。

附注 虽然我们有必要返回正确的状态码,但这并不是必须的。比如,当某个用户没有权限访问某个资源时,返回404错误要比403错误更加友好。  

本文基于Flask Web开发实战2章《Flask与HTTP》删减改写而来,完整的章节目录请访问本书主页http://helloflask.com/book查看。

《Flask Web开发实战》勘误、源码等资源索引

这篇文章列出了本书的勘误、源码等相关资源。衷心的希望这本书能够帮助到你,同时也为书中包含的错误为你带来的不便说声抱歉。

勘误 & FAQ & 可改进实现 & 版本更新记录

在本书的Meta仓库helloflask(https://github.com/greyli/helloflask)中,你可以找到下列资源:

实战项目源码

本书第7~11章的5个实战项目的源码地址如下:
这些项目的介绍以及在线Demo链接可以在本书主页找到。

其他相关资源

本书附带的其他相关资源如下:

HelloFlask.com

helloflask.com是本书的衍生站点,以上的资源信息都可以在本书的主页http://helloflask.com/book找到。

问题与错误反馈

如果你发现了书中的错误和不足,或是有和书相关的问题和反馈,根据类别,你可以分别选择下面的途径告诉我:
  • 书中包含的笔误、错误和不足的反馈:在helloflask仓库创建issue或PR
  • 各个项目的bug:在各个项目所在的仓库创建issue或PR
  • 其他问题、建议和批评:直接发邮件给我(withlihui@gmail.com),或是发送知乎私信、新浪微博私信、Twitter私信给我(邮件可以被我最快看到)

Powered by This Book

如果你通过阅读整本书编写了自己的小项目,欢迎通过各种方式告诉我,我会把你的项目添加到本书主页中的“Powered by This Book”栏目。
 
最后,欢迎大家在新浪微博Twitter上关注我,以便及时获取本书的最新动态。

《Flask Web开发实战》第二部分项目Demo和源码上线

很抱歉,因为电子书突然提前上架,一些进度被拖延了,现在终于把所有项目的源码都推送到GitHub了(如果你不方便访问GitHub,本书主页上提供了这些项目的源码合集文件下载)。

下面是这些项目的源码和Demo链接。关于这些项目的截图和功能介绍参见《Flask Web开发实战》中的示例程序们或本书主页(helloflask.com/book)。

第1~6章、13章:HelloFlask

第7章:留言板 – SayHello

Say hello to the world.

第8章:个人博客 – Bluelog

A blue blog.

第9章:图片社交网站 – Albumy

Capture and share every wonderful moment.

第10章:待办事项程序 – Todoism

We are todoist, we use todoism.

第11章:在线聊天室 – CatChat

Chatroom for coders, not cats.

提示 在线Demo部署在DigitalOcean的廉价主机上,某些地区或在特定时段可能会无法访问,请尝试使用VPN。另外,在线Demo关闭了部分功能。建议根据书中第二部分每章开始的操作指导在本地运行程序。

特别说明(给使用Windows系统的Python2.7用户)

Werkzeug当前版本(14.2)存在一个Bug,当在Windows系统下使用Python2开启调试模式时,重载器会因为环境变量FLASK_ENV的编码问题而出现TypeError异常。这个Bug已在master分支修复(话说定位这个Bug花了我很长时间),预计在纸书正式发售前会发布Werkzeug 0.15版本。

目前,临时的解决方案有修改Werkzeug源码、修改python-dotenv源码、从GitHub上的master分支更新Werkzeug等,但这些方法都太麻烦。我建议你临时不开启调试模式来避免这个异常出现,也就是在.flaskenv文件中将FLASK_ENV定义那一行注释掉(使用#号),比如:

# FLASK_ENV=development

等到Werkzeug 0.15发布后,我会发一篇文章通知大家更新本地依赖,并给出具体的更新方法。

致购买《Flask Web开发实战》电子版的读者

按照编辑的说法,电子书是要和纸书一起发售的。没想到的是,纸书还在印刷的时候,电子书突然就在24号上架了……这个“突袭”带来了一些问题,这篇文章汇总了这些问题及对应的解决方法。很抱歉这些问题为你带来了不便!

电子书亚马逊链接:https://www.amazon.cn/dp/B07GST8Z8M

豆瓣阅读链接:https://read.douban.com/ebook/56335667/

排版错误

或许是因为排版人员不够专心,又或者是软件问题,电子书存在一些排版问题:

  • 文本中所有的半角括号被转换为全角括号
  • 类似“python -m”命令中的空格被去掉
  • 部分代码缩进错乱
  • 部分字符缺失

我这几天会大致的过一遍电子书,汇总出所有的排版问题,然后尽快推送更新。

你可以访问勘误文件查看完整的勘误列表。

运行程序时出现TypeError异常(针对在Windows系统使用Python2的用户)

更新 python-dotenv 到最新版本即可:

$ pip install -U python-dotenv

Flask 0.12.2版本发现安全漏洞,请考虑升级

因为Flask-CKEditor的示例程序目录下包含一个旧的requirements.txt文件,其中Flask版本被固定为0.12.2,推动代码到GitHub时,触发了内置的依赖安全提示,进而了解了一下这个关于Flask 0.12.2版本的漏洞。

漏洞描述

这个漏洞(CVE-2018-1000656)四天前(8月20号)被发布在NVD(National Vulnerability Database,国家漏洞数据库)上,漏洞描述如下:
The Pallets Project flask version Before 0.12.3 contains a CWE-20: Improper Input Validation vulnerability in flask that can result in Large amount of memory usage possibly leading to denial of service. This attack appear to be exploitable via Attacker provides JSON data in incorrect encoding. This vulnerability appears to have been fixed in 0.12.3.
大致的翻译如下:
Pallets项目组开发的Flask 0.12.3及以下版本包含CWE-20类型的漏洞:不合适的输入验证漏洞。这个漏洞将会导致大量内存占用,可能会导致拒绝服务。攻击者可以通过提供使用了错误编码的JSON数据来进行攻击。这个漏洞已经在0.12.3版本中修复(#2691)。

应对措施

对于这个漏洞,你可以通过升级来进行防范。如果你打算使用最新版本(Flask 1.0.2),可以使用下面的命令更新(参见这篇文章了解Flask 1.0版本包含哪些主要变化):
$ pip install -U flask
如果你使用Pipenv,则可以使用下面的命令:
$ pipenv update flask
如果你还没有准备好使用最新版本,可以升级到0.12.3版本
$ pip install flask==0.12.3
然后更新requirements.txt:
flask ~> 0.12.3
如果使用Pipenv,则使用下面的命令:
$ pipenv install flask==0.12.3

附注

《Flask Web开发实战》签名版开始预售

《Flask Web开发实战》即将下厂印刷,如果想要购买作者签名版,可以访问http://helloflask.com/book/signed。本书定价129,电商平台预计价格为99,签名版为109。

blank

注意,此商品为预售,无现货,具体发货时间取决于本书正式发售日期。更多信息请访问预售页面查看。

Flask-Origin:Flask 0.1版本源码注解

本项目是《Flask Web开发实战》的衍生品。在本书第16章的前半部分,为了让读者快速对Flask的源码结构建立一个初步的认识(以便阅读后面的内容),推荐读者阅读0.1版本的源码。

本项目对0.1版本Flask源码(项目根目录下的flask.py脚本)中的注释和文档字符串进行了翻译,并在必要的地方添加了一些额外的注解,以便于阅读和理解。

项目地址:https://github.com/greyli/flask-origin

欢迎fork项目进行补充和纠错。

阅读前的准备

为了更容易理解Flask的实现原理,你需要对WSGI协议以及HTTP协议有一些了解,建议先简单浏览下面的基本知识:

进一步阅读

Flask内部实现大量依赖于Werkzeug,包括请求和响应对象,路由匹配,URL生成等等,你可以阅读Werkzeug的文档来深入了解这些内容的具体实现。另外,如果你对模板渲染部分的内容感兴趣,也可以考虑阅读Jinja2文档:

注意:新版本的Werkzeug和Jinja2已经发生很大的变化,0.1版本的Flask对应的Werkzeug源码版本为0.6.1,对应的Jinja2源码版本为2.4。上述文档链接分别为0.14和2.9版本,请谨慎参考。

新版本的Flask中如何启动开发服务器和开启调试模式

从Flask 0.11版本开始,官方就建议使用flask run命令来取代app.run()方法运行开发服务器。尽管如此,两年多过去了,仍然有大量新发布的文章和教程在示例中使用app.run()方法启动程序。类似的,虽然内置的命令行支持已经非常完善,但还有很多人在使用Flask-Script。

Added flask and the flask.cli module to start the local debug server through the click CLI system. This is recommended over the old flask.run() method as it works faster and more reliable due to a different design and also replaces Flask-Script.

Flask Changelog 0.11

不得不承认,在某些特殊场景下,app.run()更加方便,比如创建Flask命令在附加Werkzeug提供的性能分析中间件后启动程序,这时通过app.run()可以直接在脚本内启动程序。但是在大多数情况下,flask run更能胜任启动开发服务器的工作。而且,在大型项目中,使用app.run()需要你在项目根目录单独创建一个启动脚本,flask run则没有这个要求;在单脚本程序中,使用flask run也可以省掉脚本末尾的两行代码。

注意 这两种方法都只是用来启动内置(Werkzeug提供)的开发服务器,仅适用于开发用途。在生产环境下,应该使用性能更好,更加完善的开发服务器,比如Gunicorn、uWSGI等。

不同组织形式的程序的启动方式

下面我们来了解一下使用flask run启动开发服务器时在几种方式。

简单的单脚本程序

如果脚本命名为app.pywsgi.py,那么在包含程序脚本的目录下直接调用flask run即可:

$ flask run

Flask会自动探测找到脚本中的程序实例并启动。如果脚本命名为其他名称,比如hello.py,那么需要将脚本名写入环境变量FLASK_APP,然后再调用flask run命令:

$ export FLASK_APP=hello
$ flask run

提示 在Windows系统下,你需要使用set命令来设置环境变量,比如 > set FLASK_APP=hello,后面的命令亦同。

使用包组织的程序

这种情况下,可以将包含程序实例的对应模块的路径写入FLASK_APP

$ export FLASK_APP=my_pkg.app
$ flask run

通常情况下,我们会在包内的__init__.py文件中创建程序实例,所以这时可以直接将包名称写入FLASK_APP

$ export FLASK_APP=my_pkg
$ flask run

使用工厂函数创建程序实例的程序

因为Flask会自动探测程序实例,所以使用工厂函数创建程序实例时不需要进行额外设置。具体来说,Flask会在FLASK_APP变量存储的对应模块/包构造文件中寻找名为create_appmake_app的函数,并调用这个函数来创建一个程序实例。

为了让你的程序能够被探测到,工厂函数的名称需要命名为create_appmake_app,而且要确保工厂函数接受默认值参数。这时启动开发服务器的方式仍然不变:

$ export FLASK_APP=my_pkg
$ flask run

如果你的工厂函数接受的参数不是默认参数,或者你想详细定义调用工厂函数的方式,那么也可以通过FLASK_APP环境变量来定义:

$ export FLASK_APP="my_pkg:create_app('development')" 
$ flask run

提示 Flask的FLASK_APP还接受其他形式的输入值,你可以参考文末给出的文档相关部分链接了解完整内容。

如何避免重复设置FLASK_APP环境变量

在上面的几种方式中,除了包含程序实例的程序脚本命名为app.pywsgi.py的情况外,都需要设置FLASK_APP环境变量。有没有办法避免重启电脑或是新打开命令行会话时重复输入FLASK_APP呢?当然。Flask提供了对一个常用的Python虚拟环境管理工具python-dotenv的支持,我们需要先安装它:

$ pip install python-dotenv

当python-dotenv安装后,执行flask run命令会首先将项目根目录下的.env.flaskenv文件中的环境变量写入。所以,你可以将FLASK_APP写在这两个文件中。按照约定,.env存储包含敏感数据的环境变量,这个文件需要加入到.gitignore中以避免提交到Git仓库中;而.flaskenv时Flask特别支持的文件,这个文件则用来存储和Flask相关的环境变量,比如FLASK_ENVFLASK_DEBUG等,所以我们可以把FLASK_APP写到这个文件中:

FLASK_APP=my_pkg

现在,我们可以仅通过一个命令来启动开发服务器:

$ flask run

使用flask run时如何开启调试模式?

在使用app.run()方法时,我们会通过将debug参数设为True来开启调试模式。而当使用flask run时,则需要通过FLASK_ENV环境变量来设置调试模式。默认情况下,FLASK_ENV的值为production,在开发时我们可以将其设为development来开启调试模式。

同样的,为了避免重复写入这个环境变量,我们也将其写到.flaskenv中:

FLASK_ENV=development

提示 目前已不推荐使用FLASK_DEBUG来开启调试模式,当FLASK_ENV的值为development时调试模式会自动开启。

使用flask run时如何自定义主机和端口

在通过flask run启动开发服务器时,你可以通过命令行选项来自定义监听的主机和端口,示例如下:

$ flask run --port 5001

下面的示例同时指定了端口和主机:

$ flask run --host 0.0.0.0 --port 5001

另外,Flask还支持通过环境变量来定义命令选项,支持的环境变量名称模式为“FLASK_命令_选项”。比如,如果你想设置端口,那么可以定义FLASK_RUN_PORT环境变量,作用和传入--port选项相同。

启动包含程序上下文的Python Shell

你可以通过flask shell命令来启动一个激活了程序上下文的Python Shell,而不是使用python命令:

$ flask shell

app.run()的未来

从0.11版本到现在的1.0.2版本,app.run()始终处于不建议使用状态,而且Flask的命令行系统、flask run命令的程序探测都在逐渐完善,我觉得未来也许会正式”deprecate“这个app.run()方法。不过,因为某些特殊用途仍然需要使用app.run(),未来的变化还不好说。而且,Miguel Grinberg提交了1个PRapp.run()间接调用flask run,如果这个PR被合并,也许app.run()将会重回正轨。

就目前来说,flask run要远比app.run()更加方便、好用、简洁、直观,准备好了吗?穿上新衣服吧。

相关链接

Flask test_client()测试客户端为勾选框传递布尔值数据

今天写单元测试发现了一个常见的问题,即测试时发送POST请求时如何传入布尔值数据(勾选框字段值)?答案是:你没法直接传递布尔值。其实这个答案相当显而易见,客户端当然没法向服务器端发送Python类型的数据,数据的转换是在接受到请求数据后在服务器端进行的。之前在不借助Flask-WTF/WTForms,手动编写表单并处理时就已经注意到了这个问题,不过在测试中不太容易想到。

首先,我们需要了解一下勾选框(<input type="checkbox">)提交的行为:

  • 如果没有勾选,那么勾选框字段的值为空值,而且这个字段不会被序列化到请求中;在服务器端,WTForms会将其转换为False
  • 如果勾选框被勾选,那么传入服务器端的数据会是该字段value属性的值,如果value属性的值为空,那么则提交字符串"on";在服务器端,WTForms会将其转换为True

也就是说,勾选框的数据只要不为空,WTForms就会将其转换为True。所以,在测试中,如果你想让勾选框的值最终转换为True,那么就传入任意字符串;反之则传递空字符串或直接不加入该字段。下面是传入空字符串的示例:

def test_privacy_setting(self):
    self.login()
    response = self.client.post(url_for('user.privacy_setting'), data=dict(
        public_collections='',  # <--
    ), follow_redirects=True)

    user = User.query.get(1)
    self.assertEqual(user.public_collections, False)

顺便说一句,基于勾选框的提交行为,如果没有使用Flask-WTF/WTForms,那么在手动处理提交数据的时候也要进行相应的处理:没有在request.form中获取到勾选框字段(比如,request.form.get('remember')会是None),即表示没有勾选,那么就转换为False;勾选框字段一旦出现,那么就表示勾选,转换为True

Flask Web开发实战番外

《Flask Web开发实战》删减下近8万字的内容,有时间我会把其中有价值的内容整理成文章发布出来。

使用Flask-Avatars在Flask项目中设置头像

Flask-Avatars

大多数Web程序中都会涉及到头像的实现。不同类型的项目,对于头像的需求不同,有些项目可以直接使用Gravatar提供的头像服务,而有的项目则需要提供自定义头像设置。扩展Flask-Avatars几乎满足了所有常见的头像需求:

  • 默认头像
  • Gravatar头像
  • Robohash头像
  • 社交网站头像
  • 生成随机图案头像Identicon
  • 图片裁剪头像

Flask-Avatars

GitHub主页:https://github.com/greyli/flask-avatars

安装与初始化

使用pip安装:

$ pip install flask-avatars

像其他扩展类似,你需要实例化从flask_avatars导入的Avatars类,并传入app实例:

from flask_avatars import Avatars

app = Flask(__name__)
avatars = Avatars(app)

如果你使用工厂函数创建程序实例,那么这里也可以不传入程序实例app,在工厂函数中对这个avatars对象调用init_app()方法时再传入app实例。

默认头像

Flask-Avatars内置了几个默认头像,可以用来作为用户注册后的初始头像,或是作为博客评论者的头像。在模板中调用avatars.default()即可获取URL:

<img src="{{ avatars.default() }}">

你可以通过size参数来设置尺寸,默认为m,其他可选值有l和s。实际的调用示例如下所示:default avatar

 

Gravatar

在模板中调用avatars.gravatar()方法并传入Email散列值即可获取Gravatar(gravatar.com)的头像URL:

<img src="{{ avatars.gravatar(email_hash) }}">

Email散列值可以通过下面的方式获取:

import hashlib

avatar_hash = hashlib.md5(my_email.lower().encode('utf-8')).hexdigest()

实际的调用示例如下所示:gravatar

Robohash

Robohash(robohash.org)是一个生成随机机器人头像的服务(目前Gravatar的默认头像中已经支持这一类型,可以通过将default参数设为robohash获取)。在模板中调用avatars.robohash()并传入随机文本作为参数即可获取Robohash的头像URL:

<img src="{{ avatars.robohash(some_text) }}">

实际的调用示例如下所示:

robohash

社交网站头像

Flask-Avatars通过Avatars.io提供了社交头像获取服务,目前支持Facebook、Twitter、Instagram和Gravatar。通过在模板中调用avatars.social_media()方法并传入用户名(username)即可获取对应的头像URL,通过size参数可以设置尺寸,可选值为small、medium和large:

<img src="{{ avatars.social_media(username) }}">

通过platform参数可以设置平台,默认为twitter,可选值为twitter、facebook、instagram和gravatar:

<img src="{{ avatars.social_media(username, platform='facebook') }}">

实际的调用示例如下所示:

avatars.io

生成随机图案头像Identicon

Gravatar服务可能会有不稳定的情况,这种情况下,你可以在本地为用户生成头像(identicon),下面是一个简单的示例:

app.config['AVATARS_SAVE_PATH '] = 'the/path/to/save/avatar'

avatar = Identicon()
filenames = avatar.generate(text=‘一串唯一字符’)

avatar.generate()会根据传入的随机字符创建三个尺寸(可以通过配置变量AVATARS_SIZE_TUPLE自定义)的头像,保存到指定的位置,并返回三个头像文件名。你可以将这个文件名保存到数据库中,并创建一个视图函数来提供头像文件:

from flask import send_form_directory, current_app

@app.route('/avatars/<path:filename>')
def get_avatar(filename):
    return send_from_directory(current_app.config['AVATARS_SAVE_PATH'], filename)

实际生成的头像示例如下所示:identicon

裁剪头像

Flask-Avatars基于Jcrop提供了头像裁剪功能,具体步骤可以参考文档中的相关部分。下面是示例程序中的裁剪页面:裁剪

 

裁剪后的结果:裁剪完成

配置

Flask-Avatars支持的配置列表如下所示:

配置 默认值 说明
AVATARS_GRAVATAR_DEFAULT identicon Gravatar默认头像类型
AVATARS_SAVE_PATH None 头像保存路径
AVATARS_SIZE_TUPLE (30, 60, 150) 头像尺寸三元素元组,格式为 (small, medium, large),用于生成identicon头像和裁剪头像
AVATARS_IDENTICON_COLS 7 Identicon头像一行的色块数量
AVATARS_IDENTICON_ROWS 7 Identicon头像一列的色块数量
AVATARS_IDENTICON_BG None Identicaon头像的背景颜色,传入RGB元组,比如(125, 125, 125)。默认使用随机颜色
AVATARS_CROP_BASE_WIDTH 500 裁剪图片的显示宽度
AVATARS_CROP_INIT_POS (0, 0) 裁剪框起始位置,两元素元组(x, y),默认为左上角
AVATARS_CROP_INIT_SIZE None  裁剪框的尺寸,默认为尺寸元组中设置的l尺寸大小,即AVATARS_SIZE_TUPLE[0]
AVATARS_CROP_MIN_SIZE None 裁剪框的限制最小尺寸,默认无限制
AVATARS_CROP_PREVIEW_SIZE None 预览窗口的尺寸,默认为尺寸元组中设置的m尺寸大小,即AVATARS_SIZE_TUPLE[1]
AVATARS_SERVE_LOCAL False 是否从本地加载Jcrop资源,默认从CDN加载

示例程序

Flask-Avatars的Git仓库中包含三个实例程序,也就是文中的截图对应的程序:

  • examples/basic —— 基本示例
  • examples/identicon —— Identicon示例
  • examples/crop —— 裁剪示例

你可以通过下面的方式来运行实例程序:

$ git clone https://github.com/greyli/flask-avatars.git
$ cd flask-avatars/examples
$ pip install flask flask-avatars
$ cd basic  # 切换到identicon和crop目录可以运行对应的示例程序
$ flask run

这篇文章属于“Flask常用扩展介绍系列”,这个系列的文章目录索引可以在《Flask常用扩展介绍系列文章索引》看到。

相关链接

使用Flask-SQLAlchemy调用create_all()创建数据库表前是否需要导入模型类?

当继承db.Model基类的子类被声明创建时,根据db.Model基类继承的元类中设置的行为,类声明后会将表信息注册到db.Model.metadata.tables属性中。

create_all()方法被调用时正是通过这个属性来获取表信息。因此,当我们调用create_all()前,需要确保模型类被声明创建。如果模型类存储在单独的模块中,不导入该模块就不会执行其中的代码,模型类便不会被创建,进而便无法注册表信息到db.Model.metadata.tables中,所以这时需要导入相应的模块。

因为我们的目的是让模型类被创建,所以不论是导入整个模块还是导入其中某个模型类都可以,并不需要导入全部模型类。

一般情况下,我们不用关心这个问题。在单脚本的Flask程序中自不必说,在使用包组织的Flask程序中,创建程序实例时必然需要导入视图函数所在的模块,或是蓝本所在的模块,而这些模块会导入模型类。

下面我们会通过解析源码简单了解模型类对应的表信息是如何注册到db.Model.metadata.tables中的。

不论是单独使用SQLAlchemy时创建的Base基类,还是使用Flask-SQLAlchemy时创建db对象后的db.Model基类,都是通过declarative_base()函数创建,具体源码如下:

def declarative_base(bind=None, metadata=None, mapper=None, cls=object,
                     name='Base', constructor=_declarative_constructor,
                     class_registry=None,
                     metaclass=DeclarativeMeta):

    lcl_metadata = metadata or MetaData()
    if bind:
        lcl_metadata.bind = bind

    if class_registry is None:
        class_registry = weakref.WeakValueDictionary()

    bases = not isinstance(cls, tuple) and (cls,) or cls
    class_dict = dict(_decl_class_registry=class_registry,
                      metadata=lcl_metadata)

    if isinstance(cls, type):
        class_dict['__doc__'] = cls.__doc__

    if constructor:
        class_dict['__init__'] = constructor
    if mapper:
        class_dict['__mapper_cls__'] = mapper

    return metaclass(name, bases, class_dict)

源码位置:github.com/zzzeek/sqlal

这个函数返回一个元类实例,对应的元类为DeclarativeMeta,这个元类定义了一些特殊行为:

class DeclarativeMeta(type):
    def __init__(cls, classname, bases, dict_):
        if '_decl_class_registry' not in cls.__dict__:
            _as_declarative(cls, classname, cls.__dict__)
        type.__init__(cls, classname, bases, dict_)

    def __setattr__(cls, key, value):
        _add_attribute(cls, key, value)

    def __delattr__(cls, key):
        _del_attribute(cls, key)

源码位置:github.com/zzzeek/sqlal

_as_declarative()函数以及附加的其他多层调用为这个类进行了更多设置,比如添加__table__属性为存储表信息的Table对象,设置metadata属性等等。

其中魔法方法__setattr__()中调用了_add_attribute()函数,这个函数执行了一系列模型类属性的注册操作,其中的一个操作便是向基类 __table__属性指向的Table对象调用append_column()方法添加表字段信息:

def _add_attribute(cls, key, value):
    if '__mapper__' in cls.__dict__:
        if isinstance(value, Column):
            _undefer_column_name(key, value)
            cls.__table__.append_column(value)
            cls.__mapper__.add_property(key, value)
        ...

源码位置:github.com/zzzeek/sqlal

经过这一系列注册操作,表信息就被添加到db.Model.metadata.tables属性中,这个属性返回包含所有表信息的字典(表名称与Table实例的映射),下面是一个示例:

immutabledict({'comment': Table('comment', MetaData(bind=None), Column('id'
, Integer(), table=<comment>, primary_key=True, nullable=False), Column('bo
dy', Text(), table=<comment>), Column('timestamp', DateTime(), table=<comme
nt>, default=ColumnDefault(<function utcnow at 0x03D2E3F0>)), Column('flag'
, Integer(), table=<comment>, default=ColumnDefault(0)), Column('author_id
', Integer(), ForeignKey('user.id'), table=<comment>), Column('photo_id', I
nteger(), ForeignKey('photo.id'), table=<comment>), schema=None)})             

db.Model.metadata存储MetaData类实例,MetaData类实例存储Table类实例的集合,而Table类实例存储模型类对应的数据库表字段信息,可以通过模型类的__table__属性获取。create_all()方法实际调用的是db.Model.metadata.create_all 方法,这个方法会将Table类实例存储的信息转换为数据库模式(通过sqlclchemy.sql.ddl.SchemaGenerator)。

顺便说一句,因为表信息存储在特定的基类中,所以为了正确创建数据库表,你需要对模型类继承的基类调用create_all()方法,即db.create_all(),或是Base.metadata.create_all(engine)。如果你在测试时新创建一个db对象或是Base基类,那么它是不会包含表信息的。

这篇文章来自我在知乎写的这个回答,作为备份。