API

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

Объект приложения

class flask.Flask(import_name, static_url_path=None, static_folder='static', static_host=None, host_matching=False, subdomain_matching=False, template_folder='templates', instance_path=None, instance_relative_config=False, root_path=None)

Объект flask реализует приложение WSGI и служит центральным объектом. Ему передаётся имя модуля или пакета приложения. После создания он будет выступать центральным регистром для функций представления, правил URL, конфигурации шаблонов и многого другого.

Имя пакета используется для разрешения ресурсов изнутри пакета или папки, в которой находится модуль, в зависимости от того, разрешается ли параметр package в фактический пакет Python (папка с файлом __init__.py внутри) или стандартный модуль (просто файл .py).

Дополнительную информацию о загрузке ресурсов см. в open_resource().

Обычно вы создаёте экземпляр Flask в главном модуле или в файле __init__.py вашего пакета так:

from flask import Flask
app = Flask(__name__)

О первом параметре

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

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

Например, если ваше приложение определено в yourapplication/app.py , вы должны создать его с одной из двух версий ниже:

app = Flask('yourapplication')
app = Flask(__name__.split('.')[0])

Почему? Приложение будет работать даже с __name__, благодаря тому, как ищутся ресурсы. Однако это затруднит отладку. Некоторые расширения могут делать предположения, основанные на имени импорта вашего приложения. Например, расширение Flask-SQLAlchemy будет искать код в вашем приложении, который вызвал запрос SQL в режиме отладки. Если имя импорта не настроено должным образом, эта информация об отладке теряется. (Например, он будет собирать запросы SQL только в yourapplication.app , а не в yourapplication.views.frontend).

Изменения

В версии 1.0: Добавлены параметры host_matching и static_host.

В версии 1.0: Добавлен параметр subdomain_matching. Сопоставление по поддомену теперь нужно включать вручную. Установка SERVER_NAME не подразумевает его включения.

В версии 0.11: Добавлен параметр root_path.

В версии 0.8: Добавлены параметры instance_path и instance_relative_config.

В версии 0.7: Добавлены параметры static_url_path, static_folder и template_folder.

Параметры

• import_name – имя пакета приложения
• static_url_path – может быть использован для указания другого пути к статическим файлам в веб-приложении. По умолчанию используется имя папки static_folder.
• static_folder – Папка со статическими файлами, которые обслуживаются по адресу static_url_path. Относительно корня приложения root_path или абсолютный путь. По умолчанию 'static'.
• static_host – хост, который следует использовать при добавлении статического маршрута. По умолчанию None. Требуется при использовании host_matching=True с настроенным static_folder.
• host_matching – установить атрибут url_map.host_matching. По умолчанию False.
• subdomain_matching – учитывать поддомен относительно SERVER_NAME при сопоставлении маршрутов. По умолчанию False.
• template_folder – папка, содержащая шаблоны, которые должны использоваться приложением. По умолчанию папка 'templates' в корне приложения.
• instance_path – альтернативный путь к папке приложения. По умолчанию предполагается, что папка 'instance' рядом с пакетом или модулем является путём к экземпляру.
• instance_relative_config – если установлено в True, предполагаются относительные имена файлов для загрузки конфигурации относительно пути к экземпляру, а не корня приложения.
• root_path – Flask по умолчанию автоматически вычисляет путь к корню приложения. В определённых ситуациях это невозможно (например, если пакет является пространством имён пакета Python 3) и необходимо определить его вручную.

add_template_filter(f, name=None)

Регистрация пользовательского фильтра шаблона. Работает точно так же, как декоратор template_filter().

Параметры

name – необязательное имя фильтра, в противном случае используется имя функции.

add_template_global(f, name=None)

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

Изменения

В версии 0.10.

Параметры

name – необязательное имя глобальной функции, в противном случае используется имя функции.

add_template_test(f, name=None)

Регистрация пользовательского теста шаблона. Работает точно так же, как декоратор template_test().

Изменения

В версии 0.10.

Параметры

name – необязательное имя теста, в противном случае используется имя функции.

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

Подключает правило URL. Работает точно так же, как декоратор route(). Если view_func предоставлен, он будет зарегистрирован с конечной точкой.

В основном этот пример:

@app.route('/')
def index():
    pass

Эквивалентен следующему:

def index():
    pass
app.add_url_rule('/', 'index', index)

Если view_func не предоставлен, вам нужно подключить конечную точку к функции представления, как показано ниже:

app.view_functions['index'] = index

Внутренне route() вызывает add_url_rule(), поэтому если вы хотите настроить поведение путём наследования, вам нужно изменить только этот метод.

Дополнительную информацию см. в Регистрация маршрутов URL.

Изменения

Изменено в версии 0.6: OPTIONS автоматически добавляется как метод.

Изменено в версии 0.2: Добавлен параметр view_func.

Параметры

• rule – правило URL как строка
• endpoint – конечная точка для зарегистрированного правила URL. Flask сам предполагает имя функции представления как конечную точку
• view_func – функция, которая вызывается при обработке запроса к указанной конечной точке
• provide_automatic_options – управляет тем, добавляется ли метод OPTIONS автоматически. Это также можно контролировать, установив view_func.provide_automatic_options = False перед добавлением правила.
• options – параметры, передаваемые в объект Rule. Изменение Werkzeug обрабатывает параметры методов. methods — список методов, к которым должно быть ограничено это правило (GET, POST и т. д.). По умолчанию правило просто слушает GET (и неявно HEAD). Начиная с Flask 0.6, OPTIONS неявно добавляется и обрабатывается стандартной обработкой запросов.

after_request(f)

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

Ваша функция должна принимать один параметр — экземпляр response_class, и возвращать новый объект ответа или тот же (см. process_response()).

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

after_request_funcs = None

Словарь со списками функций, которые должны вызываться после каждого запроса. Ключ словаря — имя голубого плана, для которого активна эта функция, None для всех запросов. Это, например, можно использовать для закрытия соединений с базой данных. Для регистрации функции используйте декоратор after_request().

app_context()

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

Контекст приложения автоматически помещается функцией RequestContext.push() при обработке запроса и при запуске команды CLI. Используйте эту функцию для ручного создания контекста в других ситуациях.

with app.app_context():
    init_db()

См. Контекст приложения.

Changelog

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

app_ctx_globals_class

Псевдоним для flask.ctx._AppCtxGlobals

auto_find_instance_path()

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

Changelog

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

before_first_request(f)

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

Функция будет вызвана без аргументов, а ее возвращаемое значение будет проигнорировано.

Changelog

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

before_first_request_funcs = None

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

Changelog

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

before_request(f)

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

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

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

before_request_funcs = None

Словарь со списками функций, которые будут вызваны в начале каждого запроса. Ключом словаря является имя модуля, для которого активна эта функция, или None для всех запросов. Для регистрации функции используйте декоратор before_request().

blueprints = None

Все присоединенные модули в словаре по имени. Модули могут быть присоединены несколько раз, поэтому этот словарь не указывает, сколько раз они были присоединены.

Changelog

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

config = None

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

config_class

Псевдоним для flask.config.Config

context_processor(f)

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

create_global_jinja_loader()

Создает загрузчик для среды Jinja2. Может использоваться для переопределения только загрузчика, сохраняя остальное неизменным. Не рекомендуется переопределять эту функцию. Вместо этого следует переопределить функцию jinja_loader().

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

Changelog

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

create_jinja_environment()

Создает среду Jinja на основе jinja_options и различных методов приложения, связанных с Jinja. Изменение jinja_options после этого не повлияет. Также добавляет в среду глобальные переменные и фильтры, связанные с Flask.

Changelog

Изменено в версии 0.11: Environment.auto_reload устанавливается в соответствии с параметром конфигурации TEMPLATES_AUTO_RELOAD.

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

create_url_adapter(request)

Создает адаптер URL для данного запроса. Адаптер URL создается в момент, когда контекст запроса еще не настроен, поэтому запрос передается явно.

Changelog

Изменено в версии 1.0: SERVER_NAME больше не неявно включает сопоставление по поддоменам. Используйте subdomain_matching вместо этого.

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

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

property debug

Включен ли режим отладки. При использовании flask run для запуска сервера разработки, интерактивный отладчик будет показан для необработанных исключений, а сервер будет перезапущен при изменении кода. Соответствует ключу конфигурации DEBUG. Включается, когда env равно 'development', и переопределяется переменной среды FLASK_DEBUG. Может работать некорректно, если задано в коде.

Не включайте режим отладки при развертывании в рабочей среде.

По умолчанию: True если env равно 'development', или False в противном случае.

default_config = {'APPLICATION_ROOT': '/', 'DEBUG': None, 'ENV': None, 'EXPLAIN_TEMPLATE_LOADING': False, 'JSONIFY_MIMETYPE': 'application/json', 'JSONIFY_PRETTYPRINT_REGULAR': False, 'JSON_AS_ASCII': True, 'JSON_SORT_KEYS': True, 'MAX_CONTENT_LENGTH': None, 'MAX_COOKIE_SIZE': 4093, 'PERMANENT_SESSION_LIFETIME': datetime.timedelta(days=31), 'PREFERRED_URL_SCHEME': 'http', 'PRESERVE_CONTEXT_ON_EXCEPTION': None, 'PROPAGATE_EXCEPTIONS': None, 'SECRET_KEY': None, 'SEND_FILE_MAX_AGE_DEFAULT': datetime.timedelta(seconds=43200), 'SERVER_NAME': None, 'SESSION_COOKIE_DOMAIN': None, 'SESSION_COOKIE_HTTPONLY': True, 'SESSION_COOKIE_NAME': 'session', 'SESSION_COOKIE_PATH': None, 'SESSION_COOKIE_SAMESITE': None, 'SESSION_COOKIE_SECURE': False, 'SESSION_REFRESH_EACH_REQUEST': True, 'TEMPLATES_AUTO_RELOAD': None, 'TESTING': False, 'TRAP_BAD_REQUEST_ERRORS': None, 'TRAP_HTTP_EXCEPTIONS': False, 'USE_X_SENDFILE': False}

Параметры конфигурации по умолчанию.

dispatch_request()

Выполняет распределение запросов. Сопоставляет URL и возвращает возвращаемое значение представления или обработчика ошибок. Это не обязательно должен быть объект ответа. Для преобразования возвращаемого значения в соответствующий объект ответа вызовите make_response().

Changelog

Изменено в версии 0.7: Больше не выполняет обработку исключений, этот код был перемещен в новую функцию full_dispatch_request().

do_teardown_appcontext(exc=<object object>)

Вызывается непосредственно перед извлечением контекста приложения.

При обработке запроса контекст приложения извлекается после контекста запроса. См. do_teardown_request().

Вызывает все функции, помеченные декоратором teardown_appcontext(). Затем отправляется сигнал appcontext_tearing_down.

Вызывается функцией AppContext.pop().

Changelog

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

do_teardown_request(exc=<object object>)

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

Вызывает все функции, помеченные декоратором teardown_request(), и Blueprint.teardown_request(), если запрос обрабатывался планом. В заключение, отправляется сигнал request_tearing_down.

Вызывается методом RequestContext.pop(), который может быть отложен во время тестирования для сохранения доступа к ресурсам.

Параметры

exc – Необработанное исключение, возникшее во время обработки запроса. Обнаруживается из текущей информации об исключении, если не передано. Передаётся каждой функции завершения.

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

Изменено в версии 0.9: Добавлен аргумент exc.

endpoint(endpoint)

Декоратор для регистрации функции в качестве конечной точки. Пример:

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

Параметры

endpoint – имя конечной точки

env

Среда, в которой запущено приложение. Flask и расширения могут активировать поведение на основе среды, например, включить отладочный режим. Соответствует ключу конфигурации ENV. Устанавливается переменной окружения FLASK_ENV и может не работать как ожидается, если установлена в коде.

Не включайте разработку при развертывании в продакшене.

Значение по умолчанию: 'production'

error_handler_spec = None

Словарь всех зарегистрированных обработчиков ошибок. Ключ None для обработчиков ошибок, активных в приложении, в противном случае ключ — имя плана. Каждый ключ указывает на другой словарь, где ключ — код состояния HTTP-исключения. Специальный ключ 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

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

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

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

Параметры

code_or_exception – код обработчика как целое число или произвольное исключение

extensions = None

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

if not hasattr(app, 'extensions'):
    app.extensions = {}
app.extensions['extensionname'] = SomeObject()

Ключ должен соответствовать имени модуля расширения. Например, в случае расширения «Flask-Foo» в flask_foo, ключ будет 'foo'.

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

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

full_dispatch_request()

Обрабатывает запрос, выполняя предварительную и последующую обработку запроса, а также перехват и обработку HTTP-исключений.

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

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

get_send_file_max_age(filename)

Предоставляет значение по умолчанию для параметра cache_timeout для функций send_file().

По умолчанию эта функция возвращает SEND_FILE_MAX_AGE_DEFAULT из конфигурации current_app.

Функции статических файлов, такие как send_from_directory(), используют эту функцию, а send_file() вызывает эту функцию для current_app, если заданное значение cache_timeout равно None. Если значение cache_timeout задано в send_file(), используется это значение; в противном случае вызывается этот метод.

Это позволяет подклассам изменять поведение при отправке файлов на основе имени файла. Например, чтобы установить время кеширования для файлов .js в 60 секунд:

class MyFlask(flask.Flask):
    def get_send_file_max_age(self, name):
        if name.lower().endswith('.js'):
            return 60
        return flask.Flask.get_send_file_max_age(self, name)

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

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

property got_first_request

Этот атрибут устанавливается в True, если приложение начало обработку первого запроса.

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

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

handle_exception(e)

Обрабатывает исключение, для которого не было зарегистрированного обработчика ошибок или которое возникло в обработчике ошибок. Это всегда приводит к ответу 500 InternalServerError.

Всегда отправляет сигнал got_request_exception.

Если propagate_exceptions равно True, например, в отладочном режиме, ошибка будет повторно поднята, чтобы отладчик мог её отобразить. В противном случае исходное исключение записывается в журнал, и возвращается исключение InternalServerError.

Если зарегистрирован обработчик ошибок для InternalServerError или 500, он будет использован. Для единообразия обработчик всегда получит InternalServerError. Исходное необработанное исключение доступно как e.original_exception.

Примечание

До Werkzeug 1.0.0 у InternalServerError не всегда будет атрибут original_exception. Используйте getattr(e, "original_exception", None) для имитации поведения в целях совместимости.

Изменено в версии 1.1.0: Всегда передаёт экземпляр InternalServerError обработчику, устанавливая original_exception в значение необработанной ошибки.

Изменено в версии 1.1.0: after_request функции и другая финализация выполняется даже для стандартного ответа 500, когда нет обработчика.

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

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

handle_http_exception(e)

Обрабатывает HTTP-исключение. По умолчанию это вызовет зарегистрированные обработчики ошибок и вернёт исключение в качестве ответа.

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

Изменено в версии 1.0.3: RoutingException, используемый внутренне для действий, таких как перенаправления слэша во время маршрутизации, не передаётся обработчикам ошибок.

Изменено в версии 1.0: Исключения ищутся по коду и по MRO, поэтому подклассы HTTPExcpetion могут обрабатываться обработчиком по умолчанию для базового HTTPException.

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

handle_url_build_error(error, endpoint, values)

Обрабатывает BuildError в методе url_for().

handle_user_exception(e)

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

Changelog

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

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

property has_static_folder

Это True , если в контейнере привязанного к пакету объекта есть папка для статических файлов.

Changelog

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

import_name = None

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

inject_url_defaults(endpoint, values)

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

Changelog

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

instance_path = None

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

Changelog

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

iter_blueprints()

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

Changelog

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

jinja_env

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

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

jinja_environment

псевдоним flask.templating.Environment

jinja_loader

Загрузчик Jinja для этого объекта, связанного с пакетом.

Changelog

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

jinja_options = {'extensions': ['jinja2.ext.autoescape', 'jinja2.ext.with_']}

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

Изменено в версии 1.1.0: Это dict , а не ImmutableDict для более удобной конфигурации.

json_decoder

псевдоним flask.json.JSONDecoder

json_encoder

псевдоним flask.json.JSONEncoder

log_exception(exc_info)

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

Changelog

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

logger

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

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

Если обработчики не настроены, будет добавлен обработчик по умолчанию. Для получения дополнительной информации см. Логирование.

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

Changelog

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

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

make_config(instance_relative=False)

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

Changelog

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

make_default_options_response()

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

Changelog

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

make_null_session()

Создаёт новую отсутствующую сессию. Вместо переопределения этого метода, рекомендуем заменить session_interface.

Changelog

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

make_response(rv)

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

Параметры

rv –

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

str (unicode in Python 2)

Создаётся объект ответа, в котором строка закодирована в UTF-8 как тело.

bytes (str in Python 2)

Создаётся объект ответа, в котором байты являются телом.

dict

Словарь, который будет сериализован в JSON перед возвращением.

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-приложение. Результат используется для создания объекта ответа.

Changelog

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

make_shell_context()

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

Changelog

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

name

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

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

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

open_instance_resource(resource, mode='rb')

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

Параметры

• resource – имя ресурса. Для доступа к ресурсам внутри подпапок используйте слеши в качестве разделителей.
• mode – режим открытия файла ресурса, по умолчанию «rb».

open_resource(resource, mode='rb')

Открывает ресурс из папки ресурсов приложения. Чтобы понять, как это работает, рассмотрите следующую структуру папок:

/myapplication.py
/schema.sql
/static
    /style.css
/templates
    /layout.html
    /index.html

Если вы хотите открыть файл schema.sql, выполните следующие действия:

with app.open_resource('schema.sql') as f:
    contents = f.read()
    do_something_with(contents)

Параметры

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

open_session(request)

Создаёт или открывает новую сессию. По умолчанию все данные сессии хранятся в подписанном cookie. Для этого необходимо установить secret_key. Вместо переопределения этого метода рекомендуется заменить session_interface.

Параметры

request – экземпляр request_class.

permanent_session_lifetime

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

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

preprocess_request()

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

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

property preserve_context_on_exception

Возвращает значение конфигурации PRESERVE_CONTEXT_ON_EXCEPTION, если оно установлено, иначе возвращает разумное значение по умолчанию.

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

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

process_response(response)

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

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

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

Параметры

response – объект response_class.

Возвращает

новый объект ответа или тот же, должен быть экземпляром response_class.

property propagate_exceptions

Возвращает значение конфигурации PROPAGATE_EXCEPTIONS, если оно установлено, иначе возвращает разумное значение по умолчанию.

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

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

register_blueprint(blueprint, **options)

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

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

Параметры

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

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

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

register_error_handler(code_or_exception, f)

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

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

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

request_class

псевдоним flask.wrappers.Request

request_context(environ)

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

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

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

Параметры

environ – WSGI-среда

response_class

псевдоним flask.wrappers.Response

root_path = None

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

route(rule, **options)

Декоратор, используемый для регистрации функции представления для заданного правила URL. Он делает то же самое, что и add_url_rule(), но предназначен для использования в качестве декоратора:

@app.route('/')
def index():
    return 'Hello World'

Дополнительную информацию см. в разделе Регистрация правил URL.

Параметры

• rule – правило URL в виде строки
• endpoint – конечная точка для зарегистрированного правила URL. Flask предполагает, что имя функции представления является конечной точкой
• options – параметры, которые будут переданы базовому объекту Rule. Изменение в Werkzeug касается обработки параметров метода. methods — список методов, к которым должно быть ограничено это правило (GET, POST и т. д.). По умолчанию правило просто прослушивает GET (и неявно HEAD). Начиная с Flask 0.6, OPTIONS неявно добавляется и обрабатывается стандартной обработкой запросов.

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

Изменения

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

Если установлено, переменные окружения FLASK_ENV и FLASK_DEBUG переопределят env и debug.

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

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

save_session(session, response)

Сохраняет сессию, если она требует обновлений. Для реализации по умолчанию см. open_session(). Вместо переопределения этого метода рекомендуется заменить session_interface.

Параметры

• session – сессия для сохранения (объект SecureCookie)
• response – экземпляр response_class

secret_key

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

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

select_jinja_autoescape(filename)

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

Изменения

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

send_file_max_age_default

timedelta, используемый в качестве значения по умолчанию для cache_timeout функций send_file(). По умолчанию 12 часов.

Этот атрибут также можно настроить из конфигурации с помощью ключа конфигурации SEND_FILE_MAX_AGE_DEFAULT . Этот параметр конфигурации также может быть задан целым числом, используемым как количество секунд. По умолчанию timedelta(hours=12)

send_static_file(filename)

Функция, используемая внутри для отправки статических файлов из папки static в браузер.

Изменения

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

session_cookie_name

Защищённые cookie используют это имя для cookie сессии.

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

session_interface = <flask.sessions.SecureCookieSessionInterface object>

Интерфейс сессии для использования. По умолчанию используется экземпляр SecureCookieSessionInterface.

Изменения

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

shell_context_processor(f)

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

Изменения

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

shell_context_processors = None

Список функций процессоров контекста оболочки, которые должны быть выполнены при создании контекста оболочки.

Изменения

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

should_ignore_error(error)

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

Изменения

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

property static_folder

Абсолютный путь к папке static.

property static_url_path

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

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

teardown_appcontext(f)

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

Пример:

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

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

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

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

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

Changelog

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

teardown_appcontext_funcs = None

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

Changelog

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

teardown_request(f)

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

Пример:

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

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

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

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

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

Debug Note

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

teardown_request_funcs = None

Словарь со списками функций, которые вызываются после каждого запроса, даже если произошла исключительная ситуация. Ключ словаря — имя схемы, для которой активна данная функция, None для всех запросов. Эти функции не имеют права изменять запрос, а их возвращаемые значения игнорируются. Если при обработке запроса возникла исключительная ситуация, она передаётся каждой функции teardown_request. Для регистрации функции здесь используется декоратор teardown_request().

Changelog

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

template_context_processors = None

Словарь со списком функций, которые вызываются без аргументов для заполнения контекста шаблона. Ключ словаря — имя схемы, для которой активна данная функция, None для всех запросов. Каждая функция возвращает словарь, которым обновляется контекст шаблона. Для регистрации функции здесь используется декоратор context_processor().

template_filter(name=None)

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

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

Параметры

name — необязательное имя фильтра, в противном случае будет использовано имя функции.

template_folder = None

Расположение файлов шаблонов, которые будут добавлены в поиск шаблонов. None если шаблоны не должны быть добавлены.

template_global(name=None)

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

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

Changelog

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

Параметры

name — необязательное имя глобальной функции, в противном случае будет использовано имя функции.

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

Changelog

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

Параметры

name — необязательное имя теста, в противном случае будет использовано имя функции.

property templates_auto_reload

Перезагружать шаблоны при их изменении. Используется create_jinja_environment().

Этот атрибут можно настроить с помощью TEMPLATES_AUTO_RELOAD. Если не задано, он будет включён в режиме отладки.

Changelog

Новое в версии 1.0: Этот свойство было добавлено, но лежащие в его основе конфигурация и поведение уже существовали.

test_cli_runner(**kwargs)

Создать исполняемый файл CLI для тестирования команд CLI. См. Тестирование команд CLI.

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

Changelog

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

test_cli_runner_class = 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 для клиента.

test_client_class = None

тестовый клиент, используемый при test_client.

Изменения

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

test_request_context(*args, **kwargs)

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

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

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

with test_request_context(...):
    generate_report()

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

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

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

Параметры

• 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 – другие позиционные аргументы, передаваемые в EnvironBuilder.
• kwargs – другие именованные аргументы, передаваемые в EnvironBuilder.

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.

Изменения

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

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

update_template_context(context)

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

Параметры

context – контекст в виде словаря, который обновляется на месте для добавления дополнительных переменных.

url_build_error_handlers = None

Список функций, вызываемых при возникновении исключения BuildError при вызове url_for(). Каждая функция, зарегистрированная здесь, вызывается с error, endpoint и values. Если функция возвращает None или возбуждает исключение BuildError, пытается вызвать следующую функцию.

Изменения

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

url_default_functions = None

Словарь со списками функций, которые можно использовать в качестве предобработчиков значений URL. Ключ None используется для приложений, а иначе – для имени модуля. Каждая из этих функций может изменить словарь значений URL перед их использованием в качестве именованных аргументов функции представления. Для каждой зарегистрированной функции также должна быть предоставлена функция url_defaults(), которая добавляет параметры автоматически, удалённые таким образом.

Изменения

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

url_defaults(f)

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

url_map = None

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

Псевдоним werkzeug.routing.Map

url_rule_class

Псевдоним werkzeug.routing.Rule

url_value_preprocessor(f)

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

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

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

url_value_preprocessors = None

Словарь со списками функций, которые вызываются перед функциями before_request_funcs. Ключ словаря – имя модуля, для которого активна эта функция, или None для всех запросов. Для регистрации функции используйте url_value_preprocessor().

Изменения

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

use_x_sendfile

Включите это, если хотите использовать функцию X-Sendfile. Имейте в виду, что сервер должен поддерживать её. Это влияет только на файлы, отправленные методом send_file().

Изменения

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

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

view_functions = None

Словарь всех зарегистрированных функций представлений. Ключи – имена функций, которые также используются для генерации URL, а значения – сами объекты функций. Для регистрации функции представления используйте декоратор route().

wsgi_app(environ, start_response)

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

app = MyMiddleware(app)

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

app.wsgi_app = MyMiddleware(app.wsgi_app)

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

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

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

Параметры

• environ – Окружение WSGI.
• start_response – Вызываемый объект, принимающий код состояния, список заголовков и необязательный контекст исключения для начала ответа.

Объекты 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>)

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

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

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

Для получения дополнительной информации см. Модульные приложения с бланкетами.

Изменено в версии 1.1.0: Бланкеты имеют группу cli для регистрации вложенных команд CLI. Параметр cli_group управляет именем группы в рамках команды flask.

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

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

Параметры

• name – Имя бланкета. Будет добавляться перед именем каждого конечной точки.
• import_name – Имя пакета бланкета, обычно __name__. Это помогает найти root_path для бланкета.
• static_folder – Папка со статическими файлами, которые должны обслуживаться статическим маршрутом бланкета. Путь относится к корневому пути бланкета. Статические файлы бланкета отключены по умолчанию.
• static_url_path – URL для предоставления статических файлов. По умолчанию static_folder. Если у бланкета нет url_prefix, приоритет будет у статического маршрута приложения, и статические файлы бланкета не будут доступны.
• template_folder – Папка с шаблонами, которые должны быть добавлены в путь поиска шаблонов приложения. Путь относится к корневому пути бланкета. Шаблоны бланкета отключены по умолчанию. Шаблоны бланкета имеют меньший приоритет, чем шаблоны в папке шаблонов приложения.
• url_prefix – Путь, который должен добавляться перед всеми URL-адресами бланкета, чтобы сделать их отличными от остальных маршрутов приложения.
• subdomain – Поддомен, на котором маршруты бланкета будут соответствовать по умолчанию.
• url_defaults – Словарь значений по умолчанию, которые маршруты бланкета будут получать по умолчанию.
• root_path – По умолчанию бланкет автоматически определяет это значение на основе import_name. В определённых ситуациях это автоматическое определение может потерпеть неудачу, поэтому путь можно указать вручную.

add_app_template_filter(f, name=None)

Регистрация пользовательского фильтра шаблонов, доступного во всём приложении. Как Flask.add_template_filter(), но для бланкета. Работает точно так же, как декоратор app_template_filter().

Параметры

name – необязательное имя фильтра, в противном случае будет использовано имя функции.

add_app_template_global(f, name=None)

Регистрация пользовательской глобальной переменной для шаблонов, доступной во всём приложении. Как Flask.add_template_global(), но для бланкета. Работает точно так же, как декоратор app_template_global().

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

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

Параметры

name – необязательное имя глобальной переменной, в противном случае будет использовано имя функции.

add_app_template_test(f, name=None)

Регистрация пользовательского теста для шаблонов, доступного во всём приложении. Как Flask.add_template_test(), но для бланкета. Работает точно так же, как декоратор app_template_test().

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

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

Параметры

name – необязательное имя теста, в противном случае будет использовано имя функции.

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

Как Flask.add_url_rule(), но для бланкета. Конечная точка для функции url_for() префиксруется именем бланкета.

after_app_request(f)

Как Flask.after_request(), но для бланкета. Такая функция выполняется после каждого запроса, даже если вне бланкета.

after_request(f)

Как Flask.after_request(), но для бланкета. Эта функция выполняется только после каждого запроса, обработанного функцией этого бланкета.

app_context_processor(f)

Как Flask.context_processor(), но для бланкета. Такая функция выполняется для каждого запроса, даже если вне бланкета.

app_errorhandler(code)

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

app_template_filter(name=None)

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

Параметры

name – необязательное имя фильтра, в противном случае будет использовано имя функции.

app_template_global(name=None)

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

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

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

Параметры

name – необязательное имя глобальной переменной, в противном случае будет использовано имя функции.

app_template_test(name=None)

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

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

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

Параметры

name – необязательное имя теста, в противном случае будет использовано имя функции.

app_url_defaults(f)

То же, что и url_defaults(), но для всего приложения.

app_url_value_preprocessor(f)

То же, что и url_value_preprocessor(), но для всего приложения.

before_app_first_request(f)

Как Flask.before_first_request(). Такая функция выполняется до первого запроса к приложению.

before_app_request(f)

Как Flask.before_request(). Такая функция выполняется перед каждым запросом, даже если вне бланкета.

before_request(f)

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

context_processor(f)

Как Flask.context_processor(), но для бланкета. Эта функция выполняется только для запросов, обработанных бланкетом.

endpoint(endpoint)

Подобно Flask.endpoint(), но для схемы. Это не добавляет префикс имени схемы к точке входа; это необходимо сделать явно пользователем этого метода. Если точка входа начинается с ., она будет зарегистрирована в текущей схеме, в противном случае это независимая от приложения точка входа.

errorhandler(code_or_exception)

Регистрирует обработчик ошибок, который становится активным только для данной схемы. Обратите внимание, что маршрутизация не происходит локально для схемы, поэтому обработчик ошибок 404 обычно не обрабатывается схемой, если он не вызван внутри функции представления. Другой особый случай — ошибка 500 (внутренняя ошибка сервера), которая всегда ищется в приложении.

В противном случае работает так же, как декоратор errorhandler() объекта Flask.

get_send_file_max_age(filename)

Предоставляет значение по умолчанию для параметра cache_timeout для функций send_file().

По умолчанию эта функция возвращает SEND_FILE_MAX_AGE_DEFAULT из конфигурации current_app.

Функции статических файлов, такие как send_from_directory(), используют эту функцию, а send_file() вызывает эту функцию для current_app, если заданный cache_timeout None. Если в send_file() задан cache_timeout, используется это значение; в противном случае вызывается этот метод.

Это позволяет подклассам изменять поведение при отправке файлов на основе имени файла. Например, чтобы установить тайм-аут кеша для файлов .js в 60 секунд:

class MyFlask(flask.Flask):
    def get_send_file_max_age(self, name):
        if name.lower().endswith('.js'):
            return 60
        return flask.Flask.get_send_file_max_age(self, name)

Changelog

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

property has_static_folder

Это True , если контейнер связанного объекта пакета содержит папку для статических файлов.

Changelog

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

import_name = None

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

jinja_loader

Загрузчик Jinja для этого связанного с пакетом объекта.

Changelog

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

json_decoder = None

Локальный для схемы класс декодера JSON для использования. Установите в None для использования декодера приложения json_decoder.

json_encoder = None

Локальный для схемы класс кодировщика JSON для использования. Установите в None для использования кодировщика приложения json_encoder.

make_setup_state(app, options, first_registration=False)

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

open_resource(resource, mode='rb')

Открывает ресурс из папки ресурсов приложения. Для понимания работы рассмотрите следующую структуру папок:

/myapplication.py
/schema.sql
/static
    /style.css
/templates
    /layout.html
    /index.html

Если вы хотите открыть файл schema.sql, выполните следующие действия:

with app.open_resource('schema.sql') as f:
    contents = f.read()
    do_something_with(contents)

Параметры

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

record(func)

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

record_once(func)

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

register(app, options, first_registration=False)

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

Параметры

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

register_error_handler(code_or_exception, f)

Недекоративная версия функции прикрепления ошибок errorhandler(), аналогичная функции register_error_handler() на уровне приложения объекта Flask, но для обработчиков ошибок, ограниченных этой схемой.

Changelog

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

root_path = None

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

route(rule, **options)

Подобно Flask.route(), но для схемы. Точка входа для функции url_for() имеет префикс, соответствующий имени схемы.

send_static_file(filename)

Функция, используемая внутри для отправки статических файлов из папки static в браузер.

Changelog

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

property static_folder

Абсолютный путь к настроенной папке статических файлов.

property static_url_path

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

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

teardown_app_request(f)

Подобно Flask.teardown_request(), но для схемы. Такая функция выполняется при разборе каждого запроса, даже если за пределами схемы.

teardown_request(f)

Подобно Flask.teardown_request(), но для схемы. Эта функция выполняется только при разборе запросов, обработанных функцией этой схемы. Функции разбора запроса выполняются при извлечении контекста запроса, даже если фактически запрос не выполнялся.

template_folder = None

Расположение файлов шаблонов, которые будут добавлены в поиск шаблонов. None если шаблоны не должны добавляться.

url_defaults(f)

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

url_value_preprocessor(f)

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

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

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

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

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

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

environ

Основная среда WSGI.

path

full_path

script_root

url

base_url

url_root

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

http://www.example.com/myapplication

И пользователь запрашивает следующий URI:

http://www.example.com/myapplication/%CF%80/page.html?x=y

В этом случае значения вышеупомянутых атрибутов будут следующими:

path	u'/π/page.html'
full_path	u'/π/page.html?x=y'
script_root	u'/myapplication'
base_url	u'http://www.example.com/myapplication/π/page.html'
url	u'http://www.example.com/myapplication/π/page.html?x=y'
url_root	u'http://www.example.com/myapplication/'

property accept_charsets

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

property accept_encodings

Список кодировок, принимаемых клиентом. Кодировки в терминологии HTTP — это кодировки сжатия, такие как gzip. Для кодировок символов см. accept_charset.

property accept_languages

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

property accept_mimetypes

Список MIME-типов, поддерживаемых клиентом, как объект MIMEAccept.

access_control_request_headers

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

access_control_request_method

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

property access_route

Если существует заголовок перенаправления, это список всех IP-адресов от IP-адреса клиента до последнего прокси-сервера.

classmethod application(f)

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

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

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

Параметры

f — вызываемый WSGI для декорирования

Возвращает

новый вызываемый WSGI

property args

Разложенные параметры URL (часть URL после знака вопроса).

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

property authorization

Объект Authorization в обработанном виде.

property base_url

Как url, но без запроса. См. также: trusted_hosts.

property blueprint

Имя текущего модуля.

property cache_control

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

close()

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

Changelog

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

content_encoding

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

Changelog

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

property content_length

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

content_md5

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

Changelog

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

content_type

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

property cookies

dict со всем содержимым файлов cookie, переданных с запросом.

property data

Содержит входящие данные запроса в виде строки, если они пришли с типом MIME, который Werkzeug не обрабатывает.

date

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

dict_storage_class

Псевдоним werkzeug.datastructures.ImmutableMultiDict

property endpoint

Конечная точка, соответствующая запросу. Это в сочетании с view_args может использоваться для восстановления того же или изменённого URL-адреса. Если при сопоставлении произошла ошибка, это будет None.

property files

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. Это можно изменить, установив parameter_storage_class на другой тип. Это может потребоваться, если порядок данных формы важен.

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

Изменения

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

form_data_parser_class

псевдоним werkzeug.formparser.FormDataParser

classmethod from_values(*args, **kwargs)

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

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

Изменения

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

Возвращает

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

property full_path

Запрошенный путь в виде Unicode, включая строку запроса.

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

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

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

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

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

Изменения

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

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

Разбирает data как JSON.

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

Если разбор завершится ошибкой, вызывается on_json_loading_failed(), и его возвращаемое значение используется в качестве возвращаемого значения.

Параметры

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

property headers

Заголовки из WSGI environ в виде неизменяемого объекта EnvironHeaders.

property host

Только хост, включая порт, если он доступен. См. также: trusted_hosts.

property host_url

Только хост со схемой в качестве IRI. См. также: trusted_hosts.

property if_match

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

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

ETags

property if_modified_since

Обработанный заголовок If-Modified-Since в качестве объекта datetime.

property if_none_match

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

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

ETags

property if_range

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

Изменения

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

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

IfRange

property if_unmodified_since

Обработанный заголовок If-Unmodified-Since в качестве объекта datetime.

property is_json

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

is_multiprocess

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

is_multithread

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

is_run_once

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

property is_secure

True если запрос защищён.

property json

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

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

json_module = <module 'flask.json' from '/home/docs/checkouts/readthedocs.org/user_builds/flask/envs/1.1.x/lib/python3.7/site-packages/Flask-1.1.2-py3.7.egg/flask/json/__init__.py'>

list_storage_class

Псевдоним werkzeug.datastructures.ImmutableList

make_form_data_parser()

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

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

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

property max_content_length

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

max_forwards

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

method

Метод запроса. (Например, 'GET' или 'POST').

property mimetype

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

property mimetype_params

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

on_json_loading_failed(e)

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

origin

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

parameter_storage_class

Псевдоним werkzeug.datastructures.ImmutableMultiDict

property path

Запрошенный путь в виде unicode. Работает аналогично обычному пути в среде WSGI, но всегда включает ведущий слэш, даже если доступен корень URL.

property pragma

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

query_string

Параметры URL в виде строкового значения байтов.

property range

Обработанное поле заголовка Range.

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

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

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

Range

referrer

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

property remote_addr

Удаленный адрес клиента.

remote_user

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

routing_exception = None

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

scheme

Схема URL (http или https).

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

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

property script_root

Корневой путь сценария без заключительного слэша.

property stream

Если входящие данные формы не были закодированы с известным типом MIME, данные хранятся в этом потоке в неизменённом виде для обработки. В большинстве случаев лучше использовать data, который предоставит эти данные в виде строки. Поток возвращает данные только один раз.

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

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

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

property url

Восстановленный текущий URL как IRI. См. также: trusted_hosts.

property url_charset

Кодировка символов, предполагаемая для URL. По умолчанию соответствует значению charset.

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

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

property url_root

Полный корневой URL (с именем хоста), это корневой путь приложения как IRI. См. также: trusted_hosts.

url_rule = None

Внутреннее правило URL, которое соответствовало запросу. Это может быть полезно для проверки разрешенных методов для URL из обработчика до/после (request.url_rule.methods) и т. д. Однако, если метод запроса не был допустим для правила URL, список допустимых значений доступен в routing_exception.valid_methods (атрибут исключения Werkzeug MethodNotAllowed) вместо этого, поскольку запрос никогда не связывался внутри.

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

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

property user_agent

Текущий пользовательский агент.

property values

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

view_args = None

Словарь аргументов представления, соответствующих запросу. Если при сопоставлении произошла ошибка, это будет None.

property want_form_data_parsed

Возвращает True, если метод запроса несёт данные. Начиная с Werkzeug 0.9, это будет иметь место, если передан тип содержимого.

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

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

flask.request

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

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

Объект запроса является экземпляром подкласса Request и предоставляет все атрибуты, определённые Werkzeug. Здесь приведён краткий обзор наиболее важных из них.

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

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.

headers

Объект Headers, представляющий заголовки ответа.

status

Строка со статусом ответа.

status_code

Статус ответа в виде целого числа.

property data

Дескриптор, вызывающий get_data() и set_data().

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

Парсит data как JSON.

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

Если парсинг завершается ошибкой, вызывается on_json_loading_failed(), и возвращаемое им значение используется в качестве возвращаемого значения.

Параметры

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

property is_json

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

property max_cookie_size

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

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

property mimetype

MIME-тип (тип содержимого без набора символов и т. д.).

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

Устанавливает куки. Параметры аналогичны объекту куки Morsel в стандартной библиотеке Python, но он также принимает данные Unicode.

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

Параметры

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

Сессии

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

Для доступа к текущей сессии можно использовать объект 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 (что является значением по умолчанию), сессия будет удалена при закрытии браузера пользователем.

Интерфейс сессии

Интерфейс сессии предоставляет простой способ заменить реализацию сессии, используемую 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)

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

Использует SESSION_COOKIE_DOMAIN, если он настроен, в противном случае использует обнаружение домена на основе SERVER_NAME.

После обнаружения (или если он вообще не задан), SESSION_COOKIE_DOMAIN обновляется, чтобы избежать повторного запуска логики.

get_cookie_httponly(app)

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

get_cookie_path(app)

Возвращает путь, для которого cookie должна быть действительной. По умолчанию реализация использует значение из конфигурационной переменной SESSION_COOKIE_PATH , если она установлена, в противном случае использует APPLICATION_ROOT или /, если она None.

get_cookie_samesite(app)

Возвращает 'Strict' или 'Lax', если cookie должна использовать атрибут SameSite. В настоящее время просто возвращает значение настройки SESSION_COOKIE_SAMESITE.

get_cookie_secure(app)

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

get_expiration_time(app, session)

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

is_null_session(obj)

Проверяет, является ли данный объект сессией-заглушкой. Сессии-заглушки не запрашивают сохранение.

По умолчанию проверяет, является ли объект экземпляром класса null_session_class.

make_null_session(app)

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

По умолчанию создаёт экземпляр null_session_class.

null_session_class

make_null_session() ищет здесь класс, который должен быть создан при запросе сессии-заглушки. Аналогично, метод is_null_session() выполняет проверку типа против этого типа.

Псевдоним NullSession.

open_session(app, request)

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

pickle_based = False

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

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

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

save_session(app, session, response)

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

should_set_cookie(app, session)

Используется бэкендами сессий для определения того, должен ли быть установлен заголовок Set-Cookie для cookie сессии для данного ответа. Если сессия была изменена, cookie устанавливается. Если сессия постоянна, и конфигурационная переменная SESSION_REFRESH_EACH_REQUEST имеет значение true, cookie всегда устанавливается.

Эта проверка обычно пропускается, если сессия была удалена.

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

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

class flask.sessions.SecureCookieSessionInterface

Стандартный интерфейс сессий, который хранит сессии в подписанных cookie через модуль itsdangerous.

static digest_method()

Функция хеширования, используемая для подписи. По умолчанию — sha1.

key_derivation = 'hmac'

Название поддерживаемого itsdangerous метода вывода ключа. По умолчанию — hmac.

open_session(app, request)

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

salt = 'cookie-session'

Соль, которая должна быть применена поверх секретного ключа для подписи сессий, основанных на cookie.

save_session(app, session, response)

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

serializer = <flask.json.tag.TaggedJSONSerializer object>

Python-сериализатор для полезной нагрузки. По умолчанию используется компактный сериализатор, основанный на JSON, с поддержкой некоторых дополнительных типов Python, таких как объекты datetime или кортежи.

session_class

Псевдоним SecureCookieSession

class flask.sessions.SecureCookieSession(initial=None)

Базовый класс для сессий, основанных на подписанных куках.

Этот бэкенд сессий установит атрибуты modified и accessed. Он не может надежно отслеживать, является ли сессия новой (по сравнению с пустой), поэтому new остается жестко закодированным в False.

accessed = False

заголовок, который позволяет кэширующим прокси-серверам кешировать разные страницы для разных пользователей.

get(key, default=None)

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

modified = False

При изменении данных, это устанавливается в True. Отслеживается только сам словарь сессии; если сессия содержит изменяемые данные (например, вложенный словарь), то это значение необходимо установить в True вручную при изменении этих данных. Куки сессии будут записаны в ответ только в том случае, если это True.

setdefault(key, default=None)

Вставляет ключ со значением по умолчанию, если ключ отсутствует в словаре.

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

class flask.sessions.NullSession(initial=None)

Класс, используемый для создания более понятных сообщений об ошибках, если сессии недоступны. По-прежнему позволяет чтение пустой сессии, но не позволяет ее изменение.

class flask.sessions.SessionMixin

Расширяет базовый словарь атрибутами сессии.

accessed = True

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

modified = True

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

property permanent

Это отражает ключ '_permanent' в словаре.

Тестовый клиент

class flask.testing.FlaskClient(*args, **kwargs)

Поведение аналогично обычному тестовому клиенту Werkzeug, но он знает, как работает Flask, чтобы отложить очистку стека контекста запроса до конца тела with при использовании в with операторе. Для общей информации о том, как использовать этот класс, обратитесь к werkzeug.test.Client.

Изменения

Изменено в версии 0.12: app.test_client() включает предварительно заданные значения среды по умолчанию, которые можно установить после создания объекта app.test_client() в client.environ_base.

Основное использование описано в главе Тестирование приложений Flask.

open(*args, **kwargs)

Принимает те же аргументы, что и класс EnvironBuilder с некоторыми дополнениями: Вы можете указать EnvironBuilder или WSGI-среду в качестве единственного аргумента вместо аргументов EnvironBuilder и два необязательных именованных аргумента (as_tuple, buffered) для изменения типа возвращаемого значения или способа выполнения приложения.

Изменения

Изменено в версии 0.5: Если в словаре в качестве файла для параметра data указан словарь, тип содержимого должен теперь называться content_type, а не mimetype. Это изменение было сделано для согласованности с werkzeug.FileWrapper.

Параметр follow_redirects был добавлен к open().

Дополнительные параметры:

Параметры

• as_tuple – Возвращает кортеж в форме (environ, result)
• buffered – Установите это значение в True для буферизации выполнения приложения. Это также автоматически закроет приложение для вас.
• follow_redirects – Установите это значение в True, если Client должен следовать HTTP-редиректам.

session_transaction(*args, **kwargs)

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

with client.session_transaction() as session:
    session['value'] = 42

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

Запуск тестовой командной строки

class flask.testing.FlaskCliRunner(app, **kwargs)

CliRunner для тестирования команд командной строки приложения Flask. Обычно создается с помощью test_cli_runner(). Смотрите Тестирование команд командной строки.

invoke(cli=None, args=None, **kwargs)

Вызывает команду CLI в изолированной среде. Смотрите CliRunner.invoke для полной документации метода. Смотрите Тестирование команд командной строки для примеров.

Если аргумент obj не задан, передается экземпляр ScriptInfo, который знает, как загрузить тестируемое приложение Flask.

Параметры

• cli – Объект команды для вызова. По умолчанию — группа cli приложения.
• args – Список строк для вызова команды.

Возвращает

объект Result.

Глобальные переменные приложения

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

flask.g

Объект пространства имен, который может хранить данные во время контексте приложения. Это экземпляр Flask.app_ctx_globals_class, который по умолчанию является ctx._AppCtxGlobals.

Это хорошее место для хранения ресурсов во время запроса. Во время тестирования вы можете использовать шаблон Имитация ресурсов и контекста для предварительной настройки таких ресурсов.

Это прокси. Подробнее см. Заметки о прокси.

Изменения

Изменено в версии 0.10: Связано с контекстом приложения, а не с контекстом запроса.

class flask.ctx._AppCtxGlobals

Простой объект. Используется в качестве пространства имён для хранения данных во время контекста приложения.

Создание контекста приложения автоматически создаёт этот объект, который доступен как g прокси.

'key' in g

Проверка наличия атрибута.

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

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

iter(g)

Возвращает итератор по именам атрибутов.

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

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

get(name, default=None)

Получение атрибута по имени или значения по умолчанию. Аналогично dict.get().

Параметры

• name – Имя атрибута для получения.
• default – Значение по умолчанию, если атрибут отсутствует.

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

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

pop(name, default=<object object>)

Получение и удаление атрибута по имени. Аналогично dict.pop().

Параметры

• name – Имя атрибута для удаления.
• default – Значение по умолчанию, которое возвращается, если атрибут отсутствует, вместо возбуждения KeyError.

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

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

setdefault(name, default=None)

Получение значения атрибута, если он существует, иначе устанавливает и возвращает значение по умолчанию. Аналогично dict.setdefault().

Параметры

name – Имя атрибута для получения.

Param

default: Значение по умолчанию, которое устанавливается и возвращается, если атрибут отсутствует.

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

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

Полезные функции и классы

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

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

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

flask.copy_current_request_context(f)

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

Пример:

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'

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

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

flask.has_app_context()

Работает так же, как has_request_context(), но для контекста приложения. Вы также можете просто проверить истинность объекта current_app.

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

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

flask.url_for(endpoint, **values)

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

Переменные аргументы, неизвестные целевой конечной точке, добавляются в сгенерированный URL в качестве аргументов запроса. Если значение аргумента запроса None, вся пара пропускается. В случае активных бланков вы можете сократить ссылки на тот же бланк, добавив точку перед локальной конечной точкой (.).

Это сошлётся на функцию index, локальную для текущего бланка:

url_for('.index')

Для получения дополнительной информации, обратитесь к Быстрый старт.

Значения конфигурации APPLICATION_ROOT и SERVER_NAME используются только при генерации URL вне контекста запроса.

Для интеграции приложений, Flask имеет обработчик для перехвата ошибок при построении URL через Flask.url_build_error_handlers. Функция url_for приводит к BuildError когда текущее приложение не имеет URL для заданной конечной точки и значений. В противном случае, current_app вызывает url_build_error_handlers если он не None, что может вернуть строку для использования в результате url_for (вместо того, чтобы url_for по умолчанию возбуждал исключение BuildError). или повторно возбуждает исключение. Пример:

def external_url_handler(error, endpoint, values):
    "Looks up an external URL when `url_for` cannot build a URL."
    # This is an example of hooking the build_error_handler.
    # Here, lookup_url is some utility function you've built
    # which looks up the endpoint in some external URL registry.
    url = lookup_url(endpoint, **values)
    if url is None:
        # External lookup did not have a URL.
        # Re-raise the BuildError, in context of original traceback.
        exc_type, exc_value, tb = sys.exc_info()
        if exc_value is error:
            raise exc_type, exc_value, tb
        else:
            raise error
    # url_for will use this result, instead of raising BuildError.
    return url

app.url_build_error_handlers.append(external_url_handler)

Здесь, error является экземпляром BuildError, а endpoint и values являются аргументами, переданными в url_for. Обратите внимание, что это для построения URL за пределами текущего приложения, а не для обработки ошибок 404 NotFound.

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

Введено в версии 0.10: Параметр _scheme был добавлен.

Введено в версии 0.9: Параметры _anchor и _method были добавлены.

Введено в версии 0.9: Вызывает Flask.handle_build_error() на BuildError.

Параметры

• endpoint – конечная точка URL (имя функции)
• values – переменные аргументы правила URL
• _external – если установлено в True, генерируется абсолютный URL. Адрес сервера может быть изменён через переменную конфигурации SERVER_NAME, которая обращается к заголовку Host, затем к IP и порту запроса.
• _scheme – строка, определяющая желаемый схему URL. Параметр _external должен быть установлен в True или возникает ValueError. По умолчанию используется схема текущего запроса или PREFERRED_URL_SCHEME из конфигурации приложения, если контекст запроса недоступен. Начиная с Werkzeug 0.10, это также может быть установлено в пустую строку для построения URL с относительными протоколами.
• _anchor – если предоставлено, это добавляется как якорь к URL.
• _method – если предоставлено, это явно указывает HTTP-метод.

flask.abort(status, *args, **kwargs)

Возбуждает исключение HTTPException для заданного кода состояния или WSGI-приложения.

Если указан код состояния, он будет искать исключение в списке исключений и возбудит это исключение. Если передано WSGI-приложение, оно будет обернуто в прокси WSGI-исключение и возбудит это:

abort(404)  # 404 Not Found
abort(Response('Hello World'))

flask.redirect(location, code=302, Response=None)

Возвращает объект ответа (приложение WSGI), который, при вызове, перенаправляет клиента на целевой URL. Поддерживаемые коды: 301, 302, 303, 305, 307 и 308. 300 не поддерживается, так как это не настоящее перенаправление, а 304 — ответ на запрос с заданными заголовками If-Modified-Since.

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

Добавлено в версии 0.10: Теперь можно передать класс, используемый для объекта Response.

Добавлено в версии 0.6: Теперь URL может быть строкой Unicode, которая кодируется с помощью функции iri_to_uri().

Параметры

• location – URL, на который необходимо перенаправить.
• code – код статуса перенаправления. По умолчанию 302.
• Response (класс) – класс Response, используемый при создании объекта ответа. По умолчанию werkzeug.wrappers.Response, если не указано иное.

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() в виде кортежа.

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

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

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!'

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

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

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

flask.send_file(filename_or_fp, mimetype=None, as_attachment=False, attachment_filename=None, add_etags=True, cache_timeout=None, conditional=False, last_modified=None)

Отправляет содержимое файла клиенту. Будет использоваться наиболее эффективный доступный и настроенный метод. По умолчанию будет использоваться поддержка file_wrapper сервера WSGI. В качестве альтернативы можно установить атрибут приложения use_x_sendfile в True для прямого вывода заголовка X-Sendfile. Однако для этого требуется поддержка базового веб-сервера для X-Sendfile.

По умолчанию будет сделана попытка определить тип MIME, но вы также можете явно указать его. Для дополнительной безопасности, возможно, вы захотите отправлять определенные файлы как вложение (например, HTML). Определение типа MIME требует наличия filename или attachment_filename.

ETags также будут автоматически добавлены, если предоставлен filename. Вы можете отключить это, установив add_etags=False.

Если conditional=True и filename указаны, этот метод попытается обновить поток ответа для поддержки запросов диапазона. Это позволит ответить на запрос частичным содержимым.

Никогда не передавайте имена файлов в эту функцию из пользовательских источников; вместо этого используйте send_from_directory().

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

Изменено в версии 1.0: Поддерживаются имена файлов UTF-8, как указано в RFC 2231.

Изменено в версии 0.12: Имя файла больше не определяется автоматически из объектов файлов. Если вы хотите использовать автоматическое определение типа MIME и поддержку ETag, передайте путь к файлу через filename_or_fp или attachment_filename.

Изменено в версии 0.12: Для определения типа MIME предпочитается attachment_filename вместо filename.

Изменено в версии 0.9: cache_timeout получает значение по умолчанию из конфигурации приложения, когда None.

Изменено в версии 0.7: Определения MIME и поддержка ETag для объектов файлов были устаревшими из-за ненадежности. Если возможно, передайте имя файла, в противном случае добавьте ETag самостоятельно. Эта функциональность будет удалена в Flask 1.0

Добавлено в версии 0.5: Были добавлены параметры add_etags, cache_timeout и conditional . Теперь по умолчанию добавляются ETags.

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

Изменено в версии 1.1: Имя файла может быть объектом PathLike.

Добавлено в версии 1.1: Частичное содержимое поддерживает BytesIO.

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

Изменено в версии 1.0.3: Имена файлов кодируются с помощью ASCII вместо Latin-1 для большей совместимости с серверами WSGI.

Параметры

• filename_or_fp – имя файла для отправки. Оно относительно root_path, если указан относительный путь. В качестве альтернативы может быть предоставлен объект файла, в этом случае X-Sendfile может не сработать и использовать традиционный метод. Убедитесь, что указатель файла находится в начале отправляемых данных перед вызовом send_file().
• mimetype – тип MIME файла, если предоставлен. Если указан путь к файлу, используется автоматическое определение в качестве резервного варианта, иначе произойдет ошибка.
• as_attachment – установите в True , если нужно отправить этот файл с заголовком Content-Disposition: attachment.
• attachment_filename – имя файла вложения, если оно отличается от имени файла.
• add_etags – установите в False для отключения добавления ETags.
• conditional – установите в True для включения условных ответов.
• cache_timeout – тайм-аут в секундах для заголовков. Когда None (значение по умолчанию), это значение устанавливается методом get_send_file_max_age() приложения current_app.
• last_modified – установите заголовок Last-Modified в это значение, объект datetime или временная метка. Если был передан файл, это значение переопределяет его mtime.

flask.send_from_directory(directory, filename, **options)

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

Пример использования:

@app.route('/uploads/<path:filename>')
def download_file(filename):
    return send_from_directory(app.config['UPLOAD_FOLDER'],
                               filename, as_attachment=True)

Отправка файлов и производительность

Сильно рекомендуется активировать поддержку X-Sendfile на веб-сервере или (если нет аутентификации) указать веб-серверу обслуживать файлы для данного пути самостоятельно без обращений к веб-приложению для повышения производительности.

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

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

Параметры

• directory – каталог, где хранятся все файлы.
• filename – имя файла относительно этого каталога для скачивания.
• options – необязательные ключевые аргументы, которые непосредственно передаются в send_file().

flask.safe_join(directory, *pathnames)

Безопасно объединяет directory и ноль или более ненадежных pathnames компонентов.

Пример использования:

@app.route('/wiki/<path:filename>')
def wiki_page(filename):
    filename = safe_join(app.config['WIKI_FOLDER'], filename)
    with open(filename, 'rb') as fd:
        content = fd.read()  # Read and process the file content...

Параметры

• directory – надёжная базовая директория.
• pathnames – ненадежные имена путей, относительные к этой директории.

Исключения

NotFound, если один или несколько переданных путей выходят за её пределы.

flask.escape(s) → markup

Преобразует символы &, <, >, ‘ и ” в строке s в безопасные для HTML последовательности. Используйте эту функцию, если вам нужно отобразить текст, который может содержать такие символы в HTML. Помечает возвращаемое значение как строку разметки.

class flask.Markup

Строка, готовая к безопасному вставлению в HTML или XML документ, либо потому, что она была экранирована, либо потому, что она была помечена как безопасная.

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

>>> Markup('Hello, <em>World</em>!')
Markup('Hello, <em>World</em>!')
>>> Markup(42)
Markup('42')
>>> Markup.escape('Hello, <em>World</em>!')
Markup('Hello &lt;em&gt;World&lt;/em&gt;!')

Реализует интерфейс __html__(), который используют некоторые фреймворки. Передача объекта, реализующего __html__(), обернёт результат этого метода, помечая его как безопасный.

>>> class Foo:
...     def __html__(self):
...         return '<a href="/foo">foo</a>'
...
>>> Markup(Foo())
Markup('<a href="/foo">foo</a>')

Этот класс является подклассом типа text (str в Python 3, unicode в Python 2). Он имеет те же методы, что и этот тип, но все методы экранируют свои аргументы и возвращают экземпляр Markup.

>>> Markup('<em>%s</em>') % 'foo & bar'
Markup('<em>foo &amp; bar</em>')
>>> Markup('<em>Hello</em> ') + '<foo>'
Markup('<em>Hello</em> &lt;foo&gt;')

classmethod escape(s)

Экранировать строку. Вызывает escape() и гарантирует, что для подклассов возвращается правильный тип.

striptags()

Разбирать разметку, удалять теги и нормализовать пробелы до одиночных пробелов.

>>> Markup('Main &raquo;        <em>About</em>').striptags()
'Main » About'

unescape()

Преобразовать экранированную разметку обратно в текстовую строку. Это заменяет HTML-сущности соответствующими символами.

>>> Markup('Main &raquo; <em>About</em>').unescape()
'Main » <em>About</em>'

Выдача сообщений

flask.flash(message, category='message')

Выдаёт сообщение на следующий запрос. Чтобы удалить сохранённое сообщение из сессии и отобразить его пользователю, шаблон должен вызвать get_flashed_messages().

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

Изменено в версии 0.3: Добавлен параметр category.

Параметры

• message – сообщение для выдачи.
• category – категория для сообщения. Рекомендуются следующие значения: 'message' для любого вида сообщения, 'error' для ошибок, 'info' для информационных сообщений и 'warning' для предупреждений. Однако может быть использована любая строка.

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 – установите в True для получения категорий.
• category_filter – белый список категорий для ограничения возвращаемых значений

Поддержка JSON

Flask использует simplejson для реализации JSON. Так как simplejson предоставляется как стандартной библиотекой, так и расширением, Flask сначала попробует simplejson, а затем перейдёт к модулю json стандартной библиотеки. Кроме того, он делегирует доступ к текущим JSON-кодировщикам и -декодировщикам приложения для более лёгкой настройки.

Таким образом, вместо:

try:
    import simplejson as json
except ImportError:
    import json

Вы можете сделать так:

from flask import json

Для примеров использования ознакомьтесь с документацией json в стандартной библиотеке. К модулю JSON стандартной библиотеки по умолчанию применяются следующие расширения:

1. datetime объекты сериализуются как строки RFC 822.
2. Любой объект с методом __html__ (например, Markup) будет вызывать этот метод, а затем результат сериализуется как строка.

Функция htmlsafe_dumps() этого модуля JSON также доступна как фильтр |tojson в Jinja2. Обратите внимание, что в версиях Flask до Flask 0.10 необходимо отключить экранирование с помощью |safe, если вы планируете использовать вывод |tojson внутри тегов script. В Flask 0.10 и выше это происходит автоматически (но включение |safe не навредит).

<script type=text/javascript>
    doSomethingWith({{ user.username|tojson|safe }});
</script>

flask.json.jsonify(*args, **kwargs)

Эта функция обертывает dumps(), добавляя несколько улучшений, упрощающих работу. Она преобразует вывод JSON в объект Response с MIME-типом application/json. Для удобства она также преобразует несколько аргументов в массив или несколько аргументов ключевых слов в словарь. Это означает, что как jsonify(1,2,3) , так и jsonify([1,2,3]) сериализуются в [1,2,3].

Для ясности, поведение сериализации JSON отличается от dumps() следующим образом:

1. Один аргумент: Передаётся напрямую в dumps().
2. Несколько аргументов: Преобразуется в массив перед передачей в dumps().
3. Несколько аргументов ключевых слов: Преобразуется в словарь перед передачей в dumps().
4. И аргументы, и ключевые слова: Поведение не определено и вызовет исключение.

Пример использования:

from flask import jsonify

@app.route('/_get_current_user')
def get_current_user():
    return jsonify(username=g.user.username,
                   email=g.user.email,
                   id=g.user.id)

Это отправит браузеру ответ JSON в таком виде:

{
    "username": "admin",
    "email": "admin@localhost",
    "id": 42
}

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

Изменено в версии 0.11: Добавлена поддержка сериализации массивов верхнего уровня. Это вводит риск безопасности в старых браузерах. Подробности см. в Безопасность JSON.

Ответ этой функции будет красиво отформатирован, если параметр конфигурации JSONIFY_PRETTYPRINT_REGULAR установлен в True или приложение Flask работает в режиме отладки. Сжатый (не красивый) формат сейчас означает отсутствие отступов и пробелов после разделителей.

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

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

flask.json.dumps(obj, app=None, **kwargs)

Сериализовать obj в строку в формате JSON. Если контекст приложения установлен, используется конфигурированный кодировщик приложения (json_encoder), иначе используется по умолчанию JSONEncoder.

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

Параметры

• obj – Объект для сериализации в JSON.
• app – Экземпляр приложения для конфигурации кодировщика JSON. Если не указано, используется current_app, и по умолчанию используется кодировщик, если контекст приложения не задан.
• kwargs – Дополнительные аргументы, передаваемые в json.dumps().

Changelog

Изменено в версии 1.0.3: app может быть передан напрямую, а не требует контекста приложения для конфигурации.

flask.json.dump(obj, fp, app=None, **kwargs)

Аналогично dumps(), но записывает в объект файла.

flask.json.loads(s, app=None, **kwargs)

Десериализовать объект из строки в формате JSON s. Если контекст приложения установлен, используется конфигурированный декодер приложения (json_decoder), иначе используется по умолчанию JSONDecoder.

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

Параметры

• s – Строка JSON для десериализации.
• app – Экземпляр приложения для конфигурации декодера JSON. Если не указано, используется current_app, и по умолчанию используется кодировщик, если контекст приложения не задан.
• kwargs – Дополнительные аргументы, передаваемые в json.dumps().

Changelog

Изменено в версии 1.0.3: app может быть передан напрямую, а не требует контекста приложения для конфигурации.

flask.json.load(fp, app=None, **kwargs)

Аналогично loads(), но считывает из объекта файла.

class flask.json.JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Кодировщик JSON по умолчанию для Flask. Он расширяет стандартный кодировщик, поддерживая также объекты datetime, UUID, dataclasses, и Markup.

Объекты datetime сериализуются как строки даты RFC 822. Это соответствует формату даты HTTP.

Для поддержки дополнительных типов данных переопределите метод default().

default(o)

Реализуйте этот метод в подклассе, чтобы вернуть сериализуемый объект для o, или вызовите базовый метод реализации (чтобы вызвать TypeError).

Например, для поддержки произвольных итераторов, можно реализовать default так:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    return JSONEncoder.default(self, o)

class flask.json.JSONDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)

Декодер JSON по умолчанию. Он не изменяет поведение декодера simplejson по умолчанию. Для получения дополнительной информации см. документацию json. Этот декодер используется не только для функций загрузки этого модуля, но также и для Request.

Tagged JSON

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

class flask.json.tag.TaggedJSONSerializer

Сериализатор, использующий систему тегов для компактного представления объектов, которые не являются типами JSON. Передаётся как промежуточный сериализатор в itsdangerous.Serializer.

Поддерживаются следующие дополнительные типы:

• dict
• tuple
• bytes
• Markup
• UUID
• datetime

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.

loads(value)

Загрузить данные из строки JSON и десериализовать все помеченные объекты.

register(tag_class, force=False, index=None)

Зарегистрировать новый тег в этом сериализаторе.

Параметры

• tag_class – класс тега для регистрации. Будет инстанцирован с помощью экземпляра этого сериализатора.
• force – перезаписать существующий тег. Если false (по умолчанию), генерируется KeyError.
• index – индекс для вставки нового тега в порядке тегов. Полезно, когда новый тег — это специальный случай существующего тега. Если None (по умолчанию), тег добавляется в конец порядка.

Исключения

KeyError – если ключ тега уже зарегистрирован и force не true.

tag(value)

Преобразовать значение в помеченное представление, если необходимо.

untag(value)

Преобразовать помеченное представление обратно в исходный тип.

class flask.json.tag.JSONTag(serializer)

Базовый класс для определения тегов типов для TaggedJSONSerializer.

check(value)

Проверить, должно ли данное значение быть помечено этим тегом.

key = None

Тег для маркировки сериализованного объекта. Если None, этот тег используется только как промежуточная стадия при маркировке.

tag(value)

Преобразовать значение в допустимый тип JSON и добавить вокруг него структуру тега.

to_json(value)

Преобразовать объект Python в объект, являющийся допустимым типом JSON. Тег будет добавлен позже.

to_python(value)

Преобразовать представление JSON обратно в правильный тип. Тег уже будет удалён.

Рассмотрим пример, добавляющий поддержку OrderedDict. Словари не имеют порядка в Python или 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 – имя шаблона для отображения или итерируемый объект с именами шаблонов, первый из которых будет отображен
• context – переменные, которые должны быть доступны в контексте шаблона.

flask.render_template_string(source, **context)

Отображает шаблон из заданной строки исходного кода шаблона с заданным контекстом. Переменные шаблона будут автоматически экранированы.

Параметры

• source – исходный код шаблона для отображения
• context – переменные, которые должны быть доступны в контексте шаблона.

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 – имя шаблона
• attribute – имя переменной или макроса для доступа

Настройка

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 – путь, относительно которого считываются файлы. Когда объект конфигурации создаётся приложением, это корневой путь приложения root_path.
• defaults – необязательный словарь значений по умолчанию

from_envvar(variable_name, silent=False)

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

app.config.from_pyfile(os.environ['YOURAPPLICATION_SETTINGS'])

Параметры

• variable_name – имя переменной среды
• silent – установить в True если вы хотите, чтобы при отсутствии файла не выводились сообщения об ошибках.

Возвращает

bool. True если конфигурацию удалось загрузить, False в противном случае.

from_json(filename, silent=False)

Обновляет значения в конфигурации из файла JSON. Эта функция ведет себя так, как если бы JSON-объект был словарем и передан функции from_mapping().

Параметры

• filename – имя файла JSON. Это может быть абсолютный путь или путь, относительный к корневому пути.
• silent – установить в True если вы хотите, чтобы при отсутствии файла не выводились сообщения об ошибках.

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

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

from_mapping(*mapping, **kwargs)

Обновляет конфигурацию, как update() игнорируя элементы с не-заглавными ключами.

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

Добавлена в версии 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 – имя импорта или объект

from_pyfile(filename, silent=False)

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

Параметры

• filename – имя файла конфигурации. Это может быть абсолютный путь или путь, относительный к корневому пути.
• silent – установить в 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 – пространство имён конфигурации
• lowercase – флаг, указывающий, должны ли ключи результирующего словаря быть в нижнем регистре
• trim_namespace – флаг, указывающий, должны ли ключи результирующего словаря не включать пространство имён

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

Добавлена в версии 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.

Полезные внутренние механизмы

class flask.ctx.RequestContext(app, environ, request=None, session=None)

Контекст запроса содержит всю информацию, относящуюся к запросу. Он создается в начале запроса и помещается в _request_ctx_stack, а удаляется в конце. Он создаст адаптер URL и объект запроса для предоставленной среды WSGI.

Не пытайтесь использовать этот класс напрямую, вместо этого используйте test_request_context() и request_context() для создания этого объекта.

Когда контекст запроса извлекается, он выполнит все функции, зарегистрированные в приложении, для выполнения действий при завершении (teardown_request()).

Контекст запроса автоматически извлекается в конце запроса. В режиме отладки контекст запроса сохраняется при возникновении исключений, чтобы интерактивные отладчики имели возможность исследовать данные. С версии 0.4 это также может быть принудительно сделано для запросов, которые не завершились сбоем и находятся вне DEBUG режима. Установив 'flask._preserve_context' в True в среде WSGI, контекст не будет извлекаться в конце запроса. Это используется, например, в test_client() для реализации функциональности отложенной очистки.

Это может быть полезно для юнит-тестов, когда вам нужна информация из локального контекста на немного более длительное время. Убедитесь, что вы правильно pop() стек самостоятельно в этой ситуации, иначе ваши юнит-тесты будут утечки памяти.

copy()

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

Изменено в версии 1.1: Используется текущий объект сессии вместо перезагрузки исходных данных. Это предотвращает flask.session указание на устаревший объект.

Изменения

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

match_request()

Может быть переопределен подклассом для подключения к соответствию запроса.

pop(exc=<object object>)

Извлекает контекст запроса и отвязывает его. Это также запустит выполнение функций, зарегистрированных декоратором teardown_request().

Изменения

Изменено в версии 0.9: Добавлен аргумент exc.

push()

Связывает контекст запроса с текущим контекстом.

flask._request_ctx_stack

Внутренний LocalStack, который хранит экземпляры RequestContext. Обычно, к прокси request и session следует обращаться вместо стека. Может быть полезно обратиться к стеку в расширенном коде.

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

app

активное приложение Flask.

url_adapter

адаптер URL, который использовался для сопоставления запроса.

request

текущий объект запроса.

session

активный объект сессии.

g

объект со всеми атрибутами объекта flask.g.

flashes

внутренший кэш для сохраненных сообщений.

Пример использования:

from flask import _request_ctx_stack

def get_session():
    ctx = _request_ctx_stack.top
    if ctx is not None:
        return ctx.session

class flask.ctx.AppContext(app)

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

pop(exc=<object object>)

Извлекает контекст приложения.

push()

Связывает контекст приложения с текущим контекстом.

flask._app_ctx_stack

Внутренний LocalStack, который хранит экземпляры AppContext. Обычно, к прокси current_app и g следует обращаться вместо стека. Расширения могут обращаться к контекстам в стеке как к пространству имён для хранения данных.

Изменения

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

class flask.blueprints.BlueprintSetupState(blueprint, app, options, first_registration)

Временный объект для регистрации модуля Blueprint в приложении. Экземпляр этого класса создаётся методом make_setup_state() и затем передаётся всем функциям обратного вызова регистрации.

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

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

app = None

ссылка на текущее приложение

blueprint = None

ссылка на модуль Blueprint, который создал это состояние настройки.

first_registration = None

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

options = None

словарь со всеми параметрами, которые были переданы методу register_blueprint().

subdomain = None

Суффикс домена, для которого модуль Blueprint должен быть активен, None в противном случае.

url_defaults = None

Словарь со значениями по умолчанию для URL, который добавляется к каждому URL, определённому с помощью модуля Blueprint.

url_prefix = None

Префикс, который должен использоваться для всех URL, определённых в модуле Blueprint.

Сигналы

signals.signals_available

True если система сигнализации доступна. Это так, когда установлен blinker.

Следующие сигналы существуют в Flask:

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.

Пример подписчика:

def log_exception(sender, exception, **extra):
    sender.logger.debug('Got exception during processing: %s', exception)

from flask import got_request_exception
got_request_exception.connect(log_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.

class signals.Namespace

Псевдоним для blinker.base.Namespace, если blinker доступен, иначе — базовый класс, создающий фиктивные сигналы. Этот класс доступен для расширений Flask, которые хотят предоставить такую же систему обратного вызова, как и сам Flask.

signal(name, doc=None)

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

Представления на основе классов

class flask.views.View

Альтернативный способ использования функций представлений. Подкласс должен реализовать dispatch_request(), который вызывается с аргументами представления из системы маршрутизации URL. Если указан methods, методы не нужно явно передавать в метод add_url_rule():

class MyView(View):
    methods = ['GET']

    def dispatch_request(self, name):
        return 'Hello %s!' % name

app.add_url_rule('/hello/<name>', view_func=MyView.as_view('myview'))

Когда необходимо декорировать подключаемое представление, необходимо либо сделать это при создании функции представления (обернув возвращаемое значение as_view()), либо использовать атрибут decorators:

class SecretView(View):
    methods = ['GET']
    decorators = [superuser_required]

    def dispatch_request(self):
        ...

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

classmethod as_view(name, *class_args, **class_kwargs)

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

Аргументы, передаваемые в as_view(), передаются конструктору класса.

decorators = ()

Канонический способ декорирования представлений на основе классов — декорировать возвращаемое значение as_view(). Однако, поскольку это перемещает части логики из объявления класса в место, где она подключается к системе маршрутизации.

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

Changelog

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

dispatch_request()

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

methods = None

Список методов, которые может обрабатывать это представление.

provide_automatic_options = None

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

class flask.views.MethodView

Представление на основе класса, которое перенаправляет методы запроса соответствующим методам класса. Например, если вы реализуете метод get, он будет использоваться для обработки запросов GET.

class CounterAPI(MethodView):
    def get(self):
        return session.get('counter', 0)

    def post(self):
        session['counter'] = session.get('counter', 0) + 1
        return 'OK'

app.add_url_rule('/counter', view_func=CounterAPI.as_view('counter'))

dispatch_request(*args, **kwargs)

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

Регистрация маршрутов URL

В целом, есть три способа определения правил для системы маршрутизации:

1. Можно использовать декоратор flask.Flask.route().
2. Можно использовать функцию flask.Flask.add_url_rule().
3. Можно напрямую обратиться к базовой системе маршрутизации Werkzeug, которая доступна как flask.Flask.url_map.

Переменные части маршрута могут быть указаны с помощью угловых скобок (/user/<username>). По умолчанию переменная часть в URL принимает любой строковый символ без слэша, однако можно указать другой конвертер, используя <converter:name>.

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

Доступны следующие конвертеры:

Пользовательские конвертеры можно определить, используя 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 был уникальным, поэтому применяются следующие правила:

1. Если правило заканчивается слэшем, а пользователь запрашивает его без слэша, пользователь автоматически перенаправляется на ту же страницу со слэшем в конце.
2. Если правило не заканчивается слэшем, а пользователь запрашивает страницу со слэшем в конце, возникает ошибка 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.

Параметры функции представления

Для внутреннего использования функции представления могут иметь некоторые атрибуты, добавленные для настройки поведения, над которым функция представления обычно не имеет контроля. Следующие атрибуты можно предоставить необязательно, чтобы переопределить некоторые значения по умолчанию для 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)

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

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 – если это True, будут добавлены команды по умолчанию run и shell.
• add_version_option – добавляет опцию --version.
• create_app – необязательный обратный вызов, которому передаются сведения о скрипте и который возвращает загруженное приложение.
• load_dotenv – Загружает ближайшие файлы .env и .flaskenv для установки переменных окружения. Также изменит рабочую директорию на директорию, содержащую первый найденный файл.
• set_debug_flag – Установить флаг отладки приложения на основе активной среды

Изменения

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

get_command(ctx, name)

В данном контексте и имени команды возвращает объект Command, если он существует, или None.

list_commands(ctx)

Возвращает список имён подкоманд в порядке их появления.

main(*args, **kwargs)

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

Этот метод также доступен путем прямого вызова экземпляра Command.

В версии 3.0: Добавлен флаг standalone_mode для управления режимом автономной работы.

Параметры

• args – аргументы, которые должны использоваться для разбора. Если не указаны, используется sys.argv[1:].
• prog_name – имя программы, которое должно использоваться. По умолчанию имя программы строится путём взятия имени файла из sys.argv[0].
• complete_var – переменная среды, которая управляет поддержкой завершения ввода bash. По умолчанию "_<prog_name>_COMPLETE" с prog_name в верхнем регистре.
• standalone_mode – по умолчанию скрипт вызывается в автономном режиме. Click затем обрабатывает исключения и преобразует их в сообщения об ошибках, и функция никогда не возвращается, а выключает интерпретатор. Если это установлено в False, они будут переданы вызывающей стороне, а возвращаемое значение этой функции — возвращаемое значение invoke().
• extra – дополнительные ключевые аргументы передаются конструктору контекста. См. Context для получения дополнительной информации.

class flask.cli.AppGroup(name=None, commands=None, **attrs)

Это работает аналогично обычной группе click Group, но изменяет поведение декоратора command() таким образом, что функции автоматически оборачиваются в with_appcontext().

Не путать с FlaskGroup.

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 = None

Необязательно путь импорта приложения Flask.

create_app = None

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

data = None

Словарь со произвольными данными, которые можно связать с этими сведениями о скрипте.

load_app()

Загружает приложение Flask (если оно еще не загружено) и возвращает его. Вызов этого метода несколько раз приведет только к возврату уже загруженного приложения.

flask.cli.load_dotenv(path=None)

Загрузка файлов “dotenv” в порядке приоритета для установки переменных окружения.

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

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

Это ничто, если python-dotenv не установлен.

Параметры

path – Загрузка файла по этому пути вместо поиска.

Возвращает

True если файл был загружен.

Изменено в версии 1.1.0: Возвращает False если python-dotenv не установлен или заданный путь не является файлом.

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

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

flask.cli.with_appcontext(f)

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

flask.cli.pass_script_info(f)

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

flask.cli.run_command = <Command run>

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

Этот сервер предназначен только для целей разработки. Он не обеспечивает стабильность, безопасность или производительность производственных WSGI-серверов.

Релоадер и отладчик включены по умолчанию, если FLASK_ENV=development или FLASK_DEBUG=1.

flask.cli.shell_command = <Command shell>

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

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