标签归档:Flask

WTForms自定义验证方法(行内验证器)是如何被调用的?

这篇文章基于我在知乎上的这个回答,进行了相应的简化处理,放到这里做个备份。

万能的回答

答案在源码里。

简单的回答

WTForms会在你对表单实例调用Form.validate()方法时收集所有的行内验证方法,然后在对每个字段调用Field.validate()方法验证时将这些自定义行内验证方法一并和通过validators参数传入的验证器列表一起调用,进行验证。因为WTForms在调用时把对应的field作为参数传入了行内验证方法,所以你可以在自定义验证方法中通过field.data获取对应字段的数据。

深入的回答

WTForms会在你对表单实例调用Form.validate()方法时收集所有的行内验证方法。在Form类中的validate()方法定义中,你可以看到WTForms是如何收集这些行内验证方法的:

class Form(with_metaclass(FormMeta, BaseForm)): 
   ....
   def validate(self):
        extra = {}
        for name in self._fields:
            inline = getattr(self.__class__, 'validate_%s' % name, None)
            if inline is not None:
                extra[name] = [inline]

        return super(Form, self).validate(extra)

源码位置:github.com/wtforms/wtfo

这里迭代所有的字段属性,然后表单类中是否包含validate_字段名形式的方法。如果有,那么就添加到extra字段里,这个字段被传递到BaseForm类的validate()方法中。在BaseForm类的validate()方法中,WTForms迭代所有字段,并对每个字段调用Field.validate()方法验证字段,继续传入自定义的行内验证方法:

class BaseForm(object):
    ...
    def validate(self, extra_validators=None):
        self._errors = None
        success = True
        for name, field in iteritems(self._fields):  # 迭代字段名和字段对象
            if extra_validators is not None and name in extra_validators:  # 判断当前迭代字段是否存在自定义验证器
                extra = extra_validators[name]
            else:
                extra = tuple()
            if not field.validate(self, extra):  # 调用字段类的验证方法进行验证,传入自定义验证器
                success = False
        return success

源码位置:github.com/wtforms/wtfo

而在字段基类Field的validate()方法中,WTForms使用itertool模块提供的chain()函数把你实例化字段类时传入的验证器(self.validators)和自定义行内验证器(extra_validators)连接到一起:

class Field(object):    
    ...
    def validate(self, form, extra_validators=tuple()):
        ...
        # Run validators
        if not stop_validation:
            chain = itertools.chain(self.validators, extra_validators)  # 合并两类验证器
            stop_validation = self._run_validation_chain(form, chain)  # 运行验证器
        ...

源码位置:github.com/wtforms/wtfo

连接起来的所有验证器赋值为chain变量,并传入到self._run_validation_chain(form, chain)进行进一步调用:

class Field(object):    
    ...
    def _run_validation_chain(self, form, validators):
        for validator in validators:
            try:
                validator(form, self)  # 传入字段类本身作为第二个参数

源码位置:github.com/wtforms/wtfo

这个方法迭代所有的验证器对字段数据进行验证。关键在于validator(form, self),可以看到这里传入了第二个参数self,即Field类本身,这也是为什么你可以在自定义验证方法中通过field.data获取当前字段数据。

《Flask Web开发实战》中的实战项目

很多朋友对《Flask Web开发实战》中的项目实例很感兴趣,这篇文章就来简单的对这些项目进行介绍,并给出一些截图。这几个项目的源码和在线Demo链接均可以在helloflask.com看到。

第1~6章及13章:helloflask

Hello, Flask!

第1~6章以及第13章的示例程序统一包含在helloflask仓库中的demos目录下。另外,这个仓库也作为《Flask Web开发实战》的仓库,书的勘误文件等内容也会一并在这里更新。

Flask Web开发实战第6章电子邮件示例程序

Flask Web开发实战第6章电子邮件示例程序

Flask Web开发实战第5章数据库示例程序

Flask Web开发实战第5章数据库示例程序


第7章:留言板 – SayHello

Say hello to the world.

这个项目比较简单,主要用来介绍项目组织和Web程序开发流程,没有复杂功能,介绍了虚拟数据的生成和时间日期的本地化。

SayHello绝对时间弹窗

SayHello绝对时间弹窗

SayHello主页

SayHello主页

第8章:个人博客 – Bluelog

A blue blog.

一个基础的博客程序,使用工厂函数和蓝本组织程序,主要包含下面这些功能点:

  • 使用工厂函数创建程序实例
  • 使用蓝本模块化程序
  • 使用富文本编辑器
  • 创建文章/分类/评论
  • 编辑文章/分类
  • 删除文章/分类/评论
  • 回复评论
  • 管理后台
  • 文章分类
  • 文章分页
  • 博客设置
  • 用户认证
  • 网站主题切换

博客主页

博客主页

更换了主题的博客主页

更换了主题的博客主页

博客后台的文章管理页面

博客后台的文章管理页面

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

Capture and share every wonderful moment.

一个进阶的程序实例,主要包含下面的功能点:

  • 大型项目组织形式
  • 用户注册流程
  • 用户角色和权限管理
  • 图片上传
  • 图片处理
  • 删除确认模态框
  • 图片分类
  • 图片标签
  • 用户资料弹窗
  • 图片收藏
  • 用户关注
  • 在资料弹窗中执行关注操作
  • 消息提醒
  • 消息提醒的实时更新
  • 生成随机头像
  • 用户自定义头像
  • 更改密码
  • 提醒消息开关
  • 收藏可见开关
  • 注销账户
  • 全文搜索
用户个人主页

用户个人主页

网站动态页面

网站动态页面

评论中的用户资料弹窗

评论中的用户资料弹窗

头像裁剪

头像裁剪


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

We are todoist, we use todoism.

一个简单的待办事项程序,使用jQuery实现简单的单页效果,主要包含下面的功能点:

  • 单页程序
  • 国际化和本地化支持
  • 实现Web API
程序主页

程序主页

切换语言后的程序主页

切换语言后的程序主页


第11章:在线聊天室 – CatChat

Chatroom for coders, not cats.

一个使用Flask-SocketIO实现的聊天室,主要包含下面这些功能点:

  • Gravatar头像
  • 实时双向通讯
  • 第三方登录
  • 无限滚动加载历史消息
  • Markdown支持
  • 代码语法高亮
  • 标签页消息提醒
  • 浏览器桌面通知
聊天页面

聊天页面

登录页面

登录页面

代码语法高亮

代码语法高亮


第15章:Flask扩展 – Flask-Share

Create social share component in Jinja2 template based on share.js.

Flask-Share是一个基于share.js实现,可以在模板中方便的创建社交分享组件的扩展。

创建社交分享组件

创建社交分享组件

使用GitHub-Flask实现GitHub第三方登录

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

前言

这篇文章大部分内容为《Flask Web开发实战》第10章的删减章节,另外摘取了部分书中现有的内容。我为这篇文章单独编写了示例程序,GitHub地址为https://github.com/helloflask/github-login。运行示例程序的步骤如下:

$ git clone https://github.com/helloflask/github-flask.git
$ cd github-login
$ pipenv install --skip-lock  # 如果没有安装pipenv,那么执行pip install pipenv
$ flask run  # 在此之前需要在GitHub注册OAuth程序并将客户端ID与密钥写入程序,具体见下文
如果你想直接体验程序,可以访问部署在PythonAnywhere(“到处都是蛇”)的在线实例
 

附注 第三方登录的原理是与第三方服务进行OAuth认证交互的,这里不会详细介绍OAuth,具体可以阅读OAuth官网列出的资源,另外即将上市的Flask新书里也提供了相关内容。

什么是第三方登录

简单来说,为一个网站添加第三方登录指的是提供通过其他第三方平台账号登入当前网站的功能。比如,使用QQ、微信、新浪微博账号登录。对于某些网站,甚至可以仅提供社交账号登录的选项,这样网站本身就不需要管理用户账户等相关信息。对用户来说,使用第三方登录可以省去注册的步骤,更加方便和快捷。

如果项目和GitHub、开源项目、编程语言等方面相关,或是面向的主要用户群是程序员时,可以仅支持GitHub的第三方登录,比如Gitter、GitBook、Coveralls和Travis CI等。在Flask程序中,除了手动实现,我们可以借助其他扩展或库,我们在这篇文章里要使用的GitHub-Flask扩展专门用于实现GitHub第三方登录,以及与GitHub进行Web API资源交互。

第三方登录授权流程

起这个标题是为了更好理解,具体来说,整个流程实际上是指OAuth2中Authorization Code模式的授权流程。为了便于理解,这里按照实际操作顺序列出了整个授权流程的实现步骤:

  1. 在GitHub为我们的程序注册OAuth程序,获得Client ID(客户端ID)和Client Secret(客户端密钥)。
  2. 我们在登录页面添加“使用GitHub登录”按钮,按钮的URL指向GitHub提供的授权URL,即https://github.com/login/oauth/authorize
  3. 用户点击登录按钮,程序访问GitHub的授权URL,我们在授权URL后附加查询参数Client ID以及可选的Scope等。GitHub会根据授权URL中的Client ID识别出我们的程序信息,根据scope获取请求的权限范围,最后把这些信息显示在授权页面上。
  4. 用户输入GitHub的账户及密码,同意授权
  5. 用户同意授权后GitHub会将用户重定向到我们注册OAuth程序时提供的回调URL。如果用户同意授权,回调URL中会附加一个code(即Authorization Code,通常称为授权码),用来交换access令牌(即访问令牌,也被称为登录令牌、存取令牌等)。
  6. 我们在程序中接受到这个回调请求,获取code,发送一个POST请求到用于获取access令牌的URL,并附加Client ID、Client Secret和code值以及其他可选的值。
  7. GitHub接收到请求后,验证code值,成功后会再次向回调URL发起请求,同时在URL的查询字符串中或请求主体中加入access令牌的值、过期时间、token类型等信息。
  8. 我们的程序获取access令牌,可以用于后续发起API资源调用,或保存到数据库备用
  9. 如果用户是第一次登入,就创建用户对象并保存到数据库,最后登入用户
  10. 这里可选的步骤是让用户设置密码或资料

在GitHub注册OAuth程序

和其他主流第三方服务相同,GitHub使用OAuth2中的Authorization Code模式认证。因为认证后,根据授权的权限,客户端可以获取到用户的资源,为了便于对客户端进行识别和限制,我们需要在GitHub上进行注册,获取到客户端ID和密钥才能进行OAuth授权。

在服务提供方的网站上进行OAuth程序注册时,通常需要提供程序的基本信息,比如程序的名称、描述、主页等,这些信息会显示在要求用户授权的页面上,供用户识别。在GitHub中进行OAuth程序注册非常简单,访问https://github.com/settings/applications/new填写注册表单(如果你没有GitHub账户,那么需要先注册一个才能访问这个页面。),注册表单各个字段的作用和示例如图所示。

在GitHub注册OAuth程序

在GitHub注册OAuth程序

表单中的信息都可以后续进行修改。在开发时,程序的名称、主页和描述可以使用临时的占位内容。但Callback URL(回调URL)需要正确填写,这个回调URL用来在用户确认授权后重定向到程序中。因为我们需要在本地开发时进行测试,所以需要填写本地程序的URL,比如http://127.0.0.1:5000/callback/github,我们需要创建处理这个请求的视图函数,在这个视图函数中获取回调URL附加的信息,后面会详细介绍。

注意 这里因为是在开发时进行本地测试,所以填写了程序运行的地址,在生产环境要避免指定端口。另外,在这里localhost和127.0.0.1将会被视为两个地址。在程序部署上线时,你需要将这些地址更换为真实的网站域名地址。

注册成功后,我们会在重定向后的页面看到我们的Client ID(客户端ID)和Client Secret(客户端密钥),我们需要将这两个值分别赋值给配置变量GITHUB_CLIENT_ID和GITHUB_CLIENT_SECRET:

GITHUB_CLIENT_ID = 'GitHub客户端ID'
GITHUB_CLIENT_SECRET = 'GitHub客户端密钥'

注意 示例程序中为了便于测试,直接在脚本中写出了,在生产环境下,你应该将它们写入到环境变量,然后在脚本中从环境变量读取。

安装并初始化GitHub-Flask

首先使用pip或Pipenv等工具安装GitHub-Flask:

$ pip install github-flask

和其他扩展类似,你可以使用下面的方式初始化扩展(注意扩展类大小写):

from flask import Flask
from flask_github import GitHub
app = Flask(__name__)
github = GitHub(app)

如果你使用工厂函数创建程序,那么可以使用下面的方式初始化扩展:

from flask import Flask
from flask_github import GitHub
github = GitHub()
... 

def create_app():
    app = Flask(__name__)
    app.config.from_pyfile('settings.py')
    github.init_app(app)
    ...
    return app

注意 虽然扩展名称是GitHub-Flask,但实际的包名称仍然是flask_github(Flask扩展名称可以倒置(即“Foo-Flask”),但包名称的形式必须为“flask_foo“。)。另外要注意扩展类的拼写,其中H为大写。

进行OAuth授权

创建用户模型

在示例程序中,我们首先进行了下面的基础工作:

  • 定义基本配置
  • 创建一个简单的用户模型来存储用户信息(使用Flask-SQLAlchemy)
  • 实现登录和注销的管理功能(使用session实现,可以使用Flask-Login简化)
  • 创建用于初始化数据库的命令函数
app = Flask(__name__)

app.config['SECRET_KEY'] = os.getenv('SECRET_KEY', 'secret string')
# Flask-SQLAlchemy
app.config['SQLALCHEMY_DATABASE_URI'] = os.getenv('DATABASE_URL', 'sqlite:///' + os.path.join(app.root_path, 'data.db'))
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False

db = SQLAlchemy(app)

# 命令函数
@app.cli.command()
@click.option('--drop', is_flag=True, help='Create after drop.')
def initdb(drop):
    """Initialize the database."""
    if drop:
        db.drop_all()
    db.create_all()
    click.echo('Initialized database.')

# 存储用户信息的数据库模型类
class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(100))  # 用户名
    access_token = db.Column(db.String(200))  # 授权完成后获取的访问令牌

# 管理每个请求的登录状态,如果已登录(session里有用户id值),将模型类对象保存到g对象中
@app.before_request
def before_request():
    g.user = None
    if 'user_id' in session:
        g.user = User.query.get(session['user_id'])

# 登入
@app.route('/login')
def login():
    if session.get('user_id', None) is None:
        ...  # 进行OAuth授权流程,具体见后面
    flash('Already logged in.')
    return redirect(url_for('index'))

# 登出
@app.route('/logout')
def logout():
    session.pop('user_id', None)
    flash('Goodbye.')
    return redirect(url_for('index'))

现在我们可以执行上面创建的initdb命令来创建数据库和表(确保当前目录在demos/github-login下):

$ flask initdb

创建登录按钮

我们在本节一开始详细描述了以GitHub为例的完整的OAuth授权的过程,现在让我们来创建登录按钮。示例程序非常简单,只包含一个主页(index.html),这个页面由index视图处理:

@app.route('/')
def index():
    is_login = True if g.user else False  # 判断用户登录状态
    return render_template('index.html', is_login=is_login)

这个视图在渲染模板时传入了用于判断用户登录状态的is_login变量,我们在模板中根据这个变量渲染不同的元素,如果已经登入,显示退出按钮,否则显示登入按钮:

{% if is_login %}
    <a class="btn" href="{{ url_for('logout') }}">Logout</a>
{% else %}
    <a class="btn" href="{{ url_for('login') }}">Login with GitHub</a>
{% endif %}

在实际的项目中,你可以使用GitHub的logo来让登录按钮更好看一些。

提示 使用Flask-Login时,你可以直接在模板中通过current_user.is_authenticated属性来判断用户登入状态。

发送授权请求

这个登录按钮的URL指向的是login视图,这个视图用来发送授权请求,如下所示:

@app.route('/login')
def login():
    if session.get('user_id', None) is None:  # 判断用户登录状态
        return github.authorize(scope='repo')
    flash('Already logged in.')
    return redirect(url_for('index'))

在这个视图中,如果用户没有登录,我们就调用github.authorize()方法。这个方法会生成授权URL,并向这个URL发送请求。

附注 GitHub-Flask扩内置了除了客户端ID和密钥外所有必要的URL,比如API的URL,获取访问令牌的URL等(我们也可以通过相应的配置键进行修改,具体参考GitHub-Flask的文档)。

发起认证请求的URL中必须加入的参数是客户端ID,GitHub-Flask会自动使用我们之前通过配置变量传入的值。在授权URL中附加的可选参数如下所示:

名称

类型

说明

scope

字符串

请求的权限列表,使用空格分隔

state

字符串

用于CSRF保护的随机字符,也就是CSRF令牌

redirect_uri

字符串

用户授权结束后的重定向URL(必须是外部URL)

这三个参数都可以在调用github.authorize()方法时使用对应的名称作为关键字参数传入。

如果不设置scope,GitHub-Flask扩展默认设置为None,那么会拥有的权限是获取用户的公开信息。但是因为我们需要测试为项目加星(star)的操作,所以需要请求名为repo的权限值。

附注 选择scope时尽量只选择需要的内容,申请太多的权限可能会被用户拒绝。GitHub提供的所有的可用scope列表及其说明可以在GitHub开发文档看到。

如果不设置redirect_uri,那么GitHub会使用我们填写的callback URL。但是需要注意的是,如果我们填写了,那就必须和注册程序时填写的URL完全相同。我们在这里没有指定,因此将会使用注册OAuth程序时设置的http://localhost:5000/callback/github

获取access令牌(访问令牌)

现在程序会重定向到GitHub的授权页面(会先要求登录GitHub),如下所示:

授权页面

授权页面

当用户同意授权或拒绝授权后,GitHub会将用户重定向到我们设置的callback URL,我们需要创建一个视图函数来处理回调请求。如果用户同意授权,GitHub会在重定向的请求中加入code参数,一个临时生成的值,用于程序再次发起请求交换access token。程序这时需要向请求访问令牌URL(即https://github.com/login/oauth/access_token)发起一个POST请求,附带客户端ID、客户端密钥、code以及可选的redirect_uri和state。请求成功后的的响应会包含访问令牌(Access Token)。

很幸运,上面的一系列工作GitHub-Flask会在背后替我们完成。我们只需要创建一个视图函数,定义正确的URL规则(这里的URL规则需要和GitHub上填写的Callback URL匹配),并为其附加一个github.authorized_handler装饰器。另外,这个函数要接受一个access_token参数,GitHub-Flask会在授权请求结束后通过这个参数传入访问令牌,如下所示:

@app.route('/callback/github')
@github.authorized_handler
def authorized(access_token):
    if access_token is None:
        flash('Login failed.')
        return redirect(url_for('index'))
    # 下面会进行创建新用户,保存访问令牌,登入用户等操作,具体见后面
    ...
    return redirect(url_for('chat.app'))

接受到GitHub返回的响应后,GitHub-Flask会调用这个authorized()函数,并传入access_token的值。如果授权失败,access_token的值会是None,这时我们重定向到主页页面,并显示一个错误消息。如果access_token不为None,我们会进行创建新用户,保存访问令牌,登入用户等操作,具体见下一节。

获取用户在GitHub上的资源

在获取到访问令牌后,我们需要做下面的工作:

  • 判断用户是否已经存在于数据库中,如果存在就登入用户,更新访问令牌值(因为access是有过期时间的)
  • 如果数据库中没有该用户,那么创建一个新的用户记录,传入对应的数据,最后登入用户

在这个示例程序中,我们使用用户名(username)作为用户的唯一标识,为了从数据库中查找对应的用户,我们需要获取用户在GitHub上的用户名。

如果授权成功,那么我们就使用这个访问令牌向GitHub提供的Web API的/user端点发起一次GET请求。这可以通过GitHub-Flask提供的get()方法实现,传入访问令牌作为access_token参数的值。我们把表示用户的资源端点“user”传入get()方法,因为GitHub-Flask会自动补全完整的请求URL,即https://api.github.com/user

response = github.get('user', access_token=access_token)

提示 GitHub-Flask提供了一系列方法来调用GitHub通过Web API开放的资源。和在jQuery为AJAX提供的方法类似,它提供了底层的request()方法和方便的get()、post()、put()、delete()等方法(这些方法内部会调用request方法),可以用来发送不同HTTP方法的请求。

/user端点对应用户资料,返回的JSON数据如下所示:

{
 "avatar_url": "https://avatars3.githubusercontent.com/u/12967000?v=4", 
 "bio": null, 
 "blog": "greyli.com", 
 "company": "None", 
 "created_at": "2015-06-19T13:00:23Z", 
 "email": "withlihui@gmail.com", 
 "events_url": "https://api.github.com/users/greyli/events{/privacy}", 
 "followers": 132, 
 "followers_url": "https://api.github.com/users/greyli/followers", 
 "following": 8, 
 "following_url": "https://api.github.com/users/greyli/following{/other_user}", 
 "gists_url": "https://api.github.com/users/greyli/gists{/gist_id}", 
 "gravatar_id": "", 
 "hireable": true, 
 "html_url": "https://github.com/greyli", 
 "id": 12967000, 
 "location": "China", 
 "login": "greyli", 
 "name": "Grey Li", 
 "node_id": "MDQ6VXNlcjEyOTY3MDAw", 
 "organizations_url": "https://api.github.com/users/greyli/orgs", 
 "public_gists": 7, 
 "public_repos": 61, 
 "received_events_url": "https://api.github.com/users/greyli/received_events", 
 "repos_url": "https://api.github.com/users/greyli/repos", 
 "site_admin": false, 
 "starred_url": "https://api.github.com/users/greyli/starred{/owner}{/repo}", 
 "subscriptions_url": "https://api.github.com/users/greyli/subscriptions", 
 "type": "User", 
 "updated_at": "2018-06-24T02:05:38Z", 
 "url": "https://api.github.com/users/greyli"
}

附注 用户端点返回的响应示例以及其他所有开放的资源端点可以在GitHub的API文档(https://developer.github.com/v3/)中看到。

GitHub-Flask会把GitHub的JSON响应主体解析为一个字典并返回,我们使用对应的键获取这些数据。其中登录用户名使用login作为键获取:

username = response['login']

获取到用户名后,我们判断是否已存在该用户,如果存在更新access_token字段值;如果不存在则创建一个新的User实例,把用户名和访问令牌存储到用户模型的对应字段里:

user = User.query.filter_by(username=username).first()
if user is None:
    user = User(username=username, access_token=access_token)
    db.session.add(user)
 user.access_token = access_token # update access token
 db.session.commit()

最后,我们登入对应的用户对象或是新创建的用户对象(将用户id写入session):

flash('Login success.')
# log the user in
# if you use flask-login, just call login_user() here.
session['user_id'] = user.id

因为我们需要在其他视图里调用GitHub资源,为了避免每次都获取和传入访问令牌,我们可以使用github.access_token_getter装饰器创建一个统一的令牌获取函数: 

@github.access_token_getter
def token_getter():
    user = g.user
    if user is not None:
       return user.access_token

当你在某处直接使用github.get()等方法而不传入访问令牌时,GitHub-Flask会通过你提供的这个回调函数来获取访问令牌。

注意 虽然在很多开源库的示例程序中,都会把access令牌存储到session中,但session不能用来存储敏感信息(具体可以访问专栏的这篇文章了解)。所以除了作测试用途,在生产环境下正确的做法是把访问令牌存储到数据库中。

现在,我们的主页视图需要更新,对于登录的用户,我们将会显示用户在GitHub上的资料:

@app.route('/')
def index():
    if g.user:
        is_login = True
        response = github.get('user')
        avatar = response['avatar_url']
        username = response['name']
        url = response['html_url']
        return render_template('index.html', is_login=is_login, avatar=avatar, username=username, url=url)
    is_login = False
    return render_template('index.html', is_login=is_login)

类似的,我们使用github.get()方法获取/user端点的用户资料,因为设置了令牌获取函数,所以不用显式的传入访问令牌值。这些数据(头像、显示用户名和GitHub用户主页URL)将会显示在主页,如下图所示:

登录成功后的主页

登录成功后的主页

因为我们在进行授权时请求了repo权限,我们还可以对用户的仓库进行各类操作,示例程序中添加了一个加星的示例,如果你登录后点击主页的“Star HelloFlask on GitHub”按钮,就会加星对应的仓库。这个按钮指向的star视图如下所示:

@app.route('/star/helloflask')
def star():
    github.put('user/starred/greyli/helloflask', headers={'Content-Length': '0'})
    flash('Star success.')
    return redirect(url_for('index'))

完整的用于处理回调请求的authorized()视图函数如下所示:

@app.route('/callback/github')
@github.authorized_handler
def authorized(access_token):
    if access_token is None:
        flash('Login failed.')
        return redirect(url_for('index'))

    response = github.get('user', access_token=access_token)
    username = response['login'] # get username
    user = User.query.filter_by(username=username).first()
    if user is None:
        user = User(username=username, access_token=access_token)
        db.session.add(user)
    user.access_token = access_token # update access token
    db.session.commit()
    flash('Login success.')
    # log the user in
    # if you use flask-login, just call login_user() here.
    session['user_id'] = user.id
    return redirect(url_for('index'))

走进现实

一次完整的OAuth认证就这样完成了。在实际的项目中,支持第三方登录后,我们需要对原有的登录系统进行调整。通过第三方认证创建的用户没有密码,所以如果这部分用户使用传统方式登录的话会出现错误。我们添加一个if判断,如果用户对象的password_hash字段为空时,我们会返回一个错误提示,提醒用户使用上次使用的第三方服务进行登录,如下所示:

@app.route('/login', methods=['GET', 'POST'])
def login():
    ...
    if request.method == 'POST':
        ...
        user = User.query.filter_by(email=email).first()

        if user is not None:
            if user.password_hash is None:
                flash('Please use the third patry service to log in.')
                return redirect(url_for('.login'))
        ...

如果你想让用户也可以直接使用账户密码登录,那么可以在授权成功后重定向到新的页面请求用户设置密码。

相关链接

《Flask Web开发实战》最新动态

《Flask Web开发实战:入门、进阶与原理解析》是我刚刚完成写作的一本技术书,涵盖了Flask Web开发学习的完整路径,而且包含大量的程序实例。你可以通过下面的文章了解这本书的更多信息:

本书动态:

  • 2017/3/1 开始写作
  • 2017/12/7 初稿完成
  • 2018/1/18 二稿完成
  • 2018/3/26 三稿完成
  • 2018/4/29 四稿完成
  • 2018/5/16 五稿完成
  • 2018/5/22 定稿(六稿)
  • 2018/6/5 确定最终修改,写作正式完结
  • 2018/6/20 完成封面设计初稿
  • 2018/6/22 完成封面文案初稿
  • 2018/6/22 确定英文书名为《Python Web Development with Flask》
  • 2018/8/20 下厂印刷
  • 2018/8/24 Kindle电子书上架(https://www.amazon.cn/dp/B07GST8Z8M
  • 2018/8/26 本书的豆瓣条目页面创建成功
  • 2018/8/28 电子书上架豆瓣阅读(read.douban.com/ebook/5
  • 2018/9/10 电商平台已经可以购买,亚马逊和京东自营预计9/15有货,访问本书主页查看购买链接

一本更好的Flask书——《Flask Web开发实战》

如果你想了解这本书的最新动态,可以关注我的公众号Twitter豆瓣,也可以访问本书主页 http://helloflask.com/book

欢迎加入 HelloFlask 论坛QQ群(419980814)、微信群(备注“入群”)或 Telegram 群组讨论相关话题。

购买方式

欢迎访问本书的豆瓣图书页面撰写书评或短评。

电子书各平台的排版效果不一,购买前请先进行试读。

为什么说这是一本更好的Flask书

现有的几本Flask书包含下面这些问题:
 
  • 内容较旧,不论是Flask本身,还是其他扩展和Python库。
  • 包含误区或不完善的代码实现,比如在使用SQLAlchemy建立数据库关系时,出于性能的考虑,一般不会把加载关系记录的方式设为dynamic。
  • 示例程序过于简单,比如甚至没有删除帖子的功能。
  • 内容比较单一,仅包含入门知识。
相对的,这本《Flask Web开发实战:入门、进阶与原理解析》当然避免了以上问题:
 
  • Flask使用最新的1.0.2版本,使用Pipenv管理示例程序依赖,所有扩展和其他Python库均使用最新版本。不仅如此,项目中使用的前端框架Bootstrap(4.1)、Materialize(1.0)和Semantic-UI(2.3)也均使用最新版本。
  • 纠正了常见误区,并在相应位置给出提示。
  • 包含多个不同复杂程度的示例程序,尽可能的让程序贴近真实使用情况。
  • 如副书名所示,这本书除了基本的入门知识,还包含进阶内容和原理解析。
看到书名,你的第一想法也许是:为什么书名和Miguel Grinberg的书那么像?起书名并非由我一人决定,而且技术书的起名没有多大自由度,你不仅要考虑加入合适的关键词,还要考虑到如何凸显书的主要特点。“Flask Web开发”的确是简洁又突出重点的好名字,我们在后面添加了“实战”,用来着重体现这本书的最大特点。

3个推荐语

这本书内容翔实,推荐给想要系统学习Flask的人。不要漏掉书中的小知识点哦。
             —— Flask开发团队(Pallets)核心维护者 Hsiaoming Yang(lepture)
这本《Flask Web开发实战》非常有趣,是一本能够给读者带来帮助的书,作为一个Flask框架的爱好者,我也很期待这本书的出版。
—— 《Redis设计与实现》作者 黄健宏(huangz)
Grey Li is a really helpful contributor to Flask and the Python community. He is making it easier for more people to learn and use Flask.
—— Flask开发团队(Pallets)核心维护者 David Lord(davidism)

8个示例程序、5个项目实例、1个扩展

包含丰富的实例是这本书的最大特点,这也是为什么要把“实战”放到书名里。
 
书的第一部分(基础篇)共6章,每一章都包含一个示例程序,示例程序包含每章涉及的大部分代码,你可以实际运行程序来查看效果。以第5章《数据库》为例,除了一个简单的演示“增删查改”的笔记程序外,示例程序中还包含“一对多”、“多对一”、“一对一”、“多对多”、“一对多+双向关系”、“一对多+双向关系+使用backref简化关系定义”、“级联设置”“数据库时间监听函数”等15(2 * 7 + 1)个模型类定义和2个事件监听函数(两种实现方式)。
第1~6章以及第13章的示例程序统一包含在helloflask仓库中的demos目录下。
第二部分(实战篇)共5章,每一章都通过一个程序来组织起所有的知识点。这5个程序分别为:留言板SayHello、个人博客Bluelog、图片社交网站Albumy、待办事项程序Todoism和聊天室CatChat。你可以在下面的《章节概括》部分查看每一个示例程序所涉及的知识点。
和《Flask Web开发》中的做法类似,这部分的示例程序均使用Git标签来组织不同阶段的代码,方便你签出相应的版本或是进行对比。
第三部分(进阶篇)第13章《性能优化》通过两个实例程序来介绍使用Flask-Caching和Flask-Assets对Flask程序添加缓存和进行静态资源优化的前后变化对比。第15章《Flask扩展开发》则通过一个简单的为页面中添加社交分享组件的Flask-Share扩展来完整介绍从创建Git仓库到使用twine将包上传到PyPI的完整扩展开发流程。
你可以在文章《Flask Web开发实战》中的示例程序们一文中了解这些程序的具体信息,其中包含大量程序界面截图。
这几个项目的源码和在线Demo链接均可以在helloflask.com看到。

满足80%的读者提议

在文章《写一本Flask书》中,很多知友通过评论给出了希望看到的内容和建议。我做了简单的收集和处理,粗略的浏览,大概有80%的读者提议得到了满足。

内容丰富,大约700页

这本书在介绍基础知识外,还引入了许多进阶技巧。第一部分从第2章开始每一章都包含一个《进阶实践》章节,其中包含一些常见的技巧,比如“如何安全的跳转回上一页”,“使用WTForms表单内置的中文错误消息”,“数据库事件监听”等,具体可以参考下面的《目录》部分。
 
另外,这本书还介绍了一些被其他Flask书忽略,但又非常实用的知识,比如实现AJAX时Flask和JavaScript交互数据的方式、通过AJAX实现的资料弹窗、在弹窗中实现动态的关注收藏按钮、通过AJAX实现简单的单页程序、实时双向通讯、国际化和本地化、全文搜索、第三方登录、Markdown支持、代码语法高亮、头像裁剪、设置缓存等。
 
本书会尽量提供多个技术选型,比如第6章《电子邮件》中,除了介绍使用Flask-Mail实现发送电子邮件,还介绍了使用事务邮件服务SendGrid发送电子邮件的两种方式;在第14章《部署上线》中,我介绍了一个基本的服务器初始化过程,包括安装基本的而库、设置SSH密钥登录、设置防火墙等部署,接着才是Gunicorn、Nginx和Supervisor的使用介绍。除了Linux部署,还介绍了使用PythonAnywhere和Heroku的程序部署流程。
 
尽管如此,在多次修改的过程中,我还是删掉了大量内容(近8万字约240页):
 
  • 在Flask程序中使用Celery
  • Fabric自动化部署
  • 使用Tox自动化测试
  • 使用Sentry处理日志
  • 使用Docker开发和部署Flask程序
  • NoSQL数据库的使用介绍
  • 使用Frozen-Flask静态化处理程序
  • 静态部署
  • Flask-SSE的使用
  • Travis CI、Coverall的使用
  • 使用GitHub-Flask集成GitHub登录
这些内容或是偏离主题,或是有了更好的替代内容,删掉这些内容一方面可以保证书的内容贴近主题,同时也可以避免成书太厚。因为内容丰富,所以最终完稿共980页,成书大概会在700页左右。
对于这些删减掉的内容,我会抽取有价值的内容并进行完善后陆续发布在专栏中。

关于我

我是李辉,一个Python开发者,Flask开发团队(Pallets Team)的成员。我在GitHub上维护了几个Flask扩展项目,也尝试为多个Flask相关项目贡献代码和处理Issue;除了知乎,我偶尔会在Stack Overflow上回答一些Flask相关的问题。如果你想了解我的项目或书的最新动态,可以关注我的Twitter新浪微博账号。

章节概括

下面是本书的章节概括,简单的介绍了各章的内容,你可以通过下面的《目录》部分来了解详细的内容。本书由四部分组成,分别为基本篇、实战篇、进阶篇和附录,共16章。本书的章节安排经过精心的设计,力求让读者可以循序渐进的掌握Flask开发基础知识和技巧。
 
第一部分:基础篇 介绍Flask开发相关的基础知识。
 
  • 第1章:搭建开发环境,编写一个最小的Flask程序并运行它,了解Flask基本知识。
  • 第2章:介绍了Flask与HTTP的交互方式以及相关的Flask功能。
  • 第3章:Jinja2模板的使用和技巧。
  • 第4章:Web表单的创建和表单数据的验证。
  • 第5章:在Flask程序中使用数据库进行CRUD操作,各类数据库关系的建立。
  • 第6章:在Flask程序中发送电子邮件的几种方式,使用Flask-Mail通过SMTP服务器发送,或是通过事务邮件服务SendGrid(SMTP和Web API两种方式)。
第二部分:实战篇 通过几个示例程序来介绍Flask开发中的各类功能实现和技巧。
 
  • 第7章:通过一个简单的留言板程序SayHello介绍Web开发基本流程和基本的项目管理方式,对第一部分的基础知识进行简单的回顾,最后还介绍了Faker、Flask-Moment和Flask-DebugToolbar的使用。
  • 第8章 :通过个人博客程序Bluelog介绍CRUD操作、用户认证(Flask-Login)、文章评论和回复、后台管理等功能,其中还包括网站主题更换,渲染导航链接等小技巧。
  • 第9章:通过图片社交程序Albumy介绍用户注册和认证、用户权限管理、图片上传(Flask-Dropzone)与处理(Pillow)、用户头像、复杂的数据库关系、复杂的数据库查询、全文搜索(Flask-Whooshee)等内容。
  • 第10章:通过待办事项程序Todoism介绍单页应用、国际化与本地化(Flask-Babel)、Web API、OAuth服务器端实现等内容。
  • 第11章:通过聊天室程序CatChat介绍Websocket应用(实时双向通讯,通过Flask-SocketIO实现)、OAuth客户端实现(第三方登录,通过Flask-OAuthlib实现)、Markdown支持(markdown)、代码语法高亮(pygments)等内容。
第三部分:进阶篇 介绍Flask程序的部署流程:测试、性能优化、部署上线;介绍Flask开发的进阶话题:Flask扩展开发和Flask源码与机制分析。
 
  • 第12章:介绍Flask程序的自动化测试,包括单元测试和UI测试的编写、计算测试覆盖率和代码质量检查。
  • 第13章:对Flask程序进行性能优化的主要措施,包括函数与数据库查询的性能分析、缓存的使用(Flask-Caching)、静态文件优化(Flask-Assets)。
  • 第14章:介绍部署Flask程序前的准备,以及部署到Linux服务器和云平台Heroku、PythonAnywhere的完整流程。
  • 第15章:通过扩展Flask-Share来介绍编写Flask扩展的完整流程,从创建项目到上传到PyPI。
  • 第16章:介绍了Flask的一些设计理念,包括底层WSGI的相关实现,并对各个主要功能点进行源码分析。

新发布的Flask1.0带来了哪些新变化?

就在五个小时前,Flask终于发布了8年来的第一个主版本——1.0,这个版本带来了很多新的变化,让我们拥抱变化吧,请使用下面的命令来更新:

$ pip install -U flask

主要的变化

  • 从0.11开始,Flask引入了命令行支持,建议使用flask run命令来取代app.run()方法。1.0版本支持将Flask_APP环境变量设为包名称。Flask会自动在app.pywsgi.py寻找名称为appapplication的程序实例,同时会在传入的模块或包中寻找名称为create_app()make_app()的0参数的工厂函数。
  • 新添加了一个FLASK_ENV环境变量来设置Flask运行的环境,默认为production。在开发时需要设为development,这会自动开启调试器和重载器(即调试模式),避免直接使用FLASK_DEBUG
  • 当安装了python-dotenv时,flask命令(比如flask runflask shell等)会自动从项目根目录下的.flaskenv.env文件中导入环境变量,这样可以避免每次都手动设置环境变量。前者用来存储公开的Flask相关的环境变量,比如FLASK_APPFLASK_ENV等,后者用来存储包含敏感信息的环境变量,比如邮箱密码,API密钥等等,需要将文件名添加到.gitignore中。
  • 开发服务器默认开启多线程支持。
  • 日志系统被极大的简化,日志器总是命名为flask.app,它只会在没有日志处理器注册的情况下才添加处理器,而且不会移除已经存在的处理器。
  • 测试客户端(test_client)支持使用json参数来传入JSON数据,你可以使用这个特性来测试Web API。返回的响应对象添加了get_json方法来获取JSON数据。
  • 添加了一个 test_cli_runner() 方法,它可以用来触发使用Click注册的flask命令,我们可以使用它来测试自定义的flask命令。
  • 添加了一个flask routes命令,用来输出程序所有注册的路由。
  • 移除了旧的扩展导入代码flask.ext,还在使用旧的导入方式的扩展将无法使用。
  • 带来了一个重写后的Flaskr教程,包含了大量重构和改进,其他部分的文档也包含大量更新。
  • 和大多数项目一样,1.0版本不再支持Python2.6和3.3。

你可以访问Flask Changelog – Flask 1.0 documentation查看完整的Changelog,并了解每一个变化所对应的PR或Issue。

顺便说一句

正在写的Flask书将在五月初结束写作,不过距离上市还需要一小段时间(按照正常的出版流程,大概是40天~三个月区间内)。这本书的内容完全采用1.0版本的Flask,其他库也都使用最新版,包括Bootstrap等前端库。另外,专栏之前发布的文章相关的示例程序已经过时,请不要参考,可以阅读Flask文档中更新的Flaskr教程。如果不着急的话,可以等一等,新书会带来几个更完善的示例程序。

Flask-CKEditor:为Flask项目集成富文本编辑器

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

富文本编辑器即WYSIWYG(What You See Is What You Get)编辑器(所见即所得编辑器)。在Web程序中可用的开源富文本编辑器中,CKEditor是一个流行的选择。Flask-CKEditor简化了将CKEditor集成到Flask项目中的过程,可以让你方便的在Flask项目中添加富文本编辑器。它包含下面这些特性:

  • 提供WTForms/Flask-WTF集成支持
  • 支持图片上传与插入
  • 通过Flask配置来设置编辑器的语言、高度等参数
  • 支持代码块语法高亮

《Flask Web开发实战》中的第2个示例程序(博客程序Bluelog)使用了这个扩展。

基本用法

安装

首先使用pip或Pipenv等工具安装:

$ pip install flask-ckeditor

初始化扩展

一般情况下,你只需要导入并实例化CKEditor类,并传入程序实例即可:

from flask_ckeditor import CKEditor

app = Flask(__name__)
ckeditor = CKEditor(app)

如果你使用了工厂函数,那么也可以调用init_app()方法来进行初始化:

from flask_ckeditor import CKEditor

ckeditor = CKEditor()

def create_app():
    app = Flask(__name__)
    ckeditor.init_app(app)
    return app

引入CKEditor资源

为了使用CKEditor,我们首先要在模板中引入CKEditor的JavaScript等资源文件。推荐的做法是自己编写资源引用语句,你可以在CKEditor提供的Online Builder构建一个自定义的资源包,下载解压后放到项目的static目录下, 并引入资源包内的ckeditor.js文件,比如(实际路径按需调整):

<script src="{{ url_for('static', filename='ckeditor/ckeditor.js') }}"></script>

如果你不需要自定义,那么也可以从CDN加载:

<script src="//cdn.ckeditor.com/4.9.2/standard/ckeditor.js"></script>

最后,作为替代选项,你也可以使用Flask-CKEditor提供的ckeditor.load()方法来生成引用语句:

{{ ckeditor.load() }}

它默认从CDN加载资源,将配置变量CKEDITOR_SERVE_LOCAL设为True会使用扩展内置的本地资源。另外,你也可以使用custom_url参数来使用自定义资源包:

{{ ckeditor.load(custom_url=url_for('static', filename='ckeditor/ckeditor.js')) }}

创建CKEditor文本区域

Flask-CKEditor提供了两种方式来CKEditor文本区域:

1. 与WTForms/Flask-WTF集成

Flask-CKEditor提供了一个CKEditorField字段类,和你平时从WTForms导入的StringField、SubmitField用法相同。事实上,它就是对WTForms提供的TextAreaField进行了包装。

作为示例,我们可以创建一个写文章的表单类。这个表单类包含一个标题字段(StringField),一个正文字段(CKEditorField)和一个提交字段(SubmitField)。你会看到,其中的正文字段使用了CKEditorField。

from flask_wtf import FlaskForm
from flask_ckeditor import CKEditorField
from wtforms import StringField, SubmitField

class PostForm(FlaskForm):
    title = StringField('Title')
    body = CKEditorField('Body')
    submit = SubmitField('Submit')

 

在渲染文本编辑区域的模板中,我们可以像往常一样渲染表单:

<form method="post">
    {{ form.title.label }}{{ form.title() }}
    {{ form.body.label }}{{ form.body() }}
    {{ form.submit() }}
</form>

{{ ckeditor.load() }}
{{ ckeditor.config(name='body') }}

唯一需要注意的是,我们需要在资源引用语句后调用ckeditor.config()方法来让对CKEditor进行配置和初始化,并将name参数的值设为CKEditor字段的属性名,这里即body。

当表单提交后,你可以像其他字段一样通过form.attr.data属性来获取数据,这里的文本区域数据即form.body.data。

2. 手动创建

如果你不使用WTForms/Flask-WTF,那么可以直接使用Flask-CKEditor提供的ckeditor.create()方法在模板中创建文本编辑区域:

<form method="post">
    {{ ckeditor.create() }}
    <input type="submit">
</form>

{{ ckeditor.load() }}
{{ ckeditor.config() }}  <!-- 这时不用设置name参数 -->

在表单被提交后,你可以使用ckeditor作为键从表单数据中获取对应的值,即request.form.get('ckeditor')。

提示 完整的示例程序在examples/basic/examples/without-flask-wtf目录下。

配置变量

Flask-CKEditor提供了下面这些配置变量:

配置 默认值 说明
CKEDITOR_SERVE_LOCAL False 使用内置的ckeditor.load()方法时,设置是否使用本地资源,默认从CDN加载
CKEDITOR_PKG_TYPE 'standard' CKEditor资源包的类型,basicstandardfull中的一个
CKEDITOR_LANGUAGE None 设置CKEditor文本编辑器的语言,默认会自动探测用户浏览器语言,所以一般不需要设置。你也可以设置ISO 639格式的语言码,比如zhenjp等
CKEDITOR_HEIGHT CKEditor默认 编辑器高度,单位为px
CKEDITOR_WIDTH CKEditor默认 编辑器宽度,单位为px
CKEDITOR_FILE_UPLOADER None 处理上传文件的URL或端点
CKEDITOR_FILE_BROWSER None 处理文件浏览的URL或端点
CKEDITOR_ENABLE_MARKDOWN False 设置是否开启markdown插件,需要安装对应插件
CKEDITOR_ENABLE_CODESNIPPET False 设置是否开启codesnippet插件(插入代码块),需要安装对应插件
CKEDITOR_CODE_THEME 'monokai_sublime' 当使用codesnippet插件时,设置语法高亮的主题
CKEDITOR_EXTRA_PLUGINS [] 在CKEditor中开启的额外扩展列表,对应的扩展需要被安装

图片上传

在使用文本编辑器写文章时,上传图片是一个很常见的需求。在CKEditor中,图片上传可以通过File Browser插件实现。在服务器端的Flask程序中,你需要做三件事:

  1. 创建一个视图函数来处理并保存上传文件
  2. 创建一个视图函数来获取图片文件,类似Flask内置的static端点
  3. 将配置变量CKEDITOR_FILE_UPLOADER设为这个视图函数的URL或端点值

完整的代码示例如下所示:

from flask_ckeditor import upload_success, upload_fail

app.config['CKEDITOR_FILE_UPLOADER'] = 'upload'

@app.route('/files/<path:filename>')
def uploaded_files(filename):
    path = '/the/uploaded/directory'
    return send_from_directory(path, filename)

@app.route('/upload', methods=['POST'])
def upload():
    f = request.files.get('upload')  # 获取上传图片文件对象
    # Add more validations here
    extension = f.filename.split('.')[1].lower()
    if extension not in ['jpg', 'gif', 'png', 'jpeg']:  # 验证文件类型示例
        return upload_fail(message='Image only!')  # 返回upload_fail调用
    f.save(os.path.join('/the/uploaded/directory', f.filename))
    url = url_for('uploaded_files', filename=f.filename)
    return upload_success(url=url) # 返回upload_success调用

注意 传入request.files.get()的键必须为'upload', 这是CKEditor定义的上传字段name值。

在处理上传文件的视图函数中,你必须返回upload_success()调用,每将url参数设置为获取上传文件的URL。通常情况下,除了保存文件,你还需要对上传的图片进行验证和处理(大小、格式、文件名处理等等,具体可以访问这篇《Flask文件上传(一):原生实现》了解),在验证未通过时,你需要返回upload_fail()调用,并使用message参数传入错误消息。

当设置了CKEDITOR_FILE_UPLOADER配置变量后,你可以在编辑区域点开图片按钮打开的弹窗中看到一个新的上传标签。另外,你也可以直接将图片文件拖拽到编辑区域进行上传,或复制文件并粘贴到文本区域进行上传(CKEditor >= 4.5)。

提示 对应的示例程序在examples/image-upload/目录下。

如果你使用的 CKEditor 版本小于 4.5,则使用下面的方式实现:

from flask import send_from_directory

app.config['CKEDITOR_FILE_UPLOADER'] = 'upload'  # this value can be endpoint or url

@app.route('/files/<filename>')
def uploaded_files(filename):
    path = '/the/uploaded/directory'
    return send_from_directory(path, filename)

@app.route('/upload', methods=['POST'])
@ckeditor.uploader
def upload():
    f = request.files.get('upload')
    f.save(os.path.join('/the/uploaded/directory', f.filename))
    url = url_for('uploaded_files', filename=f.filename)
    return url

为图片上传请求添加 CSRF 保护

如果你想为图片上传的请求添加 CSRF 保护,可以通过 CSRFProtect 实现(Flask-WTF 内置),首先安装 Flask-WTF:

$ pip install flask-wtf

然后初始化扩展:

from flask_wtf import CSRFProtect

csrf = CSRFProtect(app) 

Flask-CKEditor 0.4.3 版本内置了对 CSRFProtect 的支持,当使用 CSRFProtect 时,只需要把配置变量 `CKEDITOR_ENABLE_CSRF` 设为 `True` 即可开启 CSRF 保护:

app.config['CKEDITOR_ENABLE_CSRF'] = True

顺便说一句,在 Flask-CKEditor 内部需要把 CSRF 令牌放到上传图片的 AJAX 请求首部,这通过 CKEditor 4.9.0 版本新添加的一个配置选项 fileTools_requestHeaders 实现,这个配置可以用来想文件上传请求插入自定义的首部字段 。所以,如果想要实现 CSRF 保护,CKEditor 的版本需要大于或等于 4.9.0。

代码语法高亮

代码语法高亮可以通过Code Snippet插件实现(基于hightlight.js),你可以将配置变量CKEDITOR_ENABLE_CODESNIPPET设为Ture来开启。在此之前,你需要确保安装了这个插件(内置的资源包包含了这个插件)。

为了正确渲染代码块,你还需要引入对应的资源文件,最简单的方式是使用Flask-CKEditor提供的ckeditor.load_code_theme()方法:

<head>
 ...
 {{ ckeditor.load_code_theme() }}
</head>

你可以通过配置变量CKEDITOR_CODE_THEME来设置语法高亮的主题,默认为monokai_sublime,你可以在这个页面看到所有可用的主题对应的字符串。

提示 对应的示例程序在examples/codesnippet/目录下。

使用示例程序

项目仓库中提供了5个示例程序,分别展示基本用法、图片上传插入、代码语法高亮、Markdown模式和不使用Flask-WTF/WTForms。以基本示例程序为例,你可以通过下面的命令来获取并运行它:

$ git clone https://github.com/greyli/flask-ckeditor
$ cd flask-ckeditor/examples
$ pip install -r requirements.txt
$ python basic/app.py

然后在浏览器访问http://127.0.0.1:5000。

另外,helloflask仓库里在demos/form目录下的示例程序也包含一个Flask-CKEditor使用示例。

相关链接

 

Flask-Dropzone:为你的Flask程序添加文件上传功能

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

某天在Stack Overflow上看到一个关于Dropzone.js的问题,就去研究了一下,写了一个回答,顺便写了一个小demo。我发现,如果有一个集成Dropzone.js到Flask,并且简化设置步骤的扩展,肯定要比其他上传方式简单的多——于是就有了Flask-Dropzone

Flask-Dropzone在模板中提供了一些方法来帮助你创建上传区域,引入相关资源。你只需要添加一些配置就可以实现上传类型的过滤,文件大小限制,上传后跳转等功能。当然,你还要自己编写视图函数来处理和保存文件,并进行服务器端的二次验证。

《Flask Web开发实战》中的第3个示例程序(图片社交程序Albumy)使用了这个扩展。

用法说明

安装

$ pip install flask-dropzone

初始化

和其他扩展类似,你可以通过实例化Dropzone类,并传入程序实例app进行初始化:

from flask_dropzone import Dropzone

app = Flask(__name__)
dropzone = Dropzone(app)

在使用工厂函数创建程序实例时,你也可以使用init_app()方法:

from flask_dropzone import Dropzone

dropzone = Dropzone()

def create_app():
    app = Flask(__name__)
    dropzone.init_app(app)
    return app

引入Dropzone.js资源

你需要自己手动编写引入Dropzone.js的CSS和JavaScript资源的语句。在开发时,或对于玩具项目,你可以可以使用Flask-Dropzone提供的两个快捷方法:

<head>
    ...
    {{ dropzone.load_css() }}
</head>
<body>
    ...
    {{ dropzone.load_js() }}
</body>

创建并美化上传区域

如果你不需要对上传区域的样式有太多控制,那么你只需要在想要渲染上传区域的地方使用dropzone.create()方法:

{{ dropzone.create(action='处理上传文件的路由URL') }}

记得把action的值更改成你要处理文件上传的的URL。你可以使用style()方法为上传区域添加简单的自定义样式:

<head>
...  <!-- 在引入Dropzone.js的CSS文件后调用style()方法 -->
{{ dropzone.style('border: 2px dashed #0087F7; margin: 10%') }}
</head>

上传区域的截图示例如下所示:

Flask-Dropzone上传截图

Flask-Dropzone上传截图

在服务器端处理并保存上传文件

当文件被拖拽到上传区域,或是点击上传区域选择上传文件后,这些文件会以AJAX请求的形式发送到你在dropzone.create()方法中使用action参数传入的URL。我们需要在服务器端创建对应的视图函数来处理这些请求,下面是一个最基本的示例:

import os

from flask import Flask, request
from flask_dropzone import Dropzone

app = Flask(__name__)

dropzone = Dropzone(app)

@app.route('/uploads', methods=['GET', 'POST'])
def upload():

    if request.method == 'POST':  # 如果请求类型为POST,说明是文件上传请求
        f = request.files.get('file')  # 获取文件对象
        f.save(os.path.join('the/path/to/save', f.filename))  # 保存文件

    return 'upload template'  # 渲染上传页面

 

上传完成后重定向

这里需要注意的是,因为Dropzone.js通过AJAX请求提交文件,所以你没法在保存文件后将页面重定向。对于这个问题,你可以使用配置变量DROPZONE_REDIRECT_VIEW设置上传完成后跳转到的目标端点,或是添加一个按钮让用户自己点击进行跳转。

服务器端验证

尽管Dropzone.js可以在前端对用户提交的文件进行验证,但为了安全考虑,我们仍然需要在服务器端进行二次验证。在服务器端验证时,如果验证出错,我们不能像往常那样使用flash()函数“闪现”错误消息,因为AJAX请求接受到响应后并不会重载页面,所以不会显示通过flash()函数发送的消息。正确的做法是返回400错误响应,使用错误消息作为响应的主体。下面是一个简单的进行服务器端验证并返回错误消息得示例:

@app.route('/', methods=['POST', 'GET'])
def upload():
    if request.method == 'POST':
        f = request.files.get('file')
        if f.filename.split('.')[1] != 'png':
            return 'PNG only!', 400  # return the error message, with a proper 4XX code
        f.save(os.path.join('the/path/to/save', f.filename))
    return render_template('index.html')

在上面的代码中,我们验证图片是不是png格式,如果不是就返回一个错误提示,在服务器端会在图片下面看到我们返回的错误消息:

blank

 

 

完整的配置列表

Flask-Dropzone提供了丰富的配置变量,你可以使用它们对Dropzone.js进行各类配置。

Name Default Value Info
DROPZONE_SERVE_LOCAL   False       使用Flask-Dropzone提供的load_css()和load_js()方法时,这个变量设置是否使用内置的本地资源,默认从CND加载
DROPZONE_MAX_FILE_SIZE 3 允许的文件最大值,单位为MB
DROPZONE_INPUT_NAME file 上传字段的name值
DROPZONE_ALLOWED_FILE_CUSTOM False 是否使用自定义文件类型允许规则,具体见后面
DROPZONE_ALLOWED_FILE_TYPE 'default' 允许的文件类型,具体见后面
DROPZONE_MAX_FILES ‘null’ 一次可以上传的文件数量最大值
DROPZONE_DEFAULT_MESSAGE “Drop files here to upload” 上传区域显示的提示文字
DROPZONE_INVALID_FILE_TYPE “You can’t upload files of this type.” 文件类型错误的错误消息
DROPZONE_FILE_TOO_BIG “File is too big {{filesize}}. Max filesize: {{maxFilesize}}MiB.” 文件太大时显示的错误消息
DROPZONE_SERVER_ERROR “Server error: {{statusCode}}” 服务器错误的错误消息
DROPZONE_BROWSER_UNSUPPORTED “Your browser does not support drag’n’drop file uploads.” 浏览器不支持的错误消息
DROPZONE_MAX_FILE_EXCEED “Your can’t upload any more files.” 超过最大文件数量限制的错误消息
DROPZONE_UPLOAD_MULTIPLE False 是否在单个请求中发送多个文件,默认一个请求发送一个文件
DROPZONE_PARALLEL_UPLOADS 2 当DROPZONE_UPLOAD_MULTIPLE设为True时,设置单个请求包含的文件数量
DROPZONE_REDIRECT_VIEW None 上传完成后重定向的模板端点
DROPZONE_ENABLE_CSRF False 是否开启CSRF保护

这些配置的用法你可以参考Flask-Drozone的文档或是示例程序了解,这里我们仅简单介绍一下对文件类型进行过滤的设置方法。

设置文件类型过滤

Flask-Dropzone内置了一些文件类型(通过MIME定义),可选的值和对应的文件类型如下所示:

  • default:默认值,运行所有类型
  • image:图片
  • audio:音频
  • video:视频
  • text:文本
  • app:程序

你需要为DROPZONE_ALLOWED_FILE_TYPE设置对应的值,比如下面设置仅允许上传图片:

app.config['DROPZONE_ALLOWED_FILE_TYPE'] = 'image'

如果你想要自己定义允许的文件类型列表,那么你需要将DROPZONE_ALLOWED_FILE_CUSTOM设置True,然后传入一个包含允许的文件后缀名列表组成的字符串给DROPZONE_ALLOWED_FILE_TYPE变量,使用逗号分隔多个后缀名,比如:

app.config['DROPZONE_ALLOWED_FILE_CUSTOM'] = True
app.config['DROPZONE_ALLOWED_FILE_TYPE'] = 'image/*, .pdf, .txt'

对于平行上传、CSRF保护等内容的具体实现方法你可以参考文档了解。不过,这个项目目前还没有创建完善的文档,暂时只是写到README里,如果你发现了英文语法或拼写错误,欢迎指正,同时也欢迎为项目贡献代码。

示例程序

Flask-Dropzone的Git仓库中的examples目录下包含4个示例程序,分别演示了基本用法、CSRF保护、平行上传和上传完成后跳转四个功能。

源码可以在这里找到:https://github.com/greyli/flask-dropzone/tree/master/examples

另外,helloflask仓库里在demos/form目录下的示例程序也包含一个Flask-Dropzone使用示例。

相关链接

 

用Flask从零实现豆瓣相册

这是我在知乎专栏 – Hello, Flask!上连载的一个教程,这篇作为目录会持续更新。

被新年绑架,一个月忙忙碌碌,现在终于有时间继续写专栏。本来想先写其他的实践,比如便签本、个人博客,但这些都和《Flask Web开发》的Flasky差不多,没什么好写的。想着干脆先把这个相册实现了。

为什么是豆瓣相册

当然,最主要的原因是豆瓣相册比较简单,容易实现。而且用一个东西用久了,总想改造一下。

页面逻辑和豆瓣相册相同:用户相册主页——相册页——图片页——大图

主要的功能点:

  1. 相册与图片
  2. 添加喜欢
  3. 图片上传
  4. 批量编辑
  5. 拖拽排序
  6. 图片浏览
  7. 图片处理
  8. 隐私设置
  9. 自定义头像
  10. 相册增强插件

 

系列目录

  1. 相册与图片

 

相关项目

上面的功能实现在这个项目里都可以看到,后面的文章也会基于这个项目。因为这也是个实验场,有很多代码和实现方法需要重新考量。如果发现问题,欢迎提issue和贡献代码~

github.com/greyli/fanxiangce

部分截图

user page

用户主页

相册页面

相册页面

批量编辑页面

批量编辑页面

photo page

图片浏览页

做个新的相册网站

等这个系列结束,你就可以自己做个相册网站,找一些厉害的插件改造它,再起个好名字。然后到豆瓣里发篇日记,就叫《我做了个更好的豆瓣相册》。当然,那时它可能叫西红柿相册,或是袋鼠相册……

 

图片墙生成器

用Flask重写了图片墙生成器。

Github项目:https://github.com/greyli/image-wall
图片墙Demo:http://fanxiangce.com/demo1(旧Demo)

 

主要变化

和之前的Python版本相比的变动:

  • 实现了上传功能
  • 优化了CSS和JS代码
  • 简化了页面元素,去掉了没用的赞助页面
  • 把HTML分离出Python,代码结构更清晰

 

实现步骤

1、用户上传图片;

2、生成用户文件夹,重命名图片;

@app.route('/', methods=['GET', 'POST'])
def index():
    # 为每一个用户创建文件夹
    username = hashlib.md5('demo' + str(time.time())).hexdigest()[:7]
    if request.method == 'POST' and 'photo' in request.files:
        amount = len(request.files.getlist('photo'))
    if amount in range(10, 101):  # 控制图片数量在10~100之间
        for num, img in enumerate(request.files.getlist('photo')):
            filename = username + str(num)  # 使用用户名加序号命名图片
            photos.save(img, name=username + '/' + filename + '.')
        return redirect(url_for('image_wall', username=username))
    return render_template('index.html')

3、根据图片数量分配相应的行列图片数量,并为每一张图片生成三维坐标;

4、渲染模板,传入这些坐标;

{% for image in images %}
<div class="step center-text" data-x="{{ image[1] }}" data-y="{{ image[2] }}" data-z="{{ image[3] }}">
    <img class="image" src="{{ url_for('static', filename='photos/') }}{{ image[0] }}">
</div>
{% endfor %}

 

 

Google+社群——Hello, Flask!

为了方便讨论和交流,创建了一个Google+社群。现在可以在社群里分享信息,创建问题和讨论。欢迎加入!

关于提问

专栏关注人数增多以后,提问也越来越多。但是有些问题我完全不知道问的是什么……学会提问很重要!

遇到问题后应该有这么一个解决流程:

检查代码是否有语法错误——查看相应的源码和文档——Google搜索——如果到了这一步还没法解决,再到论坛上发帖(建议到StackOverflow上提问)。

问题应该尽量包括下面的内容:

  1. 期望效果
  2. 实际效果
  3. 你的操作步骤和尝试过的解决办法
  4. 相关的代码和错误输出
  5. 操作系统和语言、库等的版本

最后还要注意排版,内容尽量简洁,措辞礼貌一些。

因为Google+社群里不好放代码,可以在StackOverflow或知乎上提问,粘贴链接过来,或是在Github上创建Gist

 

Google+社群

你可以在这里分享关于Flask、Python以及Web开发的一切信息,说点儿想说的,不用拘束。

plus.google.com/u/0/com

Flask文件上传系列教程

文章目录

1、Flask文件上传(一):原生实现

    • 上传配置
    • 安全问题

2、Flask文件上传(二):使用扩展实现

    • 使用Flask-Uploads简化上传过程
    • 大型项目里Flask-Uploads的配置

3、Flask文件上传(三):完整实现

    • 使用Flask-WTF创建上传表单
    • 分离模板文件

4、Flask文件上传(四):文件管理与多文件上传

  • 文件管理
  • 文件名处理
  • 中文文件名问题
  • 多文件上传

5、Flask文件上传(五):拖拽上传和进度条

    • 使用插件集成进度条等功能
    • 使用Pillow生成图像缩略图

 

项目Demo

1、简单的文件管理系统:helloflask/cloud-drive

    • 文件上传
    • 文件删除
    • 图片预览

2、完善的文件管理系统:greyli/flask-file-uploader

    • 拖拽上传
    • 进度条
    • 文件管理
    • Bootstrap样式
    • 图片预览
    • 文件信息