- en
- Language: ru
- Documentation version: 1.1.x
Интерфейс командной строки¶
Установка Flask устанавливает скрипт flask
, интерфейс командной строки Click, в ваш virtualenv. Выполняемый из терминала, этот скрипт предоставляет доступ к встроенным командам, командам расширения и командам, определяемым приложением. Опция --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
Использует экземпляр колбы
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()
для добавления других автоматических импортов.
Среды¶
Добавлено в версии 1.0.
Окружение, в котором работает приложение 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, вы все равно можете установить переменные окружения, добавив их в конец скрипта 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.
Регистрация команд в чертежах¶
Если ваше приложение использует чертежи, вы можете зарегистрировать команды 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
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
Ошибки в пользовательских сценариях
При использовании пользовательского сценария, если вы внесете ошибку в код на уровне модуля, перезагрузчик не сможет загрузить точку входа.
Команда flask
, будучи отделенной от вашего кода, не имеет этой проблемы и рекомендуется в большинстве случаев.
Интеграция PyCharm¶
PyCharm Professional предоставляет специальную конфигурацию запуска Flask. Для Community Edition нам нужно настроить его на вызов команды flask run
CLI с правильными переменными окружения. Эти инструкции должны быть аналогичными для любой другой IDE, которую вы захотите использовать.
В PyCharm, когда ваш проект открыт, нажмите на Run в строке меню и перейдите к Edit Configurations. Перед вами откроется окно, похожее на это:
![Screenshot of PyCharms's run configuration settings.](../_images/pycharm-runconfig.png)
Здесь довольно много параметров для изменения, но после того, как мы сделали это для одной команды, мы можем легко скопировать всю конфигурацию и сделать одну настройку, чтобы получить доступ к другим командам, включая любые пользовательские команды, которые вы можете реализовать самостоятельно.
Нажмите кнопку + (Добавить новую конфигурацию) и выберите 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
.