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

При установке 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, которая возвращает экземпляр.

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

Если env установлено в 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

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

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

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 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 для вызова команды.

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

Когда вы используете шаблон фабрики приложений, может быть удобнее определить свой собственный скрипт 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. Вы увидите экран, похожий на этот:

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

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

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

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

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

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

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

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

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