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

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

Команда 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

Использует экземпляр колбы 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

$ 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() вручную.

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

Переменные среды из virtualenv¶

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

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 entry point. Это полезно для расширений, которые хотят добавить команды при установке. Точки входа указываются в 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 и экспортировать его как точку входа 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'
        ],
    },
)

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

$ pip install -e .
$ wiki run

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

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

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

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

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

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

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

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

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

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

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

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