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

Установка Flask устанавливает скрипт flask, интерфейс командной строки Click, в вашем virtualenv. Выполняясь из терминала, этот скрипт предоставляет доступ к встроенным, расширенным и определенным приложением командам. Опция --help предоставит больше информации о любых командах и опциях.

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

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

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

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

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

Среды

Среда, в которой выполняется приложение 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 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

Отслеживание дополнительных файлов с перезагрузчиком

При использовании режима разработки перезагрузчик будет срабатывать при каждом изменении вашего Python-кода или импортированных модулей. Перезагрузчик может отслеживать дополнительные файлы с помощью опции --extra-files или переменной среды FLASK_RUN_EXTRA_FILES . Несколько путей разделяются символом :, или ; в Windows.

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

Установка опций команд

Click настроен на загрузку значений по умолчанию для опций команд из переменных среды. Переменные используют шаблон FLASK_COMMAND_OPTION. Например, чтобы установить порт для команды run, вместо flask run --port 8000:

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

Эти команды можно добавить в файл .flaskenv так же, как FLASK_APP, чтобы настроить параметры команд по умолчанию.

Отключение dotenv

Команда flask отобразит сообщение, если она обнаружит файлы dotenv, но python-dotenv не установлен.

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

Вы можете указать Flask не загружать файлы dotenv, даже если python-dotenv установлен, задав переменную окружения FLASK_SKIP_DOTENV. Это может быть полезно, если вы хотите загрузить их вручную или если вы используете загрузчик проекта, который уже загружает их. Имейте в виду, что переменные окружения должны быть установлены до загрузки приложения, иначе оно не сконфигурируется должным образом.

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

Регистрация команд с Blueprints

Если ваше приложение использует Blueprints, вы можете дополнительно зарегистрировать команды CLI непосредственно в них. Когда ваш Blueprint зарегистрирован в приложении, связанные команды будут доступны для команды flask. По умолчанию эти команды будут вложены в группу, соответствующую имени Blueprint.

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

Вы можете изменить имя группы, указав параметр cli_group при создании объекта Blueprint или позже с помощью 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

Контекст приложения

Команды, добавленные с помощью декоратора cli приложения Flask 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():
    ...

После установки этого пакета в той же virtualenv, что и ваш проект 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'
        ],
    },
)

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

$ pip install -e .
$ wiki run

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

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

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

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

Нажмите кнопку + (Добавить новую конфигурацию) и выберите 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, мы можем скопировать эту конфигурацию и изменить аргумент Script, чтобы запустить другую команду CLI, например flask shell.