API

handle_user_exception(e)

Этот метод вызывается всякий раз, когда происходит исключение, которое должно быть обработано. Особо HTTPException, которое перенаправляется в метод handle_http_exception(). Эта функция либо вернёт значение ответа, либо повторно поднимет исключение с тем же стеком вызовов.

Журнал изменений

Изменено в версии 1.0: Ошибки ключей, поднятые из данных запроса, например form, в режиме отладки показывают неверный ключ, а не общее сообщение об ошибке запроса.

Добавлено в версии 0.7.

Параметры:: e (Исключение) –
Тип возвращаемого значения:: HTTPException | ft.ResponseReturnValue

property has_static_folder: bool: True если static_folder задан.

Журнал изменений

Добавлено в версии 0.5.

import_name: Имя пакета или модуля, к которому относится этот объект. Не изменяйте это после установки конструктором.

inject_url_defaults(endpoint, values)

Вставляет значения по умолчанию URL для заданного конечного пункта непосредственно в словарь values, переданный. Используется внутри и автоматически вызывается при построении URL.

Журнал изменений

Добавлено в версии 0.7.

Параметры:

endpoint (str) –
values (dict) –

Тип возвращаемого значения:

None

instance_path: Содержит путь к папке экземпляра.

Журнал изменений

Добавлено в версии 0.8.

iter_blueprints()

Итерируется по всем blueprints в порядке их регистрации.

Журнал изменений

Добавлено в версии 0.11.

Тип возвращаемого значения:: t.ValuesView[Blueprint]

property jinja_env: Environment

Среда Jinja, используемая для загрузки шаблонов.

Среда создаётся при первом обращении к этому свойству. Изменение jinja_options после этого не повлияет на результат.

jinja_environment: Псевдоним для Environment

property jinja_loader: FileSystemLoader | None: Загрузчик Jinja для шаблонов этого объекта. По умолчанию это класс jinja2.loaders.FileSystemLoader со template_folder, если он установлен.

Changelog

Новое в версии 0.5.

jinja_options: dict = {}: Параметры, передаваемые среде Jinja в create_jinja_environment(). Изменение этих параметров после создания среды (обращение к jinja_env) не повлияет на результат.

Changelog

Изменено в версии 1.1.0: Это dict вместо ImmutableDict, что упрощает настройку.

json: JSONProvider

Предоставляет доступ к методам JSON. Функции в flask.json вызывают методы этого поставщика, когда активен контекст приложения. Используется для обработки запросов и ответов JSON.

Экземпляр json_provider_class. Может быть настроен изменением этого атрибута в подклассе или последующей привязкой.

По умолчанию, DefaultJSONProvider, использует встроенную в Python библиотеку json. Другой поставщик может использовать другую библиотеку JSON.

Changelog

Новое в версии 2.2.

json_provider_class: Псевдоним для DefaultJSONProvider

log_exception(exc_info)

Регистрирует исключение. Вызывается handle_exception(), если отладка отключена, и непосредственно перед вызовом обработчика. По умолчанию, исключение регистрируется как ошибка в logger.

Changelog

Новое в версии 0.8.

Parameters:: exc_info (кортеж[тип, BaseException, стек_вызовов] | кортеж[None, None, None]) –
Возвращаемое значение:: None

property logger: Logger

Стандартный Python Logger для приложения, с тем же именем, что и name.

В режиме отладки уровень регистрации логгера level будет установлен на DEBUG.

Если нет настроенных обработчиков, будет добавлен обработчик по умолчанию. Более подробная информация в Ведение логов.

Changelog

Изменено в версии 1.1.0: Логгер принимает имя, совпадающее с name, а не жёстко заданное "flask.app".

Изменено в версии 1.0.0: Поведение упрощено. Логгер всегда имеет имя "flask.app". Уровень устанавливается только во время конфигурации, не проверяя app.debug каждый раз. Используется только один формат, а не разные в зависимости от app.debug. Обработчики не удаляются, и обработчик добавляется только если обработчиков ещё нет.

Новое в версии 0.3.

make_aborter()

Создаёт объект для присваивания aborter. Этот объект используется flask.abort() для повышения HTTP-ошибок, и может также вызываться напрямую.

По умолчанию, создаёт экземпляр aborter_class, который по умолчанию равен werkzeug.exceptions.Aborter.

Changelog

Новое в версии 2.2.

Возвращаемое значение:: Aborter

make_config(instance_relative=False)

Используется для создания атрибута config конструктором Flask. Параметр instance_relative передаётся из конструктора Flask (там он называется instance_relative_config) и указывает, должен ли config относиться к пути экземпляра или корневому пути приложения.

Changelog

Новое в версии 0.8.

Parameters:: instance_relative (bool) –
Возвращаемое значение:: Config

make_default_options_response()

Этот метод вызывается для создания ответа по умолчанию OPTIONS. Его можно изменить путём наследования для изменения поведения по умолчанию для ответов OPTIONS.

Changelog

Новое в версии 0.7.

Возвращаемое значение:: Response

make_response(rv)

Преобразуйте возвращаемое значение функции представления в экземпляр response_class.

Параметры:

rv (ft.ResponseReturnValue) –

возвращаемое значение функции представления. Функция представления должна вернуть ответ. Возвращение None, или завершение функции представления без возврата, запрещено. Допускаются следующие типы для view_rv:

str: Создается объект ответа с строкой, закодированной в UTF-8, как телом.
bytes: Создается объект ответа с байтами как телом.
dict: Словарь, который будет сериализован в JSON перед возвратом.
list: Список, который будет сериализован в JSON перед возвратом.
generator or iterator: Генератор, который возвращает str или bytes для потоковой передачи ответа.
tuple: Либо (body, status, headers), (body, status), или (body, headers), где body — любой из других разрешенных здесь типов, status — строка или целое число, а headers — словарь или список (key, value) кортежей. Если body — экземпляр response_class, status перезаписывает существующее значение, а headers расширяются.
response_class: Объект возвращается без изменений.
other Response class: Объект приводится к типу response_class.
callable(): Функция вызывается как WSGI-приложение. Результат используется для создания объекта ответа.

Тип возвращаемого значения:

Изменения

Изменено в версии 2.2: Генератор будет преобразован в ответ потоковой передачи. Список будет преобразован в ответ в формате JSON.

Изменено в версии 1.1: Словарь будет преобразован в ответ в формате JSON.

Изменено в версии 0.9: Ранее кортеж интерпретировался как аргументы для объекта ответа.

make_shell_context()

Возвращает контекст оболочки для интерактивной оболочки для этого приложения. Это выполняет все зарегистрированные обработчики контекста оболочки.

Изменения

Введено в версии 0.11.

Тип возвращаемого значения:: dict

property name: str: Имя приложения. Обычно это имя импорта с отличием, что оно угадывается из файла запуска, если имя импорта — main. Это имя используется в качестве отображаемого имени, когда Flask нуждается в имени приложения. Его можно установить и переопределить, чтобы изменить значение.

Изменения

Введено в версии 0.8.

open_instance_resource(resource, mode='rb')

Открывает ресурс из папки экземпляра приложения (instance_path). В противном случае работает как open_resource(). Ресурсы экземпляров также можно открыть для записи.

Параметры:

resource (str) – имя ресурса. Для доступа к ресурсам в подпапках используйте косые черты в качестве разделителей.
mode (str) – режим открытия файла ресурса, по умолчанию ‘rb’.

Тип возвращаемого значения:

open_resource(resource, mode='rb')

Открывает файл ресурса относительно root_path для чтения.

Например, если файл schema.sql находится рядом с файлом app.py, где определено приложение Flask, его можно открыть следующим образом:

with app.open_resource("schema.sql") as f:
    conn.executescript(f.read())

Параметры:

resource (str) – Путь к ресурсу относительно root_path.
mode (str) – Режим открытия файла. Поддерживается только чтение, допустимые значения — “r” (или “rt”) и “rb”.

Тип возвращаемого значения:

Примечание: это дубликат того же метода в классе Flask.

patch(rule, **options)

Сокращение для route() с methods=["PATCH"].

Изменения

Введено в версии 2.0.

Параметры:

rule (str) –
options (Any) –

Тип возвращаемого значения:

Callable[[T_route], T_route]

permanent_session_lifetime

timedelta, используемый для установки даты истечения срока действия постоянной сессии. По умолчанию 31 день, что делает постоянную сессию активной примерно в течение месяца.

Этот атрибут также можно настроить из конфигурации с ключом конфигурации PERMANENT_SESSION_LIFETIME. Значение по умолчанию timedelta(days=31)

post(rule, **options)

Сокращение для route() с methods=["POST"].

Изменения

Введено в версии 2.0.

Параметры:

rule (str) –
options (Any) –

Тип возвращаемого значения:

Callable[[T_route], T_route]

preprocess_request()

Вызывается перед обработкой запроса. Вызывает зарегистрированные в приложении и текущем шаблоне url_value_preprocessors функции. Затем вызывает зарегистрированные в приложении и шаблоне before_request_funcs функции.

Если любой обработчик before_request() возвращает значение, отличное от None, это значение обрабатывается так, как если бы это было значением возврата из представления, и дальнейшая обработка запроса прекращается.

Тип возвращаемого значения:: ft.ResponseReturnValue | None

process_response(response)

Может быть переопределён для изменения объекта ответа перед его отправкой на WSGI-сервер. По умолчанию, вызываются все функции, декорированные after_request().

Изменения

Изменено в версии 0.5: Начиная с Flask 0.5, функции, зарегистрированные для выполнения после запроса, вызываются в обратном порядке регистрации.

Параметры:: response (Response) – объект response_class.
Возвращаемое значение:: новый объект ответа или тот же, должен быть экземпляром response_class.
Тип возвращаемого значения:: Response

put(rule, **options)

Сокращение для route() с methods=["PUT"].

Изменения

Добавлен в версии 2.0.

Параметры:

rule (str) –
options (Any) –

Тип возвращаемого значения:

Callable[[T_route], T_route]

redirect(location, code=302)

Создаёт объект ответа перенаправления.

Вызывается методом flask.redirect() и может быть вызван напрямую.

Параметры:

location (str) – URL для перенаправления.
code (int) – Код состояния для перенаправления.

Тип возвращаемого значения:

BaseResponse

Изменения

Добавлен в версии 2.2: Перемещён из flask.redirect, который вызывает этот метод.

register_blueprint(blueprint, **options)

Регистрирует Blueprint в приложении. Значения по умолчанию, заданные в шаблоне, будут переопределены.

Вызывает метод register() шаблона после записи шаблона в blueprints приложения.

Параметры:

blueprint (Blueprint) – Шаблон для регистрации.
url_prefix – Маршруты шаблона будут иметь этот префикс.
subdomain – Маршруты шаблона будут соответствовать этому поддомену.
url_defaults – Маршруты шаблона будут использовать эти значения по умолчанию для аргументов представления.
options (t.Any) – Дополнительные ключевые аргументы передаются в BlueprintSetupState. К ним можно получить доступ в вызовах record().

Тип возвращаемого значения:

None

Изменения

Изменено в версии 2.0.1: Параметр name может быть использован для изменения имени шаблона (с предшествующим точкой), с которым он зарегистрирован. Это позволяет регистрировать один и тот же шаблон несколько раз с уникальными именами для url_for.

Добавлен в версии 0.7.

register_error_handler(code_or_exception, f)

Альтернативная функция для добавления обработчиков ошибок к декоратору errorhandler(), более удобная для использования без декораторов.

Изменения

Добавлен в версии 0.7.

Параметры:

code_or_exception (type[Exception] | int) –
f (ft.ErrorHandlerCallable) –

Тип возвращаемого значения:

None

request_class: псевдоним для Request

request_context(environ)

Создаёт RequestContext, представляющий WSGI-среду. Используйте блок with, чтобы добавить контекст, что сделает request направленным на этот запрос.

См. Контекст запроса.

Как правило, вы не должны вызывать это из своего кода. Контекст запроса автоматически добавляется методом wsgi_app() при обработке запроса. Используйте test_request_context() для создания среды и контекста вместо этого метода.

Параметры:: environ (dict) – WSGI-среда
Тип возвращаемого значения:: RequestContext

response_class: псевдоним для Response

root_path: Абсолютный путь к пакету в файловой системе. Используется для поиска ресурсов, содержащихся в пакете.

route(rule, **options)

Декорирует функцию представления для регистрации её с заданным правилом URL и параметрами. Вызывает add_url_rule(), в котором содержатся более подробные сведения об имплементации.

@app.route("/")
def index():
    return "Hello, World!"

См. Регистрации правил URL.

Имя конечной точки для маршрута по умолчанию соответствует имени функции представления, если параметр endpoint не передан.

Параметр methods по умолчанию равен ["GET"]. HEAD и OPTIONS добавляются автоматически.

Параметры:

rule (str) – Строка правила URL.
options (Any) – Дополнительные параметры, передаваемые объекту Rule.

Тип возвращаемого значения:

Callable[[T_route], T_route]

run(host=None, port=None, debug=None, load_dotenv=True, **options)

Запускает приложение на локальном сервере разработки.

Не используйте run() в рабочей среде. Он не предназначен для удовлетворения требований безопасности и производительности для сервера в рабочей среде. Вместо этого см. Развертывание в рабочей среде для рекомендаций по серверам WSGI.

Если флаг debug установлен, сервер будет автоматически перезагружаться при изменениях кода и показывать отладчик в случае возникновения исключения.

Если вы хотите запустить приложение в режиме отладки, но отключить выполнение кода в интерактивном отладчике, вы можете передать use_evalex=False в качестве параметра. Это сохранит экран отладчика, но отключит выполнение кода.

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

Обратите внимание

Flask будет подавлять любые ошибки сервера с помощью общей страницы ошибки, если он не находится в режиме отладки. Таким образом, для активации только интерактивного отладчика без перезагрузки кода вам необходимо вызвать run() с debug=True и use_reloader=False. Установка use_debugger в True без режима отладки не перехватит исключения, потому что их не будет.

Параметры:

host (str | None) – имя хоста для прослушивания. Установите это значение в '0.0.0.0', чтобы сервер был доступен и внешне. По умолчанию '127.0.0.1' или хост в переменной конфигурации SERVER_NAME (если она присутствует).
port (int | None) – порт веб-сервера. По умолчанию 5000 или порт, определенный в переменной конфигурации SERVER_NAME (если она присутствует).
debug (bool | None) – если указано, включить или отключить режим отладки. См. debug.
load_dotenv (bool) – Загрузить ближайшие файлы .env и .flaskenv для установки переменных окружения. Также изменит рабочую директорию на директорию, содержащую первый найденный файл.
options (Any) – параметры для передачи подлежащему серверу Werkzeug. См. werkzeug.serving.run_simple() для получения дополнительной информации.

Тип возвращаемого значения:

None

Журнал изменений

Изменено в версии 1.0: Если установлен, python-dotenv будет использоваться для загрузки переменных окружения из файлов .env и .flaskenv.

Переменная окружения FLASK_DEBUG переопределит debug.

Режим с потоками включен по умолчанию.

Изменено в версии 0.10: Порт по умолчанию теперь выбирается из переменной SERVER_NAME.

secret_key

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

Этот атрибут также можно настроить из конфигурации с помощью ключа конфигурации SECRET_KEY. По умолчанию None.

select_jinja_autoescape(filename)

Возвращает True, если автоматическая экранизация должна быть активна для данного имени шаблона. Если имя шаблона не указано, возвращает True.

Журнал изменений

Изменено в версии 2.2: Автоматическая экранизация теперь включена по умолчанию для файлов .svg.

Добавлено в версии 0.5.

Параметры:: filename (str) –
Тип возвращаемого значения:: bool

send_static_file(filename)

Функция представления, используемая для обработки файлов из static_folder. Маршрут автоматически регистрируется для этого представления по адресу static_url_path, если static_folder задан.

Обратите внимание, что это дублирование той же функции в классе Flask.

Журнал изменений

Добавлено в версии 0.5.

Параметры:: filename (str) –
Тип возвращаемого значения:: Response

session_interface: SessionInterface = <flask.sessions.SecureCookieSessionInterface object>: Интерфейс сеансов для использования. По умолчанию здесь используется экземпляр SecureCookieSessionInterface.

Журнал изменений

Добавлено в версии 0.8.

shell_context_processor(f)

Регистрирует функцию обработчика контекста оболочки.

Журнал изменений

Добавлено в версии 0.11.

Параметры:: f (T_shell_context_processor) –
Тип возвращаемого значения:: T_shell_context_processor

shell_context_processors: list[ft.ShellContextProcessorCallable]: Список функций обработчиков контекста оболочки, которые должны быть выполнены при создании контекста оболочки.

Журнал изменений

Добавлено в версии 0.11.

should_ignore_error(error)

Это вызывается для определения, следует ли игнорировать ошибку с точки зрения системы завершения работы. Если эта функция возвращает True, обработчики завершения не будут получать ошибку.

Изменения

Новая в версии 0.10.

Параметры:: error (BaseException | None) –
Тип возвращаемого значения:: bool

property static_folder: str | None: Абсолютный путь к папке со статическими файлами. None если папка со статическими файлами не задана.

property static_url_path: str | None

Префикс URL, по которому будет доступен статический маршрут.

Если он не был настроен во время инициализации, он определяется по static_folder.

teardown_appcontext(f)

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

with app.app_context():
    ...

Когда блок with завершается (или вызывается ctx.pop()), функции завершения вызываются непосредственно перед тем, как контекст приложения станет неактивным. Поскольку контекст запроса обычно также управляет контекстом приложения, он также будет вызываться при извлечении контекста запроса.

Когда функция завершения была вызвана из-за необработанной исключительной ситуации, ей передаётся объект ошибки. Если зарегистрирован обработчик ошибок errorhandler(), он обработает исключение, и функция завершения не получит его.

Функции завершения не должны вызывать исключения. Если они выполняют код, который может вызвать ошибку, они должны заключить этот код в блок try/except и регистрировать любые ошибки.

Значения возвращаемых функций завершения игнорируются.

Изменения

Новая в версии 0.9.

Параметры:: f (T_teardown) –
Тип возвращаемого значения:: T_teardown

teardown_appcontext_funcs: list[ft.TeardownCallable]: Список функций, которые вызываются при уничтожении контекста приложения. Поскольку контекст приложения также уничтожается при завершении запроса, здесь хранится код, который отключается от баз данных.

Изменения

Новая в версии 0.9.

teardown_request(f)

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

with app.test_request_context():
    ...

Когда блок with завершается (или вызывается ctx.pop()), функции завершения вызываются непосредственно перед тем, как контекст запроса станет неактивным.

Значения возвращаемых функций завершения игнорируются.

Это доступно как для объектов приложения, так и для объектов ссылок. При использовании с приложением это выполняется после каждого запроса. При использовании с ссылкой это выполняется после каждого запроса, обрабатываемого ссылкой. Для регистрации с помощью ссылки и выполнения после каждого запроса используйте Blueprint.teardown_app_request().

Параметры:: f (T_teardown) –
Тип возвращаемого значения:: T_teardown

teardown_request_funcs: dict[ft.AppOrBlueprintKey, list[ft.TeardownCallable]]

Структура данных функций, которые вызываются в конце каждого запроса, даже если возникает исключение, в формате {scope: [functions]}. Ключ scope — имя ссылки, для которой активны функции, или None для всех запросов.

Для регистрации функции используйте декоратор teardown_request().

Эта структура данных внутренняя. Её нельзя изменять напрямую, и её формат может быть изменён в любое время.

template_context_processors: dict[ft.AppOrBlueprintKey, list[ft.TemplateContextProcessorCallable]]

Структура данных функций, которые вызываются для передачи дополнительных значений контекста при отображении шаблонов, в формате {scope: [functions]}. Ключ scope — имя ссылки, для которой активны функции, или None для всех запросов.

Для регистрации функции используйте декоратор context_processor().

Эта структура данных внутренняя. Её нельзя изменять напрямую, и её формат может быть изменён в любое время.

template_filter(name=None)

Декоратор, используемый для регистрации пользовательских фильтров шаблонов. Вы можете указать имя для фильтра, в противном случае будет использовано имя функции. Пример:

@app.template_filter()
def reverse(s):
    return s[::-1]

Параметры:: name (str | None) – необязательное имя фильтра, иначе используется имя функции.
Тип возвращаемого значения:: Callable[[T_template_filter], T_template_filter]

template_folder: Путь к папке с шаблонами, относительно root_path, для добавления в загрузчик шаблонов. None если шаблоны не должны быть добавлены.

template_global(name=None)

Декоратор, используемый для регистрации пользовательской глобальной функции шаблона. Вы можете указать имя для глобальной функции, в противном случае будет использовано имя функции. Пример:

@app.template_global()
def double(n):
    return 2 * n

Изменения

Новая в версии 0.10.

Параметры:: name (str | None) – необязательное имя глобальной функции, иначе используется имя функции.
Тип возвращаемого значения:: Callable[[T_template_global], T_template_global]

template_test(name=None)

Декоратор, используемый для регистрации пользовательских тестов шаблонов. Вы можете указать имя для теста, в противном случае будет использовано имя функции. Пример:

@app.template_test()
def is_prime(n):
    if n == 2:
        return True
    for i in range(2, int(math.ceil(math.sqrt(n))) + 1):
        if n % i == 0:
            return False
    return True

Изменения

Новая в версии 0.10.

Параметры:: name (str | None) – необязательное имя теста, иначе используется имя функции.
Тип возвращаемого значения:: Callable[[T_template_test], T_template_test]

test_cli_runner(**kwargs)

Создать CLI-раннер для тестирования команд CLI. См. Запуск команд с помощью CLI-раннера.

Возвращает экземпляр test_cli_runner_class, по умолчанию FlaskCliRunner. Объект приложения Flask передается в качестве первого аргумента.

Changelog

Новое в версии 1.0.

Parameters:: kwargs (t.Any) –
Return type:: FlaskCliRunner

test_cli_runner_class: type[FlaskCliRunner] | None = None: Подкласс CliRunner, по умолчанию FlaskCliRunner, который используется методом test_cli_runner(). Его метод __init__ должен принимать объект приложения Flask в качестве первого аргумента.

Changelog

Новое в версии 1.0.

test_client(use_cookies=True, **kwargs)

Создает тестовый клиент для этого приложения. Сведения о тестировании единиц см. в Тестирование приложений Flask.

Обратите внимание, что если вы тестируете утверждения или исключения в вашем коде приложения, вам необходимо установить app.testing = True для того, чтобы исключения передавались тестовому клиенту. В противном случае исключение будет обработано приложением (не видно тестовому клиенту), и единственным признаком AssertionError или другого исключения будет ответ с кодом состояния 500 тестовому клиенту. См. атрибут testing. Например:

app.testing = True
client = app.test_client()

Тестовый клиент может использоваться в блоке with для отсрочки закрытия контекста до конца блока with. Это полезно, если вы хотите получить доступ к локальным переменным контекста для тестирования:

with app.test_client() as c:
    rv = c.get('/?vodka=42')
    assert request.args['vodka'] == '42'

Кроме того, вы можете передать необязательные ключевые аргументы, которые затем будут переданы конструктору приложения test_client_class. Например:

from flask.testing import FlaskClient

class CustomClient(FlaskClient):
    def __init__(self, *args, **kwargs):
        self._authentication = kwargs.pop("authentication")
        super(CustomClient,self).__init__( *args, **kwargs)

app.test_client_class = CustomClient
client = app.test_client(authentication='Basic ....')

См. FlaskClient для получения дополнительной информации.

Changelog

Изменено в версии 0.11: Добавлен **kwargs для поддержки передачи дополнительных ключевых аргументов в конструктор test_client_class.

Новое в версии 0.7: Добавлен параметр use_cookies а также возможность переопределения используемого клиента путем установки атрибута test_client_class.

Изменено в версии 0.4: добавлена поддержка использования блока with для клиента.

Parameters:

use_cookies (bool) –
kwargs (t.Any) –

Return type:

FlaskClient

test_client_class: type[FlaskClient] | None = None: Метод test_client() создает экземпляр этого класса тестового клиента. По умолчанию FlaskClient.

Changelog

Новое в версии 0.7.

test_request_context(*args, **kwargs)

Создать RequestContext для WSGI-окружения, созданного из заданных значений. Это в основном полезно во время тестирования, когда вы можете запустить функцию, использующую данные запроса, без отправки полного запроса.

См. Контекст запроса.

Используйте блок with для помещения контекста, что сделает request указывающим на запрос для созданного окружения.

with app.test_request_context(...):
    generate_report()

При использовании оболочки может быть проще вручную помещать и извлекать контекст, чтобы избежать отступов.

ctx = app.test_request_context(...)
ctx.push()
...
ctx.pop()

Принимает те же аргументы, что и EnvironBuilder Werkzeug, с некоторыми значениями по умолчанию из приложения. Большинство доступных аргументов см. в связанной документации Werkzeug. Flask-специфическое поведение приведено здесь.

Parameters:

path – Путь URL-запроса.
base_url – Базовый URL, где обслуживается приложение, который path является относительным. Если не задано, создается из PREFERRED_URL_SCHEME, subdomain, SERVER_NAME и APPLICATION_ROOT.
subdomain – Имя поддомена, добавляемое к SERVER_NAME.
url_scheme – Схема, используемая вместо PREFERRED_URL_SCHEME.
data – Тело запроса, в виде строки или словаря с ключами формы и значениями.
json – Если указано, оно сериализуется в JSON и передаётся как data. Также по умолчанию content_type является application/json.
args (Any) – другие позиционные аргументы, передаваемые в EnvironBuilder.
kwargs (Any) – другие ключевые аргументы, передаваемые в EnvironBuilder.

Return type:

RequestContext

testing

Флаг тестирования. Установите его в True для включения тестового режима расширений Flask (и, возможно, в будущем также самого Flask). Например, это может активировать тестовые помощники, которые имеют дополнительные затраты во время выполнения, которые не должны быть включены по умолчанию.

Если это включено и PROPAGATE_EXCEPTIONS не изменён от значения по умолчанию, то оно неявно включено.

Этот атрибут также может быть настроен из конфигурации с ключом конфигурации TESTING. По умолчанию False.

trap_http_exception(e)

Проверяет, нужно ли перехватывать HTTP-исключение. По умолчанию это вернёт False для всех исключений, кроме ошибки ключа при плохом запросе, если TRAP_BAD_REQUEST_ERRORS установлено в True. Также возвращает True если TRAP_HTTP_EXCEPTIONS установлено в True.

Это вызывается для всех HTTP-исключений, поднятых функцией представления. Если для любого исключения возвращается True, обработчик ошибок для этого исключения не вызывается, и оно отображается как обычное исключение в трассировке. Это полезно для отладки неявно поднятых HTTP-исключений.

Changelog

Изменено в версии 1.0: Ошибки плохих запросов по умолчанию не перехватываются в режиме отладки.

Новое в версии 0.8.

Параметры:: e (Исключение) –
Тип возвращаемого значения:: bool

update_template_context(context)

Обновляет контекст шаблона некоторыми часто используемыми переменными. Это вставляет request, session, config и g в контекст шаблона, а также всё, что обработчики контекста шаблона хотят вставить. Обратите внимание, что исходные значения в контексте не будут перезаписаны, если обработчик контекста решит вернуть значение с тем же ключом, начиная с Flask 0.6.

Параметры:: context (словарь) – контекст в виде словаря, который обновляется на месте для добавления дополнительных переменных.
Тип возвращаемого значения:: None

url_build_error_handlers: list[t.Callable[[Exception, str, dict[str, t.Any]], str]]: Список функций, вызываемых handle_url_build_error() при поднятии url_for() исключения BuildError. Каждая функция вызывается с error, endpoint и values. Если функция возвращает None или поднимает BuildError, она пропускается. В противном случае, её возвращаемое значение возвращается методом url_for.

Changelog

Новое в версии 0.9.

url_default_functions: dict[ft.AppOrBlueprintKey, list[ft.URLDefaultCallable]]

Структура данных функций для изменения ключевых аргументов при генерации URL, в формате {scope: [functions]}. Ключ scope — имя модуля, для которого активны функции, или None для всех запросов.

Для регистрации функции используйте декоратор url_defaults().

Эта структура данных внутренняя. Её не следует изменять напрямую, и её формат может измениться в любое время.

url_defaults(f)

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

Доступна как для объекта приложения, так и для объекта модуля. При использовании на приложении вызывается для каждого запроса. При использовании на модуле — для запросов, которые обрабатываются модулем. Для регистрации в модуле и воздействия на каждый запрос используйте Blueprint.app_url_defaults().

Параметры:: f (T_url_defaults) –
Тип возвращаемого значения:: T_url_defaults

url_for(endpoint, *, _anchor=None, _method=None, _scheme=None, _external=None, **values)

Генерирует URL для указанной конечной точки с указанными значениями.

Вызывается flask.url_for() и может быть вызван непосредственно.

Конечная точка — это имя правила URL, обычно добавляемое с помощью @app.route() и обычно совпадает с именем функции представления. Правило, определённое в Blueprint, будет добавлять имя модуля, разделенное ., к конечной точке.

В некоторых случаях, например, в сообщениях электронной почты, вам нужны URL, включающие схему и домен, как https://example.com/hello. Когда не в активном запросе, URL по умолчанию будут внешними, но это требует настройки SERVER_NAME, чтобы Flask знал, какой домен использовать. APPLICATION_ROOT и PREFERRED_URL_SCHEME также должны быть настроены по необходимости. Эта настройка используется только при отсутствии активного запроса.

Функции могут быть оформлены с помощью url_defaults() для изменения ключевых аргументов перед построением URL.

Если построение URL завершается ошибкой (например, неизвестная конечная точка или неверные значения), вызывается метод приложения handle_url_build_error(). Если он возвращает строку, эта строка и возвращается; в противном случае поднимается исключение BuildError.

Параметры:

endpoint (строка) – имя конечной точки, связанной с URL, который нужно сгенерировать. Если это начинается с ., будет использовано текущее имя модуля (если оно есть).
_anchor (строка | None) – если указано, добавить это как #anchor к URL.
_method (строка | None) – если указано, сгенерировать URL, связанный с этим методом для конечной точки.
_scheme (строка | None) – если указано, URL будет иметь эту схему, если это внешний URL.
_external (bool | None) – если указано, предпочесть внутренний URL (False) или потребовать внешний URL (True). Внешние URL включают схему и домен. При отсутствии активного запроса URL по умолчанию являются внешними.
values (любое) – значения для использования в переменных частях правила URL. Неизвестные ключи добавляются как аргументы строки запроса, как ?a=b&c=d.

Тип возвращаемого значения:

строка

Changelog

Новое в версии 2.2: Перемещено из flask.url_for, который вызывает этот метод.

url_map

Объект Map для этого экземпляра. Вы можете использовать его для изменения преобразователей маршрутизации после создания класса, но до подключения каких-либо маршрутов. Пример:

from werkzeug.routing import BaseConverter

class ListConverter(BaseConverter):
    def to_python(self, value):
        return value.split(',')
    def to_url(self, values):
        return ','.join(super(ListConverter, self).to_url(value)
                        for value in values)

app = Flask(__name__)
app.url_map.converters['list'] = ListConverter

url_map_class: псевдоним Map

url_rule_class: псевдоним Rule

END_OF_DOCUMENT_MARKER

url_value_preprocessor(f)

Регистрирует функцию предварительной обработки значений URL для всех функций представления в приложении. Эти функции будут вызваны перед функциями before_request().

Функция может изменять значения, полученные из сопоставленного URL, прежде чем они будут переданы представлению. Например, это можно использовать для извлечения общего кода языка и размещения его в g вместо передачи его каждому представлению.

Функции передаются имя конечной точки и словарь значений. Возвращаемое значение игнорируется.

Эта функция доступна как для объектов приложения, так и для объектов blueprints. При использовании с приложением она вызывается для каждого запроса. При использовании с blueprint она вызывается для запросов, обрабатываемых этим blueprint. Чтобы зарегистрировать функцию с blueprint и повлиять на каждый запрос, используйте Blueprint.app_url_value_preprocessor().

Параметры:: f (T_url_value_preprocessor) –
Тип возвращаемого значения:: T_url_value_preprocessor

url_value_preprocessors: dict[ft.AppOrBlueprintKey, list[ft.URLValuePreprocessorCallable]]

Структура данных функций для модификации ключевых аргументов, передаваемых функции представления, в формате {scope: [functions]}. Ключ scope указывает на имя blueprint, для которого эти функции активны, или None для всех запросов.

Для регистрации функции используйте декоратор url_value_preprocessor().

Эта структура данных является внутренней. Ее не следует изменять напрямую, и ее формат может измениться в любое время.

view_functions: dict[str, t.Callable]

Словарь, сопоставляющий имена конечных точек с функциями представления.

Для регистрации функции представления используйте декоратор route().

wsgi_app(environ, start_response)

Фактическое приложение WSGI. Это не реализовано в __call__() для того, чтобы middleware можно было применять без потери ссылки на объект приложения. Вместо этого:

app = MyMiddleware(app)

Лучше сделать так:

app.wsgi_app = MyMiddleware(app.wsgi_app)

Тогда у вас по-прежнему есть исходный объект приложения, и вы можете продолжить вызывать методы на нём.

Changelog

Изменено в версии 0.7: События завершения работы для контекстов запроса и приложения вызываются даже если произошла необработанная ошибка. Другие события могут не быть вызваны, в зависимости от того, когда произошла ошибка во время обработки запроса. См. Обработка ошибок и колбеки.

Параметры:

environ (dict) – Среда WSGI.
start_response (Callable) – Вызываемый объект, принимающий код состояния, список заголовков и контекст исключения для начала ответа.

Тип возвращаемого значения:

См. Регистрация правил маршрутизации URL.

Объекты Blueprint

class flask.Blueprint(name, import_name, static_folder=None, static_url_path=None, template_folder=None, url_prefix=None, subdomain=None, url_defaults=None, root_path=None, cli_group=<object object>)

Параметры:

name (str) –
import_name (str) –
static_folder (str | os.PathLike | None) –
static_url_path (str | None) –
template_folder (str | os.PathLike | None) –
url_prefix (str | None) –
subdomain (str | None) –
url_defaults (dict | None) –
root_path (str | None) –
cli_group (str | None) –

add_app_template_filter(f, name=None)

Регистрирует фильтр шаблонов, доступный в любом шаблоне, рендерящемся приложением. Работает как декоратор app_template_filter(). Эквивалентно Flask.add_template_filter().

Параметры:

name (str | None) – необязательное имя фильтра, в противном случае используется имя функции.
f (Callable[[...], Any]) –

Тип возвращаемого значения:

None

add_app_template_global(f, name=None)

Регистрирует глобальную переменную шаблона, доступную в любом шаблоне, рендерящемся приложением. Работает как декоратор app_template_global(). Эквивалентно Flask.add_template_global().

Изменения

Введено в версии 0.10.

Параметры:

name (str | None) – необязательное имя глобальной переменной, в противном случае используется имя функции.
f (Callable[[...], Any]) –

Тип возвращаемого значения:

None

add_app_template_test(f, name=None)

Регистрирует тест шаблона, доступный в любом шаблоне, рендерящемся приложением. Работает как декоратор app_template_test(). Эквивалентно Flask.add_template_test().

Изменения

Введено в версии 0.10.

Параметры:

name (str | None) – необязательное имя теста, в противном случае используется имя функции.
f (Callable[[...], bool]) –

Тип возвращаемого значения:

None

add_url_rule(rule, endpoint=None, view_func=None, provide_automatic_options=None, **options)

Регистрирует правило URL с Blueprint. Смотрите Flask.add_url_rule() для полной документации.

Правило URL префиксруется префиксом URL Blueprint. Имя конечной точки, используемое с url_for(), префиксруется именем Blueprint.

Параметры:

rule (str) –
endpoint (str | None) –
view_func (ft.RouteCallable | None) –
provide_automatic_options (bool | None) –
options (t.Any) –

Тип возвращаемого значения:

None

after_app_request(f)

Аналогично after_request(), но после каждого запроса, а не только тех, которые обрабатываются Blueprint. Эквивалентно Flask.after_request().

Параметры:: f (T_after_request) –
Тип возвращаемого значения:: T_after_request

after_request(f)

Регистрирует функцию, которая выполняется после каждого запроса для этого объекта.

Функция вызывается с объектом ответа и должна возвращать объект ответа. Это позволяет функциям изменять или заменять ответ перед отправкой.

Если функция вызывает исключение, любые оставшиеся after_request функции не будут вызваны. Поэтому это не следует использовать для действий, которые должны быть выполнены, например, для закрытия ресурсов. Используйте teardown_request() для этого.

Это доступно как для объектов приложения, так и для Blueprint. При использовании в приложении это выполняется после каждого запроса. При использовании в Blueprint это выполняется после каждого запроса, который обрабатывает Blueprint. Для регистрации в Blueprint и выполнения после каждого запроса используйте Blueprint.after_app_request().

Параметры:: f (T_after_request) –
Тип возвращаемого значения:: T_after_request

after_request_funcs: dict[ft.AppOrBlueprintKey, list[ft.AfterRequestCallable]]

Структура данных функций для вызова в конце каждого запроса, в формате {scope: [functions]}. Ключ scope — это имя Blueprint, для которого функции активны, или None для всех запросов.

Для регистрации функции используйте декоратор after_request().

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

END_OF_DOCUMENT_MARKER

app_context_processor(f)

Как context_processor(), но для шаблонов, рендерящихся каждой схемой представления, а не только схемой представления. Эквивалентно Flask.context_processor().

Параметры:: f (T_template_context_processor) –
Тип возвращаемого значения:: T_template_context_processor

app_errorhandler(code)

Как errorhandler(), но для каждого запроса, а не только для тех, которые обрабатываются схемой представления. Эквивалентно Flask.errorhandler().

Параметры:: code (type[Исключение] | int) –
Тип возвращаемого значения:: Callable[[T_error_handler], T_error_handler]

app_template_filter(name=None)

Регистрация фильтра шаблона, доступного в любом шаблоне, рендерящемся приложением. Эквивалентно Flask.template_filter().

Параметры:: name (str | None) – необязательное имя фильтра, в противном случае используется имя функции.
Тип возвращаемого значения:: Callable[[T_template_filter], T_template_filter]

app_template_global(name=None)

Регистрация глобальной переменной шаблона, доступной в любом шаблоне, рендерящемся приложением. Эквивалентно Flask.template_global().

Изменения

Введено в версии 0.10.

Параметры:: name (str | None) – необязательное имя глобальной переменной, в противном случае используется имя функции.
Тип возвращаемого значения:: Callable[[T_template_global], T_template_global]

app_template_test(name=None)

Регистрация теста шаблона, доступного в любом шаблоне, рендерящемся приложением. Эквивалентно Flask.template_test().

Изменения

Введено в версии 0.10.

Параметры:: name (str | None) – необязательное имя теста, в противном случае используется имя функции.
Тип возвращаемого значения:: Callable[[T_template_test], T_template_test]

app_url_defaults(f)

Как url_defaults(), но для каждого запроса, а не только для тех, которые обрабатываются схемой представления. Эквивалентно Flask.url_defaults().

Параметры:: f (T_url_defaults) –
Тип возвращаемого значения:: T_url_defaults

app_url_value_preprocessor(f)

Как url_value_preprocessor(), но для каждого запроса, а не только для тех, которые обрабатываются схемой представления. Эквивалентно Flask.url_value_preprocessor().

Параметры:: f (T_url_value_preprocessor) –
Тип возвращаемого значения:: T_url_value_preprocessor

before_app_request(f)

Как before_request(), но перед каждым запросом, а не только теми, которые обрабатываются схемой представления. Эквивалентно Flask.before_request().

Параметры:: f (T_before_request) –
Тип возвращаемого значения:: T_before_request

before_request(f)

Регистрация функции для выполнения перед каждым запросом.

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

@app.before_request
def load_user():
    if "user_id" in session:
        g.user = db.session.get(session["user_id"])

Функция будет вызываться без аргументов. Если она возвращает значение, отличное от None , значение обрабатывается так, как будто это возвращаемое значение из представления, и дальнейшая обработка запроса прекращается.

Это доступно как для объектов приложения, так и для объектов схемы представления. При использовании с приложением, это выполняется перед каждым запросом. При использовании со схемой представления, это выполняется перед каждым запросом, обрабатываемым схемой представления. Чтобы зарегистрировать функцию со схемой представления и выполнить её перед каждым запросом, используйте Blueprint.before_app_request().

Параметры:: f (T_before_request) –
Тип возвращаемого значения:: T_before_request

before_request_funcs: dict[ft.AppOrBlueprintKey, list[ft.BeforeRequestCallable]]

Структура данных функций для вызова в начале каждого запроса, в формате {scope: [functions]}. Ключ scope — имя схемы представления, для которой функции активны, или None для всех запросов.

Для регистрации функции используйте декоратор before_request().

Эта структура данных является внутренней. Её не следует изменять напрямую, и её формат может измениться в любое время.

cli: Группа команд Click для регистрации команд CLI для этого объекта. Команды доступны из команды flask после обнаружения приложения и регистрации схем представления.

context_processor(f)

Регистрирует функцию-обработчика контекста шаблона. Эти функции выполняются перед рендерингом шаблона. Ключи возвращаемого словаря добавляются в качестве переменных, доступных в шаблоне.

Это доступно как для объектов приложения, так и для объектов схемы представления. При использовании с приложением, это вызывается для каждого рендерящегося шаблона. При использовании со схемой представления, это вызывается для шаблонов, рендерящихся из представлений схемы представления. Чтобы зарегистрировать функцию со схемой представления и повлиять на каждый шаблон, используйте Blueprint.app_context_processor().

Параметры:: f (T_template_context_processor) –
Тип возвращаемого значения:: T_template_context_processor

delete(rule, **options)

Сокращение для route() со значением methods=["DELETE"].

Журнал изменений

Введено в версии 2.0.

Параметры:

rule (str) –
options (Any) –

Тип возвращаемого значения:

Callable[[T_route], T_route]

endpoint(endpoint)

Декорирование функции представления для регистрации ее для данного конечной точки. Используется, если правило добавлено без view_func с помощью add_url_rule().

app.add_url_rule("/ex", endpoint="example")

@app.endpoint("example")
def example():
    ...

Параметры:: endpoint (str) – Имя конечной точки для ассоциации с функцией представления.
Тип возвращаемого значения:: Callable[[F], F]

error_handler_spec: dict[ft.AppOrBlueprintKey, dict[int | None, dict[type[Exception], ft.ErrorHandlerCallable]]]

Структура данных зарегистрированных обработчиков ошибок в формате {scope: {code: {class: handler}}}. Ключ scope — это имя бланкета, для которого активны обработчики, или None для всех запросов. Ключ code — это код HTTP-статуса для HTTPException, или None для других исключений. Внутренний словарь сопоставляет классы исключений с функциями-обработчиками.

Для регистрации обработчика ошибок используйте декоратор errorhandler().

errorhandler(code_or_exception)

Регистрация функции для обработки ошибок по коду или классу исключения.

Декоратор, используемый для регистрации функции для заданного кода ошибки. Пример:

@app.errorhandler(404)
def page_not_found(error):
    return 'This page does not exist', 404

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

@app.errorhandler(DatabaseError)
def special_exception_handler(error):
    return 'Database connection failed', 500

Доступно как для объектов приложения, так и для объектов бланкета. При использовании на приложении, это может обрабатывать ошибки из каждого запроса. При использовании на бланкете, это может обрабатывать ошибки из запросов, которые обрабатывает бланкет. Для регистрации в бланкете и воздействия на каждый запрос используйте Blueprint.app_errorhandler().

Журнал изменений

Введено в версии 0.7: Используйте register_error_handler() вместо непосредственного изменения error_handler_spec для обработчиков ошибок на уровне приложения.

Введено в версии 0.7: Теперь также можно регистрировать пользовательские типы исключений, которые не обязательно должны быть подклассом класса HTTPException.

Параметры:: code_or_exception (type[Exception] | int) – код как целое число для обработчика или произвольное исключение
Тип возвращаемого значения:: Callable[[T_error_handler], T_error_handler]

get(rule, **options)

Сокращение для route() со значением methods=["GET"].

Журнал изменений

Введено в версии 2.0.

Параметры:

rule (str) –
options (Any) –

Тип возвращаемого значения:

Callable[[T_route], T_route]

get_send_file_max_age(filename)

Используется send_file() для определения значения кэширования max_age для данного пути к файлу, если оно не было передано.

По умолчанию, возвращает SEND_FILE_MAX_AGE_DEFAULT из конфигурации current_app. По умолчанию это None, что сообщает браузеру использовать условные запросы вместо кэша с временем, что обычно предпочтительнее.

Примечание: это дублирование того же метода в классе Flask.

Журнал изменений

Изменено в версии 2.0: Значение конфигурации по умолчанию — None вместо 12 часов.

Введено в версии 0.9.

Параметры:: filename (str | None) –
Тип возвращаемого значения:: int | None

property has_static_folder: bool: True если static_folder установлен.

Журнал изменений

Введено в версии 0.5.

import_name: Имя пакета или модуля, к которому принадлежит этот объект. Не изменяйте его после установки конструктором.

property jinja_loader: FileSystemLoader | None: Загрузчик Jinja для шаблонов этого объекта. По умолчанию это класс jinja2.loaders.FileSystemLoader к template_folder, если он установлен.

Журнал изменений

Введено в версии 0.5.

make_setup_state(app, options, first_registration=False)

Создает экземпляр объекта BlueprintSetupState(), который позже передается в функции обратного вызова регистрации. Подклассы могут переопределять это, чтобы вернуть подкласс состояния подготовки.

Параметры:

app (App) –
options (dict) –
first_registration (bool) –

Тип возвращаемого значения:

BlueprintSetupState

open_resource(resource, mode='rb')

Открыть файл ресурса относительно root_path для чтения.

Например, если файл schema.sql находится рядом с файлом app.py, где определён Flask приложение, его можно открыть так:

with app.open_resource("schema.sql") as f:
    conn.executescript(f.read())

Параметры:

resource (str) – Путь к ресурсу относительно root_path.
mode (str) – Режим открытия файла. Поддерживается только чтение, допустимые значения – “r” (или “rt”) и “rb”.

Тип возвращаемого значения:

Обратите внимание, что это дубликат того же метода в классе Flask.

patch(rule, **options)

Сокращение для route() с methods=["PATCH"].

Изменения

В версии 2.0.

Параметры:

rule (str) –
options (Any) –

Тип возвращаемого значения:

Callable[[T_route], T_route]

post(rule, **options)

Сокращение для route() с methods=["POST"].

Изменения

В версии 2.0.

Параметры:

rule (str) –
options (Any) –

Тип возвращаемого значения:

Callable[[T_route], T_route]

put(rule, **options)

Сокращение для route() с methods=["PUT"].

Изменения

В версии 2.0.

Параметры:

rule (str) –
options (Any) –

Тип возвращаемого значения:

Callable[[T_route], T_route]

record(func)

Регистрирует функцию, которая вызывается при регистрации бланкета в приложении. Эта функция вызывается с состоянием в качестве аргумента, возвращаемого методом make_setup_state().

Параметры:: func (Callable) –
Тип возвращаемого значения:: None

record_once(func)

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

Параметры:: func (Callable) –
Тип возвращаемого значения:: None

register(app, options)

Вызывается Flask.register_blueprint() для регистрации всех представлений и обратных вызовов, зарегистрированных в бланкете, с приложением. Создаёт BlueprintSetupState и вызывает каждый обратный вызов record() с ним.

Параметры:

app (App) – Приложение, с которым регистрируется этот бланкет.
options (dict) – Аргументы ключевых слов, переданные из register_blueprint().

Тип возвращаемого значения:

None

Изменения

Изменено в версии 2.3: Вложенные бланкеты теперь правильно применяют доменные имена.

Изменено в версии 2.1: Регистрация одного и того же бланкета с тем же именем несколько раз является ошибкой.

Изменено в версии 2.0.1: Вложенные бланкеты регистрируются с их точечным именем. Это позволяет использовать разные бланкеты с одинаковым именем, вложенные в разных местах.

Изменено в версии 2.0.1: Опция name может быть использована для изменения имени бланкета (до точки), с которым он регистрируется. Это позволяет регистрировать один и тот же бланкет несколько раз с уникальными именами для url_for.

register_blueprint(blueprint, **options)

Регистрация Blueprint в этом бланкете. Аргументы ключевых слов, переданные в этот метод, переопределят значения по умолчанию, установленные в бланкете.

Изменения

В версии 2.0.

Параметры:

blueprint (Blueprint) –
options (Any) –

Тип возвращаемого значения:

None

register_error_handler(code_or_exception, f)

Функция для добавления обработчика ошибок, альтернативная декоратору errorhandler(), более удобная для использования без декораторов.

Changelog

Новая в версии 0.7.

Parameters:

code_or_exception (тип[Исключение] | int) –
f (ft.ErrorHandlerCallable) –

Тип возвращаемого значения:

None

root_path: Абсолютный путь к пакету в файловой системе. Используется для поиска ресурсов, содержащихся в пакете.

route(rule, **options)

Декорирует функцию представления, регистрируя её с заданным правилом URL и параметрами. Вызывает add_url_rule(), в котором содержатся более подробные сведения об реализации.

@app.route("/")
def index():
    return "Hello, World!"

Имя конечной точки маршрута по умолчанию соответствует имени функции представления, если параметр endpoint не передан.

Параметр methods по умолчанию равен ["GET"]. HEAD и OPTIONS добавляются автоматически.

Parameters:

rule (строка) – Строка правила URL.
options (любой) – Дополнительные параметры, передаваемые объекту Rule.

Тип возвращаемого значения:

Вызываемый объект[[T_route], T_route]

send_static_file(filename)

Функция представления, используемая для обработки файлов из static_folder. Маршрут для этой функции представления автоматически регистрируется по адресу static_url_path, если static_folder задан.

Обратите внимание, что это дубликат метода в классе Flask.

Changelog

Новая в версии 0.5.

Parameters:: filename (строка) –
Тип возвращаемого значения:: Ответ

property static_folder: str | None: Абсолютный путь к папке со статическими файлами. None если папка со статическими файлами не задана.

property static_url_path: str | None

Префикс URL, по которому будет доступен статический маршрут.

Если он не был настроен при инициализации, он выводится из static_folder.

teardown_app_request(f)

Аналогично teardown_request(), но выполняется после каждого запроса, а не только тех, которые обрабатываются блейнпринтом. Эквивалентно Flask.teardown_request().

Parameters:: f (T_teardown) –
Тип возвращаемого значения:: T_teardown

teardown_request(f)

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

with app.test_request_context():
    ...

Когда блок with завершается (или вызывается ctx.pop()), функции завершения вызываются непосредственно перед тем, как контекст запроса становится неактивным.

Если функция завершения была вызвана из-за необработанного исключения, ей будет передан объект ошибки. Если зарегистрирован errorhandler(), он обработает исключение, и функция завершения его не получит.

Функции завершения не должны генерировать исключения. Если они выполняют код, который может завершиться ошибкой, они должны обернуть этот код в блок try/except и регистрировать любые ошибки.

Значения возвращаемых функциями завершения игнорируются.

Доступно как для объектов приложения, так и для объектов блейнпринта. При использовании с приложением выполняется после каждого запроса. При использовании с блейнпринтом выполняется после каждого запроса, обработанного блейнпринтом. Чтобы зарегистрировать с блейнпринтом и выполнить после каждого запроса, используйте Blueprint.teardown_app_request().

Parameters:: f (T_teardown) –
Тип возвращаемого значения:: T_teardown

teardown_request_funcs: dict[ft.AppOrBlueprintKey, list[ft.TeardownCallable]]

Структура данных функций, которые вызываются в конце каждого запроса, даже если возникает исключение, в формате {scope: [functions]}. Ключ scope указывает имя блейнпринта, для которого активны функции, или None для всех запросов.

Для регистрации функции используйте декоратор teardown_request().

template_context_processors: dict[ft.AppOrBlueprintKey, list[ft.TemplateContextProcessorCallable]]

Структура данных функций, вызываемых для передачи дополнительных значений контекста при рендеринге шаблонов, в формате {scope: [functions]}. Ключ scope указывает имя блейнпринта, для которого активны функции, или None для всех запросов.

Для регистрации функции используйте декоратор context_processor().

template_folder: Путь к папке с шаблонами, относительно root_path, для добавления в загрузчик шаблонов. None если шаблоны не должны быть добавлены.

url_default_functions: dict[ft.AppOrBlueprintKey, list[ft.URLDefaultCallable]]

Структура данных функций, вызываемых для изменения ключевых аргументов при генерации URL, в формате {scope: [functions]}. Ключ scope указывает имя блейнпринта, для которого активны функции, или None для всех запросов.

Для регистрации функции используйте декоратор url_defaults().

url_defaults(f)

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

Доступна как для объектов приложения, так и для объектов схемы. При использовании с приложением она вызывается для каждого запроса. При использовании со схемой она вызывается для запросов, обрабатываемых схемой. Чтобы зарегистрировать её со схемой и повлиять на каждый запрос, используйте Blueprint.app_url_defaults().

Параметры:: f (T_url_defaults) –
Тип возвращаемого значения:: T_url_defaults

url_value_preprocessor(f)

Регистрирует функцию предварительной обработки значений URL для всех функций представления в приложении. Эти функции вызываются перед функциями before_request().

Функция может изменять значения, полученные из сопоставленного URL, прежде чем они будут переданы в представление. Например, это можно использовать для извлечения общего кода языка и его размещения в g вместо передачи его в каждое представление.

Функции передаются имя конечной точки и словарь значений. Значение возврата игнорируется.

Параметры:: f (T_url_value_preprocessor) –
Тип возвращаемого значения:: T_url_value_preprocessor

url_value_preprocessors: dict[ft.AppOrBlueprintKey, list[ft.URLValuePreprocessorCallable]]

Структура данных функций, вызываемых для изменения ключевых аргументов, передаваемых функции представления, в формате {scope: [functions]}. Ключ scope — имя схемы, для которой активны функции, или None для всех запросов.

Чтобы зарегистрировать функцию, используйте декоратор url_value_preprocessor().

view_functions: dict[str, t.Callable]

Словарь, сопоставляющий имена конечных точек с функциями представлений.

Чтобы зарегистрировать функцию представления, используйте декоратор route().

Данные входящего запроса

class flask.Request(environ, populate_request=True, shallow=False)

Объект запроса, используемый по умолчанию в Flask. Запоминает сопоставленный конечный пункт и аргументы представления.

Он и есть то, что в конечном итоге становится request. Если вы хотите заменить используемый объект запроса, вы можете унаследовать его и установить request_class в свой подкласс.

Объект запроса является подклассом Request и предоставляет все атрибуты, определенные Werkzeug, плюс несколько специфичных для Flask.

Параметры:

environ (WSGIEnvironment) –
populate_request (bool) –
shallow (bool) –

property accept_charsets: CharsetAccept: Список наборов символов, поддерживаемых этим клиентом, как объект CharsetAccept.

property accept_encodings: Accept: Список кодировок, которые принимает этот клиент. Кодировки в HTTP - это кодировки сжатия, такие как gzip. Для наборов символов см. accept_charset.

property accept_languages: LanguageAccept: Список языков, которые принимает этот клиент, как объект LanguageAccept.

property accept_mimetypes: MIMEAccept: Список MIME-типов, которые поддерживает этот клиент, как объект MIMEAccept.

access_control_request_headers: Отправляется с предварительным запросом для указания заголовков, которые будут отправлены с запросом кросс-доменного доступа. Установите access_control_allow_headers в ответе, чтобы указать разрешенные заголовки.

access_control_request_method: Отправляется с предварительным запросом для указания метода, который будет использован для запроса кросс-доменного доступа. Установите access_control_allow_methods в ответе, чтобы указать разрешенные методы.

property access_route: list[str]: Если существует заголовок перенаправления, это список всех IP-адресов от IP-адреса клиента до последнего прокси-сервера.

classmethod application(f)

Декорирует функцию в качестве обработчика, принимающего запрос в качестве последнего аргумента. Это работает как декоратор responder(), но функция получает объект запроса в качестве последнего аргумента, и объект запроса автоматически закрывается:

@Request.application
def my_wsgi_app(request):
    return Response('Hello World!')

Начиная с Werkzeug 0.14, HTTP-исключения автоматически перехватываются и преобразуются в ответы вместо аварийного завершения.

Параметры:: f (t.Callable[[Request], WSGIApplication]) – вызываемый объект WSGI для декорации
Возвращает:: новый вызываемый объект WSGI
Тип возвращаемого значения:: WSGIApplication

property args: MultiDict[str, str]

Анализ параметров URL (часть URL после вопросительного знака).

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

Журнал изменений

Изменено в версии 2.3: Некорректные байты остаются в кодировке процентов.

property authorization: Authorization | None: Заголовок Authorization, разобранный в объект Authorization. None если заголовок отсутствует.

Журнал изменений

Изменено в версии 2.3: Authorization больше не является dict. Атрибут token был добавлен для схем авторизации, которые используют токен вместо параметров.

property base_url: str: Как url, но без строки запроса.

property blueprint: str | None

Зарегистрированное имя текущего модуля.

Будет None если конечный пункт не принадлежит модулю, или если сопоставление URL не выполнено или еще не выполнено.

Это не обязательно совпадает с именем, с которым был создан модуль. Он может быть вложен или зарегистрирован с другим именем.

property blueprints: list[str]

Зарегистрированные имена текущего модуля и его родительских модулей.

Будет пустым списком, если нет текущего модуля или сопоставление URL не выполнено.

Журнал изменений

Добавлено в версии 2.0.1.

property cache_control: RequestCacheControl: Объект RequestCacheControl для заголовков управления кешем входящего запроса.

close()

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

Журнал изменений

Добавлено в версии 0.9.

Тип возвращаемого значения:: None

content_encoding: Поле заголовка сущности Content-Encoding используется в качестве модификатора типа медиа. При его наличии значение указывает, какие дополнительные кодировки содержимого были применены к телу сущности, и, следовательно, какие механизмы декодирования необходимо применить для получения типа медиа, на который ссылается поле Content-Type.

Журнал изменений

Добавлено в версии 0.9.

property content_length: int | None: Поле заголовка сущности Content-Length указывает размер тела сущности в байтах или, в случае метода HEAD, размер тела сущности, который был бы отправлен, если бы запрос был GET.

content_md5: Поле заголовка сущности Content-MD5, как определено в RFC 1864, является MD5-хешем тела сущности для обеспечения проверки целостности сообщения (MIC) тела сущности. (Примечание: MIC полезен для обнаружения случайных изменений тела сущности во время передачи, но не является доказательством от злонамеренных атак.)

Журнал изменений

Добавлено в версии 0.9.

content_type: Поле заголовка сущности Content-Type указывает тип медиа тела сущности, отправленного получателю или, в случае метода HEAD, тип медиа, который был бы отправлен, если бы запрос был GET.

property cookies: ImmutableMultiDict[str, str]: Словарь со всем содержимым cookie, переданных с запросом.

property data: bytes

Необработанные данные, считанные из stream. Будет пустым, если запрос представляет данные формы.

Чтобы получить необработанные данные, даже если они представляют данные формы, используйте get_data().

END_OF_DOCUMENT_MARKER

date: Поле заголовка Date представляет дату и время, в которое было отправлено сообщение, имея те же семантики, что и orig-date в RFC 822.

Изменения

Изменено в версии 2.0: Объект datetime учитывает часовой пояс.

dict_storage_class: Псевдоним ImmutableMultiDict

property endpoint: str | None

Точка входа, которая соответствовала запрошенному URL.

Будет None если соответствие не найдено или ещё не выполнено.

В сочетании с view_args можно восстановить тот же URL или изменённый URL.

environ: WSGIEnvironment: WSGI-среда, содержащая HTTP-заголовки и информацию от WSGI-сервера.

property files: ImmutableMultiDict[str, FileStorage]

MultiDict объект, содержащий все загруженные файлы. Каждый ключ в files — это имя из <input type="file" name="">. Каждое значение в files — это объект Werkzeug FileStorage.

По сути, он ведет себя как стандартный объект файла из Python, с той разницей, что у него также есть функция save(), которая может сохранить файл на файловой системе.

Обратите внимание, что files будет содержать данные только если метод запроса был POST, PUT или PATCH и <form> который был отправлен в запросе, содержал enctype="multipart/form-data". В противном случае он будет пустым.

См. документацию MultiDict / FileStorage для получения более подробной информации о используемой структуре данных.

property form: ImmutableMultiDict[str, str]

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

Обратите внимание, что загрузки файлов не попадут сюда, а вместо этого в атрибут files.

Изменения

Изменено в версии 0.9: До Werkzeug 0.9 это содержало только данные формы для запросов POST и PUT.

form_data_parser_class: Псевдоним FormDataParser

classmethod from_values(*args, **kwargs)

Создает новый объект запроса на основе предоставленных значений. Если environ указан, пропущенные значения заполняются из него. Этот метод полезен для небольших скриптов, когда нужно смоделировать запрос из URL. Не используйте этот метод для тестирования, есть полнофункциональный объект клиента (Client), который позволяет создавать multipart-запросы, поддерживает куки и т. д.

Принимает те же параметры, что и EnvironBuilder.

Изменения

Изменено в версии 0.5: Этот метод теперь принимает те же аргументы, что и EnvironBuilder. Из-за этого параметр environ теперь называется environ_overrides.

Возвращает:

объект запроса

Параметры:

args (Any) –
kwargs (Any) –

Тип возвращаемого значения:

Request

property full_path: str: Запрошенный путь, включая строку запроса.

get_data(cache=True, as_text=False, parse_form_data=False)

Считывает буферизованные входящие данные от клиента в один байтовый объект. По умолчанию это кэшируется, но это поведение можно изменить, установив cache в False.

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

Обратите внимание, что если данные формы уже обработаны, этот метод ничего не вернёт, так как обработка данных формы не кэширует данные, как этот метод. Чтобы неявно вызвать функцию обработки данных формы, установите parse_form_data в True. В этом случае возвращаемое значение этого метода будет пустой строкой, если обработчик формы обрабатывает данные. Обычно это не требуется, так как если все данные кэшируются (что является по умолчанию), обработчик формы будет использовать кэшированные данные для обработки данных формы. В любом случае, перед вызовом этого метода крайне важно проверять длину содержимого, чтобы избежать перегрузки памяти сервера.

Если as_text установлено в True возвращаемое значение будет декодированной строкой.

Изменения

Новое в версии 0.9.

Параметры:

cache (bool) –
as_text (bool) –
parse_form_data (bool) –

Тип возвращаемого значения:

bytes | str

END_OF_DOCUMENT_MARKER

get_json(force=False, silent=False, cache=True)

Обработать data как JSON.

Если тип MIME не указывает JSON (application/json, см. is_json), или при парсинге произошла ошибка, вызывается on_json_loading_failed(), и возвращается его значение. По умолчанию это вызывает ошибку 415 Unsupported Media Type.

Parameters:

force (bool) – Игнорировать тип MIME и всегда пытаться обработать JSON.
silent (bool) – Скрыть ошибки типа MIME и парсинга, и вернуть None вместо этого.
cache (bool) – Сохранить обработанный JSON для последующего использования.

Return type:

Any | None

Changelog

Изменено в версии 2.3: Возвращать ошибку 415 вместо 400.

Изменено в версии 2.1: Возвращать ошибку 400, если тип контента неверный.

headers: Заголовки, полученные с запросом.

property host: str: Имя хоста, к которому был отправлен запрос, включая порт, если он нестандартный. Проверяется с помощью trusted_hosts.

property host_url: str: Схема и имя хоста URL запроса.

property if_match: ETags

Объект, содержащий все теги в заголовке If-Match.

Return type:: ETags

property if_modified_since: datetime | None: Обработанный заголовок If-Modified-Since как объект datetime.

Changelog

Изменено в версии 2.0: Объект datetime с учетом часового пояса.

property if_none_match: ETags

Объект, содержащий все теги в заголовке If-None-Match.

Return type:: ETags

property if_range: IfRange: Обработанный заголовок If-Range.

Changelog

Изменено в версии 2.0: IfRange.date с учетом часового пояса.

Добавлен в версии 0.7.

property if_unmodified_since: datetime | None: Обработанный заголовок If-Unmodified-Since как объект datetime.

Changelog

Изменено в версии 2.0: Объект datetime с учетом часового пояса.

input_stream

Необработанный входной поток WSGI без проверок безопасности.

Использование опасно. Не защищает от бесконечных потоков или чтения за пределами content_length или max_content_length.

Используйте stream вместо этого.

property is_json: bool: Проверка, указывает ли тип MIME данные JSON, либо application/json, либо application/*+json.

is_multiprocess: Булево значение, True если приложение обслуживается сервером WSGI, который запускает несколько процессов.

is_multithread: Булево значение, True если приложение обслуживается многопоточным сервером WSGI.

is_run_once: Булево значение, True если приложение будет выполнено только один раз за время работы процесса. Например, это характерно для CGI, но не гарантируется, что выполнение произойдёт только один раз.

property is_secure: bool: True если запрос был отправлен с безопасным протоколом (HTTPS или WSS).

property json: Any | None

Обработанные данные JSON, если mimetype указывает на JSON (application/json, см. is_json).

Вызывает get_json() с параметрами по умолчанию.

Если тип контента запроса не application/json, будет вызвана ошибка 415 Unsupported Media Type.

Changelog

Изменено в версии 2.3: Возвращать ошибку 415 вместо 400.

Изменено в версии 2.1: Возвращать ошибку 400, если тип контента неверный.

list_storage_class: Псевдоним ImmutableList

make_form_data_parser()

Создаёт парсер данных формы. Создаёт экземпляр form_data_parser_class с некоторыми параметрами.

Changelog

Добавлен в версии 0.8.

Return type:: FormDataParser

property max_content_length: int | None: Только для чтения, представление значения конфигурации MAX_CONTENT_LENGTH.

max_form_memory_size: int | None = None: Максимальный размер поля формы. Передаётся функции парсинга данных формы (parse_form_data()). При установке и обращении к атрибутам form или files и размере данных в памяти для данных POST, превышающем заданное значение, возникает исключение RequestEntityTooLarge.

Changelog

Добавлен в версии 0.5.

max_form_parts = 1000: Максимальное количество частей multipart для парсинга, передаваемое в form_data_parser_class. Парсинг данных формы с количеством частей, превышающим это значение, вызовет RequestEntityTooLarge.

Changelog

Добавлен в версии 2.2.3.

max_forwards: Поле заголовка запроса Max-Forwards предоставляет механизм для ограничение количества прокси-серверов или шлюзов, которые могут перенаправлять запрос к следующему входящему серверу с использованием методов TRACE и OPTIONS.

method: Метод, с помощью которого был отправлен запрос, например, GET.

property mimetype: str: Аналогично content_type, но без параметров (например, без кодировки, типа и т. д.) и всегда в нижнем регистре. Например, если тип содержимого равен text/HTML; charset=utf-8, то mimetype будет 'text/html'.

property mimetype_params: dict[str, str]: Параметры mimetype в виде словаря. Например, если тип содержимого равен text/html; charset=utf-8, то параметры будут {'charset': 'utf-8'}.

on_json_loading_failed(e)

Вызывается, если get_json() терпит неудачу и не отключается.

Если этот метод возвращает значение, оно используется в качестве значения возврата для get_json(). По умолчанию реализация вызывает BadRequest.

Parameters:: e (ValueError | None) – Если произошла ошибка при парсинге, это исключение. Оно будет равно None , если тип содержимого не был application/json.
Return type:: Any

Changelog

Изменено в версии 2.3: Вызывать ошибку 415 вместо 400.

origin: Хост, с которого исходит запрос. Установите access_control_allow_origin в ответе, чтобы указать разрешенные источники.

parameter_storage_class: Псевдоним для ImmutableMultiDict

path: Часть пути URL после root_path. Это путь, используемый для маршрутизации внутри приложения.

property pragma: HeaderSet: Поле заголовка Pragma используется для включения директив, специфичных для реализации, которые могут применяться к любому получателю вдоль цепочки запрос/ответ. Все директивы pragma определяют необязательное поведение с точки зрения протокола; однако некоторые системы МОГУТ потребовать, чтобы это поведение соответствовало директивам.

query_string: Часть URL после символа “?”. Это значение в сыром виде; используйте args для распарсенных значений.

property range: Range | None

Распарсенное поле заголовка Range.

Changelog

Добавлена в версии 0.7.

Return type:: Range

referrer: Поле заголовка запроса Referer позволяет клиенту указать для сервера адрес (URI) ресурса, из которого был получен запрашиваемый ресурс (referrer), хотя имя поля заголовка написано с ошибкой.

remote_addr: Адрес клиента, отправившего запрос.

remote_user: Если сервер поддерживает аутентификацию пользователя и сценарий защищен, это атрибут содержит имя пользователя, под которым пользователь прошел аутентификацию.

root_path: Префикс, под которым установлено приложение, без конечной косой черты. path идёт после этого.

property root_url: str: Схема, хост и корневой путь URL запроса. Это корень, с которого осуществляется доступ к приложению.

routing_exception: Exception | None = None: Если сопоставление URL завершилось неудачей, это исключение, которое будет/было вызвано в рамках обработки запроса. Обычно это исключение NotFound или аналогичное ему.

scheme: Схема URL используемого протокола, например, https или wss.

property script_root: str: Псевдоним для self.root_path. environ["SCRIPT_ROOT"] без конечной косой черты.

server: Адрес сервера. (host, port), (path, None) для сокетов Unix или None если неизвестен.

shallow: bool: Устанавливается при создании объекта запроса. Если True, чтение из тела запроса вызовет RuntimeException. Полезно для предотвращения изменения потока из промежуточного слоя.

property stream: IO[bytes]

Поток ввода WSGI с проверками безопасности. Этот поток может быть обработан только один раз.

Используйте get_data() для получения всего данных в байтах или тексте. Атрибут data будет содержать все байты только если они не представляют данные формы. Атрибут form в этом случае будет содержать распарсенные данные формы.

В отличие от input_stream, этот поток защищает от бесконечных потоков или чтения за пределами content_length или max_content_length.

Если max_content_length установлен, это может быть применено к потокам, если wsgi.input_terminated установлен. В противном случае возвращается пустой поток.

Если предел достигнут до того, как исчерпан основной поток (например, файл слишком большой или бесконечный поток), остальное содержимое потока безопасно не прочитать. В зависимости от того, как сервер обрабатывает это, клиенты могут показать ошибку «прерывание соединения» вместо отображения ответа 413.

Changelog

Изменено в версии 2.3: Проверять max_content_length заранее и во время чтения.

Изменено в версии 0.9: Поток всегда установлен (но может быть использован), даже если сначала был получен доступ к парсингу формы.

trusted_hosts: list[str] | None = None

Допустимые имена хостов при обработке запросов. По умолчанию все хосты доверяются, что означает, что любой хост, указанный клиентом, будет принят.

Поскольку заголовки Host и X-Forwarded-Host могут быть установлены любым значением злонамеренным клиентом, рекомендуется либо установить это свойство, либо реализовать аналогичную проверку в прокси (если приложение выполняется за ним).

Changelog

Добавлена в версии 0.9.

property url: str: Полный URL запроса со схемой, хостом, корневым путём, путём и строкой запроса.

END_OF_DOCUMENT_MARKER

property url_root: str: Псевдоним для root_url. URL со схемой, хостом и корневым путём. Например, https://example.com/app/.

url_rule: Rule | None = None: Внутреннее правило URL, которое совпало с запросом. Это может быть полезно для проверки разрешённых методов для URL из обработчика before/after (request.url_rule.methods) и т.п. Хотя, если метод запроса был недопустимым для правила URL, список допустимых методов доступен в routing_exception.valid_methods вместо этого (атрибут исключения Werkzeug MethodNotAllowed), поскольку запрос никогда не связывался внутренне.

Changelog

Добавлено в версии 0.6.

property user_agent: UserAgent: Пользовательский агент. Используйте user_agent.string для получения значения заголовка. Установите user_agent_class в подкласс UserAgent для обеспечения разбора других свойств или других расширенных данных.

Changelog

Изменено в версии 2.1: Встроенный анализатор был удалён. Установите user_agent_class в подкласс UserAgent для разбора данных из строки.

user_agent_class: Псевдоним для UserAgent

property values: CombinedMultiDict[str, str]

werkzeug.datastructures.CombinedMultiDict, объединяющая args и form.

Для запросов GET присутствуют только args, а не form.

Changelog

Изменено в версии 2.0: Для запросов GET присутствуют только args, а не form.

view_args: dict[str, t.Any] | None = None: Словарь аргументов представления, соответствующих запросу. Если при сопоставлении произошла ошибка, это будет None.

property want_form_data_parsed: bool: True , если метод запроса несёт содержимое. По умолчанию это True, если отправлен Content-Type.

Changelog

Добавлено в версии 0.8.

flask.request

Для доступа к данным входящего запроса можно использовать глобальный объект request. Flask анализирует данные входящего запроса и предоставляет доступ к ним через этот глобальный объект. Внутренне Flask гарантирует, что вы всегда получаете правильные данные для активной нити, если вы работаете в многопоточной среде.

Это прокси. Дополнительную информацию см. в Примечания по прокси.

Объект запроса является экземпляром Request.

Объекты ответов

class flask.Response(response=None, status=None, headers=None, mimetype=None, content_type=None, direct_passthrough=False)

Объект ответа по умолчанию в Flask. Работает как объект ответа из Werkzeug, но по умолчанию имеет MIME-тип HTML. Часто вам не нужно создавать этот объект самостоятельно, потому что make_response() позаботится об этом за вас.

Если вы хотите заменить используемый объект ответа, вы можете создать подкласс и установить response_class на ваш подкласс.

Журнал изменений

Изменено в версии 1.0: Поддержка JSON добавлена в ответ, как и в запросе. Это полезно при тестировании для получения данных ответа тестового клиента в формате JSON.

Изменено в версии 1.0: Добавлен max_cookie_size.

Параметры:

response (Iterable[str] | Iterable[bytes]) –
status (int | str | HTTPStatus | None) –
headers (Headers) –
mimetype (str | None) –
content_type (str | None) –
direct_passthrough (bool) –

accept_ranges

Заголовок Accept-Ranges. Хотя имя предполагает поддержку нескольких значений, должно быть только одно строковое значение.

Общие значения 'bytes' и 'none'.

Журнал изменений

Добавлена в версии 0.7.

property access_control_allow_credentials: bool: Разрешение браузеру обмениваться учетными данными с кодом JavaScript. В рамках запроса предварительной проверки указывается, можно ли использовать учетные данные при кросс-доменном запросе.

access_control_allow_headers: Заголовки, которые можно отправлять при кросс-доменном запросе.

access_control_allow_methods: Методы, которые можно использовать при кросс-доменном запросе.

access_control_allow_origin: Происхождение или «*» для любого происхождения, которое может выполнять кросс-доменные запросы.

access_control_expose_headers: Заголовки, которые может обмениваться браузер с кодом JavaScript.

access_control_max_age: Максимальное время в секундах, в течение которого настройки контроля доступа могут быть кэшированы.

add_etag(overwrite=False, weak=False)

Добавить etag для текущего ответа, если его еще нет.

Журнал изменений

Изменено в версии 2.0: Для генерации значения используется SHA-1. MD5 может быть недоступен в некоторых средах.

Параметры:

overwrite (bool) –
weak (bool) –

Тип возвращаемого значения:

None

age

Поле заголовка ответа Age передает оценку отправителем времени, прошедшего с момента создания (или повторной проверки) ответа на исходном сервере.

Значения возраста — это целые неотрицательные десятичные числа, представляющие время в секундах.

property allow: HeaderSet: Поле заголовка сущности Allow перечисляет набор методов, поддерживаемых ресурсом, идентифицируемым URI запроса. Цель этого поля — строго информировать получателя о допустимых методах, связанных с ресурсом. Заголовок Allow ОБЯЗАТЕЛЬНО должен быть присутствовать в ответе 405 (Метод не поддерживается).

autocorrect_location_header = False: Если заголовок перенаправления Location является относительным URL, сделайте его абсолютным URL, включая схему и домен.

Журнал изменений

Изменено в версии 2.1: По умолчанию отключено, поэтому ответы будут отправлять относительные перенаправления.

Добавлена в версии 0.8.

automatically_set_content_length = True: Должен ли этот объект ответа автоматически устанавливать заголовок content-length при возможности? По умолчанию значение — True.

Журнал изменений

Добавлена в версии 0.8.

property cache_control: ResponseCacheControl: Поле общего заголовка Cache-Control используется для указания директив, которые должны соблюдаться всеми механизмами кэширования вдоль цепочки запрос/ответ.

calculate_content_length()

Возвращает длину содержимого, если она доступна, или None в противном случае.

Тип возвращаемого значения:: int | None

call_on_close(func)

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

Журнал изменений

Добавлена в версии 0.6.

Параметры:: func (Callable[[], Any]) –
Тип возвращаемого значения:: Callable[[], Any]

close()

Закрыть обернутый ответ, если возможно. Вы также можете использовать объект в операторе with, который автоматически закроет его.

Журнал изменений

Добавлена в версии 0.9: Теперь можно использовать в операторе with.

Тип возвращаемого значения:: None

content_encoding: Поле заголовка сущности Content-Encoding используется в качестве модификатора типа содержимого. При его наличии значение указывает, какие дополнительные кодировки содержимого были применены к телу сущности, и какие механизмы декодирования необходимо применить для получения типа содержимого, указанного в поле Content-Type.

property content_language: HeaderSet: Поле заголовка сущности Content-Language описывает естественный(е) язык(и) целевой аудитории для вложенной сущности. Обратите внимание, что это может не совпадать со всеми языками, используемыми в теле сущности.

END_OF_DOCUMENT_MARKER

content_length: Поле заголовка сущности Content-Length указывает размер тела сущности, в десятичном количестве октетов, отправляемых получателю или, в случае метода HEAD, размер тела сущности, который был бы отправлен, если бы запрос был GET.

content_location: Поле заголовка сущности Content-Location МОЖЕТ использоваться для предоставления местоположения ресурса для сущности, заключённой в сообщении, когда эта сущность доступна из местоположения, отличного от URI запрошенного ресурса.

content_md5: Поле заголовка сущности Content-MD5, как определено в RFC 1864, представляет собой хэш MD5 тела сущности для обеспечения проверки целостности сообщения (MIC) тела сущности от начала до конца. (Примечание: MIC хорош для обнаружения случайного изменения тела сущности во время передачи, но не является доказательством защиты от злонамеренных атак.)

property content_range: ContentRange: Заголовок Content-Range в виде объекта ContentRange. Доступен даже если заголовок не задан.

Changelog

Новое в версии 0.7.

property content_security_policy: ContentSecurityPolicy

Заголовок Content-Security-Policy в виде объекта ContentSecurityPolicy. Доступен даже если заголовок не задан.

Заголовок Content-Security-Policy добавляет дополнительный уровень безопасности для выявления и смягчения определённых типов атак.

property content_security_policy_report_only: ContentSecurityPolicy

Заголовок Content-Security-policy-report-only в виде объекта ContentSecurityPolicy. Доступен даже если заголовок не задан.

Заголовок Content-Security-Policy-Report-Only добавляет политику CSP, которая не выполняется, но сообщает об этом, тем самым помогая выявить определённые типы атак.

content_type: Поле заголовка сущности Content-Type указывает тип носителя тела сущности, отправляемого получателю или, в случае метода HEAD, тип носителя, который был бы отправлен, если бы запрос был GET.

cross_origin_embedder_policy: Запрещает документу загружать любые ресурсы из другого источника, которые не предоставляют документу явно разрешение. Значения должны быть членами перечисления werkzeug.http.COEP.

cross_origin_opener_policy: Позволяет контролировать совместное использование группы контекста просмотра с документами из другого источника. Значения должны быть членами перечисления werkzeug.http.COOP.

property data: bytes | str: Дескриптор, который вызывает get_data() и set_data().

date: Поле общего заголовка Date представляет дату и время, в которые было отправлено сообщение, имея те же семантики, что и orig-date в RFC 822.

Changelog

Изменено в версии 2.0: Объект datetime имеет часовой пояс.

default_mimetype: str | None = 'text/html': по умолчанию тип MIME, если он не предоставлен.

default_status = 200: значение по умолчанию статуса, если оно не предоставлено.

delete_cookie(key, path='/', domain=None, secure=False, httponly=False, samesite=None)

Удаляет куки. Безмолвно завершает работу, если ключ не существует.

Параметры:

key (строка) – ключ (имя) куки для удаления.
path (строка | None) – если куки, которая должна быть удалена, была ограничена путем, путь должен быть определён здесь.
domain (строка | None) – если куки, которая должна быть удалена, была ограничена доменом, этот домен должен быть определён здесь.
secure (булево) – Если True, куки будет доступна только через HTTPS.
httponly (булево) – Запрещает доступ JavaScript к куки.
samesite (строка | None) – Ограничивает область действия куки, чтобы она прикреплялась только к запросам, которые являются «одного сайта».

Тип возвращаемого значения:

None

direct_passthrough: Передаёт тело ответа непосредственно как WSGI итерируемый объект. Это может быть использовано, когда тело является бинарным файлом или другим итератором байтов, чтобы пропустить некоторые ненужные проверки. Используйте send_file() вместо ручного задания этого.

expires: Поле заголовка сущности Expires указывает дату/время, после которого ответ считается устаревшим. Кэшированный элемент, считающийся устаревшим, обычно не возвращается кэшем.

Changelog

Изменено в версии 2.0: Объект datetime имеет часовой пояс.

classmethod force_type(response, environ=None)

Принудительно задаёт, что WSGI-ответ является объектом ответа текущего типа. Werkzeug будет использовать объект Response во многих ситуациях, таких как исключения. Если вы вызовете get_response() на исключении, вы получите обычный объект Response, даже если вы используете пользовательский подкласс.

Этот метод может принудительно задать определённый тип ответа, и он также преобразует произвольные WSGI-вызовы в объекты ответа, если предоставлен environ:

# convert a Werkzeug response object into an instance of the
# MyResponseClass subclass.
response = MyResponseClass.force_type(response)

# convert any WSGI application into a response object
response = MyResponseClass.force_type(response, environ)

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

Помните, что это может изменять объекты ответов на месте, если это возможно!

Параметры:

response (Ответ) – объект ответа или WSGI-приложение.
environ (WSGIEnvironment | None) – объект WSGI-среды.

Возвращаемое значение:

объект ответа.

Тип возвращаемого значения:

Ответ

freeze()

Подготавливает объект ответа к сериализации. Выполняет следующие действия:

Буферизует ответ в список, игнорируя implicity_sequence_conversion и direct_passthrough.
Устанавливает заголовок Content-Length.
Генерирует заголовок ETag , если он ещё не установлен.

Changelog

Изменено в версии 2.1: Удалён параметр no_etag.

Изменено в версии 2.0: Заголовок ETag всегда добавляется.

Изменено в версии 0.6: Устанавливается заголовок Content-Length.

Тип возвращаемого значения:: None

END_OF_DOCUMENT_MARKER

classmethod from_app(app, environ, buffered=False)

Создать новый объект ответа из вывода приложения. Это лучше всего работает, если вы передаете ему приложение, которое постоянно возвращает генератор. Иногда приложения могут использовать вызываемый write() функции start_response. Это пытается автоматически разрешить такие граничные случаи. Но если вы не получаете ожидаемый результат, вы должны установить buffered в True, что обеспечивает буферизацию.

Параметры:

app (WSGIApplication) – WSGI-приложение для выполнения.
environ (WSGIEnvironment) – WSGI-среда для выполнения.
buffered (bool) – установите в True для принудительной буферизации.

Возвращает:

объект ответа.

Тип возвращаемого значения:

get_app_iter(environ)

Возвращает итератор приложения для заданной среды. В зависимости от метода запроса и текущего кода состояния возвращаемое значение может быть пустым ответом, а не тем, который получен из ответа.

Если метод запроса HEAD, или код состояния находится в диапазоне, где спецификация HTTP требует пустого ответа, возвращается пустая итерируемая последовательность.

Changelog

Введен в версии 0.6.

Параметры:: environ (WSGIEnvironment) – WSGI-среда запроса.
Возвращает:: итерируемый объект ответа.
Тип возвращаемого значения:: t.Iterable[bytes]

get_data(as_text=False)

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

Это поведение можно отключить, установив implicit_sequence_conversion в False.

Если as_text установлено в True, возвращаемое значение будет декодированной строкой.

Changelog

Введен в версии 0.9.

Параметры:: as_text (bool) –
Тип возвращаемого значения:: bytes | str

get_etag()

Возвращает кортеж в форме (etag, is_weak). Если тега ETag нет, возвращаемое значение (None, None).

Тип возвращаемого значения:: tuple[str, bool] | tuple[None, None]

get_json(force=False, silent=False)

Разбор data как JSON. Полезно во время тестирования.

Если MIME-тип не указывает JSON (application/json, см. is_json), это возвращает None.

В отличие от Request.get_json(), результат не кэшируется.

Параметры:

force (bool) – Игнорировать MIME-тип и всегда пытаться разобрать JSON.
silent (bool) – Заглушить ошибки разбора и вернуть None вместо этого.

Тип возвращаемого значения:

Any | None

get_wsgi_headers(environ)

Это автоматически вызывается непосредственно перед запуском ответа и возвращает заголовки, измененные для данной среды. Он возвращает копию заголовков из ответа с внесенными, при необходимости, некоторыми изменениями.

Например, заголовок расположения (если он присутствует) объединяется с корневым URL среды. Также длина содержимого автоматически устанавливается в ноль для определенных кодов состояния.

Changelog

Изменено в версии 0.6: Ранее эта функция называлась fix_headers и изменяла объект ответа на месте. Также начиная с версии 0.6, IRIs в заголовках location и content-location обрабатываются должным образом.

Также начиная с версии 0.6, Werkzeug попытается установить длину содержимого, если сможет определить её самостоятельно. Это происходит, если все строки в итерируемом объекте ответа уже закодированы, и итерируемый объект отбуферизован.

Параметры:: environ (WSGIEnvironment) – WSGI-среда запроса.
Возвращает:: возвращает новый объект Headers.
Тип возвращаемого значения:: Headers

get_wsgi_response(environ)

Возвращает конечный WSGI-ответ в виде кортежа. Первый элемент кортежа — итератор приложения, второй — код состояния, а третий — список заголовков. Возвращаемый ответ создается специально для данной среды. Например, если метод запроса в WSGI-среде 'HEAD', ответ будет пустым и будут присутствовать только заголовки и код состояния.

Changelog

Введен в версии 0.6.

Параметры:: environ (WSGIEnvironment) – WSGI-среда запроса.
Возвращает:: кортеж (app_iter, status, headers).
Тип возвращаемого значения:: tuple[t.Iterable[bytes], str, list[tuple[str, str]]]

implicit_sequence_conversion = True: если установлено в False, доступ к свойствам объекта ответа не будет пытаться обработать итератор ответа и преобразовать его в список.

Changelog

Введен в версии 0.6.2: Это свойство ранее называлось implicit_seqence_conversion. (Обратите внимание на опечатку). Если вы использовали эту функцию, вам нужно адаптировать свой код к изменению названия.

property is_json: bool: Проверка, указывает ли MIME-тип данные JSON, либо application/json, либо application/*+json.

END_OF_DOCUMENT_MARKER

property is_sequence: bool: Если итератор буферизован, это свойство будет True. Объект ответа будет рассматривать итератор как буферизованный, если атрибут ответа является списком или кортежем.

Changelog

Новое в версии 0.6.

property is_streamed: bool

Если ответ передаётся потоком (ответ не является итерируемым объектом с информацией о длине), это свойство равно True. В этом случае передача потоком означает, что нет информации о количестве итераций. Обычно это True , если в объект ответа передаётся генератор.

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

iter_encoded()

Итерация закодированного ответа с кодировкой ответа. Если объект ответа вызывается как WSGI-приложение, значение возвращаемого этим методом итератора используется как итератор приложения, если не был активирован direct_passthrough.

Тип возвращаемого значения:: Итератор[байты]

property json: Any | None

Разложенные данные JSON, если mimetype указывает на JSON (application/json, см. is_json).

Вызывает get_json() с параметрами по умолчанию.

last_modified: Поле Last-Modified заголовка сущности указывает дату и время, когда, по мнению сервера источника, произошла последняя модификация варианта.

Changelog

Изменено в версии 2.0: Объект datetime является часовым.

location: Поле заголовка ответа Location используется для перенаправления получателя в местоположение, отличное от Request-URI, для завершения запроса или идентификации нового ресурса.

make_conditional(request_or_environ, accept_ranges=False, complete_length=None)

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

Ничего не делает, если метод запроса в запросе или окружении — не GET или HEAD.

Для оптимальной производительности при обработке запросов диапазонов рекомендуется, чтобы ваш объект данных ответа реализовывал методы seekable, seek и tell, как описано в io.IOBase. Объекты, возвращаемые wrap_file(), автоматически реализуют эти методы.

Не удаляет тело ответа, так как функция __call__() автоматически делает это за нас.

Возвращает self, чтобы вы могли сделать return resp.make_conditional(req), но изменяет объект на месте.

Параметры:

request_or_environ (WSGIEnvironment | Запрос) – объект запроса или WSGI-окружение, которое будет использоваться для того, чтобы сделать ответ условным по отношению к нему.
accept_ranges (bool | строка) – Этот параметр определяет значение заголовка Accept-Ranges. Если False (по умолчанию), заголовок не устанавливается. Если True, он будет установлен на значение "bytes". Если это строка, будет использовано это значение.
complete_length (целое число | None) – Будет использоваться только в допустимых запросах диапазона. Он установит значение полной длины Content-Range и вычислит значение Content-Length фактического значения. Этот параметр обязателен для успешного завершения запросов диапазона.

Возможные исключения:

RequestedRangeNotSatisfiable, если заголовок Range не удалось разобрать или удовлетворить.

Тип возвращаемого значения:

Ответ

Changelog

Изменено в версии 2.0: Обработка диапазона пропускается, если длина равна 0, вместо повышения ошибки 416 Range Not Satisfiable.

make_sequence()

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

Changelog

Новое в версии 0.6.

Тип возвращаемого значения:: None

property max_cookie_size: int

Только для чтения представление конфигурационного ключа MAX_COOKIE_SIZE.

См. max_cookie_size в документации Werkzeug.

property mimetype: str | None: Тип MIME (тип содержимого без кодировки символов и т. д.).

property mimetype_params: dict[str, str]: Параметры типа MIME в виде словаря. Например, если тип содержимого — text/html; charset=utf-8, параметры будут {'charset': 'utf-8'}.

Changelog

Новое в версии 0.5.

response: t.Iterable[str] | t.Iterable[bytes]

Тело ответа для отправки в качестве WSGI-итерируемого объекта. Список строк или байтов представляет ответ фиксированной длины, любой другой итерируемый объект — ответ, передаваемый потоком. Строки кодируются в байты в формате UTF-8.

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

property retry_after: datetime | None

Поле заголовка ответа Retry-After можно использовать с ответом 503 (Service Unavailable) для указания времени, в течение которого ожидается недоступность службы для клиента-заявителя.

Время в секундах до истечения срока действия или дата.

Changelog

Изменено в версии 2.0: Объект datetime является часовым.

set_cookie(key, value='', max_age=None, expires=None, path='/', domain=None, secure=False, httponly=False, samesite=None)

Устанавливает куки.

Выдается предупреждение, если размер заголовка куки превышает max_cookie_size, но заголовок всё равно будет установлен.

Параметры:

ключ (str) – ключ (имя) куки, которую нужно установить.
значение (str) – значение куки.
max_age (timedelta | int | None) – должно быть числом секунд, или None (по умолчанию), если куки должна действовать только до окончания сессии браузера клиента.
expires (str | datetime | int | float | None) – должно быть объектом datetime, или меткой времени Unix.
path (str | None) – ограничивает куки заданным путём, по умолчанию куки распространяется на весь домен.
domain (str | None) – если вы хотите установить куки для другого домена. Например, domain="example.com" установит куки, доступную для домена www.example.com, foo.example.com и т. д. В противном случае куки будет доступна только для домена, который её установил.
secure (bool) – Если True, куки будет доступна только через HTTPS.
httponly (bool) – Запрещает доступ к куки из JavaScript.
samesite (str | None) – Ограничивает область действия куки только запросами с того же сайта.

Тип возвращаемого значения:

None

set_data(value)

Устанавливает новую строку в качестве ответа. Значение должно быть строкой или байтами. Если устанавливается строка, она кодируется в кодировке ответа (по умолчанию utf-8).

Изменения

Введено в версии 0.9.

Параметры:: значение (bytes | str) –
Тип возвращаемого значения:: None

set_etag(etag, weak=False)

Устанавливает etag и перезаписывает старое значение, если оно было.

Параметры:

etag (str) –
weak (bool) –

Тип возвращаемого значения:

None

property status: str: Код HTTP-статуса в виде строки.

property status_code: int: Код HTTP-статуса в виде числа.

property stream: ResponseStream: Итерируемый объект ответа как потоковая запись только для записи.

property vary: HeaderSet: Значение поля Vary указывает набор полей заголовка запроса, которые полностью определяют, пока ответ свеж, разрешено ли использовать ответ кешу для ответа на последующий запрос без повторной проверки.

property www_authenticate: WWWAuthenticate

Заголовок WWW-Authenticate распарсен в объект WWWAuthenticate. Изменение объекта изменит значение заголовка.

Этот заголовок по умолчанию не установлен. Чтобы установить этот заголовок, присвойте экземпляр WWWAuthenticate этому атрибуту.

response.www_authenticate = WWWAuthenticate(
    "basic", {"realm": "Authentication Required"}
)

Несколько значений для этого заголовка могут быть отправлены, чтобы предоставить клиенту несколько вариантов. Присвойте список для установки нескольких заголовков. Однако изменение элементов в списке не будет автоматически обновлять значения заголовков, и доступ к этому атрибуту всегда будет возвращать только первое значение.

Чтобы сбросить этот заголовок, присвойте None или используйте del.

Изменения

Изменено в версии 2.3: Этому атрибуту можно присвоить значение для установки заголовка. Можно присвоить список для установки нескольких значений заголовка. Используйте del для удаления заголовка.

Изменено в версии 2.3: WWWAuthenticate больше не является dict. Атрибут token был добавлен для вызовов аутентификации, которые используют токен вместо параметров.

Сессии

Если вы установили Flask.secret_key (или настроите его из SECRET_KEY), вы можете использовать сессии в приложениях Flask. Сессия позволяет сохранять информацию между запросами. Flask использует для этого подписанный cookie. Пользователь может просмотреть содержимое сессии, но не может его изменить, не зная секретного ключа, поэтому убедитесь, что вы установили что-то сложное и не поддающееся угадыванию.

Для доступа к текущей сессии можно использовать объект session:

class flask.session

Объект сессии работает практически как обычный словарь, с той разницей, что он отслеживает изменения.

Это прокси. См. Заметки о прокси для получения дополнительной информации.

Следующие атрибуты представляют интерес:

new: True если сессия новая, False в противном случае.

modified

True если объект сессии обнаружил изменение. Обратите внимание, что изменения в изменяемых структурах не обнаруживаются автоматически, в этом случае вам необходимо явно установить атрибут в True самостоятельно. Вот пример:

# this change is not picked up because a mutable object (here
# a list) is changed.
session['objects'].append(42)
# so mark it as modified yourself
session.modified = True

permanent: Если установлено значение True, сессия будет жить в течение permanent_session_lifetime секунд. По умолчанию 31 день. Если установлено значение False, которое является значением по умолчанию, сессия будет удалена при закрытии браузера пользователем.

Интерфейс сессий

Изменения

Новое в версии 0.8.

Интерфейс сессий предоставляет простой способ заменить реализацию сессий, используемую Flask.

class flask.sessions.SessionInterface

Базовый интерфейс, который необходимо реализовать для замены стандартного интерфейса сессий, использующего реализацию securecookie от Werkzeug. Единственные методы, которые нужно реализовать, это open_session() и save_session(), остальные имеют полезные значения по умолчанию, которые менять не нужно.

Объект сессии, возвращаемый методом open_session(), должен предоставлять интерфейс типа словаря, а также свойства и методы из SessionMixin. Рекомендуется просто создать подкласс словаря и добавить в него этот миксин:

class Session(dict, SessionMixin):
    pass

Если open_session() возвращает None Flask вызовет make_null_session() для создания сессии-заместителя, если поддержка сессий не может работать из-за отсутствия какого-либо требования. По умолчанию создаётся класс NullSession, который будет жаловаться на то, что закрытый ключ не задан.

Чтобы заменить интерфейс сессий в приложении, необходимо назначить flask.Flask.session_interface:

app = Flask(__name__)
app.session_interface = MySessionInterface()

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

Изменения

Новое в версии 0.8.

get_cookie_domain(app)

Значение параметра Domain в cookie сессии. Если не задано, браузеры будут отправлять cookie только на тот домен, с которого он был установлен. В противном случае, они будут отправлять его и на все поддомены заданного значения.

Использует конфигурацию SESSION_COOKIE_DOMAIN.

Изменения

Изменено в версии 2.3: По умолчанию не задано, не использует значение по умолчанию SERVER_NAME.

Параметры:: app (Flask) –
Тип возвращаемого значения:: str | None

get_cookie_httponly(app)

Возвращает True, если cookie сессии должна быть httponly. В настоящее время просто возвращает значение конфигурации SESSION_COOKIE_HTTPONLY.

Параметры:: app (Flask) –
Тип возвращаемого значения:: bool

get_cookie_name(app)

Имя cookie сессии. Использует``app.config[“SESSION_COOKIE_NAME”]``.

Параметры:: app (Flask) –
Тип возвращаемого значения:: str

get_cookie_path(app)

Возвращает путь, для которого cookie должна быть действительной. Реализация по умолчанию использует значение из конфигурации SESSION_COOKIE_PATH , если оно задано, и использует APPLICATION_ROOT или / , если None.

Параметры:: app (Flask) –
Тип возвращаемого значения:: str

get_cookie_samesite(app)

Возвращает 'Strict' или 'Lax', если cookie должна использовать атрибут SameSite. В настоящее время просто возвращает значение настройки SESSION_COOKIE_SAMESITE.

Параметры:: app (Flask) –
Тип возвращаемого значения:: str

get_cookie_secure(app)

Возвращает True, если cookie должна быть безопасной. В настоящее время просто возвращает значение настройки SESSION_COOKIE_SECURE.

Параметры:: app (Flask) –
Тип возвращаемого значения:: bool

get_expiration_time(app, session)

Вспомогательный метод, возвращающий дату истечения срока действия сессии или None, если сессия связана с сессией браузера. Реализация по умолчанию возвращает текущее время + постоянный срок действия сессии, настроенный в приложении.

Параметры:

app (Flask) –
session (SessionMixin) –

Тип возвращаемого значения:

datetime | None

is_null_session(obj)

Проверяет, является ли данный объект пустой сессией. Пустые сессии не просят сохранить их.

По умолчанию проверяет, является ли объект экземпляром null_session_class.

Параметры:: obj (object) –
Тип возвращаемого значения:: bool

make_null_session(app)

Создает пустую сессию, которая действует как заменяющий объект, если реальная поддержка сессий не может быть загружена из-за ошибки конфигурации. Это в основном помогает пользователю, потому что задача пустой сессии — всё ещё поддерживать поиск без сообщений об ошибках, но модификации будут сопровождаться полезным сообщением об ошибке о том, что не удалось.

По умолчанию создаёт экземпляр null_session_class.

Параметры:: app (Flask) –
Тип возвращаемого значения:: NullSession

null_session_class

make_null_session() будет искать здесь класс, который должен быть создан при запросе пустой сессии. Аналогично, метод is_null_session() выполнит проверку типа против этого типа.

Псевдоним класса NullSession

open_session(app, request)

Вызывается в начале каждого запроса после добавления контекста запроса, перед сопоставлением URL.

Должен вернуть объект, реализующий интерфейс словаря, а также интерфейс SessionMixin.

Этот метод вернёт None, чтобы указать, что загрузка не удалась каким-то образом, который не является непосредственной ошибкой. В этом случае контекст запроса вернётся к использованию make_null_session().

Параметры:

app (Flask) –
request (Request) –

Тип возвращаемого значения:

SessionMixin | None

pickle_based = False: Флаг, указывающий, основан ли интерфейс сессии на pickle. Это может быть использовано расширениями Flask, чтобы принять решение о том, как обрабатывать объект сессии.

Изменения

Введено в версии 0.10.

save_session(app, session, response)

Вызывается в конце каждого запроса после генерации ответа, перед удалением контекста запроса. Пропускается, если is_null_session() возвращает True.

Параметры:

app (Flask) –
session (SessionMixin) –
response (Response) –

Тип возвращаемого значения:

None

should_set_cookie(app, session)

Используется бэкендами сессии для определения, должен ли заголовок Set-Cookie устанавливаться для cookie сессии для данного ответа. Если сессия была изменена, cookie устанавливается. Если сессия постоянна и конфигурация SESSION_REFRESH_EACH_REQUEST имеет значение true, cookie всегда устанавливается.

Эта проверка обычно пропускается, если сессия была удалена.

Изменения

Введено в версии 0.11.

Параметры:

app (Flask) –
session (SessionMixin) –

Тип возвращаемого значения:

class flask.sessions.SecureCookieSessionInterface

Стандартный интерфейс сессии, хранящий сессии в подписанных cookie через модуль itsdangerous.

static digest_method(string=b'', *, usedforsecurity=True): Функция хэширования для подписи. По умолчанию sha1

key_derivation = 'hmac': Имя поддерживаемого itsdangerous механизма вывода ключа. По умолчанию hmac.

open_session(app, request)

Вызывается в начале каждого запроса после добавления контекста запроса, перед сопоставлением URL.

Должен вернуть объект, реализующий интерфейс словаря, а также интерфейс SessionMixin.

Вернёт None, чтобы указать, что загрузка не удалась каким-то образом, который не является непосредственной ошибкой. В этом случае контекст запроса вернётся к использованию make_null_session().

Параметры:

app (Flask) –
request (Request) –

Тип возвращаемого значения:

SecureCookieSession | None

salt = 'cookie-session': Соль, которая должна быть применена поверх секретного ключа для подписи cookie-сессий.

save_session(app, session, response)

Параметры:

app (Flask) –
session (SessionMixin) –
response (Response) –

Тип возвращаемого значения:

None

serializer = <flask.json.tag.TaggedJSONSerializer object>: Python-сериализатор для полезной нагрузки. По умолчанию используется компактный JSON-сериализатор с поддержкой некоторых дополнительных типов Python, таких как объекты datetime или кортежи.

session_class: Псевдоним класса SecureCookieSession

END_OF_DOCUMENT_MARKER

class flask.sessions.SecureCookieSession(initial=None)

Базовый класс для сессий на основе подписанных файлов cookie.

Этот бэкэнд сессий будет устанавливать атрибуты modified и accessed. Он не может надежно отслеживать, является ли сессия новой (по сравнению с пустой), поэтому new остается жестко закодированным в False.

Параметры:: initial (t.Any) –

accessed = False: заголовок, который позволяет кэширующим прокси кэшировать разные страницы для разных пользователей.

get(key, default=None)

Возвращает значение для ключа, если ключ есть в словаре, иначе возвращает значение по умолчанию.

Параметры:

key (str) –
default (Any | None) –

Тип возвращаемого значения:

modified = False: Когда данные изменяются, это устанавливается в True. Отслеживается только сам словарь сессии; если сессия содержит изменяемые данные (например, вложенный словарь), то это должно быть установлено в True вручную при изменении этих данных. Файл cookie сессии будет записан в ответ только в том случае, если это True.

setdefault(key, default=None)

Вставляет ключ со значением по умолчанию, если ключ отсутствует в словаре.

Возвращает значение для ключа, если ключ есть в словаре, иначе возвращает значение по умолчанию.

Параметры:

key (str) –
default (Any | None) –

Тип возвращаемого значения:

class flask.sessions.NullSession(initial=None)

Класс, используемый для генерации более информативных сообщений об ошибках, если сессии недоступны. По-прежнему будет разрешен доступ только для чтения к пустой сессии, но установка значений будет приводить к ошибке.

Параметры:: initial (t.Any) –

clear() → None. Remove all items from D.

Параметры:

args (Any) –
kwargs (Any) –

Тип возвращаемого значения:

pop(k[, d]) → v, remove specified key and return the corresponding value.

Если ключ не найден, возвращает значение по умолчанию, если оно задано; в противном случае, вызывает KeyError.

Параметры:

args (Any) –
kwargs (Any) –

Тип возвращаемого значения:

popitem(*args, **kwargs)

Удаляет и возвращает пару (ключ, значение) в виде 2-кортежа.

Пары возвращаются в порядке LIFO (last-in, first-out). Вызывает KeyError, если словарь пуст.

Параметры:

args (Any) –
kwargs (Any) –

Тип возвращаемого значения:

setdefault(*args, **kwargs)

Вставляет ключ со значением по умолчанию, если ключ отсутствует в словаре.

Возвращает значение для ключа, если ключ есть в словаре, иначе возвращает значение по умолчанию.

Параметры:

args (Any) –
kwargs (Any) –

Тип возвращаемого значения:

update([E, ]**F) → None. Update D from dict/iterable E and F.

Если E присутствует и имеет метод .keys(), то выполняет: for k in E: D[k] = E[k] Если E присутствует и не имеет метода .keys(), то выполняет: for k, v in E: D[k] = v В любом случае, за этим следует: for k in F: D[k] = F[k]

Параметры:

args (Any) –
kwargs (Any) –

Тип возвращаемого значения:

class flask.sessions.SessionMixin

Расширяет базовый словарь атрибутами сессии.

accessed = True: Некоторые реализации могут обнаруживать, когда данные сессии читаются или записываются, и устанавливают это, когда это происходит. Значение по умолчанию для mixin жестко закодировано в True.

modified = True: Некоторые реализации могут обнаруживать изменения в сессии и устанавливать это, когда это происходит. Значение по умолчанию для mixin жестко закодировано в True.

property permanent: bool: Это отражает ключ '_permanent' в словаре.

Заметка

Настройка PERMANENT_SESSION_LIFETIME может быть целым числом или timedelta. Атрибут permanent_session_lifetime всегда является timedelta.

Тестовый клиент

class flask.testing.FlaskClient(*args, **kwargs)

Работает как обычный тестовый клиент Werkzeug, но имеет знания о контекстах Flask, чтобы отложить очистку контекста запроса до конца блока with. Для общей информации о том, как использовать этот класс, обратитесь к werkzeug.test.Client.

Журнал изменений

Изменено в версии 0.12: app.test_client() включает предопределенную среду по умолчанию, которую можно установить после создания объекта app.test_client() в client.environ_base.

Базовое использование описано в главе Тестирование приложений Flask.

Параметры:

args (t.Any) –
kwargs (t.Any) –

open(*args, buffered=False, follow_redirects=False, **kwargs)

Генерирует словарь environ из заданных аргументов, отправляет запрос к приложению с его использованием и возвращает ответ.

Параметры:

args (t.Any) – Передаётся в EnvironBuilder для создания environ для запроса. Если передаётся один аргумент, он может быть существующим EnvironBuilder или словарем environ.
buffered (bool) – Преобразует итератор, возвращённый приложением, в список. Если у итератора есть метод close(), он вызывается автоматически.
follow_redirects (bool) – Отправляет дополнительные запросы для следования HTTP-редиректам до тех пор, пока не будет возвращён статус, не являющийся редиректом. TestResponse.history перечисляет промежуточные ответы.
kwargs (t.Any) –

Тип возвращаемого значения:

TestResponse

Журнал изменений

Изменено в версии 2.1: Удалён параметр as_tuple.

Изменено в версии 2.0: Поток входных данных запроса закрывается при вызове response.close(). Потоки входных данных для редиректов автоматически закрываются.

Изменено в версии 0.5: Если словарь предоставляется как файл в словаре для параметра data, тип содержимого должен быть назван content_type вместо mimetype. Это изменение было сделано для согласованности с werkzeug.FileWrapper.

Изменено в версии 0.5: Добавлен параметр follow_redirects.

session_transaction(*args, **kwargs)

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

with client.session_transaction() as session:
    session['value'] = 42

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

Параметры:

args (Any) –
kwargs (Any) –

Тип возвращаемого значения:

Generator[SessionMixin, None, None]

Запуск команд CLI

class flask.testing.FlaskCliRunner(app, **kwargs)

CliRunner для тестирования команд CLI приложения Flask. Обычно создаётся с помощью test_cli_runner(). См. Запуск команд с помощью CLI-запускателя.

Параметры:

app (Flask) –
kwargs (t.Any) –

invoke(cli=None, args=None, **kwargs)

Вызывает команду CLI в изолированной среде. См. CliRunner.invoke для полной документации метода. См. Запуск команд с помощью CLI-запускателя для примеров.

Если аргумент obj не задан, передаётся экземпляр ScriptInfo, который знает, как загрузить тестируемое приложение Flask.

Параметры:

cli (Any | None) – Объект команды для вызова. По умолчанию это группа cli приложения.
args (Any | None) – Список строк для вызова команды.
kwargs (Any) –

Возвращаемое значение:

объект Result.

Тип возвращаемого значения:

Глобальные переменные приложения

Для совместного использования данных, действительных только для одного запроса, одной функцией с другой, глобальная переменная не подходит, поскольку она будет нарушена в многопоточных средах. Flask предоставляет специальный объект, который гарантирует, что он действителен только для активного запроса и будет возвращать разные значения для каждого запроса. Короче говоря: он делает всё правильно, как для request и session.

flask.g

Объект пространства имен, который может хранить данные во время контекста приложения. Это экземпляр Flask.app_ctx_globals_class, по умолчанию ctx._AppCtxGlobals.

Это хорошее место для хранения ресурсов во время запроса. Например, функция before_request может загрузить объект пользователя по идентификатору сессии, а затем установить g.user для использования в функции представления.

Это прокси. См. Примечания по прокси для получения дополнительной информации.

Журнал изменений

Изменено в версии 0.10: Связано с контекстом приложения вместо контекста запроса.

class flask.ctx._AppCtxGlobals

Простой объект. Используется в качестве пространства имен для хранения данных в контексте приложения.

Создание контекста приложения автоматически создаёт этот объект, который доступен как g прокси.

'key' in g: Проверка наличия атрибута.

Журнал изменений

Добавлен в версии 0.10.

iter(g): Возвращает итератор по именам атрибутов.

Журнал изменений

Добавлен в версии 0.10.

get(name, default=None)

Получить атрибут по имени или значение по умолчанию. Подобно dict.get().

Параметры:

name (str) – Имя атрибута для получения.
default (Any | None) – Значение по умолчанию для возврата, если атрибута нет.

Тип возвращаемого значения:

Журнал изменений

Добавлен в версии 0.10.

pop(name, default=<object object>)

Получить и удалить атрибут по имени. Подобно dict.pop().

Параметры:

name (str) – Имя атрибута для удаления.
default (Any) – Значение по умолчанию для возврата, если атрибута нет, вместо того, чтобы вызывать KeyError.

Тип возвращаемого значения:

Журнал изменений

Добавлен в версии 0.11.

setdefault(name, default=None)

Получить значение атрибута, если оно присутствует, иначе установить и вернуть значение по умолчанию. Подобно dict.setdefault().

Параметры:

name (str) – Имя атрибута для получения.
default (Any | None) – Значение по умолчанию для установки и возврата, если атрибута нет.

Тип возвращаемого значения:

Журнал изменений

Добавлен в версии 0.11.

END_OF_DOCUMENT_MARKER

Полезные функции и классы

flask.current_app

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

Доступен только при установке контекста приложения. Это происходит автоматически во время запросов и команд CLI. Можно управлять вручную с помощью app_context().

Это прокси. Дополнительную информацию можно найти в Примечания по прокси.

flask.has_request_context()

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

class User(db.Model):

    def __init__(self, username, remote_addr=None):
        self.username = username
        if remote_addr is None and has_request_context():
            remote_addr = request.remote_addr
        self.remote_addr = remote_addr

Альтернативно, можно проверить на истинность любое из объектов, связанных с контекстом (например, request или g):

class User(db.Model):

    def __init__(self, username, remote_addr=None):
        self.username = username
        if remote_addr is None and request:
            remote_addr = request.remote_addr
        self.remote_addr = remote_addr

Changelog

Новое в версии 0.7.

Тип возвращаемого значения:: bool

flask.copy_current_request_context(f)

Вспомогательная функция, которая декорирует функцию для сохранения текущего контекста запроса. Это полезно при работе с greenlets. В момент декорирования создается копия контекста запроса, а затем она устанавливается при вызове функции. В копию контекста запроса также включается текущая сессия.

Пример:

import gevent
from flask import copy_current_request_context

@app.route('/')
def index():
    @copy_current_request_context
    def do_some_work():
        # do some work here, it can access flask.request or
        # flask.session like you would otherwise in the view function.
        ...
    gevent.spawn(do_some_work)
    return 'Regular response'

Changelog

Новое в версии 0.10.

Параметры:: f (Callable) –
Тип возвращаемого значения:: Callable

flask.has_app_context()

Работает так же, как has_request_context(), но для контекста приложения. Также можно проверить объект current_app на истинность.

Changelog

Новое в версии 0.9.

Тип возвращаемого значения:: bool

flask.url_for(endpoint, *, _anchor=None, _method=None, _scheme=None, _external=None, **values)

Генерирует URL для заданного конечной точки с заданными значениями.

Требуется активный запрос или контекст приложения, и вызывается current_app.url_for(). Полная документация в этом методе.

Параметры:

endpoint (str) – Имя конечной точки, связанной с генерируемым URL. Если начинается с ., используется имя текущего модуля (если таковой имеется).
_anchor (str | None) – Если указано, добавляет это в качестве #anchor к URL.
_method (str | None) – Если задано, генерирует URL, связанный с этим методом для конечной точки.
_scheme (str | None) – Если задано, URL будет иметь этот протокол, если он внешний.
_external (bool | None) – Если задано, URL предпочтительно должен быть внутренним (False) или обязательным внешним (True). Внешние URL включают протокол и домен. Если контекст запроса не активен, URL по умолчанию является внешним.
values (Any) – Значения для использования в переменных частях правила URL. Неизвестные ключи добавляются как аргументы строки запроса, например, ?a=b&c=d.

Тип возвращаемого значения:

Changelog

Изменено в версии 2.2: Вызывает current_app.url_for, позволяя приложению переопределять поведение.

Изменено в версии 0.10: Добавлен параметр _scheme.

Изменено в версии 0.9: Добавлены параметры _anchor и _method.

Изменено в версии 0.9: При ошибках компиляции вызывается app.handle_url_build_error.

flask.abort(code, *args, **kwargs)

Вызвать HTTPException для заданного кода состояния.

Если доступно current_app, оно вызовет свой объект aborter, в противном случае будет использоваться werkzeug.exceptions.abort().

Параметры:

code (int | BaseResponse) – Код состояния для исключения, который должен быть зарегистрирован в app.aborter.
args (t.Any) – Передается в исключение.
kwargs (t.Any) – Передается в исключение.

Тип возвращаемого значения:

t.NoReturn

Changelog

Новое в версии 2.2: Вызывает current_app.aborter при наличии вместо всегда использования по умолчанию Werkzeug abort.

flask.redirect(location, code=302, Response=None)

Создает объект ответа перенаправления.

Если доступно current_app, будет использоваться его метод redirect(), в противном случае будет использоваться werkzeug.utils.redirect().

Параметры:

location (str) – URL для перенаправления.
code (int) – Код состояния для перенаправления.
Response (type[BaseResponse] | None) – Класс ответа для использования. Не используется, когда current_app активен, который использует app.response_class.

Тип возвращаемого значения:

BaseResponse

Changelog

Новое в версии 2.2: Вызывает current_app.redirect при наличии вместо всегда использования по умолчанию Werkzeug redirect.

flask.make_response(*args)

Иногда требуется установить дополнительные заголовки в представлении. Поскольку представления не обязательно должны возвращать объекты ответа, а могут возвращать значение, которое Flask преобразует в объект ответа, становится сложно добавлять к нему заголовки. Эта функция может быть вызвана вместо использования возврата, и вы получите объект ответа, который можно использовать для добавления заголовков.

Если представление выглядело так, и вы хотите добавить новый заголовок:

def index():
    return render_template('index.html', foo=42)

Теперь вы можете сделать что-то вроде этого:

def index():
    response = make_response(render_template('index.html', foo=42))
    response.headers['X-Parachutes'] = 'parachutes are cool'
    return response

Эта функция принимает те же самые аргументы, которые вы можете возвращать из функции представления. Например, это создаёт ответ с кодом ошибки 404:

response = make_response(render_template('not_found.html'), 404)

Другой случай использования этой функции — принудительное преобразование возвращаемого значения функции представления в ответ, что полезно при использовании декораторов представлений:

response = make_response(view_function())
response.headers['X-Parachutes'] = 'parachutes are cool'

Внутренне эта функция выполняет следующие действия:

если аргументы не переданы, создается новый аргумент ответа
если передан один аргумент, вызывается flask.Flask.make_response() с ним.
если передано более одного аргумента, аргументы передаются функции flask.Flask.make_response() в качестве кортежа.

Changelog

New in version 0.6.

Parameters:: args (t.Any) –
Return type:: Response

flask.after_this_request(f)

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

Пример:

@app.route('/')
def index():
    @after_this_request
    def add_header(response):
        response.headers['X-Foo'] = 'Parachute'
        return response
    return 'Hello World!'

Это более полезно, если функция, отличная от функции представления, хочет изменить ответ. Например, представьте декоратор, который хочет добавить некоторые заголовки без преобразования возвращаемого значения в объект ответа.

Changelog

New in version 0.9.

Parameters:: f (Callable[[ResponseClass], ResponseClass] | Callable[[ResponseClass], Awaitable[ResponseClass]]) –
Return type:: Callable[[ResponseClass], ResponseClass] | Callable[[ResponseClass], Awaitable[ResponseClass]]

flask.send_file(path_or_file, mimetype=None, as_attachment=False, download_name=None, conditional=True, etag=True, last_modified=None, max_age=None)

Отправка содержимого файла клиенту.

Первый аргумент может быть путем к файлу или объектом, подобным файлу. Пути предпочтительнее в большинстве случаев, потому что Werkzeug может управлять файлом и получать дополнительную информацию из пути. Передача объекта, подобного файлу, требует, чтобы файл был открыт в двоичном режиме, и это преимущественно полезно при построении файла в памяти с помощью io.BytesIO.

Никогда не передавайте пути к файлам, предоставленным пользователем. Путь предполагается доверенным, поэтому пользователь может создать путь для доступа к файлу, который вы не имели в виду. Используйте send_from_directory() для безопасной отправки путей, запрошенных пользователем, из каталога.

Если WSGI-сервер устанавливает file_wrapper в environ, оно используется, в противном случае используется встроенный обертка Werkzeug. В качестве альтернативы, если HTTP-сервер поддерживает X-Sendfile, настройка Flask с USE_X_SENDFILE = True сообщит серверу об отправке заданного пути, что намного эффективнее, чем чтение его в Python.

Параметры:

path_or_file (os.PathLike | str | t.BinaryIO) – Путь к отправляемому файлу, относительно текущей рабочей директории, если указан относительный путь. В качестве альтернативы, объект, подобный файлу, открытый в двоичном режиме. Убедитесь, что указатель файла переведён к началу данных.
mimetype (str | None) – Тип MIME для отправки файла. Если не указан, будет попытка определить его по имени файла.
as_attachment (bool) – Указывает браузеру предложить сохранить файл вместо отображения его.
download_name (str | None) – Имя по умолчанию, которое браузеры будут использовать при сохранении файла. По умолчанию совпадает с именем переданного файла.
conditional (bool) – Включить условные и диапазонные ответы на основе заголовков запроса. Требует передачи пути к файлу и environ.
etag (bool | str) – Вычислить ETag для файла, что требует передачи пути к файлу. Также может быть строкой, используемой вместо этого.
last_modified (datetime | int | float | None) – Время последнего изменения файла в секундах. Если не указано, попытается определить его из пути к файлу.
max_age (None | (int | t.Callable[[str | None], int | None])) – Срок хранения файла клиентом в секундах. Если задано, Cache-Control будет public, в противном случае no-cache, чтобы предпочесть условное кэширование.

Тип возвращаемого значения:

Журнал изменений

Изменено в версии 2.0: download_name заменяет параметр attachment_filename. Если as_attachment=False, он передаётся с Content-Disposition: inline вместо.

Изменено в версии 2.0: max_age заменяет параметр cache_timeout. conditional включено, а max_age не задано по умолчанию.

Изменено в версии 2.0: etag заменяет параметр add_etags. Может быть строкой, вместо вычисления.

Изменено в версии 2.0: Передача объекта, подобного файлу, который наследует от TextIOBase, вызовет ValueError, а не отправку пустого файла.

Новое в версии 2.0: Реализация перенесена в Werkzeug. Сейчас это обертка для передачи некоторых специфических для Flask аргументов.

Изменено в версии 1.1: filename может быть объектом PathLike.

Изменено в версии 1.1: Передача объекта BytesIO поддерживает запросы с диапазоном.

Изменено в версии 1.0.3: Имена файлов кодируются с помощью ASCII вместо Latin-1 для более широкой совместимости с WSGI-серверами.

Изменено в версии 1.0: Поддерживаются имена файлов UTF-8, как указано в RFC 2231.

Изменено в версии 0.12: Имя файла больше не выводится автоматически из объектов файлов. Если вы хотите использовать автоматическую поддержку MIME и etag, передайте имя файла через filename_or_fp или attachment_filename.

Изменено в версии 0.12: attachment_filename предпочтительнее filename для определения MIME.

Изменено в версии 0.9: cache_timeout по умолчанию Flask.get_send_file_max_age().

Изменено в версии 0.7: Угадывание MIME и поддержка etag для объектов, подобных файлам, были удалены, так как они были ненадежны. Передайте имя файла, если можете, в противном случае добавьте etag самостоятельно.

Изменено в версии 0.5: Были добавлены параметры add_etags, cache_timeout и conditional. По умолчанию добавляются etag.

Новое в версии 0.2.

flask.send_from_directory(directory, path, **kwargs)

Отправьте файл из каталога с помощью send_file().

@app.route("/uploads/<path:name>")
def download_file(name):
    return send_from_directory(
        app.config['UPLOAD_FOLDER'], name, as_attachment=True
    )

Это безопасный способ предоставления файлов из папки, например, статических файлов или загруженных данных. Использует safe_join(), чтобы убедиться, что путь, полученный от клиента, не был злонамеренно составлен для указания на расположение вне заданного каталога.

Если конечный путь не указывает на существующий обычный файл, возникает ошибка 404 NotFound.

Параметры:

directory (os.PathLike | str) – Каталог, в котором path должен находиться, относительно корневого пути текущего приложения.
path (os.PathLike | str) – Путь к файлу для отправки, относительно directory.
kwargs (t.Any) – Аргументы для передачи в send_file().

Тип возвращаемого значения:

Изменения

Изменено в версии 2.0: path заменяет параметр filename.

Добавлен в версии 2.0: Реализация перенесена в Werkzeug. Сейчас это обёртка для передачи некоторых аргументов Flask.

Добавлен в версии 0.5.

Сообщения всплывающих подсказок

flask.flash(message, category='message')

Выводит сообщение всплывающей подсказки для следующего запроса. Для удаления сохранённого сообщения всплывающей подсказки из сессии и отображения его пользователю, шаблон должен вызвать get_flashed_messages().

Изменения

Изменено в версии 0.3: Добавлен параметр category.

Параметры:

message (str) – сообщение всплывающей подсказки.
category (str) – категория сообщения. Рекомендуются следующие значения: 'message' для любого типа сообщения, 'error' для ошибок, 'info' для сообщений об информации и 'warning' для предупреждений. Однако, может быть использована любая строка.

Тип возвращаемого значения:

None

flask.get_flashed_messages(with_categories=False, category_filter=())

Извлекает все сообщения всплывающих подсказок из сессии и возвращает их. Дальнейшие вызовы функции в одном запросе вернут те же сообщения. По умолчанию возвращаются только сообщения, но когда with_categories установлено в True, возвращаемое значение будет списком кортежей в формате (category, message) вместо этого.

Фильтрация сообщений всплывающих подсказок по одной или нескольким категориям путём предоставления этих категорий в category_filter. Это позволяет отображать категории в отдельных блоках html. Параметры with_categories и category_filter различаются:

with_categories управляет тем, возвращаются ли категории с текстом сообщения (True возвращает кортеж, где False возвращает только текст сообщения).
category_filter фильтрует сообщения, оставляя только те, которые соответствуют предоставленным категориям.

См. Сообщения всплывающих подсказок для примеров.

Изменения

Изменено в версии 0.9: Добавлен параметр category_filter.

Изменено в версии 0.3: Добавлен параметр with_categories.

Параметры:

with_categories (bool) – установить в True для получения категорий.
category_filter (Iterable[str]) – фильтр категорий для ограничения результатов. Будут возвращены только категории из списка.

Тип возвращаемого значения:

list[str] | list[tuple[str, str]]

Поддержка JSON

Flask по умолчанию использует встроенный модуль Python json для работы с JSON. Реализацию JSON можно изменить, назначив другой поставщик свойству flask.Flask.json_provider_class или flask.Flask.json. Функции, предоставляемые flask.json, будут использовать методы app.json, если активен контекст приложения.

Фильтр Jinja |tojson настроен на использование поставщика JSON приложения. Этот фильтр маркирует вывод |safe. Используйте его для отображения данных внутри HTML <script> тегов.

<script>
    const names = {{ names|tojson }};
    renderChart(names, {{ axis_data|tojson }});
</script>

flask.json.jsonify(*args, **kwargs)

Сериализует заданные аргументы в формате JSON и возвращает объект Response с типом контента application/json. Словарь или список, возвращаемые из представления, будут автоматически преобразованы в ответ JSON без необходимости вызова этой функции.

Это требует активного запроса или контекста приложения и вызывает app.json.response().

В режиме отладки вывод форматируется с отступами, чтобы его было легче читать. Это также может контролироваться поставщиком.

Можно использовать позиционные или ключевые аргументы, но не оба одновременно. Если аргументы не указаны, будет сериализован None.

Parameters:

args (t.Any) – Единственное значение для сериализации или несколько значений, которые будут обработаны как список для сериализации.
kwargs (t.Any) – Обработать как словарь для сериализации.

Return type:

Ответ

Журнал изменений

Изменено в версии 2.2: Вызывает current_app.json.response, позволяя приложению переопределить поведение.

Изменено в версии 2.0.2: Поддерживается decimal.Decimal путём преобразования в строку.

Изменено в версии 0.11: Добавлена поддержка сериализации массивов верхнего уровня. Это представляло собой риск безопасности в старых браузерах. См. Безопасность JSON.

Добавлена в версии 0.2.

flask.json.dumps(obj, **kwargs)

Сериализует данные в формате JSON.

Если доступен current_app, он будет использовать свой метод app.json.dumps(), иначе будет использоваться json.dumps().

Parameters:

obj (Любой) – Данные для сериализации.
kwargs (Любой) – Аргументы, передаваемые в реализацию dumps.

Return type:

строка

Журнал изменений

Изменено в версии 2.3: Параметр app был удалён.

Изменено в версии 2.2: Вызывает current_app.json.dumps, позволяя приложению переопределить поведение.

Изменено в версии 2.0.2: Поддерживается decimal.Decimal путём преобразования в строку.

Изменено в версии 2.0: encoding будет удалено в Flask 2.1.

Изменено в версии 1.0.3: app можно передать напрямую, вместо необходимости контекста приложения для конфигурации.

flask.json.dump(obj, fp, **kwargs)

Сериализует данные в формате JSON и записывает их в файл.

Если доступен current_app, он будет использовать свой метод app.json.dump(), иначе будет использоваться json.dump().

Parameters:

obj (Любой) – Данные для сериализации.
fp (IO[строка]) – Файл, открытый для записи текста. Должен использовать кодировку UTF-8 для корректного JSON.
kwargs (Любой) – Аргументы, передаваемые в реализацию dump.

Return type:

None

Журнал изменений

Изменено в версии 2.3: Параметр app был удалён.

Изменено в версии 2.2: Вызывает current_app.json.dump, позволяя приложению переопределить поведение.

Изменено в версии 2.0: Запись в двоичный файл и аргумент encoding будут удалены в Flask 2.1.

flask.json.loads(s, **kwargs)

Десериализует данные в формате JSON.

Если доступен current_app, он будет использовать свой метод app.json.loads(), иначе будет использоваться json.loads().

Parameters:

s (строка | байты) – Текст или байты UTF-8.
kwargs (Любой) – Аргументы, передаваемые в реализацию loads.

Return type:

Любой

Журнал изменений

Изменено в версии 2.3: Параметр app был удалён.

Изменено в версии 2.2: Вызывает current_app.json.loads, позволяя приложению переопределить поведение.

Изменено в версии 2.0: encoding будет удалено в Flask 2.1. Данные должны быть строкой или байтами UTF-8.

flask.json.load(fp, **kwargs)

Десериализация данных в формате JSON, считанных из файла.

Если доступен current_app, он будет использовать метод app.json.load(), в противном случае будет использован json.load().

Parameters:

fp (IO) – Файл, открытый для чтения текста или байтов UTF-8.
kwargs (Any) – Аргументы, передаваемые в реализацию load.

Return type:

Changelog

Изменено в версии 2.3: Параметр app был удалён.

Изменено в версии 2.2: Вызовы current_app.json.load, позволяющие приложению переопределить поведение.

Изменено в версии 2.2: Параметр app будет удалён в Flask 2.3.

Изменено в версии 2.0: encoding будет удалён в Flask 2.1. Файл должен быть открыт в текстовом режиме или в двоичном режиме с использованием UTF-8 байтов.

class flask.json.provider.JSONProvider(app)

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

Для реализации провайдера для конкретной библиотеки необходимо создать подкласс этого базового класса и реализовать как минимум dumps() и loads(). Все остальные методы имеют реализации по умолчанию.

Для использования другого провайдера можно создать подкласс Flask и установить json_provider_class на класс провайдера или установить app.json на экземпляр класса.

Parameters:: app (App) – Экземпляр приложения. Он будет сохранён как weakref.proxy на атрибуте _app.

Changelog

New in version 2.2.

dumps(obj, **kwargs)

Сериализация данных в формате JSON.

Parameters:

obj (Any) – Данные для сериализации.
kwargs (Any) – Может быть передан в базовую библиотеку JSON.

Return type:

dump(obj, fp, **kwargs)

Сериализация данных в формате JSON и запись в файл.

Parameters:

obj (Any) – Данные для сериализации.
fp (IO[str]) – Файл, открытый для записи текста. Должен использовать кодировку UTF-8 для корректного представления JSON.
kwargs (Any) – Может быть передан в базовую библиотеку JSON.

Return type:

None

loads(s, **kwargs)

Десериализация данных в формате JSON.

Parameters:

s (str | bytes) – Текст или байты UTF-8.
kwargs (Any) – Может быть передан в базовую библиотеку JSON.

Return type:

load(fp, **kwargs)

Десериализация данных в формате JSON, считанных из файла.

Parameters:

fp (IO) – Файл, открытый для чтения текста или байтов UTF-8.
kwargs (Any) – Может быть передан в базовую библиотеку JSON.

Return type:

response(*args, **kwargs)

Сериализует переданные аргументы в формате JSON и возвращает объект Response с MIME-типом application/json.

Функция jsonify() вызывает этот метод для текущего приложения.

Можно передавать позиционные или ключевые аргументы, но не оба типа одновременно. Если аргументов нет, сериализуется None.

Parameters:

args (t.Any) – Единственное значение для сериализации или несколько значений для обработки как списка для сериализации.
kwargs (t.Any) – Обработать как словарь для сериализации.

Return type:

class flask.json.provider.DefaultJSONProvider(app)

Предоставляет операции с JSON, используя встроенную в Python библиотеку json. Сериализует следующие дополнительные типы данных:

datetime.datetime и datetime.date сериализуются в строки формата RFC 822. Это соответствует формату даты HTTP.
uuid.UUID сериализуется в строку.
dataclasses.dataclass передаётся в dataclasses.asdict().
Markup (или любой объект с методом __html__ ) вызовет метод __html__ для получения строки.

Параметры:: app (App) –

static default(o)

Применение этой функции к любому объекту, для которого json.dumps() не знает, как выполнить сериализацию. Она должна возвращать допустимый тип JSON или вызывать TypeError.

Параметры:: o (Any) –
Тип возвращаемого значения:: Any

ensure_ascii = True: Замена символов, не являющихся ASCII, последовательностями экранирования. Это может быть совместимее с некоторыми клиентами, но может быть отключено для повышения производительности и размера.

sort_keys = True: Сортировка ключей в любых сериализованных словарях. Это может быть полезно в некоторых ситуациях кеширования, но может быть отключено для повышения производительности. При включении все ключи должны быть строками, они не преобразуются перед сортировкой.

compact: bool | None = None: Если True, или None вне режима отладки, выход response() не будет добавлять отступы, новые строки или пробелы. Если False, или None в режиме отладки, он будет использовать некомпактное представление.

mimetype = 'application/json': Тип MIME, заданный в response().

dumps(obj, **kwargs)

Сериализация данных в JSON в строку.

Ключевые аргументы передаются в json.dumps(). Устанавливаются некоторые значения параметров по умолчанию из атрибутов default, ensure_ascii и sort_keys.

Параметры:

obj (Any) – Данные для сериализации.
kwargs (Any) – Передаётся в json.dumps().

Тип возвращаемого значения:

loads(s, **kwargs)

Десериализация данных в формате JSON из строки или байтов.

Параметры:

s (str | bytes) – Текст или байты UTF-8.
kwargs (Any) – Передаётся в json.loads().

Тип возвращаемого значения:

response(*args, **kwargs)

Сериализует данные в JSON и возвращает объект Response с результатом. Тип MIME ответа будет «application/json», и его можно изменить с помощью mimetype.

Если compact False, или если режим отладки включён, выход будет отформатирован для большей читабельности.

Можно использовать позиционные или ключевые аргументы, но не оба вместе. Если аргументов нет, сериализуется None.

Параметры:

args (t.Any) – Единственное значение для сериализации или несколько значений для обработки как списка для сериализации.
kwargs (t.Any) – Обрабатывается как словарь для сериализации.

Тип возвращаемого значения:

Тегированный JSON

Компактное представление для бескомпромиссной сериализации нестандартных типов JSON. SecureCookieSessionInterface использует это для сериализации данных сессии, но это может быть полезно и в других местах. Его можно расширить для поддержки других типов.

class flask.json.tag.TaggedJSONSerializer

Сериализатор, использующий систему тегов для компактного представления объектов, которые не являются типами JSON. Передаётся как промежуточный сериализатор в itsdangerous.Serializer.

Поддерживаются следующие дополнительные типы:

default_tags = [<class 'flask.json.tag.TagDict'>, <class 'flask.json.tag.PassDict'>, <class 'flask.json.tag.TagTuple'>, <class 'flask.json.tag.PassList'>, <class 'flask.json.tag.TagBytes'>, <class 'flask.json.tag.TagMarkup'>, <class 'flask.json.tag.TagUUID'>, <class 'flask.json.tag.TagDateTime'>]: Классы тегов, которые связываются при создании сериализатора. Другие теги могут быть добавлены позже с помощью register().

dumps(value)

Присваивает тег значению и выводит его в компактную строку JSON.

Параметры:: значение (Any) –
Тип возвращаемого значения:: str

loads(value)

Загружает данные из строки JSON и десериализует любые помеченные объекты.

Параметры:: значение (str) –
Тип возвращаемого значения:: Any

register(tag_class, force=False, index=None)

Регистрирует новый тег с этим сериализатором.

Параметры:

класс_тега (type[flask.json.tag.JSONTag]) – регистрируемый класс тега. Будет создан с этим экземпляром сериализатора.
принудительно (bool) – перезаписывать существующий тег. Если ложь (по умолчанию), генерируется KeyError.
индекс (int | None) – индекс для вставки нового тега в порядке тегов. Полезно, когда новый тег является частным случаем существующего тега. Если None (по умолчанию), тег добавляется в конец порядка.

Возбуждает:

KeyError – если ключ тега уже зарегистрирован и force не истинно.

Тип возвращаемого значения:

None

tag(value)

Преобразует значение в тегированное представление при необходимости.

Параметры:: значение (Any) –
Тип возвращаемого значения:: dict[str, Any]

untag(value)

Преобразует тегированное представление обратно в исходный тип.

Параметры:: значение (dict[str, Any]) –
Тип возвращаемого значения:: Any

class flask.json.tag.JSONTag(serializer)

Базовый класс для определения тегов типов для TaggedJSONSerializer.

Параметры:: сериализатор (TaggedJSONSerializer) –

check(value)

Проверяет, должно ли данное значение быть помечено этим тегом.

Параметры:: значение (Any) –
Тип возвращаемого значения:: bool

key: str | None = None: Тег для маркировки сериализованного объекта. Если None, этот тег используется только как промежуточный шаг во время тегирования.

tag(value)

Преобразует значение в допустимый тип JSON и добавляет вокруг него структуру тега.

Параметры:: значение (Any) –
Тип возвращаемого значения:: Any

to_json(value)

Преобразует объект Python в объект, который является допустимым типом JSON. Тег будет добавлен позже.

Параметры:: значение (Any) –
Тип возвращаемого значения:: Any

to_python(value)

Преобразует JSON-представление обратно в правильный тип. Тег уже будет удален.

Параметры:: значение (Any) –
Тип возвращаемого значения:: Any

END_OF_DOCUMENT_MARKER

Давайте рассмотрим пример, который добавляет поддержку OrderedDict. Словари не имеют порядка в JSON, поэтому для обработки этого мы будем выгружать элементы в виде списка пар [key, value]. Подклассируйте JSONTag и присвойте ему новый ключ ' od' для идентификации типа. Сериализатор сеанса обрабатывает словари в первую очередь, поэтому вставьте новый тег в начало порядка, так как OrderedDict должен быть обработан перед dict.

from flask.json.tag import JSONTag

class TagOrderedDict(JSONTag):
    __slots__ = ('serializer',)
    key = ' od'

    def check(self, value):
        return isinstance(value, OrderedDict)

    def to_json(self, value):
        return [[k, self.serializer.tag(v)] for k, v in iteritems(value)]

    def to_python(self, value):
        return OrderedDict(value)

app.session_interface.serializer.register(TagOrderedDict, index=0)

Обработка шаблонов

flask.render_template(template_name_or_list, **context)

Отобразить шаблон по имени с заданным контекстом.

Параметры:

template_name_or_list (str | Template | list[str | jinja2.environment.Template]) – Имя шаблона для отображения. Если задан список, будет отображено первое существующее имя.
context (Any) – Переменные, доступные в шаблоне.

Тип возвращаемого значения:

flask.render_template_string(source, **context)

Отобразить шаблон из заданной строки исходного кода с заданным контекстом.

Параметры:

source (str) – Исходный код шаблона для отображения.
context (Any) – Переменные, доступные в шаблоне.

Тип возвращаемого значения:

flask.stream_template(template_name_or_list, **context)

Отобразить шаблон по имени с заданным контекстом в виде потока. Это возвращает итератор строк, который можно использовать в качестве потокового ответа из представления.

Параметры:

template_name_or_list (str | Template | list[str | jinja2.environment.Template]) – Имя шаблона для отображения. Если задан список, будет отображено первое существующее имя.
context (Any) – Переменные, доступные в шаблоне.

Тип возвращаемого значения:

Iterator[str]

Изменения

Введено в версии 2.2.

flask.stream_template_string(source, **context)

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

Параметры:

source (str) – Исходный код шаблона для отображения.
context (Any) – Переменные, доступные в шаблоне.

Тип возвращаемого значения:

Iterator[str]

Изменения

Введено в версии 2.2.

flask.get_template_attribute(template_name, attribute)

Загружает макрос (или переменную), экспортируемый шаблоном. Это можно использовать для вызова макроса из кода Python. Если, например, у вас есть шаблон с именем _cider.html со следующим содержимым:

{% macro hello(name) %}Hello {{ name }}!{% endmacro %}

Вы можете получить доступ к нему в коде Python так:

hello = get_template_attribute('_cider.html', 'hello')
return hello('World')

Изменения

Введено в версии 0.2.

Параметры:

template_name (str) – имя шаблона
attribute (str) – имя переменной или макроса для доступа

Тип возвращаемого значения:

END_OF_DOCUMENT_MARKER

Настройка

class flask.Config(root_path, defaults=None)

Работает точно так же, как словарь, но предоставляет способы заполнения его из файлов или специальных словарей. Существуют два распространённых шаблона для заполнения конфигурации.

Вы можете заполнить конфигурацию из файла конфигурации:

app.config.from_pyfile('yourconfig.cfg')

Или, как альтернативу, вы можете определить параметры конфигурации в модуле, который вызывает from_object(), или указать путь импорта к модулю, который должен быть загружен. Также можно указать использовать тот же модуль и предоставить значения конфигурации непосредственно перед вызовом:

DEBUG = True
SECRET_KEY = 'development key'
app.config.from_object(__name__)

В обоих случаях (загрузка из любого файла Python или из модулей) в конфигурацию добавляются только ключи с заглавными буквами. Это позволяет использовать значения с маленькими буквами в файле конфигурации для временных значений, которые не добавляются в саму конфигурацию, или определять ключи конфигурации в том же файле, что и реализация приложения.

Вероятно, наиболее интересный способ загрузки конфигурации — из переменной окружения, указывающей на файл:

app.config.from_envvar('YOURAPPLICATION_SETTINGS')

В этом случае перед запуском приложения необходимо установить эту переменную окружения на файл, который вы хотите использовать. В Linux и OS X используйте оператор export:

export YOURAPPLICATION_SETTINGS='/path/to/config/file'

В Windows используйте set вместо этого.

Параметры:

root_path (str | os.PathLike) – путь, относительно которого считываются файлы. Когда объект конфигурации создаётся приложением, это путь корня приложения root_path.
defaults (dict | None) – необязательный словарь значений по умолчанию

from_envvar(variable_name, silent=False)

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

app.config.from_pyfile(os.environ['YOURAPPLICATION_SETTINGS'])

Параметры:

variable_name (str) – имя переменной окружения
silent (bool) – установить в True , если вы хотите, чтобы ошибки при отсутствии файла игнорировались.

Возвращаемое значение:

True , если файл был загружен успешно.

Тип возвращаемого значения:

from_file(filename, load, silent=False, text=True)

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

import json
app.config.from_file("config.json", load=json.load)

import tomllib
app.config.from_file("config.toml", load=tomllib.load, text=False)

Параметры:

filename (str | PathLike) – путь к файлу данных. Это может быть абсолютный путь или относительный к корневому пути конфигурации.
load (Callable[[Reader], Mapping] где Reader реализует метод read.) – функция, которая принимает дескриптор файла и возвращает отображение загруженных данных из файла.
silent (bool) – игнорировать файл, если он не существует.
text (bool) – открыть файл в текстовом или двоичном режиме.

Возвращаемое значение:

True , если файл был загружен успешно.

Тип возвращаемого значения:

Изменения

Изменено в версии 2.3: Добавлен параметр text.

Введено в версии 2.0.

from_mapping(mapping=None, **kwargs)

Обновляет конфигурацию, как update() игнорируя элементы с ключами, не имеющими заглавных букв.

Возвращаемое значение:

Всегда возвращает True.

Параметры:

mapping (Mapping[str, Any] | None) –
kwargs (Any) –

Тип возвращаемого значения:

Изменения

Введено в версии 0.11.

from_object(obj)

Обновляет значения из заданного объекта. Объект может быть одного из двух типов:

строка: в этом случае будет импортирован объект с этим именем
ссылка на фактический объект: этот объект используется непосредственно

Объекты обычно представляют собой модули или классы. from_object() загружает только атрибуты модуля/класса с заглавными буквами. Объект dict не будет работать с from_object(), потому что ключи объекта dict не являются атрибутами класса dict.

Пример конфигурации на основе модуля:

app.config.from_object('yourapplication.default_config')
from yourapplication import default_config
app.config.from_object(default_config)

Над объектом перед загрузкой ничего не выполняется. Если объект — класс и имеет атрибуты @property, его необходимо создать экземпляр, прежде чем передавать в этот метод.

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

См. Разработка/Производство для примера конфигурации на основе класса с использованием from_object().

Параметры:: obj (object | str) – имя импорта или объект
Тип возвращаемого значения:: None

from_prefixed_env(prefix='FLASK', *, loads=<function loads>)

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

Ключи загружаются в sorted() порядке.

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

Конкретные элементы вложенных словарей могут быть установлены, разделив ключи двойными нижними подчёркиваниями (__). Если промежуточный ключ не существует, он будет инициализирован пустым словарем.

Параметры:

prefix (str) – Загрузить переменные окружения, начинающиеся с этого префикса, разделённого нижним подчёркиванием (_).
loads (Callable[[str], Any]) – Передайте каждое строковое значение этой функции и используйте возвращаемое значение в качестве значения конфигурации. Если возникает какая-либо ошибка, она игнорируется, и значение остаётся строкой. По умолчанию json.loads().

Тип возвращаемого значения:

Изменения

Введено в версии 2.1.

from_pyfile(filename, silent=False)

Обновляет значения в конфигурации из файла Python. Эта функция ведет себя так, как если бы файл был импортирован как модуль с помощью функции from_object().

Параметры:

filename (str | PathLike) – имя файла конфигурации. Это может быть как абсолютный путь к файлу, так и относительный путь к корневой папке.
silent (bool) – установите в True значение, если хотите получить молчаливую обработку ошибок при отсутствии файла.

Возвращаемое значение:

True если файл был загружен успешно.

Тип возвращаемого значения:

Изменения

Введено в версии 0.7: silent параметр.

get_namespace(namespace, lowercase=True, trim_namespace=True)

Возвращает словарь, содержащий подмножество параметров конфигурации, соответствующих заданному пространству имен/префиксу. Пример использования:

app.config['IMAGE_STORE_TYPE'] = 'fs'
app.config['IMAGE_STORE_PATH'] = '/var/app/images'
app.config['IMAGE_STORE_BASE_URL'] = 'http://img.website.com'
image_store_config = app.config.get_namespace('IMAGE_STORE_')

Полученный словарь image_store_config будет выглядеть так:

{
    'type': 'fs',
    'path': '/var/app/images',
    'base_url': 'http://img.website.com'
}

Это часто бывает полезно, когда параметры конфигурации напрямую соответствуют ключевым аргументам в функциях или конструкторах классов.

Параметры:

namespace (str) – пространство имен конфигурации
lowercase (bool) – флаг, указывающий, должны ли ключи результирующего словаря быть в нижнем регистре
trim_namespace (bool) – флаг, указывающий, должны ли ключи результирующего словаря не включать пространство имен

Тип возвращаемого значения:

dict[str, Any]

Изменения

Введено в версии 0.11.

Справочные данные по потокам

flask.stream_with_context(generator_or_function)

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

Однако эта функция может помочь вам сохранить контекст на более длительное время:

from flask import stream_with_context, request, Response

@app.route('/stream')
def streamed_response():
    @stream_with_context
    def generate():
        yield 'Hello '
        yield request.args['name']
        yield '!'
    return Response(generate())

В качестве альтернативы, она также может использоваться вокруг конкретного генератора:

from flask import stream_with_context, request, Response

@app.route('/stream')
def streamed_response():
    def generate():
        yield 'Hello '
        yield request.args['name']
        yield '!'
    return Response(stream_with_context(generate()))

Изменения

Введено в версии 0.9.

Параметры:: generator_or_function (Iterator | Callable[[...], Iterator]) –
Тип возвращаемого значения:: Iterator

Полезные внутренние компоненты

class flask.ctx.RequestContext(app, environ, request=None, session=None)

Контекст запроса содержит информацию о каждом запросе. Приложение Flask создаёт и помещает его в начале запроса, а затем извлекает в конце. Он создаёт адаптер URL и объект запроса для предоставленной среды WSGI.

Не пытайтесь использовать этот класс напрямую, вместо этого используйте test_request_context() и request_context() для создания этого объекта.

Когда контекст запроса извлекается, он выполнит все функции, зарегистрированные в приложении для выполнения завершающих действий (teardown_request()).

Контекст запроса автоматически извлекается в конце запроса. При использовании интерактивного отладчика контекст будет восстановлен, поэтому request по-прежнему доступен. Аналогично, клиент тестирования может сохранить контекст после завершения запроса. Однако функции завершения могут уже закрыть некоторые ресурсы, такие как подключения к базе данных.

Параметры:

app (Flask) –
environ (dict) –
request (Request | None) –
session (SessionMixin | None) –

copy()

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

Изменения

Изменено в версии 1.1: Используется текущий объект сессии вместо перезагрузки исходных данных. Это предотвращает flask.session от указания на устаревший объект.

Добавлена в версии 0.10.

Тип возвращаемого значения:: RequestContext

match_request()

Может быть переопределён подклассом для подключения к сопоставлению запроса.

Тип возвращаемого значения:: None

pop(exc=<object object>)

Извлекает контекст запроса и отвязывает его. Это также вызовет выполнение функций, зарегистрированных декоратором teardown_request().

Изменения

Изменено в версии 0.9: Добавлен аргумент exc.

Параметры:: exc (BaseException | None) –
Тип возвращаемого значения:: None

flask.globals.request_ctx

Текущий RequestContext. Если активный контекст запроса отсутствует, обращение к атрибутам этого прокси вызовет RuntimeError.

Это внутренний объект, который необходим для обработки запросов Flask. Доступ к нему обычно не нужен. Скорее всего, вам нужны request и session.

class flask.ctx.AppContext(app)

Контекст приложения содержит информацию, специфичную для приложения. Контекст приложения создаётся и помещается в начало каждого запроса, если он ещё не активен. Контекст приложения также помещается при выполнении команд CLI.

Параметры:: app (Flask) –

pop(exc=<object object>)

Извлекает контекст приложения.

Параметры:: exc (BaseException | None) –
Тип возвращаемого значения:: None

push()

Связывает контекст приложения с текущим контекстом.

Тип возвращаемого значения:: None

flask.globals.app_ctx

Текущий AppContext. Если активный контекст приложения отсутствует, обращение к атрибутам этого прокси вызовет RuntimeError.

Это внутренний объект, который необходим для обработки запросов Flask. Доступ к нему обычно не нужен. Скорее всего, вам нужны current_app и g вместо этого.

class flask.blueprints.BlueprintSetupState(blueprint, app, options, first_registration)

Временный объект-хранилище для регистрации модуля с приложением. Экземпляр этого класса создаётся методом make_setup_state() и впоследствии передаётся во все функции обратного вызова регистрации.

Параметры:

blueprint (Модуль) –
app (Приложение) –
options (t.Any) –
first_registration (bool) –

add_url_rule(rule, endpoint=None, view_func=None, **options)

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

Параметры:

rule (str) –
endpoint (str | None) –
view_func (Callable | None) –
options (Any) –

Тип возвращаемого значения:

None

app: ссылка на текущее приложение

blueprint: ссылка на модуль, который создал этот объект состояния.

first_registration: так как модули могут быть зарегистрированы в приложении несколько раз, и не всё нужно регистрировать многократно, этот атрибут можно использовать для определения, был ли модуль зарегистрирован ранее.

options: словарь со всеми параметрами, которые были переданы методу register_blueprint().

subdomain: Поддомен, для которого должен быть активен модуль, None в противном случае.

url_defaults: Словарь с значениями по умолчанию для URL, которые были определены с помощью модуля.

url_prefix: Префикс, который должен использоваться для всех URL, определённых в модуле.

Сигналы

Сигналы предоставляются библиотекой Blinker. См. Сигналы для введения.

flask.template_rendered

Этот сигнал отправляется, когда шаблон успешно отрисован. Сигнал вызывается с экземпляром шаблона, как template и контекстом как словарь (назван context).

Пример подписчика:

def log_template_renders(sender, template, context, **extra):
    sender.logger.debug('Rendering template "%s" with context %s',
                        template.name or 'string template',
                        context)

from flask import template_rendered
template_rendered.connect(log_template_renders, app)

flask.before_render_template

Этот сигнал отправляется перед процессом отрисовки шаблона. Сигнал вызывается с экземпляром шаблона, как template и контекстом как словарь (назван context).

Пример подписчика:

def log_template_renders(sender, template, context, **extra):
    sender.logger.debug('Rendering template "%s" with context %s',
                        template.name or 'string template',
                        context)

from flask import before_render_template
before_render_template.connect(log_template_renders, app)

flask.request_started

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

Пример подписчика:

def log_request(sender, **extra):
    sender.logger.debug('Request context is set up')

from flask import request_started
request_started.connect(log_request, app)

flask.request_finished

Этот сигнал отправляется непосредственно перед отправкой ответа клиенту. Ему передаётся ответ, который нужно отправить, под именем response.

Пример подписчика:

def log_response(sender, response, **extra):
    sender.logger.debug('Request context is about to close down. '
                        'Response: %s', response)

from flask import request_finished
request_finished.connect(log_response, app)

flask.got_request_exception

Этот сигнал отправляется, когда во время обработки запроса происходит необработанное исключение, включая отладку. Исключение передаётся подписчику как exception.

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

Этот пример показывает, как выполнить дополнительное логирование, если было вызвано теоретическое SecurityException:

from flask import got_request_exception

def log_security_exception(sender, exception, **extra):
    if not isinstance(exception, SecurityException):
        return

    security_logger.exception(
        f"SecurityException at {request.url!r}",
        exc_info=exception,
    )

got_request_exception.connect(log_security_exception, app)

flask.request_tearing_down

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

Пример подписчика:

def close_db_connection(sender, **extra):
    session.close()

from flask import request_tearing_down
request_tearing_down.connect(close_db_connection, app)

Начиная с Flask 0.9, ему также будет передан exc аргумент, содержащий ссылку на исключение, вызвавшее завершение, если оно имелось.

flask.appcontext_tearing_down

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

Пример подписчика:

def close_db_connection(sender, **extra):
    session.close()

from flask import appcontext_tearing_down
appcontext_tearing_down.connect(close_db_connection, app)

Ему также будет передан exc аргумент, содержащий ссылку на исключение, вызвавшее завершение, если оно имелось.

flask.appcontext_pushed

Этот сигнал отправляется при добавлении контекста приложения. Отправителем является приложение. Это обычно полезно для тестов в единицах, чтобы временно добавить информацию. Например, его можно использовать для установки ресурса в g объект.

Пример использования:

from contextlib import contextmanager
from flask import appcontext_pushed

@contextmanager
def user_set(app, user):
    def handler(sender, **kwargs):
        g.user = user
    with appcontext_pushed.connected_to(handler, app):
        yield

И в коде теста:

def test_user_me(self):
    with user_set(app, 'john'):
        c = app.test_client()
        resp = c.get('/users/me')
        assert resp.data == 'username=john'

Changelog

Новое в версии 0.10.

flask.appcontext_popped: Этот сигнал отправляется при удалении контекста приложения. Отправителем является приложение. Это обычно совпадает с сигналом appcontext_tearing_down.

Changelog

Новое в версии 0.10.

flask.message_flashed

Этот сигнал отправляется, когда приложение отображает сообщение. Сообщение передаётся как message аргумент, а категория как category.

Пример подписчика:

recorded = []
def record(sender, message, category, **extra):
    recorded.append((message, category))

from flask import message_flashed
message_flashed.connect(record, app)

Changelog

Новое в версии 0.10.

Базовые представления на основе классов

Журнал изменений

Новая версия 0.7.

class flask.views.View

Подклассируйте этот класс и переопределите dispatch_request(), чтобы создать общее представление на основе класса. Вызовите as_view() для создания функции представления, которая создаёт экземпляр класса с заданными аргументами и вызывает его метод dispatch_request с любыми переменными URL.

Подробное руководство см. в разделе Представления на основе классов.

class Hello(View):
    init_every_request = False

    def dispatch_request(self, name):
        return f"Hello, {name}!"

app.add_url_rule(
    "/hello/<name>", view_func=Hello.as_view("hello")
)

Установите methods для изменения методов, которые принимает представление.

Установите decorators для применения списка декораторов к сгенерированной функции представления. Декораторы, применённые к самому классу, не будут применены к сгенерированной функции представления!

Установите init_every_request в False, для повышения эффективности, если вам не нужно хранить данные, относящиеся к запросу, в self.

classmethod as_view(name, *class_args, **class_kwargs)

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

По умолчанию сгенерированное представление будет создавать новый экземпляр класса представления для каждого запроса и вызывать его метод dispatch_request(). Если класс представления установит init_every_request в False, один и тот же экземпляр будет использоваться для каждого запроса.

Кроме name, все остальные аргументы, переданные в этот метод, передаются методу класса представления __init__.

Журнал изменений

Изменено в версии 2.2: Добавлен атрибут класса init_every_request.

Параметры:

name (str) –
class_args (t.Any) –
class_kwargs (t.Any) –

Тип возвращаемого значения:

ft.RouteCallable

decorators: ClassVar[list[Callable]] = []: Список декораторов для применения, в порядке, к сгенерированной функции представления. Помните, что синтаксис @decorator применяется снизу вверх, поэтому первый декоратор в списке будет самым нижним декоратором.

Журнал изменений

Новая версия 0.8.

dispatch_request()

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

Тип возвращаемого значения:: ft.ResponseReturnValue

init_every_request: ClassVar[bool] = True

По умолчанию создаёт новый экземпляр этого класса представления для каждого запроса. Если подкласс представления устанавливает это значение в False, один и тот же экземпляр используется для каждого запроса.

Один экземпляр более эффективен, особенно если при инициализации выполняется сложная настройка. Однако хранение данных в self больше не безопасно для нескольких запросов, и вместо этого следует использовать g.

Журнал изменений

Новая версия 2.2.

methods: ClassVar[Collection[str] | None] = None: Методы, для которых зарегистрировано это представление. Использует тот же по умолчанию (["GET", "HEAD", "OPTIONS"]) что и route и add_url_rule по умолчанию.

provide_automatic_options: ClassVar[bool | None] = None: Управляет тем, обрабатывается ли метод OPTIONS автоматически. Использует тот же по умолчанию (True) что и route и add_url_rule по умолчанию.

class flask.views.MethodView

Передаёт методы запроса соответствующим методам экземпляра. Например, если вы реализуете метод get, он будет использоваться для обработки запросов GET.

Это может быть полезно для определения API REST.

methods автоматически устанавливается на основе методов, определённых в классе.

Подробное руководство см. в разделе Представления на основе классов.

class CounterAPI(MethodView):
    def get(self):
        return str(session.get("counter", 0))

    def post(self):
        session["counter"] = session.get("counter", 0) + 1
        return redirect(url_for("counter"))

app.add_url_rule(
    "/counter", view_func=CounterAPI.as_view("counter")
)

dispatch_request(**kwargs)

Параметры:: kwargs (t.Any) –
Тип возвращаемого значения:: ft.ResponseReturnValue

Регистрация маршрутов URL

В целом, есть три способа определить правила для системы маршрутизации:

Можно использовать декоратор flask.Flask.route().
Можно использовать функцию flask.Flask.add_url_rule().
Можно напрямую получить доступ к основной системе маршрутизации Werkzeug, которая представлена как flask.Flask.url_map.

Переменные части маршрута можно указать с помощью угловых скобок (/user/<username>). По умолчанию переменная часть в URL принимает любую строку без слеша, однако можно указать другой преобразователь, используя <converter:name>.

Переменные части передаются функции представления в качестве ключевых аргументов.

Доступны следующие преобразователи:

`string`	принимает любой текст без слеша (по умолчанию)
`int`	принимает целые числа
`float`	подобно `int`, но для чисел с плавающей точкой
`path`	подобно умолчанию, но также принимает слеши
`any`	сопоставляет один из предоставленных элементов
`uuid`	принимает строки UUID

Пользовательские преобразователи можно определить с помощью flask.Flask.url_map.

Вот несколько примеров:

@app.route('/')
def index():
    pass

@app.route('/<username>')
def show_user(username):
    pass

@app.route('/post/<int:post_id>')
def show_post(post_id):
    pass

Важно помнить, как Flask обрабатывает косые черты в конце URL. Идея состоит в том, чтобы сохранить уникальность каждого URL, поэтому применяются следующие правила:

Если правило заканчивается слешем, а пользователь запрашивает его без слеша, пользователь автоматически перенаправляется на ту же страницу со слешем в конце.
Если правило не заканчивается слешем, а пользователь запрашивает страницу со слешем в конце, генерируется ошибка 404 «Не найдено».

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

Вы также можете определить несколько правил для одной и той же функции. Однако они должны быть уникальными. Также можно указать значения по умолчанию. Например, вот определение URL, принимающего необязательную страницу:

@app.route('/users/', defaults={'page': 1})
@app.route('/users/page/<int:page>')
def show_users(page):
    pass

Это указывает, что /users/ будет URL для первой страницы и /users/page/N будет URL для страницы N.

Если URL содержит значение по умолчанию, он будет перенаправлен на его упрощенную форму с перенаправлением 301. В приведенном выше примере /users/page/1 будет перенаправлен на /users/. Если ваш маршрут обрабатывает запросы GET и POST, убедитесь, что маршрут по умолчанию обрабатывает только GET, так как перенаправления не могут сохранить данные формы.

@app.route('/region/', defaults={'id': 1})
@app.route('/region/<int:id>', methods=['GET', 'POST'])
def region(id):
   pass

Вот параметры, которые принимает route() и add_url_rule(). Единственное различие состоит в том, что с параметром route функция представления определяется с помощью декоратора вместо параметра view_func.

`rule`	правило URL в виде строки
`endpoint`	точку входа для зарегистрированного правила URL. Flask предполагает, что имя функции представления является именем точки входа, если это не указано явно.
`view_func`	функция, которая вызывается при обработке запроса к предоставленной точке входа. Если она не указана, можно указать функцию позже, сохранив ее в словаре `view_functions` с точкой входа в качестве ключа.
`defaults`	Словарь со значениями по умолчанию для этого правила. См. пример выше, чтобы понять, как работают значения по умолчанию.
`subdomain`	указывает правило для поддомена в случае использования сопоставления поддоменов. Если не указано, предполагается использование поддомена по умолчанию.
`**options`	опции, передаваемые в объект `Rule` из Werkzeug. Изменения в Werkzeug связаны с обработкой параметров метода. methods — это список методов, к которым должно быть ограничено это правило (`GET`, `POST` и т.д.). По умолчанию правило просто прослушивает `GET` (и неявно `HEAD`). Начиная с Flask 0.6, `OPTIONS` неявно добавляется и обрабатывается стандартной обработкой запросов. Они должны быть указаны в качестве ключевых аргументов.

Параметры функции представления

Для внутреннего использования функции представления могут иметь атрибуты, настраивающие поведение, над которым функция представления обычно не имеет контроля. Следующие атрибуты могут быть предоставлены необязательно для переопределения некоторых значений по умолчанию для add_url_rule() или общего поведения:

__name__: Имя функции по умолчанию используется как точка входа. Если точка входа указана явно, используется это значение. Кроме того, по умолчанию к этому значению добавляется имя схемы, что нельзя настроить из самой функции.
methods: Если методы не указаны при добавлении правила URL, Flask будет проверять сам объект функции представления, если существует атрибут methods. Если он существует, информация о методах будет взята оттуда.
provide_automatic_options: Если этот атрибут установлен, Flask либо включит, либо выключит автоматическое создание HTTP OPTIONS ответа. Это может быть полезно при работе с декораторами, которые хотят настраивать OPTIONS ответ на основе представления.
required_methods: Если этот атрибут установлен, Flask всегда будет добавлять эти методы при регистрации правила URL, даже если методы были явно переопределены в вызове route().

Полный пример:

def index():
    if request.method == 'OPTIONS':
        # custom options handling here
        ...
    return 'Hello World!'
index.provide_automatic_options = False
index.methods = ['GET', 'OPTIONS']

app.add_url_rule('/', index)

Журнал изменений

Добавлено в версии 0.8: Функциональность provide_automatic_options была добавлена.

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

class flask.cli.FlaskGroup(add_default_commands=True, create_app=None, add_version_option=True, load_dotenv=True, set_debug_flag=True, **extra)

Специальный подкласс группы AppGroup, поддерживающий загрузку дополнительных команд из конфигурированного приложения Flask. Разработчику обычно не нужно взаимодействовать с этим классом, но в некоторых очень продвинутых случаях может быть целесообразно создать экземпляр этого класса. Смотрите Пользовательские скрипты.

Параметры:

add_default_commands (bool) – если True, то будут добавлены команды run и shell по умолчанию.
add_version_option (bool) – добавляет опцию --version.
create_app (t.Callable[..., Flask] | None) – необязательный обратный вызов, которому передаётся информация о скрипте и который возвращает загруженное приложение.
load_dotenv (bool) – Загрузить ближайшие файлы .env и .flaskenv для установки переменных окружения. Также изменит текущую рабочую директорию на директорию, содержащую первый найденный файл.
set_debug_flag (bool) – Установить флаг отладки приложения.
extra (t.Any) –

Журнал изменений

Изменено в версии 2.2: Добавлены опции -A/--app, --debug/--no-debug, -e/--env-file.

Изменено в версии 2.2: При выполнении команд app.cli контекст приложения помещается, поэтому @with_appcontext больше не требуется для этих команд.

Изменено в версии 1.0: Если установлено, python-dotenv будет использоваться для загрузки переменных окружения из файлов .env и .flaskenv.

get_command(ctx, name): Принимая контекст и имя команды, возвращает объект Command , если он существует, в противном случае возвращает None.

list_commands(ctx): Возвращает список имён подкоманд в порядке их появления.

make_context(info_name, args, parent=None, **extra)

Эта функция, получив имя info и аргументы, запускает парсинг и создаёт новый Context. Однако она не вызывает фактический обратный вызов команды.

Чтобы быстро настроить используемый класс контекста без переопределения этого метода, установите атрибут context_class.

Параметры:

info_name (str | None) – имя info для этого вызова. Обычно это наиболее описательное имя для скрипта или команды. Для скрипта верхнего уровня это обычно имя скрипта, для команд ниже – имя команды.
args (list[str]) – аргументы для парсинга в виде списка строк.
parent (Context | None) – родительский контекст, если доступен.
extra (Any) – дополнительные ключевые аргументы, переданные конструктору контекста.

Тип возвращаемого значения:

Context

Изменено в версии 8.0: Добавлен атрибут context_class.

parse_args(ctx, args)

Принимая контекст и список аргументов, создаёт парсер и парсит аргументы, затем изменяет контекст по мере необходимости. Автоматически вызывается методом make_context().

Параметры:

ctx (Context) –
args (list[str]) –

Тип возвращаемого значения:

list[str]

class flask.cli.AppGroup(name=None, commands=None, **attrs)

Работает аналогично обычной группе click Group, но изменяет поведение декоратора command() таким образом, что он автоматически оборачивает функции в with_appcontext().

Не путать с FlaskGroup.

Параметры:

name (str | None) –
commands (MutableMapping[str, Command] | Sequence[Command] | None) –
attrs (Any) –

command(*args, **kwargs): Работает точно так же, как метод с таким же именем в обычной группе click.Group, но оборачивает обратные вызовы в with_appcontext(), если это не отключено путём передачи with_appcontext=False.

group(*args, **kwargs): Работает точно так же, как метод с таким же именем в обычной группе click.Group, но по умолчанию использует класс группы AppGroup.

class flask.cli.ScriptInfo(app_import_path=None, create_app=None, set_debug_flag=True)

Вспомогательный объект для работы с приложениями Flask. Обычно нет необходимости взаимодействовать с ним напрямую, так как он используется во внутренней обработке вызовов click. В будущих версиях Flask этот объект, скорее всего, будет играть более важную роль. Обычно он создаётся автоматически объектом FlaskGroup, но вы также можете создать его вручную и передать как объект click.

Параметры:

app_import_path (str | None) –
create_app (t.Callable[..., Flask] | None) –
set_debug_flag (bool) –

app_import_path: Необязательный путь импорта приложения Flask.

create_app: Необязательная функция, которая принимает информацию о скрипте для создания экземпляра приложения.

data: dict[t.Any, t.Any]: Словарь с произвольной информацией, которую можно связать с данной информацией о скрипте.

load_app()

Загружает приложение Flask (если оно ещё не загружено) и возвращает его. Многократный вызов этой функции просто вернёт уже загруженное приложение.

Тип возвращаемого значения:: Flask

flask.cli.load_dotenv(path=None)

Загрузка файлов «dotenv» в порядке приоритета для установки переменных окружения.

Если переменная окружения уже установлена, она не перезаписывается, поэтому файлы, расположенные раньше в списке, имеют приоритет над последующими.

Это ничего не делает, если модуль python-dotenv не установлен.

Параметры:: path (str | PathLike | None) – Загрузка файла по данному пути вместо поиска.
Возвращаемое значение:: True если файл был загружен.
Тип возвращаемого значения:: bool

Изменения

Изменено в версии 2.0: Текущий каталог не изменяется на расположение загруженного файла.

Изменено в версии 2.0: При загрузке файлов env используется кодировка по умолчанию UTF-8.

Изменено в версии 1.1.0: Возвращает False если python-dotenv не установлен или указанный путь не является файлом.

Добавлена в версии 1.0.

flask.cli.with_appcontext(f)

Оборачивает обратный вызов, гарантируя, что он будет выполнен в контексте приложения скрипта.

Пользовательские команды (и их параметры), зарегистрированные под app.cli или blueprint.cli всегда имеют доступ к контексту приложения, этот декоратор в этом случае не требуется.

Изменения

Изменено в версии 2.2: Контекст приложения активен как для подкоманд, так и для обратного вызова, помеченного декоратором. Контекст приложения всегда доступен для команд app.cli и обратных вызовов параметров.

flask.cli.pass_script_info(f)

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

Параметры:: f (t.Callable[te.Concatenate[T, P], R]) –
Тип возвращаемого значения:: t.Callable[P, R]

flask.cli.run_command = <Command run>

Запуск локального сервера разработки.

Этот сервер предназначен только для целей разработки. Он не обеспечивает стабильность, безопасность или производительность серверов WSGI для производства.

Релоадер и отладчик включены по умолчанию с опцией «–debug».

Параметры:

args (Any) –
kwargs (Any) –

Тип возвращаемого значения:

flask.cli.shell_command = <Command shell>

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

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

Параметры:

args (Any) –
kwargs (Any) –

Тип возвращаемого значения: