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

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

Команда 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

Использует экземпляр Flask 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 --debug run
 * 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 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.

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

Если 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’s 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-раннера для обзора того, как тестировать пользовательские команды.

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 точках входа. Это полезно для расширений, которые хотят добавлять команды при установке. Точки входа указываются в 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 для вызова команды.

Пользовательские скрипты

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

Создайте экземпляр 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'
        ],
    },
)

Установите приложение в виртуальной среде в режиме редактирования, и пользовательский скрипт доступен. Обратите внимание, что вам не нужно устанавливать --app.

$ pip install -e .
$ wiki run

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

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

В PyCharm, с открытым проектом, нажмите Run в строке меню и перейдите к Редактировать конфигурации. Вы увидите экран, похожий на этот:

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

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

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

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

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

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

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