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. По умолчанию папка '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, она будет зарегистрирована с endpoint.

В сущности, этот пример:

@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: Словарь со списками функций, которые должны вызываться после каждого запроса. Ключ словаря — имя модуля Blueprint, которому эта функция активна, None для всех запросов. Это может, например, использоваться для закрытия соединений с базой данных. Для регистрации функции используйте декоратор after_request().

app_context()

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

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

with app.app_context():
    init_db()

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

Изменения

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

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

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

Изменения

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

before_first_request(f)

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

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

Изменения

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

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

Изменения

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

before_request(f)

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

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

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

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

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

Изменения

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

cli = None

Контекст командной строки click для этого приложения. Команды, зарегистрированные здесь, отображаются в команде flask после обнаружения приложения. Стандартные команды предоставляются самим Flask и могут быть переопределены.

Это экземпляр объекта click.Group.

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

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

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

create_global_jinja_loader()

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

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

Изменения

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

create_jinja_environment(): Создает среду Jinja2 на основе jinja_options и select_jinja_autoescape(). Начиная с версии 0.7, это также добавляет глобальные переменные и фильтры Jinja2 после инициализации. Переопределите эту функцию для настройки поведения.

Изменения

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

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

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

Изменено в версии 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().

Изменения

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

do_teardown_appcontext(exc=<object object>)

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

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

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

Вызывается AppContext.pop().

Изменения

Новая версия 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. Если в 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)

Изменения

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

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

Изменения

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

handle_exception(e): Обработка исключений по умолчанию, которая срабатывает, когда возникает исключение, которое не перехвачено. В режиме отладки исключение будет повторно поднято немедленно, в противном случае оно будет записано в журнал, и будет использоваться обработчик для ошибки 500 (внутренняя ошибка сервера). Если такой обработчик не существует, отображается стандартное сообщение об ошибке 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(). Эта функция либо вернёт значение ответа, либо повторно поднимет исключение с той же трассировкой стека.

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

Изменения

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

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

Изменения

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

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

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

Изменения

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

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

Changelog

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

iter_blueprints(): Проходит по всем blueprints в порядке их регистрации.

Changelog

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

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

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

jinja_loader: Загрузчик Jinja для этого объекта пакета.

Changelog

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

jinja_options = {'extensions': ['jinja2.ext.autoescape', 'jinja2.ext.with_']}: Параметры, передаваемые напрямую в среду Jinja2.

json_decoder: Псевдоним для flask.json.JSONDecoder

json_encoder: Псевдоним для flask.json.JSONEncoder

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

Changelog

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

logger

Логгер 'flask.app', стандартный Python Logger.

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

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

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

Changelog

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

make_config(instance_relative=False): Используется для создания атрибута config конструктором Flask. Параметр instance_relative передается из конструктора Flask (там он называется instance_relative_config) и указывает, должен ли 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.

Parameters

rv –

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

str (unicode in Python 2): Создается объект ответа с телом, закодированным в UTF-8.
bytes (str in Python 2): Создается объект ответа с телом в формате байтов.
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 нуждается в имени приложения. Его можно установить и переопределить для изменения значения.

Changelog

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

open_instance_resource(resource, mode='rb')

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

Parameters

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)

Parameters

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

open_session(request)

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

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

permanent_session_lifetime

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

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

preprocess_request()

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

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

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

Changelog

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

process_response(response)

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

Changelog

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

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

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

Changelog

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

register_blueprint(blueprint, **options)

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

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

Параметры

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

Changelog

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

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

Changelog

Новая версия 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

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

Этот атрибут также можно настроить из конфигурации с ключом конфигурации 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

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

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

teardown_appcontext(f)

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

Пример:

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

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

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

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

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

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

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

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

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

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

teardown_request(f)

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

Пример:

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

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

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

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

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

Примечание по отладке

В режиме отладки 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. Если не указано, он будет включен в режиме отладки.

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

test_cli_runner(**kwargs)

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

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

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

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

Новое в версии 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.

Changelog

Новое в версии 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 в контекст шаблона, а также всё, что процессоры контекста шаблона хотят ввести. Обратите внимание, что, начиная с Flask 0.6, исходные значения в контексте не будут перезаписаны, если процессор контекста решит вернуть значение с тем же ключом.

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

url_build_error_handlers = None: Список функций, которые вызываются, когда url_for() вызывает BuildError. Каждая зарегистрированная здесь функция вызывается с 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_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__() для того, чтобы можно было применять middleware без потери ссылки на объект приложения. Вместо этого:

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)

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

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

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

Дополнительную информацию см. в разделе Модульные приложения с блок-схемами.

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

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

Параметры

name – Имя блок-схемы. Будет добавлено перед именем каждого конечной точки.
import_name – Имя пакета блок-схемы, обычно __name__. Это помогает найти root_path для блок-схемы.
static_folder – Папка со статическими файлами, которые должны обслуживаться статическим маршрутом блок-схемы. Путь относительный к корневому пути блок-схемы. Статические файлы блок-схемы по умолчанию отключены.
static_url_path – URL для загрузки статических файлов. По умолчанию static_folder. Если у блок-схемы нет url_prefix, приоритет будет у статического маршрута приложения, и статические файлы блок-схемы не будут доступны.
template_folder – Папка с шаблонами, которая должна быть добавлена в путь поиска шаблонов приложения. Путь относительный к корневому пути блок-схемы. Шаблоны блок-схемы по умолчанию отключены. Шаблоны блок-схемы имеют более низкий приоритет, чем шаблоны в папке templates приложения.
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 – режим открытия файла ресурса, по умолчанию «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: Абсолютный путь к настроенной папке static.

property static_url_path: Префикс URL, для которого будет зарегистрирован маршрут статических файлов.

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: Если существует заголовок forwarded, это список всех 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, что автоматически закроет его.

Изменения

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

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

Изменения

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

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

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

Изменения

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

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

property cookies: dict со всем содержимым куки, переданных с запросом.

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

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

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

property endpoint: Конечный пункт, который соответствовал запросу. В сочетании с view_args он может быть использован для восстановления того же или изменённого URL. Если при сопоставлении произошла ошибка, это будет None.

END_OF_DOCUMENT_MARKER

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.

Changelog

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

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

classmethod from_values(*args, **kwargs)

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

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

Changelog

Изменено в версии 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.

Changelog

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

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

Анализирует и возвращает данные как JSON. Если тип MIME не указывает на JSON (application/json, см. is_json()), это возвращает None, если force не истинно. Если анализ завершится неудачей, вызывается 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

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

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

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

property if_none_match

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

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

property if_range

Проанализированный заголовок If-Range.

Changelog

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

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

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

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

Changelog

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

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

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

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

property is_secure: True если запрос защищен.

property json: Это будет содержать разобранные данные JSON, если тип MIME указывает на JSON (application/json, см. is_json()), в противном случае это будет None.

list_storage_class: Псевдоним для werkzeug.datastructures.ImmutableList

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

Changelog

Новая в версии 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.

Changelog

Изменено в версии 0.10: Возбуждается ошибка BadRequest вместо возврата сообщения об ошибке в формате JSON. Если вам нужно такое поведение, вы можете добавить его, создав подкласс.

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

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.

Changelog

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

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

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

property remote_addr: Удалённый адрес клиента.

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

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

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

Changelog

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

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

property stream

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

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

Changelog

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

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

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

Changelog

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

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

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

Changelog

Новая в версии 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, это будет так, если передаётся тип содержимого.

Changelog

Новая в версии 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)

Разбор и возврат данных в формате JSON. Если MIME-тип не указывает на JSON (application/json, см. is_json()), этот метод возвращает None, если force не равно true. Если разбор завершается ошибкой, вызывается on_json_loading_failed(), и возвращаемое им значение используется в качестве возвращаемого значения.

Параметры

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

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

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

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

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)

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

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

Параметры

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

Сессии

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

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

class flask.session

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

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

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

modified

True если объект сессии обнаружил изменение. Имейте в виду, что изменения в изменяемых структурах не улавливаются автоматически; в этом случае вам нужно явно установить атрибут в True самостоятельно. Вот пример:

# this change is not picked up because a mutable object (here
# a list) is changed.
session['objects'].append(42)
# so mark it as modified yourself
session.modified = True

permanent: Если установлено True, сессия существует в течение permanent_session_lifetime секунд. По умолчанию 31 день. Если установлено False (что по умолчанию), сессия будет удалена при закрытии браузера пользователем.

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

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

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

Интерфейс сессий предоставляет простой способ заменить реализацию сессии, используемую Flask.

class flask.sessions.SessionInterface

Базовый интерфейс, который необходимо реализовать для замены стандартного интерфейса сессий, использующего реализацию securecookie из werkzeug. Единственные методы, которые необходимо реализовать, это open_session() и save_session(); другие методы имеют полезные значения по умолчанию, которые не нужно изменять.

Объект сессии, возвращаемый методом open_session(), должен предоставлять интерфейс типа словаря, а также свойства и методы из SessionMixin. Рекомендуется просто создать подкласс словаря и добавить этот миксин:

class Session(dict, SessionMixin):
    pass

Если метод open_session() возвращает None, Flask вызовет make_null_session() для создания сессии-замены, если поддержка сессий не может работать из-за отсутствия какого-либо требования. По умолчанию создаваемый класс NullSession будет жаловаться на то, что секретный ключ не установлен.

Для замены интерфейса сессий в приложении нужно просто назначить flask.Flask.session_interface:

app = Flask(__name__)
app.session_interface = MySessionInterface()

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

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

get_cookie_domain(app)

Возвращает домен, который должен быть установлен для 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: Флаг, указывающий, использует ли интерфейс сессии сериализацию pickle. Расширения 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)

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

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

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

get(key, default=None): Возвращает значение для ключа, если ключ есть в словаре, иначе — значение по умолчанию.

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

setdefault(key, default=None)

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

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

class flask.sessions.NullSession(initial=None): Класс, используемый для генерации более информативных сообщений об ошибках, если сессии недоступны. По-прежнему допускает чтение из пустой сессии, но вызывает ошибку при записи.

class flask.sessions.SessionMixin

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

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

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

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

Примечание

Ключ конфигурации PERMANENT_SESSION_LIFETIME также может быть целым числом начиная с Flask 0.8. Либо обработайте это самостоятельно, либо используйте атрибут permanent_session_lifetime в приложении, которое автоматически преобразует результат в целое число.

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

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(), которые передаются непосредственно.

Запуск тестов CLI

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

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

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

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

Если аргумент 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: Проверяет наличие атрибута.

Changelog

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

iter(g): Возвращает итератор по именам атрибутов.

Changelog

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

get(name, default=None)

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

Параметры

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

Changelog

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

pop(name, default=<object object>)

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

Параметры

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

Changelog

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

setdefault(name, default=None)

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

Параметры: name – Имя атрибута для получения.
Param: default: Значение, которое устанавливается и возвращается, если атрибут отсутствует.

Changelog

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

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

flask.current_app

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

Доступен только при наличии контекста приложения. Это происходит автоматически во время запросов и команд CLI. Он может контролироваться вручную с помощью app_context().

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

flask.has_request_context()

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

class User(db.Model):

    def __init__(self, username, remote_addr=None):
        self.username = username
        if remote_addr is None and has_request_context():
            remote_addr = request.remote_addr
        self.remote_addr = remote_addr

В качестве альтернативы можно также просто проверить истинность любого из контекстных объектов (таких как request или g):

class User(db.Model):

    def __init__(self, username, remote_addr=None):
        self.username = username
        if remote_addr is None and request:
            remote_addr = request.remote_addr
        self.remote_addr = remote_addr

Changelog

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

flask.copy_current_request_context(f)

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

Пример:

import gevent
from flask import copy_current_request_context

@app.route('/')
def index():
    @copy_current_request_context
    def do_some_work():
        # do some work here, it can access flask.request like you
        # would otherwise in the view function.
        ...
    gevent.spawn(do_some_work)
    return 'Regular response'

Changelog

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

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

Changelog

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

flask.url_for(endpoint, **values)

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

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

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

url_for('.index')

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

Для интеграции приложений, 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.

Changelog

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

Параметры

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

flask.make_response(*args)

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

Если представление выглядит так, и вы хотите добавить новый заголовок:

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.

ETag также автоматически добавляется, если предоставлен 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: Предпочтите attachment_filename вместо filename для определения MIME-типа.

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

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

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

В версии 0.2.

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

END_OF_DOCUMENT_MARKER

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()

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

>>> 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().

Changelog

Изменено в версии 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 фильтрует сообщения, оставляя только те, которые соответствуют указанным категориям.

См. Сообщения-всплывающие окна для примеров.

Changelog

Изменено в версии 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 стандартной библиотеки по умолчанию применяются следующие расширения:

datetime объекты сериализуются как строки RFC 822.
Любой объект с методом __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>

Автоматическая сортировка ключей JSON

Переменную конфигурации JSON_SORT_KEYS (Обработка конфигурации) можно установить в значение false, чтобы остановить автоматическую сортировку ключей Flask. По умолчанию сортировка включена, а вне контекста приложения сортировка включена.

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

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

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

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

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

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

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
}

Changelog

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

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

Changelog

Новое в версии 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().

Изменено в версии 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().

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. Он расширяет стандартный кодировщик simplejson, поддерживая также объекты datetime , UUID и объекты Markup, которые сериализуются как строки RFC 822 datetime (совпадающие с форматом 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.

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

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 не верно.

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)

Контекст запроса содержит всю информацию, относящуюся к запросу. Он создаётся в начале запроса и помещается в _request_ctx_stack, а удаляется в конце. Он создаёт адаптер URL и объект запроса для предоставленной среды WSGI.

Не пытайтесь использовать этот класс напрямую, вместо этого используйте test_request_context() и request_context() для создания этого объекта.

Когда контекст запроса извлекается, он выполняет все функции, зарегистрированные в приложении, для выполнения завершающих действий (teardown_request()).

Контекст запроса автоматически извлекается в конце запроса. В режиме отладки контекст запроса сохраняется в случае возникновения исключений, чтобы интерактивные отладчики имели возможность просмотреть данные. С версии 0.4 это также можно принудительно сделать для запросов, которые не завершились ошибкой и вне DEBUG режима. Установив 'flask._preserve_context' в True в среде WSGI, контекст не будет извлекаться в конце запроса. Это используется, например, test_client() для реализации функции отложенного очистки.

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

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

Changelog

New in version 0.10.

match_request(): Может быть переопределён подклассом для подключения к сопоставлению запроса.

pop(exc=<object object>): Извлекает контекст запроса и отвязывает его, выполняя это действие. Это также вызовет выполнение функций, зарегистрированных декоратором teardown_request().

Changelog

Изменено в версии 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. Расширения могут получить доступ к контекстам на стеке в качестве пространства имён для хранения данных.

Changelog

New in version 0.9.

class flask.blueprints.BlueprintSetupState(blueprint, app, options, first_registration)

Временный объект для регистрации бэкенда с приложением. Экземпляр этого класса создаётся методом make_setup_state() и позже передаётся всем функциям обратного вызова регистрации.

add_url_rule(rule, endpoint=None, view_func=None, **options): Вспомогательный метод для регистрации правила (и, необязательно, функции представления) в приложении. Конечная точка автоматически предваряется именем бэкенда.

app = None: ссылка на текущее приложение

blueprint = None: ссылка на бэкенд, который создал этот объект состояния установки.

first_registration = None: Поскольку бэкенды могут быть зарегистрированы несколько раз в приложении, а не всё нужно регистрировать несколько раз, этот атрибут можно использовать для определения того, был ли бэкенд зарегистрирован ранее.

options = None: словарь со всеми параметрами, которые были переданы методу register_blueprint().

subdomain = None: Поддомен, для которого бэкенд должен быть активен, None в противном случае.

url_defaults = None: Словарь с параметрами по умолчанию для URL, которые были определены с помощью бэкенда.

url_prefix = None: Префикс, который должен использоваться для всех URL, определённых в бэкенде.

Сигналы

Changelog

New in version 0.6.

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.

Представления на основе классов

Changelog

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

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

В целом, есть три способа определения правил для системы маршрутизации:

Можно использовать декоратор flask.Flask.route().
Можно использовать функцию flask.Flask.add_url_rule().
Можно напрямую обратиться к внутренней системе маршрутизации Werkzeug, которая доступна как flask.Flask.url_map.

Переменные части маршрута могут быть указаны в угловых скобках (/user/<username>). По умолчанию переменная часть в URL принимает любой строковый тип без слэша, однако можно указать другой преобразователь, используя <converter:name>.

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

Доступны следующие преобразователи:

`string`	принимает любой текст без слэша (по умолчанию)
`int`	принимает целые числа
`float`	как `int`, но для чисел с плавающей точкой
`path`	как по умолчанию, но также принимает слэши
`any`	соответствует одному из предоставленных элементов
`uuid`	принимает строки UUID

Пользовательские преобразователи могут быть определены с помощью flask.Flask.url_map.

Вот несколько примеров:

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

@app.route('/<username>')
def show_user(username):
    pass

@app.route('/post/<int:post_id>')
def show_post(post_id):
    pass

Важный момент, который нужно учитывать, — как Flask обрабатывает конечные слэши. Цель — сохранить уникальность каждого URL, поэтому применяются следующие правила:

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

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

Вы также можете определить несколько правил для одной функции. Однако они должны быть уникальными. Можно также задать значения по умолчанию. Например, вот определение URL, который принимает необязательную страницу:

@app.route('/users/', defaults={'page': 1})
@app.route('/users/page/<int:page>')
def show_users(page):
    pass

Это указывает, что /users/ будет URL для первой страницы, а /users/page/N будет URL для страницы N.

Если URL содержит значение по умолчанию, он будет перенаправлен на более простой вариант с перенаправлением 301. В приведенном выше примере /users/page/1 будет перенаправлен на /users/ . Если ваш маршрут обрабатывает запросы GET и POST , убедитесь, что маршрут по умолчанию обрабатывает только GET, так как перенаправления не могут сохранить данные формы.

@app.route('/region/', defaults={'id': 1})
@app.route('/region/<int:id>', methods=['GET', 'POST'])
def region(id):
   pass

Вот параметры, которые принимает route() и add_url_rule(). Единственное отличие заключается в том, что с параметром route функция представления определяется с помощью декоратора вместо параметра view_func.

`rule`	правило URL в виде строки
`endpoint`	точку входа для зарегистрированного правила URL. Сам Flask предполагает, что имя функции представления — это имя точки входа, если не указано явно.
`view_func`	функция, вызываемая при обработке запроса к указанной точке входа. Если она не указана, можно указать функцию позже, сохранив её в словаре `view_functions` с точкой входа в качестве ключа.
`defaults`	словарь с значениями по умолчанию для этого правила. См. пример выше, чтобы понять, как работают значения по умолчанию.
`subdomain`	указывает правило для поддомена в случае использования соответствия по поддомену. Если не указано, предполагается использование по умолчанию поддомена.
`**options`	опции, передаваемые объекту `Rule` ниже. Изменение в Werkzeug касается обработки опций метода. methods — список методов, к которым должно быть ограничено это правило (`GET`, `POST` и т. д.). По умолчанию правило просто прослушивает `GET` (и неявно `HEAD`). Начиная с Flask 0.6, `OPTIONS` неявно добавляется и обрабатывается стандартной обработкой запросов. Они должны быть указаны в качестве ключевых аргументов.

Параметры функции представления

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

__name__: Имя функции по умолчанию используется в качестве точки входа. Если точка входа указана явно, используется это значение. Кроме того, по умолчанию к этому значению будет добавлено имя модуля Blueprint, которое нельзя настроить непосредственно в самой функции.
methods: Если методы не указаны при добавлении правила URL, Flask будет искать на объекте функции представления атрибут methods. Если он существует, информация о методах будет извлечена оттуда.
provide_automatic_options: Если этот атрибут установлен, Flask будет либо включить, либо отключить автоматическое выполнение ответа HTTP OPTIONS . Это может быть полезно при работе с декораторами, которые хотят настроить ответ OPTIONS на основе каждого представления.
required_methods: Если этот атрибут установлен, Flask всегда добавит эти методы при регистрации правила URL, даже если методы были явно переопределены в вызове route().

Полный пример:

def index():
    if request.method == 'OPTIONS':
        # custom options handling here
        ...
    return 'Hello World!'
index.provide_automatic_options = False
index.methods = ['GET', 'OPTIONS']

app.add_url_rule('/', index)

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

В версии 0.8: Добавлена функциональность provide_automatic_options.

Командная строка

class flask.cli.FlaskGroup(add_default_commands=True, create_app=None, add_version_option=True, load_dotenv=True, set_debug_flag=True, **extra)

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

Информация о том, почему это полезно, находится в Пользовательские скрипты.

Параметры

add_default_commands – если это 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" с именем программы в верхнем регистре.
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.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. Приложение заполнит пространство имен по умолчанию этой оболочки в соответствии с её конфигурацией.

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