API объекта приложения Flask

Класс Flask — ядро всего фреймворка. Он работает как WSGI-приложение и централизованно управляет всеми возможностями: маршрутизацией, шаблонами, конфигурацией, хуками и другими.

Способ создания:

app = Flask(__name__)

Параметры конструктора

Ниже перечислены все параметры, которые можно передать при создании экземпляра Flask:

Параметр Type Значение по умолчанию Описание
import_name str Обязательный Имя модуля/пакета приложения. Flask использует его для поиска шаблонов и статических файлов. Передаётся как один файл.__name__, передайте имя пакета
static_url_path str Отсутствует URL-путь, предоставляемый для статических файлов. Если не задан, используется имя папки static_folder, например /static.
static_folder str "static" Путь к папке для статических файлов (CSS, JS, изображений), относительно root_path или абсолютный путь.
static_host str Отсутствует Имя хоста для маршрута статических файлов. Требуется только при host_matching=True.
host_matching bool False Сопоставлять ли маршруты по заголовку Host
subdomain_matching bool False Включить ли сопоставление маршрутов поддоменов
template_folder str "templates" Путь к папке для файлов шаблонов Jinja2.
instance_path str None (автообнаружение) Путь к папке instance, используемый для хранения файлов, которые не попадают в систему контроля версий во время выполнения. Укажите абсолютный путь
instance_relative_config bool False Если True, относительные пути в файле конфигурации основываются на instance_path, а не на root_path
root_path str None (автообнаружение) Корневой путь приложения, обычно определяется автоматически. Вручную его нужно задавать только для namespace-пакетов.

Основные атрибуты

Свойство Type Описание
name str Имя приложения. Если import_name — __main__, используется имя файла главного модуля.
config Config Объект словаря конфигурации, хранящий все элементы конфигурации
debug bool Включён ли режим отладки. Эквивалентно config["DEBUG"].
testing bool Включён ли режим тестирования. Эквивалентно config["TESTING"].
secret_key str Секретный ключ, используемый для подписи сессии. Эквивалентно config["SECRET_KEY"]
permanent_session_lifetime timedelta Время жизни постоянных сессий, по умолчанию 31 день.
url_map Map URL-карта Werkzeug, содержащая все правила маршрутизации.
view_functions dict Словарь сопоставления endpoint → функции представления.
blueprints dict Сопоставление зарегистрированного имени blueprint → экземпляру Blueprint
extensions dict Словарь хранения расширений. Расширения хранят своё состояние по имени модуля.
logger Logger Стандартный Python logging.Logger, где имя приложения используется как имя логгера
jinja_env Окружение Экземпляр окружения Jinja2, управляющий загрузкой шаблонов
json JSONProvider Экземпляр провайдера обработчика JSON, заменяемый на пользовательскую библиотеку JSON
aborter Aborter Возбудитель HTTP-исключений, вызываемый функцией abort().
cli AppGroup Группа команд Click для добавления пользовательских команд CLI.
instance_path str Абсолютный путь к папке экземпляра.
root_path str Абсолютный путь к корневому каталогу приложения

Переопределяемые атрибуты класса

Следующие атрибуты можно переопределить в подклассах для настройки поведения фреймворка:

Свойство Значение по умолчанию Описание
request_class Запрос Класс, используемый для создания объектов запроса
response_class Response Класс, используемый для создания объектов ответа
session_interface SecureCookieSessionInterface() Интерфейс бэкенда сессий, заменяемый на сессии Redis/базы данных
jinja_environment Окружение Класс среды Jinja2
app_ctx_globals_class _AppCtxGlobals Класс объекта g
config_class Config Класс объекта конфигурации
aborter_class Aborter Класс объекта, выбрасывающего исключения
json_provider_class DefaultJSONProvider Класс обработчика JSON
url_rule_class Правило Класс для правил URL (Werkzeug)
url_map_class Map Класс карты URL (Werkzeug)
test_client_class None (по умолчанию FlaskClient) Класс тестового клиента
test_cli_runner_class None (по умолчанию FlaskCliRunner) Класс средства запуска тестов CLI
jinja_options {} Дополнительные параметры, передаваемые в окружение Jinja2.

Метод маршрутизации URL

Методы Сигнатура Описание
route (rule, **options) Декоратор, который привязывает правило URL к функции представления.
get (rule, **options) Декоратор, который привязывает только метод GET (эквивалентно methods=["GET"])
post (rule, **options) Декоратор, который привязывает только метод POST.
put (rule, **options) Декоратор, который привязывает только метод PUT
удаление (rule, **options) Декоратор, который привязывает только метод DELETE.
patch (rule, **options) Декоратор, который привязывает только метод PATCH.
add_url_rule (rule, endpoint, view_func, provide_automatic_options, **options) Добавляет правила URL программно. Декоратор route вызывает этот метод под капотом.
url_for (endpoint, *, _anchor, _method, _scheme, _external, **values) Генерирует URL из конечной точки и параметров. В чертежах конечная точка должна иметь префикс с именем чертежа.
register_blueprint (blueprint, **options) Регистрирует blueprint с переопределяющими параметрами, такими как url_prefix, subdomain и т. д.
iter_blueprints () Итерировать по всем blueprints в порядке регистрации

Параметры, поддерживаемые декоратором route, включают:methods(список HTTP-методов),endpoint(пользовательское имя endpoint),defaults(параметры по умолчанию),subdomain(поддомен) и т. д.


Хуки жизненного цикла запроса (декораторы)

Следующие методы можно использовать как декораторы для вставки пользовательской логики на разных этапах обработки запроса:

Методы Момент выполнения Поведение при возврате non-None Типичное использование
before_request Перед диспетчеризацией маршрута Возвращаемое значение используется как окончательный ответ, минуя функцию представления. Проверки входа, проверка разрешений
after_request После того как ответ сформирован, но перед его отправкой Должен принимать и возвращать объект Response. Добавление заголовков безопасности, заголовков CORS
teardown_request Когда контекст запроса снимается Возвращаемое значение игнорируется Освобождение ресурсов уровня запроса
teardown_appcontext Когда контекст приложения снимается Возвращаемое значение игнорируется Закрыть соединение с базой данных
errorhandler Когда возникает указанный код состояния или исключение Возвращаемое значение используется как ответ для страницы ошибки Пользовательские страницы 404/500
url_value_preprocessor После извлечения переменных URL, перед вызовом представления. Возвращаемое значение игнорируется Предварительная обработка параметров URL
url_defaults При построении URL с помощью url_for Изменяет переданный словарь значений. Добавляет параметры по умолчанию в url_for.
template_filter — (характер регистрации) — Зарегистрировать фильтр шаблонов Jinja2
template_test — (характер регистрации) — Зарегистрировать тест шаблонов Jinja2
template_global — (характер регистрации) — Зарегистрировать глобальную функцию Jinja2
shell_context_processor Когда запускается flask shell Возвращает dict, который объединяется с контекстом shell. Предварительно импортирует часто используемые объекты в flask shell.

Метод обработки запроса

Следующие методы вызываются внутренне при обработке запросов и могут быть переопределены в подклассах:

Методы Описание
preprocess_request(ctx) Предварительная обработка запроса: выполняет функции before_request и препроцессоры URL.
dispatch_request(ctx) Основная диспетчеризация: сопоставляет URL и вызывает соответствующую функцию представления.
make_response(rv) Преобразует возвращаемое значение функции представления в объект Response.
finalize_request(ctx, rv) Финализация: вызывает make_response и хуки after_request
process_response(ctx, response) Обработка после ответа: выполняет функции after_request и сохранение сессии
full_dispatch_request(ctx) Полная точка входа диспетчеризации запроса: preprocess → dispatch → finalize
handle_http_exception(ctx, e) Обрабатывает HTTP-исключения, ищет соответствующий errorhandler
handle_user_exception(ctx, e) Обрабатывает исключения из пользовательского кода, различая HTTP-исключения и обычные исключения.
handle_exception(ctx, e) Финальная обработка исключений, возвращает ответ 500.
ensure_sync(func) Гарантирует, что функция выполняется синхронно. Асинхронные функции оборачиваются, чтобы стать синхронными.
make_default_options_response(ctx) Генерирует автоматические ответы OPTIONS.
raise_routing_exception(request) Обрабатывает исключения маршрутизации (например, перенаправления при завершающем слеше).

Шаблоны и статические файлы

Методы Описание
create_jinja_environment() Создаёт и настраивает среду Jinja2. Автоматически вызывается при первом доступе к jinja_env.
create_global_jinja_loader() Создаёт глобальный загрузчик Jinja2, поддерживающий диспетчеризацию шаблонов между приложением и блюпринтами.
select_jinja_autoescape(filename) Определяет, требует ли данный файл автоматического экранирования. По умолчанию возвращает True для .html/.htm/.xml/.xhtml/.svg
update_template_context(ctx, context) Внедряет встроенные переменные, такие как request, session, g, config, в контекст шаблона
send_static_file(filename) Отправляет файлы из static_folder, автоматически регистрируется как /static/Маршрутизация
get_send_file_max_age(filename) Получает время кэширования статических файлов. По умолчанию берётся из конфигурации SEND_FILE_MAX_AGE_DEFAULT.
open_resource(resource, mode="rb") Открывает файлы ресурсов в root_path в бинарном режиме.
open_instance_resource(resource, mode="rb") Открывает файлы ресурсов в instance_path, поддерживая режим записи.

Управление контекстом

Методы Описание
app_context() Создаёт контекст приложения, который вручную помещается с помощью оператора with. Делает current_app и g доступными.
request_context(environ) Создаёт контекст запроса из WSGI-окружения.
test_request_context(*args, **kwargs) Создаёт макетный контекст запроса для тестирования. Принимает path, method, data, json и другие параметры.
wsgi_app(environ, start_response) Основной метод WSGI-приложения. Можно обернуть middleware через app.wsgi_app = Middleware(app.wsgi_app)

Инструменты тестирования и разработки

Методы Описание
test_client(use_cookies=True, **kwargs) Создайте тестовый клиент для имитации запросов браузера. Возвращает экземпляр FlaskClient
test_cli_runner(**kwargs) Создайте тестовый CLI-раннер для тестирования пользовательских команд. Возвращает экземпляр FlaskCliRunner
run(host, port, debug, load_dotenv, **options) Запускает сервер разработки. В production используйте Gunicorn/Waitress.
make_shell_context() Формирует словарь контекста для flask shell. Запускает все shell_context_processor
log_exception(ctx, exc_info) Логирует исключения в логгер, передавая кортеж exc_info

Вспомогательные методы

Методы Описание
redirect(location, code=303) Создаёт объект ответа-перенаправления
async_to_sync(func) Преобразует асинхронные функции-корутины в синхронные функции
create_url_adapter(request) Создаёт URL-адаптер из запроса или конфигурации, используемый для построения URL.
inject_url_defaults(endpoint, values) Внедряет параметры по умолчанию в процесс построения URL.
handle_url_build_error(error, endpoint, values) Обрабатывает сбои построения url_for и может вернуть резервный URL.
make_config(instance_relative) Создайте экземпляр Config, который может быть переопределён подклассами для настройки конфигурации
make_aborter() Создайте экземпляр Aborter
trap_http_exception(e) Определяет, следует ли возбуждать HTTP-исключения как обычные исключения.
auto_find_instance_path() Автоматически находит путь к папке экземпляра.

Примеры кода

Пример

from flask import Flask

# Создайте приложение, укажите папки шаблонов и статических файлов
app = Flask(__name__,
           template_folder="templates",
           static_folder="static",
           instance_relative_config=True)

# Установите секретный ключ
app.secret_key = "your-secret-key"

# Зарегистрируйте маршруты
@app.route("/")
def index():
    return "<h1>Привет, EXAMPLE!</h1>"

# Зарегистрируйте хук before_request
@app.before_request
def check_auth():
    # Проверьте статус аутентификации пользователя здесь
    pass

# Зарегистрируйте хук after_request
@app.after_request
def add_header(response):
    # Добавить пользовательские заголовки к каждому ответу
    response.headers["X-Custom-Header"] = "EXAMPLE"
    return response

# Зарегистрировать обработчики ошибок
@app.errorhandler(404)
def not_found(error):
    return "<h1>Страница не найдена</h1>", 404

# Зарегистрировать пользовательскую команду CLI
@app.cli.command("hello")
def hello_command():
    """Вывести приветствие"""
    print("Привет от EXAMPLE Flask App!")

Связанная документация

Другие расширения