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

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

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

$ export FLASK_APP=hello
$ flask run

$ set -x FLASK_APP hello
$ flask run

> set FLASK_APP=hello
> flask run

> $env:FLASK_APP = "hello"
> flask run

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

(ничего)

Импортируется имя «app» или «wsgi» (в качестве файла ".py" или пакета), автоматически обнаруживая приложение (app или application) или фабрику (create_app или 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

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

FLASK_APP="hello:create_app('dev')"

Вызывается фабрика create_app в hello с аргументом '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]. См. Адрес уже используется для обработки этой ситуации.

Открытие оболочки

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

Среды

Среда, в которой работает приложение Flask, задаётся переменной среды FLASK_ENV. Если она не задана, используется значение по умолчанию production. Другая распознаваемая среда — development. Flask и расширения могут выбирать включение поведения на основе среды.

Если env установлено в значение development, команда flask включит режим отладки, а команда flask run включит интерактивный отладчик и перезагрузчик.

$ export 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

$ set -x 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

> set 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

> $env: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

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

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

> flask run --extra-files file1:dirA/file2:dirB/
# or
> set FLASK_RUN_EXTRA_FILES=file1:dirA/file2:dirB/
> flask run
 * Running on http://127.0.0.1:8000/
 * Detected change in '/path/to/file1', reloading

> flask run --extra-files file1:dirA/file2:dirB/
# or
> $env:FLASK_RUN_EXTRA_FILES = "file1:dirA/file2:dirB/"
> flask run
 * Running on http://127.0.0.1:8000/
 * Detected change in '/path/to/file1', reloading

Режим отладки

Режим отладки будет включён, когда 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().

$ 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, вы всё ещё можете установить переменные окружения, добавив их в конец скрипта activate virtualenv. Активация 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)

@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, вы можете запустить flask my-command для вызова команды.

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

При использовании шаблона фабрики приложения, возможно, удобнее определить собственный скрипт Click. Вместо использования FLASK_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'
        ],
    },
)

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

$ pip install -e .
$ wiki run

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

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

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

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

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

Выберите Имя модуля из раскрывающегося списка (A), затем введите flask.

Поле Параметры (B) устанавливается на команду CLI для выполнения (с любыми аргументами). В этом примере мы используем run, что запустит сервер разработки.

Вы можете пропустить этот шаг, если используете Переменные окружения из dotenv. Нам нужно добавить переменную окружения (C) для идентификации нашего приложения. Нажмите кнопку обзора и добавьте запись с FLASK_APP слева и импортом Python или файлом справа (hello например). Добавьте запись с FLASK_ENV и установите значение development.

Далее нам нужно установить рабочую директорию (D) в папку, где находится наше приложение.

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

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

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