Интерфейс командной строки¶

Обнаружение приложений¶

Команда flask устанавливается Flask, а не вашим приложением; ей необходимо указать, где найти ваше приложение, чтобы использовать его. Опция --app используется для указания способа загрузки приложения.

Хотя --app поддерживает множество вариантов для указания вашего приложения, большинство случаев использования должны быть простыми. Вот типичные значения:

(ничего)

Имя «app» или «wsgi» импортируется (как файл «.py» или пакет), автоматически определяя приложение (app или application) или фабрику (create_app или make_app).

--app hello

Заданное имя импортируется, автоматически определяя приложение (app или application) или фабрику (create_app или make_app).

--app состоит из трех частей: необязательный путь, задающий текущий рабочий каталог, путь к файлу Python или точечный путь импорта, и необязательное имя переменной экземпляра или фабрики. Если имя является фабрикой, за ним по желанию могут следовать аргументы в круглых скобках. Следующие значения демонстрируют эти части:

--app src/hello

Устанавливает текущий рабочий каталог в src, затем импортирует hello.

--app hello.web

Импортирует путь hello.web.

--app hello:app2

Использует экземпляр колбы app2 в hello.

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

Фабрика create_app в hello вызывается со строкой 'dev' в качестве аргумента.

Если --app не установлено, команда попытается импортировать «app» или «wsgi» (как файл «.py» или пакет) и попытается обнаружить экземпляр приложения или фабрику.

Внутри заданного импорта команда ищет экземпляр приложения с именем app или application, затем любой экземпляр приложения. Если экземпляр не найден, команда ищет фабричную функцию с именем create_app или make_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 --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

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

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

Открыть оболочку¶

Чтобы изучить данные в вашем приложении, вы можете запустить интерактивную оболочку 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_OPTION или FLASK_COMMAND_OPTION, например FLASK_APP или FLASK_RUN_PORT.

Вместо того чтобы передавать опции каждый раз, когда вы выполняете команду, или переменные окружения каждый раз, когда вы открываете новый терминал, вы можете использовать поддержку dotenv во Flask для автоматической установки переменных окружения.

Если установлен python-dotenv, выполнение команды flask установит переменные окружения, определенные в файлах .env и .flaskenv. Вы также можете указать дополнительный файл для загрузки с помощью опции --env-file. Файлы Dotenv можно использовать, чтобы избежать необходимости устанавливать --app или FLASK_APP вручную, а также для задания конфигурации с помощью переменных окружения, аналогично тому, как работают некоторые службы развертывания.

Переменные, заданные в командной строке, используются поверх переменных, заданных в .env, которые используются поверх переменных, заданных в .flaskenv. .flaskenv следует использовать для публичных переменных, таких как FLASK_APP, а .env не следует фиксировать в вашем репозитории, чтобы он мог устанавливать приватные переменные.

Для поиска файлов каталоги сканируются вверх от каталога, из которого вы вызываете flask.

Файлы загружаются только командой flask или вызовом run(). Если вы хотите загрузить эти файлы при работе в продакшене, вам следует вызвать load_dotenv() вручную.

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

$ set -x FLASK_RUN_PORT 8000
$ flask run
 * Running on http://127.0.0.1:8000/

> set FLASK_RUN_PORT=8000
> flask run
 * Running on http://127.0.0.1:8000/

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

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

$ export FLASK_SKIP_DOTENV=1
$ flask run

$ set -x FLASK_SKIP_DOTENV 1
$ flask run

> set FLASK_SKIP_DOTENV=1
> flask run

> $env:FLASK_SKIP_DOTENV = 1
> flask run

Переменные среды из virtualenv¶

Если вы не хотите устанавливать поддержку dotenv, вы все равно можете установить переменные окружения, добавив их в конец скрипта virtualenv activate. Активация virtualenv установит переменные.

$ export FLASK_APP=hello

$ set -x FLASK_APP hello

> set FLASK_APP=hello

> $env:FLASK_APP = "hello"

Предпочтительнее использовать поддержку 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 Runner.

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

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

$ flask other create alice

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

$ flask create alice

import click
from flask.cli import with_appcontext

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

app.cli.add_command(do_work)

Плагины¶

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

Когда этот пакет установлен в том же virtualenv, что и ваш проект Flask, вы можете выполнить flask my-command для вызова команды.

Пользовательские сценарии¶

При использовании паттерна фабрики приложений может быть удобнее определить свой собственный сценарий Click. Вместо того чтобы использовать --app и позволять Flask загружать ваше приложение, вы можете создать свой собственный объект Click и экспортировать его как точку входа console script.

Создайте экземпляр 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 в редактируемом режиме, и пользовательский скрипт будет доступен. Обратите внимание, что вам не нужно устанавливать --app.

$ pip install -e .
$ wiki run

Интеграция PyCharm¶

PyCharm Professional предоставляет специальную конфигурацию запуска Flask для запуска сервера разработки. Для Community Edition, а также для других команд, кроме run, вам необходимо создать собственную конфигурацию запуска. Эти инструкции должны быть аналогичными для любой другой IDE, которую вы используете.

В PyCharm, когда ваш проект открыт, нажмите на Run в строке меню и перейдите к Edit Configurations. Вы увидите окно, похожее на это:

Создав конфигурацию для flask run, вы можете копировать и изменять ее для вызова любой другой команды.

Нажмите кнопку + (Добавить новую конфигурацию) и выберите Python. Дайте конфигурации имя, например «flask run».

Щелкните на выпадающем списке Путь к сценарию и измените его на Имя модуля, затем введите flask.

В поле Параметры задается команда CLI для выполнения вместе с любыми аргументами. В данном примере используется --app hello run --debug, которая запустит сервер разработки в режиме отладки. --app hello должен быть импортом или файлом с вашим приложением Flask.

Если вы установили свой проект как пакет в virtualenv, вы можете снять флажок с опции PYTHONPATH. Это будет более точно соответствовать тому, как вы развернете проект позже.

Нажмите OK, чтобы сохранить и закрыть конфигурацию. Выберите конфигурацию в главном окне PyCharm и нажмите кнопку play рядом с ней, чтобы запустить сервер.

Теперь, когда у вас есть конфигурация для flask run, вы можете скопировать ее и изменить аргумент Параметры, чтобы запустить другую команду CLI.