英文原文地址:http://flask.pocoo.org/docs/1.0/cli/
若有翻译错误或者不尽人意之处,请指出,谢谢~
在你的虚拟环境中安装Flask的时候会安装flask脚本——一个Click命令行接口。从终端执行,这个脚本能够访问内置的、扩展的、以及应用程序定义的命令。--help选项能够获取更多关于任何命令和选项的信息。
1. 检测应用程序
flask命令是由Flask安装的,而不是由你的应用程序安装的;为了使用flask命名,你必须告诉它,哪里能找到你的应用程序。FLASK_APP环境变量被用来指定如何加载应用程序。
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_APP支持多种选项来指定你的应用程序,但是大多数情况都是很简单的。这里列出典型的值:
(nothing)
wsgi.py文件被导入,将自动探测一个应用(app对象)。这提供了一种简单的方法,可以从带有额外参数的工厂创建一个应用(app)。
FLASK_APP=hello
名字被导入,自动探测一个应用(app对象)或者工厂(create_app)。
——————————————————————————————————————
FLASK_APP有三个部分:一个可选路径用于设置当前工作目录,一个Python文件或者点(.)导入路径,以及一个可选的实例或者工厂的变量名称。如果名称是一个工厂,它可以选择性地在括号中跟上参数。下面的值演示了上述内容:
FLASK_APP=src/hello
设置当前工作目录到src,然后导入hello。
FLASK_APP=hello.web
导入路径hello.web。
FLASK_APP="hello:create_app('dev')"
在hello中的create_app工厂被调用,并且有一个字符串类型的参数‘dev’。
如果FLASK_APP没有被设置,命令会寻找一个叫做wsgi.py或者app.py的文件,并且尝试检测一个应用程序实例或者工厂。
在给定的导入中,命令会寻找一个叫做app或者application的应用程序实例,然后再寻找任何应用程序实例。如果没有找到实例,命令会查找一个叫做create_app或者make_app的工厂方法来返回一个实例。
当调用一个应用程序工厂,如果工厂携带一个叫做info的参数,然后ScriptInfo实例会作为一个关键字参数传递进来。如果括号跟随工厂名称,它们的内容将被解析为Python常量,并且作为参数传递给这个方法。这意味着,字符串必须在引号内。
2. 运行开发服务器
run命令会运行开发服务器。大多数情况下,它代替了Flask.run()函数。
$ flask run
* Serving Flask app "hello"
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
警告:
在生产中不要使用这个命令来运行你的应用程序。仅在开发期间才会使用开发服务器。开发服务器是为了方便才提供的,因此它没有被设计的安全、稳定以及有效率。
3. 打开一个Shell
为了在你的应用程序中探测数据,你可以使用shell命令来开始一个交互式Python shell。一个应用程序上下文会被激活,并且app实例也会被导入。
$ 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
>>>
使用shell_context_processor()来添加其他自动导入。
4. 环境
(新增于版本1.0。)
Flask应用运行的环境是由FLASK_ENV环境变量设置的。如果没有设置它,默认为production。其他认可的环境是development。Flask和扩展会根据环境来决定开启某些行为。
如果env被设置为development,flask命令会开启调试模式,并且flask run会开启交互式调试器和重载器。
$ FLASK_ENV=development flask run
* Serving Flask app "hello"
* Environment: development
* Debug mode: on
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
* Restarting with inotify reloader
* Debugger is active!
* Debugger PIN: 223-456-919
5. 调试模式
当FLASK_ENV为development时,调试模式被开启。如果你希望单独地控制调试模式,使用FLASK_DEBUG可以办到:设为1表示开启调试模式,0标识禁用它。
6. 从点环境(dotenv)加载环境变量
相比于在每次开启一个新的终端时设置FLASK_APP,你可以使用Flask支持的点环境(dotenv)来自动设置环境变量。
如果python-dotenv已经安装,运行flask命令会从文件.env和.flaskenv中读取定义好的值,并设置到环境变量。这可以避免当开启新终端时不得不手动设置FLASK_APP的操作,并且使用环境变量来设置配置,类似于一些开发服务的工作方式。
在命令行设置的变量用于那些在.env中设置的变量,这些变量用于.flaskenv中设置的变量。.flaskenv应用于公共变量,如FLASK_APP,而.env不应提交到存储库,以便它可以设置私有变量。
从被你成为flask的目录开始,向上扫描以定位文件。假定在项目的最顶层目录,当前工作目录将被设置为文件的位置。
文件仅在flask命令或者调用run()时才会被加载。当在生产模式下运行时,如果你想要加载这些文件,你应该手动调用load_dotenv()。
6.1 设置命令选项
Click被配置为从环境变量中加载命令选项的默认值。这个变量使用模式FLASK_COMMAND_OPTION。举个栗子,为了设置运行命令的端口,替换flask run --port 8000的方式是:
export FLASK_RUN_PORT=8000
flask run
* Running on http://127.0.0.1:8000/
这些都能被添加到.flaskenv文件中,以便控制默认命令选项,就像是FLASK_APP的使用一样。
6.2 禁用点环境(dotenv)
如果flask探测到了点环境(dotenv)文件,但是python-dotenv并没有被安装,flask命令将显示一条信息。
flask run
* Tip: There are .env files present. Do "pip install python-dotenv" to use them.
你可以设置环境变量FLASK_SKIP_DOTENV来告诉Flask不要加载点环境文件,即使python-dotenv已经安装了。如果你想要手动加载它们,或者你使用了其他方法已经加载了它们,这个选项就很有帮助了。请记住,环境变量必须在app加载前设置,或者它的配置值没有达到预期时才设置。
export FLASK_SKIP_DOTENV=1
flask run
7. 从虚拟环境加载环境变量
如果你不想安装dotenv,你依然可以设置环境变量:将它们设置到虚拟环境的activate脚本的末尾。激活虚拟环境,这些变量就会被设置。
Unix Bash,venv/bin/activate:
export FLASK_APP=hello
Windows CMD,venv/Scripts/activate.bat:
set FLASK_APP=hello
使用dotenv的好处在于,.flaskenv能被提交到版本库中,因此当项目被签出时,项目也能自动地加载这些环境变量。
8. 自定义命令
使用Click可以实现flask命令。查看这个项目的文档来获取关于编写命令的所有知识。
这个例子添加了带有参数name的命令create_user:
import click
from flask import Flask
app = Flask(__name__)
@app.cli.command()
@click.argument('name')
def create_user(name):
...
flask create_user admin
这个示例添加了同样的命令,但是命令为user create,表示一个命令在一个命令组内。如果你想组织多种相关的命令,这是很有用的:
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):
...
app.cli.add_command(user_cli)
flask user create demo
查看Testing CLI Commands来复习一下如何测试你自定义的命名。
9. 应用程序上下文
通过Flask app的cli.command()装饰器来添加命令,这个装饰器在执行的时候会得到一个应用程序上下文,因此你的命令和扩展有权访问app和它的配置。如果你通过Click的command()装饰器创建一个命令,你可以使用with_appcontext()来获取与Flask装饰器相同的行为。
import click
from flask.cli import with_appcontext
@click.command
@with_appcontext
def do_work():
...
app.cli.add_command(do_work)
如果你确定一个命令不需要上下文,你可以禁用它:
@app.cli.command(with_appcontext=False)
def do_work():
...
10. 插件
Flask会自动地加载flask.commands入口点(entry point)指定的命令。对于想要在安装时添加命令的扩展来说,这是很有用的。入口点被指定在setup.py文件中:
from setuptools import setup
setup(
name='flask-my-extension',
...,
entry_points={
'flask.commands': [
'my-command=flask_my_extension.commands:cli'
],
},
)
在flask_my_extension/commands.py内部,你可以导出一个Click对象:
import click
@click.command()
def cli():
...
一旦在你的Flask项目所在的相同的虚拟环境下安装了这个包,你可以运行flask my-command来调用这个命令。
11. 自定义脚本
当你使用应用程序工厂模式时,它能更加方便地定义你自己的Click脚本。相较于使用FLASK_APP并且让Flask加载你的应用程序,你可以创建你自己的Click对象,并且导出它就像一个console script入口点(entry point)。
创建一个FlaskGroup实例,并且将其传给工厂:
import click
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'
],
},
)
在虚拟环境下,使用可编辑模式(editable mode)来安装应用程序,然后这个自定义脚本就是可用状态的。
注意,你不需要设置FLASK_APP。
$ pip install -e .
$ wiki run
自定义脚本中的错误:
当使用自定义脚本时,如果你在你的模块级别代码引入一个错误,重新加载器将会失败,因为它无法加载到进入点(entry point)。
flask命令,独立于你的代码,不会有这些问题,因此大多数情况下这是推荐的方式。
12. PyCharm
在PyCharm2018.1版本中,Flask CLI特定并没有完全整合到PyCharm中。我们不得不做一些微调以便它们能顺利工作。这里介绍的内容与其他IDE类似。
在PyCharm中,打开你的项目,点击菜单栏的Run,并且跳转到Edit Configurations。你会看到类似于下图的界面:
这里有些选项需要修改。
点击+(Add New Configuration)按钮,然后选择Python。给这个配置一个漂亮的带有描述性的名字,比如“Run Flask Server”。因为flask run命令的缘故,因此勾选上“Single instance only”,以便你在同一时间只能运行一次这个服务。
选择在图片标记A的下拉菜单选择Module name,并且输入flask。
在图片标记B的地方,Parameters字段用来设置CLI命令的执行参数。在这里我们使用run,用来运行开发服务器。
你可以跳过下一步,如果你使用从dotenv加载环境变量的话。在图片标记C的地方我们需要添加一个环境变量来确定我们的应用程序。点击浏览按钮,添加一个条目,左边输入FLASK_APP,右边输入Python导入或者文件(这里输入hello)。
接下来我们需要在图片标记D的地方设置工作目录,这个工作目录就是我们应用程序所在的文件夹。
如果你已经将你的项目作为包安装在了虚拟环境中,你需要在图片标记E的地方勾选上PYTHONPATH选项。这可以更精确地匹配到你在稍后会如何部署你的app。
点击Apply按钮来保存这个配置,或者OK来保存并关闭这个窗体。在PyCharm主窗体选择这个配置,并且点击play按钮来运行这个服务。
现在,我们在PyCharm中已经有一个运行flask run命令的配置。我们可以复制这个配置,并且修改脚本参数来运行不同的CLI命令,比如flask shell。