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

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

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

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

Unix Bash (Linux, Mac и т. д.):

$ export FLASK_APP=hello
$ flask run

Windows CMD:

> set FLASK_APP=hello
> flask run

Windows PowerShell:

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

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

(ничего)

Файл wsgi.py импортируется, автоматически обнаруживая приложение (app). Это предоставляет простой способ создания приложения из фабрики с дополнительными аргументами.

FLASK_APP=hello

Имя импортируется, автоматически обнаруживая приложение (app) или фабрику (create_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, которая возвращает экземпляр.

При вызове фабрики приложения, если фабрика принимает аргумент с именем info, тогда экземпляр ScriptInfo передаётся в качестве ключевого аргумента. Если после имени фабрики следуют скобки, их содержимое парсится как литералы 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 и расширения могут выбирать включение определённых режимов работы на основе среды.

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

$ 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_ENV имеет значение development, как описано выше. Если вы хотите управлять отладочным режимом отдельно, используйте FLASK_DEBUG. Значение 1 включает его, 0 — выключает.

Переменные окружения из dotenv

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

Если 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/

Эти значения можно добавить в файл .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

Переменные окружения из virtualenv

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

Unix Bash, venv/bin/activate:

$ export FLASK_APP=hello

Windows CMD, venv\Scripts\activate.bat:

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

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

Команды, добавленные с помощью декоратора cli command() приложения Flask, будут выполняться с загруженным контекстом приложения, поэтому ваша команда и расширения получат доступ к приложению и его конфигурации. Если вы создаёте команду с использованием декоратора 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, вы можете запустить flask my-command для вызова команды.

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

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

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

$ pip install -e .
$ wiki run

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

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

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

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

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

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

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

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

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

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

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

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