Flask CLI

一、说明

Flask-CLI (flask.cli)是 Flask 内置的脚本命令接口，基于 Click 实现的，深入了解请参考 Click 文档 。可以替代 Flask-Script 实现的功能。

二、安装

pip install Flask

三、终端环境变量声明

• Unix Bash （ Linux 、Mac 及其他）:

$ export FLASK_APP=hello 
$ flask run

• Windows CMD:

> set FLASK_APP=hello > flask run

• Windows PowerShell:

> $env:FLASK_APP = "hello" > flask run

四、Flask项目运行

• 可以通过在一个空的文件目录下执行 flask 命令得知，项目中有三种方式使用 flask 脚本。

> flask shell

flask 会通过自动检测项目中命名为 wsgi.py 或 app.py 的文件，另一种方式是使用环境变量管理 python-dotenv 或 environs ，通过编辑配置文件 .env 或 .flaskenv 中的 FLASK_APP，运行flask 命令 。

Usage: flask shell [OPTIONS]

Error: Could not locate a Flask application. You did not provide the "FLASK_APP" environment variable, and a "wsgi.py" or "app.py" module was not found in the current directory.

• flask 帮助说明

Usage: flask [OPTIONS] COMMAND [ARGS]...

  A general utility script for Flask applications.

  Provides commands from Flask, extensions, and the application. Loads the
  application defined in the FLASK_APP environment variable, or from a
  wsgi.py file. Setting the FLASK_ENV environment variable to 'development'
  will enable debug mode.

    > set FLASK_APP=hello.py
    > set FLASK_ENV=development
    > flask run

Options:
  --version  Show the flask version
  --help     Show this message and exit.

Commands:
  db      Perform database migrations.
  digest  md5 tag and gzip static files.
  routes  Show the routes for the app.
  run     Run a development server.
  shell   Run a shell in the app context.

创建 .env 环境变量文件，flask 项目优先获取 .env 环境变量文件里的配置信息，如果没有再检索 wsgi.py 或 app.py 文件。

# Environment variable overrides for local development 
FLASK_APP=manage.py

• 创建 extensions.py 文件

from flask import Flask


def create_app():
    app = Flask(__name__.split(".")[0])
    return app

• 创建 manage.py 文件

from flask_app.extensions import create_app
app = create_app()

通过 FLASK_APP 可以指定到项目的应用入口。以下有三种方式定义：
1.可选路径，用于设置当前工作文件夹
2.Python 文件或者带点的导入路径
3.可选的实例或工厂的变量名称

• 1. 可选路径 src：配置路径读取为当前工作文件夹的绝对路径

# Environment variable overrides for local development 
FLASK_APP=src\manage.py

• 2. Python 文件或者带点的导入路径

# Environment variable overrides for local development 
FLASK_APP=hello.web

• 3. 声明 create_app 实例，或其它命名的实例。

# Environment variable overrides for local development 
FLASK_APP=manage.py:create_app

• 若实例名为 create_app 则可以免去声明

# Environment variable overrides for local development 
FLASK_APP=manage.py

如果没有设置 FLASK_APP ，命令会查找 wsgi.py 文件或者 app.py 文件并尝试探测一个应用实例或者工厂。

• 创建 wsgi.py 或 app.py 文件

from flask import Flask

app = Flask(__name__)

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

执行 flask run 默认IP地址127.0.0.1，端口号5000，
官方不推荐使用-h：IP地址；-p：端口号，这种命令行方式启动服务。而是使用 FLASK_RUN_PORT 定义。

> flask run -h 0.0.0.0 -p 8888
 
 * Serving Flask app "app.py"
 * Environment: production
   WARNING: This is a development server. Do not use it in a production deployment.
   Use a production WSGI server instead.
 * Debug mode: off
 * Running on http://0.0.0.0:8888/ (Press CTRL+C to quit)

官方警告：不要在生产中使用此命令运行应用，只能在开发过程中使用开发服务 器。开发服务器只是为了提供方便，但是不够安全、稳定和高效。有关如何在生 产中运行服务器，请参阅 部署方式 。

WARNING: This is a development server. Do not use it in a production deployment.

五、Flask Shell

• 可以使用 flask shell 命令开启一个 Python shell 交互终端

$ flask shell
Python 3.6.2 (default, Jul 20 2017, 03:52:27)
[GCC 7.1.1 20170630] on linux
App: example
Instance: /home/user/Projects/hello/instance
>>>

六、通过 dotenv 设置环境变量

在实际的项目部署和使用中，不会每次打开新的终端都要设置 FLASK_APP，需要使用 Flask 的 dotenv 功能自动设置环境变量。官方给出的工具是 python-dotenv，另外一个工具 evirons 也是依赖于 python-dotenv ，同样可以作为环境管理工具使用。

• 安装 python-dotenv 或 environs ，运行 flask 时，会根据 .env 和 .flaskenv 中配置来设置环境变量。

pip install python-dotenv 
pip install environs

• 命令行设置的变量会重载 .env 中的变量， .env 中的变量会重载 .flaskenv 中的变量。

Flask在加载环境变量的优先级 手动设置的环境变量 > .env中设置的环境变量 > .flaskenv设置的环境变量

• .env 则应用用于私有变量，并且不提交到储存库，用来存储包含敏感信息的环境变量，比如用来配置Email服务器的账户名与密码。

# 文档注释
[email protected]
ACCOUNT=flask_user
REDIS_ADDRESS=localhost:6379
MEANING_OF_LIFE=42
MULTILINE_VAR="hello\nworld"

• .flaskenv 应当用于公共变量，用来存储和Flask相关的公开环境变量，比如FLASK_APP。

# 文档注释 
FLASK_APP=manage

Flask 应用所运行的环境由参数 FLASK_ENV 指定。默认值是 production，开发环境可以改为 development 。调试参数 FLASK_DEBUG 默认值是 0。

# Environment variable overrides for local development
FLASK_APP=manage
FLASK_ENV=development # 默认值是 production
FLASK_DEBUG=1 # 值为 1 表示开启， 0 表示关闭。
FLASK_RUN_PORT=8888

执行 flask run

> flask run
 
 * Serving Flask app "manage" (lazy loading)
 * Environment: development
 * Debug mode: on
 * Restarting with stat
 * Debugger is active!
 * Debugger PIN: 857-867-806
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

通过 load_dotenv 方法改变 .env 或 .flaskenv 文件设置环境变量的读取。
优先加载顺序 flask.cl -> python-dotenv

import os
from flask.cli import load_dotenv
load_dotenv(path='.env')
env = os.getenv("FLASK_ENV")
print(env)

• dotenv_path默认值为.env,override是表示是否可以重载，默认值为False

import os
from dotenv import load_dotenv
load_dotenv(dotenv_path='.flaskenv', override=False)
env = os.getenv("FLASK_ENV")
print(env)

• 尝试使用 load_dotenv 管理环境变量配置，创建 app.py

import click
import os
from dotenv import load_dotenv


@click.command()
@click.option('--dev', default=None, help='environment variable')
def runserver(dev):
    load_dotenv(dotenv_path='.flaskenv', override=True)  # 加载变量文件
    if dev == os.getenv("FLASK_ENV"):
        os.system(f"flask run")


if __name__ == '__main__':
    runserver()

执行 Click 命令

python app.py --dev development

禁用 环境变量配置，通过设置 FLASK_SKIP_DOTENV 可以使 Flask 不载入 dotenv 文件。

• Unix Bash （ Linux 、Mac 及其他）

$ export FLASK_SKIP_DOTENV=1 $ flask run

• Windows CMD:

> set FLASK_SKIP_DOTENV=1 > flask run

• Windows PowerShell:

> $env:FLASK_SKIP_DOTENV=1 > flask run

七、自定义命令

通过 Click 来自定义命令，以下是简单的例子

• 创建 app.y 文件

import click
from flask import Flask

app = Flask(__name__)

@app.cli.command("create-user")
@click.argument("name")
def create_user(name):
    """ 帮助注释 """
    click.echo(f'Hello, {name}!').

• 创建 .flaskenv 或 .env 文件

# Environment variable overrides for local development
FLASK_APP=app
FLASK_ENV=development
FLASK_DEBUG=1
FLASK_RUN_PORT=5000

执行 flask 命令

> flask create-user admin
Hello, admin!

• 以 AppGroup 命令组的方式添加，FlaskGroup 继承 AppGroup，AppGroup 继承 click.Group。

import click
from flask import Flask
from flask.cli import AppGroup

app = Flask(__name__)


user_cli = AppGroup('user')


@user_cli.command('create')
@click.argument('name')
def create_user(name):
    click.echo(f'Hello, {name}!')


@user_cli.command('edit')
@click.argument('name')
def create_user(name):
    click.echo(f'{name} Edit!')

• 测试 CLI 命令，flask 会通过 test_cli_runner 创建一个 FlaskCliRunner ，把 Flask 应用自动传递给 CLI，使用 invoke 调用命令。

import click

@app.cli.command('hello')
@click.option('--name', default='World')
def hello_command(name)
    click.echo(f'Hello, {name}!')

def test_hello():
    runner = app.test_cli_runner()

    # invoke the command directly
    result = runner.invoke(hello_command, ['--name', 'Flask'])
    assert 'Hello, Flask' in result.output

    # or by name
    result = runner.invoke(args=['hello'])
    assert 'World' in result.output

• 提供了以蓝图注册命令的方法，可以把 CLI 命令 直接注册到蓝图上。更多方法请参考 以蓝图注册命令

from flask import Blueprint

bp = Blueprint('students', __name__)

@bp.cli.command('create')
@click.argument('name')
def create(name):
    ...

app.register_blueprint(bp)

• 执行 蓝图命令

> flask students create alice

• 使用 setuptools 打包工具 setup.py

1.自定义脚本错误
2.当使用自定义脚本时，如果模块级别代码出错，重载器会失效，因为它无法 再载入入口点。
3.一般建议使用 flask 命令，因为该命令与你的代码是分离的，不会出现 这种问题。

• 创建一个 FlaskGroup 的实例并传递给工厂

from flask import Flask
from flask.cli import FlaskGroup

def create_app():
    app = Flask('wiki')
    # other setup
    return app

@click.group(cls=FlaskGroup, create_app=create_app)
def cli():
    """Management script for the Wiki application."""

• 在 setup.py 中定义入口点:

from setuptools import setup

setup(
    name='flask-my-extension',
    ...,
    entry_points={
        'console_scripts': [
            'wiki=wiki:cli'
        ],
    },
)

• 编辑模式安装应用，自定义脚本可用。不需要设置 FLASK_APP。

> pip install -e .
> wiki run

八、工厂函数管理命令

通过工厂函数的方式注册到flask应用，方便项目命令调用，以下是例子：创建 flask_app 目录

• 创建 .flaskenv 或 .env 文件

# Environment variable overrides for local development
FLASK_APP=manage
FLASK_ENV=development
FLASK_DEBUG=1
FLASK_RUN_PORT=5000

• 创建 commands.py 文件

# -*- coding: utf-8 -*-
import click


@click.command()
@click.option('-n', '--name', default='World')
def hello(name):
    """ 帮助注释 """
    click.echo('Hello %s!' % name)

• 创建 extensions.py 文件

# -*- coding: utf-8 -*-
from flask import Flask

from flask_app import commands


def create_app():
    app = Flask(__name__.split(".")[0])
    register_commands(app)
    return app


def register_commands(app):
    app.cli.add_command(commands.hello)

• 创建 manage.py 文件

from flask_app.extensions import create_app

app = create_app()

执行 flask --help 查看命令是否加载成功

Usage: flask [OPTIONS] COMMAND [ARGS]...

  A general utility script for Flask applications.

  Provides commands from Flask, extensions, and the application. Loads the
  application defined in the FLASK_APP environment variable, or from a
  wsgi.py file. Setting the FLASK_ENV environment variable to 'development'
  will enable debug mode.

    > set FLASK_APP=hello.py
    > set FLASK_ENV=development
    > flask run

Options:
  --version  Show the flask version
  --help     Show this message and exit.

Commands:
  db      Perform database migrations.
  digest  md5 tag and gzip static files.
  hello   帮助注释
  routes  Show the routes for the app.
  run     Run a development server.
  shell   Run a shell in the app context.

执行 flask hello

> flask hello Hello World! > flask hello -n test Hello test!

九、参考文档

https://dormousehole.readthedocs.io/en/latest/cli.html

http://www.cppcns.com/jiaoben/python/297201.html

https://www.jianshu.com/p/9506206de55b

https://dormousehole.readthedocs.io/en/latest/testing.html#testing-cli

https://click.palletsprojects.com/en/7.x/testing/#id2

https://juejin.im/post/5ddbe004f265da7e040c9828#heading-5