API

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

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

class flask.Flask(import_name, static_path=None, static_url_path=None, static_folder='static', 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)

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

В версии 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' в корне приложения.
• 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, **options)

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

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

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

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

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

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

app.view_functions['index'] = index

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

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

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

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

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

Параметры

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

after_request(f)

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

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

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

after_request_funcs = None

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

app_context()

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

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

with app.app_context():
    ...

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

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

app_ctx_globals_class

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

auto_find_instance_path()

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

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

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

before_first_request(f)

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

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

Changelog

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

before_first_request_funcs = None

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

Changelog

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

before_request(f)

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

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

before_request_funcs = None

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

blueprints = None

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

Changelog

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

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

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

Changelog

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

create_jinja_environment()

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

Changelog

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

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

create_url_adapter(request)

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

Changelog

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

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

debug

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

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

default_config = {'APPLICATION_ROOT': None, 'DEBUG': False, 'EXPLAIN_TEMPLATE_LOADING': False, 'JSONIFY_MIMETYPE': 'application/json', 'JSONIFY_PRETTYPRINT_REGULAR': True, 'JSON_AS_ASCII': True, 'JSON_SORT_KEYS': True, 'LOGGER_HANDLER_POLICY': 'always', 'LOGGER_NAME': None, 'MAX_CONTENT_LENGTH': None, '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_SECURE': False, 'SESSION_REFRESH_EACH_REQUEST': True, 'TEMPLATES_AUTO_RELOAD': None, 'TESTING': False, 'TRAP_BAD_REQUEST_ERRORS': False, 'TRAP_HTTP_EXCEPTIONS': False, 'USE_X_SENDFILE': False}

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

dispatch_request()

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

Changelog

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

do_teardown_appcontext(exc=<object object>)

Вызывается при извлечении контекста приложения. Он работает примерно так же, как do_teardown_request(), но для контекста приложения.

Changelog

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

do_teardown_request(exc=<object object>)

Вызывается после фактического распределения запросов и вызовет все функции, помеченные декоратором teardown_request(). Это не вызывается самим объектом Flask, но всегда срабатывает при извлечении контекста запроса. Таким образом, мы имеем более точный контроль над определёнными ресурсами в тестовых средах.

Changelog

Изменено в версии 0.9: Добавлен аргумент exc. Ранее всегда использовалась информация о текущем исключении.

endpoint(endpoint)

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

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

Параметры

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

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

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

def page_not_found(error):
    return 'This page does not exist', 404
app.error_handler_spec[None][404] = page_not_found

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

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

Изменения

Введено в версии 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)

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

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

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

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

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

Изменения

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

property got_first_request

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

Изменения

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

handle_exception(e)

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

Изменения

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

handle_http_exception(e)

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

Изменения

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

handle_url_build_error(error, endpoint, values)

Обрабатывает BuildError при использовании url_for().

handle_user_exception(e)

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

Изменения

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

property has_static_folder

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

Изменения

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

init_jinja_globals()

Устарело. Используется для инициализации глобальных переменных Jinja2.

Изменения

Изменено в версии 0.7: Этот метод устарел, начиная с версии 0.7. Вместо этого переопределите create_jinja_environment().

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

inject_url_defaults(endpoint, values)

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

Изменения

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

instance_path = None

Содержит путь к папке instance.

Изменения

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

iter_blueprints()

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

Изменения

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

jinja_env

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

jinja_environment

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

jinja_loader

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

Изменения

Введено в версии 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.

Изменения

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

property logger

Объект logging.Logger для этого приложения. По умолчанию ведёт логирование в stderr, если приложение находится в режиме отладки. Этот логгер можно использовать для (не удивляйтесь) записи сообщений. Вот несколько примеров:

app.logger.debug('A value for debugging')
app.logger.warning('A warning occurred (%d apples)', 42)
app.logger.error('An error occurred')

Изменения

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

logger_name

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

Изменения

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

make_config(instance_relative=False)

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

Изменения

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

make_default_options_response()

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

Изменения

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

make_null_session()

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

Изменения

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

make_response(rv)

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

Для rv разрешены следующие типы:

response_class	объект возвращается без изменений
str	создаётся объект ответа с строкой в качестве тела
unicode	создаётся объект ответа с кодированной в utf-8 строкой в качестве тела
функция WSGI	функция вызывается как WSGI-приложение и буферизуется как объект ответа
tuple	Кортеж в форме (response, status, headers) или (response, headers), где response — любой из определённых здесь типов, status — строка или целое число, а headers — список или словарь с значениями заголовков.

Параметры

rv – возвращаемое значение из функции представления

Изменения

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

make_shell_context()

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

Изменения

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

name

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

Изменения

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

open_instance_resource(resource, mode='rb')

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

Параметры

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

open_resource(resource, mode='rb')

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

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

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

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

Параметры

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

open_session(request)

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

Параметры

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

permanent_session_lifetime

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

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

preprocess_request()

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

Это также вызывает функции url_value_preprocessor() перед вызовом фактических функций before_request().

property preserve_context_on_exception

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

Изменения

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

process_response(response)

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

Изменения

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

Параметры

response – объект response_class.

Возвращает

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

property propagate_exceptions

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

Изменения

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

register_blueprint(blueprint, **options)

Регистрирует модуль-приложение на основе шаблона.

Changelog

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

register_error_handler(code_or_exception, f)

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

Changelog

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

request_class

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

request_context(environ)

Создаёт контекст запроса RequestContext на основе заданной среды и привязывает его к текущему контексту. Это необходимо использовать совместно с оператором with, так как запрос привязан к текущему контексту только на период работы блока with.

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

with app.request_context(environ):
    do_something_with(request)

Объект, возвращённый этой функцией, также можно использовать без оператора with, что полезно для работы в оболочке. Приведённый пример эквивалентен следующему коду:

ctx = app.request_context(environ)
ctx.push()
try:
    do_something_with(request)
finally:
    ctx.pop()

Changelog

Изменено в версии 0.3: Добавлена поддержка использования без оператора with и оператор with теперь получает объект ctx.

Параметры

environ – среда WSGI

response_class

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

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, **options)

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

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

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

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

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

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

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

Changelog

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

Параметры

• host – имя хоста для прослушивания. Установите это значение в '0.0.0.0', чтобы сервер также был доступен внешне. По умолчанию '127.0.0.1'.
• port – порт веб-сервера. По умолчанию 5000 или порт, определённый в переменной конфигурации SERVER_NAME, если она присутствует.
• debug – если задано, включает или отключает режим отладки. См. debug.
• options – параметры, передаваемые в подчинённый сервер Werkzeug. См. werkzeug.serving.run_simple() для получения дополнительной информации.

save_session(session, response)

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

Параметры

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

secret_key

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

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

select_jinja_autoescape(filename)

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

Changelog

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

Changelog

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

session_cookie_name

Имя файла cookie сессии, используемое безопасными cookie.

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

session_interface = <flask.sessions.SecureCookieSessionInterface object>

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

Changelog

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

shell_context_processor(f)

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

Changelog

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

shell_context_processors = None

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

Changelog

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

should_ignore_error(error)

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

Changelog

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

property static_folder

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

teardown_appcontext(f)

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

Пример:

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

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

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

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

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

Changelog

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

teardown_appcontext_funcs = None

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

Changelog

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

teardown_request(f)

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

Пример:

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

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

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

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

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

Debug Note

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

teardown_request_funcs = None

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

Changelog

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

template_context_processors = None

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

template_filter(name=None)

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

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

Параметры

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

template_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 — необязательное имя теста, в противном случае используется имя функции.

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)

Создаёт WSGI-среду из заданных значений (см. werkzeug.test.EnvironBuilder для получения дополнительной информации, эта функция принимает те же самые аргументы).

testing

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

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

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

trap_http_exception(e)

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

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

Changelog

Добавлено в версии 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, пробуется следующая функция.

Changelog

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

url_default_functions = None

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

Changelog

Добавлено в версии 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 для всех функций представлений приложения. Она вызывается перед вызовом функций представлений и может изменить предоставленные значения url.

url_value_preprocessors = None

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

Changelog

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

use_x_sendfile

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

Changelog

Добавлено в версии 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)

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

Changelog

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

Параметры

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

Объекты голубых планов

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)

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

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

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

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. Если значение cache_timeout задано в send_file(), используется это значение; в противном случае вызывается этот метод.

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

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

Changelog

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

property has_static_folder

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

Changelog

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

jinja_loader

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

Changelog

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

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() для регистрации плагина в приложении. Этот метод можно переопределить, чтобы настроить поведение регистрации. Аргументы ключевых слов из register_blueprint() напрямую передаются в этот метод в словаре options.

register_error_handler(code_or_exception, f)

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

Changelog

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

route(rule, **options)

Аналогично Flask.route(), но для плагина. Точка входа для функции url_for() префиксруется именем плагина.

send_static_file(filename)

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

Changelog

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

property static_folder

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

teardown_app_request(f)

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

teardown_request(f)

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

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.

form

A MultiDict с обработанными данными формы из POST или PUT запросов. Пожалуйста, имейте в виду, что загрузки файлов не попадут сюда, а вместо этого в атрибут files.

args

A MultiDict с обработанным содержимым строки запроса. (Часть в URL после вопросительного знака).

values

A CombinedMultiDict содержащий содержимое как form, так и args.

cookies

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

stream

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

headers

Входящие заголовки запроса в виде объекта-словаря.

data

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

files

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

environ

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

method

Текущий метод запроса (POST, GET и т. д.).

path

full_path

script_root

url

base_url

url_root

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

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

is_xhr

True, если запрос был инициирован через JavaScript XMLHttpRequest. Это работает только с библиотеками, которые поддерживают заголовок X-Requested-With и устанавливают его в XMLHttpRequest. К таким библиотекам относятся prototype, jQuery и Mochikit, а также, вероятно, ещё некоторые.

property blueprint

Имя текущего модуля-плана

property endpoint

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

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

Обрабатывает входящие данные JSON-запроса и возвращает их. По умолчанию эта функция вернёт None, если тип MIME не application/json, но это можно переопределить параметром force. Если обработка завершится неудачей, вызывается метод on_json_loading_failed() объекта запроса.

Параметры

• force – если установлено в True, тип MIME игнорируется.
• silent – если установлено в True, этот метод завершится без ошибок и вернёт None.
• cache – если установлено в True, обработанные данные JSON сохраняются в запросе.

property is_json

Указывает, является ли этот запрос JSON или нет. По умолчанию запрос считается содержащим данные JSON, если тип MIME — application/json или application/*+json.

Changelog

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

property json

Если тип MIME — application/json, здесь будут содержаться обработанные данные JSON. В противном случае здесь будет None.

Вместо этого следует использовать метод get_json().

property max_content_length

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

property module

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

on_json_loading_failed(e)

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

Changelog

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

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

routing_exception = None

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

url_rule = None

Внутреннее правило URL, сопоставленное с запросом. Это может быть полезно для проверки разрешенных методов для URL-адреса из обработчика до/после (request.url_rule.methods) и т. д.

Changelog

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

view_args = None

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

class 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 на ваш подкласс.

headers

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

status

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

status_code

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

property data

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

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

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

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

get_cookie_httponly(app)

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

get_cookie_path(app)

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

get_cookie_secure(app)

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

get_expiration_time(app, session)

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

is_null_session(obj)

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

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

make_null_session(app)

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

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

null_session_class

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

Псевдоним для NullSession

open_session(app, request)

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

pickle_based = False

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

Изменения

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

save_session(app, session, response)

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

should_set_cookie(app, session)

Указывает, следует ли сейчас устанавливать cookie или нет. Это используется бэкендами сессий, чтобы определить, должны ли они передавать заголовок set-cookie или нет. Поведение по умолчанию определяется конфигурационной переменной SESSION_REFRESH_EACH_REQUEST. Если она установлена в False, cookie устанавливается только в том случае, если сессия была изменена; если установлена в 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.sessions.TaggedJSONSerializer object>

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

session_class

Псевдоним для SecureCookieSession

class flask.sessions.SecureCookieSession(initial=None)

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

class flask.sessions.NullSession(initial=None)

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

class flask.sessions.SessionMixin

Расширяет базовый словарь с аксессорами, ожидаемыми расширениями Flask и пользователями для сессии.

modified = True

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

new = False

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

property permanent

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

flask.sessions.session_json_serializer = <flask.sessions.TaggedJSONSerializer object>

Настраиваемый сериализатор JSON, поддерживающий несколько дополнительных типов, которые мы принимаем как должное при сериализации (кортежи, объекты разметки, datetime).

Этот объект предоставляет методы выгрузки и загрузки, аналогичные simplejson, но также маркирует определённые встроенные объекты Python, которые часто встречаются в сессиях. В настоящее время в выгружаемом JSON поддерживаются следующие расширенные значения:

• Markup объекты
• UUID объекты
• datetime объекты
• tuples

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

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

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

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

flask.g

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

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

Кроме того, начиная с версии 0.10, вы можете использовать метод get() для получения атрибута или None (или второго аргумента), если он не задан. Эти два способа использования теперь эквивалентны:

user = getattr(flask.g, 'user', None)
user = flask.g.get('user', None)

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

Начиная с версии 0.11, вы можете использовать pop() и setdefault() так же, как вы бы использовали их в словаре.

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

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

flask.current_app

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

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

flask.has_request_context()

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

class User(db.Model):

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

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

class User(db.Model):

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

Изменения

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

flask.copy_current_request_context(f)

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

Изменения

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

flask.has_app_context()

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

Изменения

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

flask.url_for(endpoint, **values)

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

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

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

url_for('.index')

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

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

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

app.url_build_error_handlers.append(external_url_handler)

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

Изменения

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

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

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

Параметры

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

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

Вызывает исключение HTTPException для заданного кода состояния или WSGI-приложения:

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

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

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

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

Параметры

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

flask.make_response(*args)

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

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

def index():
    return render_template('index.html', foo=42)

Теперь вы можете сделать что-то вроде этого:

def index():
    response = make_response(render_template('index.html', foo=42))
    response.headers['X-Parachutes'] = 'parachutes are cool'
    return response

Эта функция принимает те же самые аргументы, которые можно вернуть из функции представления. Например, это создаёт ответ с кодом ошибки 404:

response = make_response(render_template('not_found.html'), 404)

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

response = make_response(view_function())
response.headers['X-Parachutes'] = 'parachutes are cool'

Внутри эта функция делает следующее:

• если не передано никаких аргументов, создаётся новый объект ответа
• если передан один аргумент, вызывается flask.Flask.make_response() с ним
• если передано более одного аргумента, аргументы передаются в функцию flask.Flask.make_response() как кортеж.

Изменения

В версии 0.6.

flask.after_this_request(f)

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

Пример:

@app.route('/')
def index():
    @after_this_request
    def add_header(response):
        response.headers['X-Foo'] = 'Parachute'
        return response
    return 'Hello World!'

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

Изменения

В версии 0.9.

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

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

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

Теги ETag также будут автоматически добавлены, если предоставлен путь к файлу. Отключить это можно, установив add_etags=False.

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

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

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

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

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

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

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

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

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

Параметры

• filename_or_fp – имя файла для отправки в latin-1. Оно относительно 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, если один или несколько переданных путей выходят за его пределы.

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

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

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

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

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

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

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

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

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

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

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

from flask import jsonify

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

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

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

Changelog

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

Ответ этой функции будет красиво отформатирован, если он не был запрошен с X-Requested-With: XMLHttpRequest, чтобы упростить отладку, если параметр конфигурации JSONIFY_PRETTYPRINT_REGULAR не установлен в false. Сжатая (не красивая) форматировка в настоящее время означает отсутствие отступов и пробелов после разделителей.

Changelog

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

flask.json.dumps(obj, **kwargs)

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

Эта функция может возвращать unicode строки или строковые байты только с ASCII-символами по умолчанию, которые автоматически преобразуются в строки Unicode. Это поведение по умолчанию контролируется переменной конфигурации JSON_AS_ASCII и может быть переопределено параметром simplejson ensure_ascii.

flask.json.dump(obj, fp, **kwargs)

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

flask.json.loads(s, **kwargs)

Десериализует JSON-объект из строки s, используя настроенный декодер приложения (json_decoder), если на стеке есть приложение.

flask.json.load(fp, **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 для дат (тот же формат, что и в 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. Этот декодер используется не только для функций load в этом модуле, но и для Request.

Отображение шаблонов

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)

Не следует использовать эту функцию для загрузки фактической конфигурации, а скорее значений конфигурации по умолчанию. Фактическая конфигурация должна загружаться с помощью 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.ext

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

Если вы хотите использовать расширение с именем «Flask-Foo», вы импортируете его из ext следующим образом:

from flask.ext import foo

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

Новая функция в версии 0.8.

Справочные потоки

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

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

Changelog

New in version 0.10.

match_request()

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

pop(exc=<object object>)

Удаляет контекст запроса и развязывает его, выполняя это действие. Это также запустит выполнение функций, зарегистрированных декоратором teardown_request().

Changelog

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

push()

Связывает контекст запроса с текущим контекстом.

flask._request_ctx_stack

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

Следующие атрибуты всегда присутствуют в каждом слое стека:

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)

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

pop(exc=<object object>)

Удаляет контекст приложения.

push()

Связывает контекст приложения с текущим контекстом.

flask._app_ctx_stack

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

Changelog

New in version 0.9.

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

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

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

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

app = None

ссылка на текущее приложение

blueprint = None

ссылка на модуль Blueprint, создавший этот объект состояния.

first_registration = None

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

options = None

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

subdomain = None

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

url_defaults = None

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

url_prefix = None

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

Сигналы

signals.signals_available

True, если система сигнализации доступна. Это так, когда установлен blinker.

Следующие сигналы существуют в Flask:

flask.template_rendered

Этот сигнал отправляется, когда шаблон был успешно отрисован. Сигнал вызывается с экземпляром шаблона как template и контекстом в виде словаря (имя context).

Пример подписчика:

def log_template_renders(sender, template, context, **extra):
    sender.logger.debug('Rendering template "%s" with context %s',
                        template.name or 'string template',
                        context)

from flask import template_rendered
template_rendered.connect(log_template_renders, app)

flask.before_render_template

Этот сигнал отправляется перед процессом рендеринга шаблона. Сигнал вызывается с экземпляром шаблона как template и контекстом в виде словаря (имя context).

Пример подписчика:

def log_template_renders(sender, template, context, **extra):
    sender.logger.debug('Rendering template "%s" with context %s',
                        template.name or 'string template',
                        context)

from flask import before_render_template
before_render_template.connect(log_template_renders, app)

flask.request_started

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

Пример подписчика:

def log_request(sender, **extra):
    sender.logger.debug('Request context is set up')

from flask import request_started
request_started.connect(log_request, app)

flask.request_finished

Этот сигнал отправляется непосредственно перед отправкой ответа клиенту. Ему передается отправляемый ответ под именем response.

Пример подписчика:

def log_response(sender, response, **extra):
    sender.logger.debug('Request context is about to close down.  '
                        'Response: %s', response)

from flask import request_finished
request_finished.connect(log_response, app)

flask.got_request_exception

Этот сигнал отправляется, когда во время обработки запроса произошла ошибка. Он отправляется *до* того, как начнется стандартная обработка исключений, и даже в отладочном режиме, где обработка исключений не происходит. Само исключение передаётся подписчику как exception.

Пример подписчика:

def log_exception(sender, exception, **extra):
    sender.logger.debug('Got exception during processing: %s', exception)

from flask import got_request_exception
got_request_exception.connect(log_exception, app)

flask.request_tearing_down

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

Пример подписчика:

def close_db_connection(sender, **extra):
    session.close()

from flask import request_tearing_down
request_tearing_down.connect(close_db_connection, app)

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

flask.appcontext_tearing_down

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

Пример подписчика:

def close_db_connection(sender, **extra):
    session.close()

from flask import appcontext_tearing_down
appcontext_tearing_down.connect(close_db_connection, app)

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

flask.appcontext_pushed

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

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

from contextlib import contextmanager
from flask import appcontext_pushed

@contextmanager
def user_set(app, user):
    def handler(sender, **kwargs):
        g.user = user
    with appcontext_pushed.connected_to(handler, app):
        yield

И в коде теста:

def test_user_me(self):
    with user_set(app, 'john'):
        c = app.test_client()
        resp = c.get('/users/me')
        assert resp.data == 'username=john'

Изменения

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

flask.appcontext_popped

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

Изменения

Добавлена в версии 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)

Изменения

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

class signals.Namespace

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

signal(name, doc=None)

Создаёт новый сигнал для этого пространства имён, если blinker доступен, иначе возвращает фиктивный сигнал, у которого метод send ничего не делает, но при этом возвращает ошибку RuntimeError для всех других операций, включая подключение.

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

class flask.views.View

Альтернативный способ использования функций представления. Подкласс должен реализовать dispatch_request(), который вызывается с аргументами представления из системы маршрутизации URL. Если предоставлен methods, методы не нужно явно передавать методу add_url_rule():

class MyView(View):
    methods = ['GET']

    def dispatch_request(self, name):
        return 'Hello %s!' % name

app.add_url_rule('/hello/<name>', view_func=MyView.as_view('myview'))

Когда вам нужно декорировать подключаемое представление, нужно либо сделать это при создании функции представления (обернув возвращаемое значение as_view()), либо использовать атрибут decorators:

class SecretView(View):
    methods = ['GET']
    decorators = [superuser_required]

    def dispatch_request(self):
        ...

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

classmethod as_view(name, *class_args, **class_kwargs)

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

Аргументы, передаваемые в as_view(), передаются в конструктор класса.

decorators = ()

Канонический способ декорирования представлений на основе класса — декорировать возвращаемое значение as_view(). Однако, поскольку это перемещает части логики из объявления класса в место, где она подключается к системе маршрутизации.

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

Изменения

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

dispatch_request()

Подклассы должны переопределить этот метод для реализации фактического кода функции представления. Этот метод вызывается со всеми аргументами из правила URL.

methods = None

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

class flask.views.MethodView

Подобно обычному представлению на основе класса, но оно перенаправляет запросы к определённым методам. Например, если вы реализуете метод с именем get(), это означает, что он будет отвечать на запросы 'GET', и реализация dispatch_request() автоматически перенаправит ваш запрос к нему. Также options устанавливается автоматически:

class CounterAPI(MethodView):

    def get(self):
        return session.get('counter', 0)

    def post(self):
        session['counter'] = session.get('counter', 0) + 1
        return 'OK'

app.add_url_rule('/counter', view_func=CounterAPI.as_view('counter'))

dispatch_request(*args, **kwargs)

Подклассы должны переопределить этот метод для реализации фактического кода функции представления. Этот метод вызывается со всеми аргументами из правила URL.

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

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

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

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

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

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

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

Вот некоторые примеры:

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

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

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

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

1. Если правило заканчивается слешем, а пользователь запрашивает его без слеша, пользователь автоматически перенаправляется на ту же страницу со слешем в конце.
2. Если правило не заканчивается слешем, а пользователь запрашивает страницу со слешем в конце, генерируется ошибка 404 "Not Found".

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

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

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

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

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

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

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

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

app.add_url_rule('/', index)

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

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

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

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

Параметры

• add_default_commands – если True, будут добавлены команды run и shell по умолчанию.
• add_version_option – добавляет параметр --version.
• create_app – необязательный обратный вызов, которому передаются сведения о скрипте, и который возвращает загруженное приложение.

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)

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

app_import_path = None

Необязательно путь импорта приложения Flask.

create_app = None

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

data = None

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

load_app()

Загружает приложение Flask (если оно ещё не загружено) и возвращает его. Вызов этого метода несколько раз просто вернёт уже загруженное приложение.

flask.cli.with_appcontext(f)

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

flask.cli.pass_script_info(f)

Помечает функцию, чтобы экземпляр ScriptInfo передавался в качестве первого аргумента в обратный вызов click.

flask.cli.run_command = <Command run>

Запускает локальный сервер разработки для приложения Flask.

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

Релоадер и отладчик по умолчанию включены, если флаг отладки Flask включен, и выключены в противном случае.

flask.cli.shell_command = <Command shell>

Запускает интерактивную оболочку Python в контексте данного приложения Flask. Приложение заполнит по умолчанию пространство имён этой оболочки в соответствии с её конфигурацией.

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