命令行界面

安装 Flask 会在你的虚拟环境中安装 flask 脚本,这是一个 Click 命令行界面。从终端执行此脚本可以访问内置、扩展和应用程序定义的命令。--help 选项将提供有关任何命令和选项的更多信息。

应用程序发现

flask 命令由 Flask 安装,而不是你的应用程序;它必须知道在哪里找到你的应用程序才能使用它。--app 选项用于指定如何加载应用程序。

虽然 --app 支持多种用于指定应用程序的选项,但大多数用例应该很简单。以下是典型值

(无)

导入名称“app”或“wsgi”(作为 “.py”文件或包),自动检测应用程序 (appapplication) 或工厂 (create_appmake_app)。

--app hello

导入给定的名称,自动检测应用程序 (appapplication) 或工厂 (create_appmake_app)。


--app 有三部分:一个可选路径,用于设置当前工作目录,一个 Python 文件或点分导入路径,以及实例或工厂的可选变量名称。如果名称是工厂,则可以选择在括号中后跟参数。以下值演示了这些部分

--app src/hello

将当前工作目录设置为 src,然后导入 hello

--app hello.web

导入路径 hello.web

--app hello:app2

hello 中使用 app2 Flask 实例。

--app 'hello:create_app("dev")'

hello 中,create_app 工厂使用字符串 'dev' 作为参数调用。

如果未设置 --app,该命令将尝试导入“app”或“wsgi”(作为“.py”文件或包),并尝试检测应用程序实例或工厂。

在给定的导入中,该命令查找名为 appapplication 的应用程序实例,然后查找任何应用程序实例。如果未找到实例,该命令将查找名为 create_appmake_app 的工厂函数,该函数返回一个实例。

如果工厂名称后面跟着括号,则其内容将被解析为 Python 文字,并作为参数和关键字参数传递给函数。这意味着字符串仍必须用引号引起来。

运行开发服务器

run 命令将启动开发服务器。在大多数情况下,它会替换 Flask.run() 方法。

$ flask --app hello run
 * Serving Flask app "hello"
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

警告

不要使用此命令在生产环境中运行应用程序。仅在开发期间使用开发服务器。提供开发服务器是为了方便,但它并非设计为特别安全、稳定或高效。请参阅 部署到生产环境,了解如何在生产环境中运行。

如果另一个程序已经在使用端口 5000,当服务器尝试启动时,您将看到 OSError: [Errno 98]OSError: [WinError 10013]。请参阅 地址已在使用中,了解如何处理这种情况。

调试模式

在调试模式下,flask run 命令默认情况下将启用交互式调试器和重新加载器,并使错误更易于查看和调试。要启用调试模式,请使用 --debug 选项。

$ flask --app hello run --debug
 * Serving Flask app "hello"
 * 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

还可以将 --debug 选项传递给顶级 flask 命令,以针对任何命令启用调试模式。以下两个 run 调用是等效的。

$ flask --app hello --debug run
$ flask --app hello run --debug

使用重新加载器监视和忽略文件

在使用调试模式时,只要 Python 代码或导入的模块发生更改,重新加载器就会触发。重新加载器可以使用 --extra-files 选项监视其他文件。多个路径使用 : 分隔,或在 Windows 中使用 ; 分隔。

$ flask run --extra-files file1:dirA/file2:dirB/
 * Running on http://127.0.0.1:8000/
 * Detected change in '/path/to/file1', reloading

重新加载器还可以使用 fnmatch 模式和 --exclude-patterns 选项忽略文件。多个模式使用 : 分隔,或在 Windows 中使用 ; 分隔。

打开 Shell

若要浏览应用程序中的数据,可以使用 shell 命令启动一个交互式 Python shell。应用程序上下文将处于活动状态,并且会导入应用程序实例。

$ flask shell
Python 3.10.0 (default, Oct 27 2021, 06:59:51) [GCC 11.1.0] on linux
App: example [production]
Instance: /home/david/Projects/pallets/flask/instance
>>>

使用 shell_context_processor() 添加其他自动导入。

来自 dotenv 的环境变量

使用环境变量,flask 命令支持为任何命令设置任何选项。变量的命名方式类似于 FLASK_OPTIONFLASK_COMMAND_OPTION,例如 FLASK_APPFLASK_RUN_PORT

与其每次运行命令时都传递选项,或每次打开新终端时都传递环境变量,不如使用 Flask 的 dotenv 支持来自动设置环境变量。

如果已安装 python-dotenv,运行 flask 命令将设置在文件 .env.flaskenv 中定义的环境变量。还可以使用 --env-file 选项指定要加载的额外文件。可以使用 Dotenv 文件避免手动设置 --appFLASK_APP,并使用类似于某些部署服务工作方式的环境变量设置配置。

命令行中设置的变量将优先于 .env 中设置的变量,后者又优先于 .flaskenv 中设置的变量。 .flaskenv 应用于公共变量,例如 FLASK_APP,而 .env 不应提交到您的存储库,以便它可以设置私有变量。

目录从调用 flask 的目录向上扫描以找到文件。

这些文件仅由 flask 命令或调用 run() 加载。如果您想在生产环境中运行时加载这些文件,您应手动调用 load_dotenv()

设置命令选项

Click 被配置为从环境变量加载命令选项的默认值。变量使用模式 FLASK_COMMAND_OPTION。例如,要设置运行命令的端口,而不是 flask run --port 8000

$ export FLASK_RUN_PORT=8000
$ flask run
 * Running on http://127.0.0.1:8000/

这些内容可以像 FLASK_APP 一样添加到 .flaskenv 文件中,以控制默认命令选项。

禁用 dotenv

如果 flask 命令检测到 dotenv 文件但未安装 python-dotenv,它将显示一条消息。

$ flask run
 * Tip: There are .env files present. Do "pip install python-dotenv" to use them.

通过设置 FLASK_SKIP_DOTENV 环境变量,即使安装了 python-dotenv,您也可以告诉 Flask 不要加载 dotenv 文件。如果您想手动加载它们,或者如果您正在使用已经加载它们的项目运行程序,这会很有用。请记住,必须在加载应用程序之前设置环境变量,否则它不会按预期配置。

$ export FLASK_SKIP_DOTENV=1
$ flask run

virtualenv 中的环境变量

如果您不想安装 dotenv 支持,您仍然可以通过将它们添加到 virtualenv 的 activate 脚本的末尾来设置环境变量。激活 virtualenv 将设置变量。

Unix Bash,.venv/bin/activate

$ export FLASK_APP=hello

最好使用 dotenv 支持,因为 .flaskenv 可以提交到存储库,以便无论在何处签出项目,它都能自动工作。

自定义命令

使用 Click 实现 flask 命令。有关编写命令的完整信息,请参阅该项目的文档。

此示例添加了 create-user 命令,该命令采用 name 参数。

import click
from flask import Flask

app = Flask(__name__)

@app.cli.command("create-user")
@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

请参阅 使用 CLI Runner 运行命令,以了解如何测试您的自定义命令的概述。

使用蓝图注册命令

如果您的应用程序使用蓝图,您可以选择直接在蓝图上注册 CLI 命令。当您的蓝图注册到您的应用程序时,关联的命令将可用于 flask 命令。默认情况下,这些命令将嵌套在与蓝图名称匹配的组中。

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

您可以通过在创建 Blueprint 对象时指定 cli_group 参数,或稍后使用 app.register_blueprint(bp, cli_group='...') 来更改组名称。以下内容是等效的

bp = Blueprint('students', __name__, cli_group='other')
# or
app.register_blueprint(bp, cli_group='other')
$ flask other create alice

指定 cli_group=None 将删除嵌套并将命令直接合并到应用程序级别

bp = Blueprint('students', __name__, cli_group=None)
# or
app.register_blueprint(bp, cli_group=None)
$ flask create alice

应用程序上下文

使用 Flask 应用程序的 cliFlaskGroup command() 装饰器添加的命令将在推送应用程序上下文后执行,因此你的自定义命令和参数可以访问应用程序及其配置。可以使用 with_appcontext() 装饰器来获得相同行为,但在大多数情况下不需要。

import click
from flask.cli import with_appcontext

@click.command()
@with_appcontext
def do_work():
    ...

app.cli.add_command(do_work)

插件

Flask 将自动加载 flask.commands 入口点 中指定的命令。对于在安装时想要添加命令的扩展,这很有用。入口点在 pyproject.toml 中指定

[project.entry-points."flask.commands"]
my-command = "my_extension.commands:cli"

然后,可以在 my_extension/commands.py 中导出一个 Click 对象

import click

@click.command()
def cli():
    ...

一旦该软件包安装在与 Flask 项目相同的虚拟环境中,你就可以运行 flask my-command 来调用该命令。

自定义脚本

当你使用应用程序工厂模式时,定义你自己的 Click 脚本可能更方便。你可以创建自己的 Click 对象并将其导出为 控制台脚本 入口点,而不是使用 --app 并让 Flask 加载你的应用程序。

创建一个 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."""

pyproject.toml 中定义入口点

[project.scripts]
wiki = "wiki:cli"

以可编辑模式在 virtualenv 中安装应用程序,自定义脚本即可用。请注意,您无需设置 --app

$ pip install -e .
$ wiki run

自定义脚本中的错误

使用自定义脚本时,如果您在模块级代码中引入错误,则重新加载器将失败,因为它无法再加载入口点。

由于 flask 命令与您的代码是分开的,因此没有此问题,并且在大多数情况下建议使用此命令。

PyCharm 集成

PyCharm Professional 提供了一个特殊的 Flask 运行配置来运行开发服务器。对于社区版以及除 run 之外的其他命令,您需要创建一个自定义运行配置。这些说明对于您使用的任何其他 IDE 应该都是类似的。

在 PyCharm 中,在您的项目打开的情况下,从菜单栏中单击运行,然后转到编辑配置。您将看到类似于此的屏幕

Screenshot of PyCharm run configuration.

flask run 创建配置后,您可以复制并更改它以调用任何其他命令。

单击+(添加新配置)按钮并选择Python。为配置指定一个名称,例如“flask run”。

单击脚本路径下拉列表并将其更改为模块名称,然后输入 flask

参数字段设置为要执行的 CLI 命令以及任何参数。此示例使用 --app hello run --debug,它将在调试模式下运行开发服务器。 --app hello 应该是导入或包含 Flask 应用程序的文件。

如果您已将项目作为包安装在 virtualenv 中,则可以取消选中PYTHONPATH 选项。这将更准确地匹配您以后的部署方式。

单击确定以保存并关闭配置。在 PyCharm 主窗口中选择配置,然后单击其旁边的播放按钮以运行服务器。

现在您已为 flask run 创建了配置,您可以复制该配置并将参数参数更改为运行不同的 CLI 命令。