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() | Автоматически находит путь к папке экземпляра. |
Примеры кода
Пример
# Создайте приложение, укажите папки шаблонов и статических файлов
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!")