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

Одной из приятных новых функций в Flask 0.11 является встроенная интеграция командной строки click. Это открывает широкий спектр новых возможностей для экосистемы Flask и ваших собственных приложений.

Основное использование

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

Работа этого скрипта заключается в предоставлении доступа ко всем командам приложения Flask через экземпляр Flask.cli, а также к некоторым встроенным командам, которые всегда присутствуют. Расширения Flask также могут регистрировать там дополнительные команды, если это необходимо.

Для работы скрипта flask необходимо обнаружить приложение. Это достигается путем экспорта переменной среды FLASK_APP. Она может быть установлена либо в путь импорта, либо в имя файла Python-модуля, содержащего приложение Flask.

В импортированном файле имя приложения должно называться app или, по желанию, указываться после двоеточия. Например, mymodule:application укажет на использование объекта application в файле mymodule.py.

Предположим, что у вас есть файл hello.py с приложением, названный app. Вот как его можно запустить.

Переменные окружения (в Windows используйте set вместо export):

export FLASK_APP=hello
flask run

Или с именем файла:

export FLASK_APP=/path/to/hello.py
flask run

Интеграция с виртуальной средой

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

Флаг отладки

Скрипт flask также может быть настроен на автоматическую включение режима отладки приложения путем экспорта FLASK_DEBUG. Если установлено 1, режим отладки включен, а 0 его выключает:

export FLASK_DEBUG=1

Запуск интерактивной оболочки

Для запуска интерактивной Python оболочки можно использовать команду shell:

flask shell

Это запустит интерактивную Python оболочку, настроит правильный контекст приложения и установит локальные переменные в оболочке. Это делается путем вызова метода Flask.make_shell_context() приложения. По умолчанию у вас есть доступ к вашему app и g.

Пользовательские команды

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

import click
from flask import Flask

app = Flask(__name__)

@app.cli.command()
def initdb():
    """Initialize the database."""
    click.echo('Init the db')

Команда затем появится в командной строке:

$ flask initdb
Init the db

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

Большинство команд работают с приложением, поэтому имеет смысл, если у них настроен контекст приложения. По этой причине, если вы регистрируете обратный вызов на app.cli с помощью command(), обратный вызов автоматически будет обернут через cli.with_appcontext(), что информирует систему командной строки о необходимости установки контекста приложения. Это поведение недоступно, если команда добавляется позже с помощью add_command() или другими способами.

Его также можно отключить, передав with_appcontext=False декоратору:

@app.cli.command(with_appcontext=False)
def example():
    pass

Функции-фабрики

В случае использования функций-фабрик для создания вашего приложения (см. Фабрики приложений) вы обнаружите, что команда flask не может работать с ними напрямую. Flask не сможет самостоятельно правильно определить, как создать ваше приложение. По этой причине рекомендуется создать отдельный файл, который инициализирует приложения. Это не единственный способ сделать это. Другой способ - поддержка Пользовательские скрипты.

Например, если у вас есть функция-фабрика, которая создает приложение из имени файла, вы можете создать отдельный файл, который создает такое приложение из переменной окружения.

Это может быть файл с именем autoapp.py со следующим содержимым:

import os
from yourapplication import create_app
app = create_app(os.environ['YOURAPPLICATION_CONFIG'])

После этого вы можете заставить команду flask автоматически обнаруживать его:

export YOURAPPLICATION_CONFIG=/path/to/config.cfg
export FLASK_APP=/path/to/autoapp.py

С этого момента flask будет находить ваше приложение.

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

Хотя наиболее распространенным способом является использование команды flask, вы также можете создать свои собственные «скрипты-драйвера». Поскольку Flask использует click для скриптов, нет причины, по которой вы не можете подключить эти скрипты к любому приложению click. Существует одно важное замечание: команды, зарегистрированные в Flask.cli, будут ожидать (по крайней мере, косвенно) запуска из группы click flask.cli.FlaskGroup. Это необходимо, чтобы команды знали, с каким приложением Flask они должны работать.

Чтобы понять, почему вам могут понадобиться пользовательские скрипты, необходимо понять, как click находит и выполняет приложение Flask. Если вы используете скрипт flask, вы указываете приложение для работы в командной строке или переменной среды как имя импорта. Это просто, но имеет некоторые ограничения. В первую очередь, это не работает с функциями-фабриками приложений (см. Фабрики приложений).

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

Чтобы объяснить все это, вот пример manage.py скрипта, который управляет гипотетическим приложением вики. Мы рассмотрим детали позже:

import os
import click
from flask.cli import FlaskGroup

def create_wiki_app(info):
    from yourwiki import create_app
    return create_app(
        config=os.environ.get('WIKI_CONFIG', 'wikiconfig.py'))

@click.group(cls=FlaskGroup, create_app=create_wiki_app)
def cli():
    """This is a management script for the wiki application."""

if __name__ == '__main__':
    cli()

Это много кода для не очень большого результата, поэтому давайте пройдемся по всем частям пошагово.

1. Сначала мы импортируем библиотеку click и расширения click из пакета flask.cli. В первую очередь, нас интересует группа click FlaskGroup.
2. Следующее, что мы делаем, - это определение функции, которая вызывается с объектом информации о скрипте (ScriptInfo) из Flask и предназначена для полного импорта и создания приложения. Это может напрямую импортировать объект приложения или создать его (см. Фабрики приложений). В этом случае мы загружаем конфигурацию из переменной окружения.

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

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

4. Все сводится к вызову скрипта.

Плагины CLI

Расширения Flask всегда могут исправлять экземпляр Flask.cli дополнительными командами, если захотят. Однако есть второй способ добавления плагинов CLI в Flask - это setuptools. Если вы создаете Python-пакет, который должен экспортировать плагин командной строки Flask, вы можете отправить файл setup.py , который объявляет точку входа, указывающую на команду click:

Пример setup.py:

from setuptools import setup

setup(
    name='flask-my-extension',
    ...
    entry_points='''
        [flask.commands]
        my-command=mypackage.commands:cli
    ''',
)

Внутри mypackage/commands.py вы можете затем экспортировать объект Click:

import click

@click.command()
def cli():
    """This is an example command."""

После того, как этот пакет установлен в той же виртуальной среде, что и Flask, вы можете запустить flask my-command для вызова вашей команды. Это полезно для предоставления дополнительной функциональности, которой сам Flask не может предоставить.