命令行界面 — Flask 文档

来自菜鸟教程
Flask/docs/2.0.x/cli
跳转至：导航、​搜索

命令行界面

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

应用发现

flask 命令由 Flask 安装，而不是您的应用程序； 必须告诉它在哪里可以找到您的应用程序才能使用它。 FLASK_APP 环境变量用于指定如何加载应用程序。

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

（没什么）
导入名称“app”或“wsgi”（作为“.py”文件或包），自动检测应用程序（app 或 application）或工厂（[ X140X] 或 make_app）。
FLASK_APP=hello
导入给定的名称，自动检测应用程序（app 或 application）或工厂（create_app 或 make_app）。


FLASK_APP 包含三个部分：设置当前工作目录的可选路径、Python 文件或虚线导入路径以及实例或工厂的可选变量名称。 如果名称是工厂，则可以选择后跟括号中的参数。 以下值说明了这些部分：

FLASK_APP=src/hello
将当前工作目录设置为 src，然后导入 hello。
FLASK_APP=hello.web
导入路径 hello.web。
FLASK_APP=hello:app2
在 hello 中使用 app2 Flask 实例。
FLASK_APP="hello:create_app('dev')"
hello 中的 create_app 工厂以字符串 'dev' 作为参数被调用。

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

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

如果工厂名称后面有括号，则它们的内容将被解析为 Python 文字并作为参数和关键字参数传递给函数。 这意味着字符串必须仍然在引号中。


运行开发服务器

run 命令将启动开发服务器。 在大多数情况下，它取代了 Flask.run() 方法。 

$ flask 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]。 请参阅 Address already in use 了解如何处理。


打开壳

要探索应用程序中的数据，您可以使用 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
>>>

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


环境

1.0 版中的新功能。


Flask 应用程序运行的环境由 FLASK_ENV 环境变量设置。 如果未设置，则默认为 production。 另一个公认的环境是development。 Flask 和扩展可以选择启用基于环境的行为。

如果 env 设置为 development，flask 命令将启用调试模式，而 flask run 将启用交互式调试器和重新加载器。

使用重载器观看额外文件

使用开发模式时，只要您的 Python 代码或导入的模块发生更改，重新加载器就会触发。 重新加载器可以使用 --extra-files 选项或 FLASK_RUN_EXTRA_FILES 环境变量查看其他文件。 在 Windows 上，多个路径用 : 或 ; 分隔。


调试模式

如上所述，当 FLASK_ENV 为 development 时，将启用调试模式。 如果要单独控制调试模式，请使用 FLASK_DEBUG。 值 1 启用它，0 禁用它。


来自 dotenv 的环境变量

无需每次打开新终端时都设置 FLASK_APP，您可以使用 Flask 的 dotenv 支持来自动设置环境变量。

如果安装了 python-dotenv，运行 flask 命令将设置文件 .env 和 .flaskenv 中定义的环境变量。 这可用于避免每次打开新终端时都必须手动设置 FLASK_APP，并使用类似于某些部署服务工作方式的环境变量来设置配置。

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

从您调用 flask 的目录向上扫描目录以定位文件。 当前工作目录将被设置为文件的位置，假设这是顶级项目目录。

文件只能通过flask命令或调用run()加载。 如果您想在生产中运行时加载这些文件，您应该手动调用 load_dotenv()。

设置命令选项

Click 配置为从环境变量加载命令选项的默认值。 变量使用模式 FLASK_COMMAND_OPTION。 例如，为运行命令设置端口，而不是 flask run --port 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 环境变量，您可以告诉 Flask 即使安装了 python-dotenv 也不加载 dotenv 文件。 如果您想手动加载它们，或者如果您正在使用已经加载它们的项目运行器，这会很有用。 请记住，必须在应用加载之前设置环境变量，否则将无法按预期进行配置。


来自 virtualenv 的环境变量

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

最好使用 dotenv 支持，因为 .flaskenv 可以提交到存储库，以便它在项目检出的任何地方自动工作。


自定义命令

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

此示例添加了命令 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 命令 。

使用蓝图注册命令

如果您的应用程序使用蓝图，您可以选择将 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 对象时或稍后使用 app.register_blueprint(bp, cli_group='...') 指定 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 应用程序的 cli command() 装饰器添加的命令将在推送应用程序上下文的情况下执行，因此您的命令和扩展可以访问应用程序及其配置。 如果您使用 Click command() 装饰器而不是 Flask 装饰器创建命令，您可以使用 with_appcontext() 来获得相同的行为。 

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():
    ...

插件

Flask 将自动加载在 flask.commands 入口点 中指定的命令。 这对于想要在安装时添加命令的扩展很有用。 入口点在 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 项目相同的 virtualenv 中，您就可以运行 flask my-command 来调用该命令。


自定义脚本

当您使用应用工厂模式时，定义您自己的 Click 脚本可能会更方便。 您可以创建自己的 Click 对象并将其导出为 控制台脚本 入口点，而不是使用 FLASK_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."""

在setup.py中定义入口点： 

from setuptools import setup

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

以可编辑模式在 virtualenv 中安装应用程序，自定义脚本可用。 注意不需要设置FLASK_APP。 

$ pip install -e .
$ wiki run

自定义脚本中的错误

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

flask 命令与您的代码分开，不存在此问题，建议在大多数情况下使用。


PyCharm 集成

PyCharm Professional 提供了特殊的 Flask 运行配置。 对于社区版，我们需要将其配置为使用正确的环境变量调用 flask run CLI 命令。 对于您可能想要使用的任何其他 IDE，这些说明应该是类似的。

在 PyCharm 中，打开您的项目，单击菜单栏中的 Run，然后转到 Edit Configurations。 您将看到类似以下的屏幕：

class=screenshot align-center|Screenshot of PyCharms's run configuration settings. 有很多选项可以更改，但是一旦我们为一个命令完成了更改，我们就可以轻松复制整个配置并进行一次调整，以便我们访问其他命令，包括您可以自己实现的任何自定义命令。

单击 + (Add New Configuration) 按钮并选择 Python。 为配置命名，例如“flask run”。 对于 flask run 命令，请选中“Single instance only”，因为您不能同时运行多次服务器。

从下拉菜单中选择 模块名称 (A)，然后输入 flask。

Parameters 字段 (B) 设置为要执行的 CLI 命令（带有任何参数）。 在本例中，我们使用 run，它将运行开发服务器。

如果您使用 dotenv 中的 环境变量，则可以跳过下一步。 我们需要添加一个环境变量 (C) 来标识我们的应用程序。 单击浏览按钮并添加一个条目，左侧为 FLASK_APP，右侧为 Python 导入或文件（例如 hello）。 添加带有 FLASK_ENV 的条目并将其设置为 development。

接下来，我们需要将工作目录 (D) 设置为我们的应用程序所在的文件夹。

如果您已将项目作为包安装在您的 virtualenv 中，您可以取消勾选 PYTHONPATH 选项（E）。 这将更准确地匹配您稍后部署应用程序的方式。

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

现在我们有一个从 PyCharm 中运行 flask run 的配置，我们可以复制该配置并更改 Script 参数以运行不同的 CLI 命令，例如 flask shell。



取自“https://cainiaojiaocheng.com/index.php?title=Flask/docs/2.0.x/cli&oldid=25696”
Powered by MediaWiki