WSGI Помощники

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

Помощники итераторов/потоков

Эти классы и функции упрощают работу с итератором приложения WSGI и входным потоком.

class werkzeug.wsgi.ClosingIterator(iterable, callbacks=None)

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

return ClosingIterator(app(environ, start_response), [cleanup_session,
                                                      cleanup_locals])

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

Итератор закрытия не нужен, если приложение использует объекты ответа и завершает обработку, если ответ начат:

try:
    return response(environ, start_response)
finally:
    cleanup_session()
    cleanup_locals()

Параметры

iterable (Iterable[bytes]) –
callbacks (Optional[Union[Callable[[], None], Iterable[Callable[[], None]]]]) –

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

None

class werkzeug.wsgi.FileWrapper(file, buffer_size=8192)

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

Этот класс не следует использовать напрямую, а следует использовать функцию wrap_file(), которая использует поддержку обертки файлов сервера WSGI, если она доступна.

Изменения

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

Если вы используете этот объект вместе с Response, вы должны использовать режим direct_passthrough.

Параметры

file (BinaryIO) – объект типа file с методом read().
buffer_size (int) – количество байтов для одной итерации.

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

None

class werkzeug.wsgi.LimitedStream(stream, limit)

Оборачивает поток, чтобы он не считывал более n байтов. Если поток исчерпан, и вызывающая сторона пытается получить больше байтов, вызывается on_exhausted(), который по умолчанию возвращает пустую строку. Возвращаемое значение этой функции передаётся в функцию чтения. Поэтому, если она возвращает пустую строку, read() также вернёт пустую строку.

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

Примечание о соответствии WSGI

Вызовы readline() и readlines() не соответствуют WSGI, потому что передают аргумент размера методам readline. К сожалению, PEP WSGI не реализуется безопасно без аргумента размера для readline(), так как в потоке нет маркера EOF. В результате использование readline() не рекомендуется.

По той же причине итерирование по LimitedStream не является переносимым. Внутри он вызывает readline().

Мы настоятельно рекомендуем использовать только read() или make_line_iter(), который безопасно итерирует по строкам в потоке WSGI.

Параметры

stream (BinaryIO) – поток для оборачивания.
limit (int) – лимит для потока, не должен быть больше, чем может предоставить строка, если поток не заканчивается на EOF (например, wsgi.input)

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

None

exhaust(chunk_size=65536)

Исчерпать поток. Это потребляет все оставшиеся данные до достижения лимита.

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

property is_exhausted: bool: Если поток исчерпан, этот атрибут True.

on_disconnect()

Что должно произойти, если обнаружено отключение? Возвращаемое значение этой функции возвращается из функций чтения в случае, если клиент отключился. По умолчанию генерируется исключение ClientDisconnected.

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

on_exhausted()

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

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

read(size=None)

Прочитать size байтов или, если размер не указан, всё.

Параметры: size (Optional[int]) – количество считываемых байтов.
Тип возвращаемого значения: bytes

readable()

Возвращает, был ли объект открыт для чтения.

Если False, read() сгенерирует OSError.

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

readline(size=None)

Считывает одну строку из потока.

Параметры: size (Optional[int]) –
Тип возвращаемого значения: bytes

readlines(size=None)

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

Параметры: size (Optional[int]) –
Тип возвращаемого значения: List[bytes]

tell()

Возвращает позицию потока.

Changelog

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

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

werkzeug.wsgi.make_line_iter(stream, limit=None, buffer_size=10240, cap_at_buffer=False)

Безопасно итерирует по входному потоку, строка за строкой. Если входной поток не является LimitedStream, то параметр limit является обязательным.

Внутренне используется метод read() потока в отличие от метода readline(), который небезопасен и может быть использован только в нарушение спецификации WSGI. Такая же проблема применима к функции __iter__ входного потока, которая вызывает readline() без аргументов.

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

Changelog

Добавлена в версии 0.11.10: добавлена поддержка параметра cap_at_buffer.

Добавлена в версии 0.9: добавлена поддержка итераторов в качестве входного потока.

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

Parameters

stream (Union[Iterable[байты], BinaryIO]) – поток или итератор для итерации.
limit (Optional[int]) – предел в байтах для потока. (Обычно длина содержимого. Необязательно, если stream является LimitedStream.
buffer_size (int) – необязательный размер буфера.
cap_at_buffer (bool) – если это установлено, фрагменты разбиваются, если их длина больше размера буфера. Внутренне реализовано так, что размер буфера может быть исчерпан в два раза.

Return type

Iterator[байты]

werkzeug.wsgi.make_chunk_iter(stream, separator, limit=None, buffer_size=10240, cap_at_buffer=False)

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

Changelog

Добавлена в версии 0.11.10: добавлена поддержка параметра cap_at_buffer.

Добавлена в версии 0.9: добавлена поддержка итераторов в качестве входного потока.

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

Parameters

stream (Union[Iterable[байты], BinaryIO]) – поток или итератор для итерации.
separator (байты) – разделитель, который делит фрагменты.
limit (Optional[int]) – предел в байтах для потока. (Обычно длина содержимого. Необязательно, если stream иначе уже ограничен).
buffer_size (int) – необязательный размер буфера.
cap_at_buffer (bool) – если это установлено, фрагменты разбиваются, если их длина больше размера буфера. Внутренне реализовано так, что размер буфера может быть исчерпан в два раза.

Return type

Iterator[байты]

werkzeug.wsgi.wrap_file(environ, file, buffer_size=8192)

Оборачивает файл. Использует оболочку файла сервера WSGI, если доступна, или в противном случае — универсальную FileWrapper.

Changelog

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

Если используется оболочка файла от сервера WSGI, важно не итерироваться по ней внутри приложения, а передавать её без изменений. Если вы хотите передать оболочку файла внутри объекта ответа, необходимо установить Response.direct_passthrough на True.

Дополнительную информацию об оболочках файлов можно найти в PEP 333.

Parameters

file (BinaryIO) – объект типа file, имеющий метод read().
buffer_size (int) – количество байтов для одной итерации.
environ (WSGIEnvironment) –

Return type

Iterable[байты]

Справочные данные среды

Эти функции работают со средой WSGI. Они извлекают полезную информацию или выполняют общие преобразования:

werkzeug.wsgi.get_host(environ, trusted_hosts=None)

Возвращает хост для данной среды WSGI.

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

Необязательно, проверьте, является ли хост доверенным, используя host_is_trusted(), и вызовите SecurityError, если он недоверен.

Параметры

environ (WSGIEnvironment) – Словарь среды WSGI.
trusted_hosts (Необязательно[Итерируемый[str]]) – Список доверенных имен хостов.

Возвращает

Хост с портом, если необходимо.

Возбуждает

SecurityError – Если хост недоверен.

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

str

werkzeug.wsgi.get_content_length(environ)

Возвращает длину содержимого из среды WSGI как целое число. Если она недоступна или используется кодировка chunked, возвращается None.

Изменения

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

Параметры: environ (WSGIEnvironment) – среда WSGI для извлечения длины содержимого.
Тип возвращаемого значения: Optional[int]

werkzeug.wsgi.get_input_stream(environ, safe_fallback=True)

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

Если длина содержимого не задана, поток будет пустым по соображениям безопасности. Если сервер WSGI поддерживает chunked или бесконечные потоки, он должен установить значение wsgi.input_terminated в среде WSGI для указания этого.

Изменения

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

Параметры

environ (WSGIEnvironment) – среда WSGI для извлечения потока.
safe_fallback (bool) – использовать пустой поток в качестве безопасного значения по умолчанию, когда длина содержимого не задана. Отключение этой возможности позволяет использовать бесконечные потоки, что может представлять риск атаки типа "отказ в обслуживании".

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

BinaryIO

werkzeug.wsgi.get_current_url(environ, root_only=False, strip_querystring=False, host_only=False, trusted_hosts=None)

Восстановление URL запроса из частей в среде WSGI.

URL — это IRI, а не URI, поэтому он может содержать символы Юникода. Используйте iri_to_uri() для преобразования в ASCII.

Параметры

environ (WSGIEnvironment) – среда WSGI для получения частей URL.
root_only (bool) – построить только корневой путь, не включать оставшийся путь или строку запроса.
strip_querystring (bool) – не включать строку запроса.
host_only (bool) – построить только схему и хост.
trusted_hosts (Необязательно[Итерируемый[str]]) – список доверенных имен хостов для проверки хоста.

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

str

werkzeug.wsgi.get_query_string(environ)

Возвращает строку запроса из среды WSGI. Также обрабатывает процесс декодирования WSGI. Возвращаемая строка будет ограничена символами ASCII.

Параметры: environ (WSGIEnvironment) – среда WSGI для получения строки запроса.
Тип возвращаемого значения: str

Изменения

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

werkzeug.wsgi.get_script_name(environ, charset='utf-8', errors='replace')

Возвращает имя скрипта из среды WSGI и декодирует его, если charset не установлено в None.

Параметры

environ (WSGIEnvironment) – среда WSGI для получения пути.
charset (str) – кодировка символов для пути, или None если декодирование не требуется.
errors (str) – обработка ошибок декодирования.

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

str

Изменения

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

werkzeug.wsgi.get_path_info(environ, charset='utf-8', errors='replace')

Возвращает информацию о пути из среды WSGI и декодирует её, если charset не равно None.

Параметры

environ (WSGIEnvironment) – среда WSGI для получения пути.
charset (str) – кодировка символов для информации о пути, или None если декодирование не требуется.
errors (str) – обработка ошибок декодирования.

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

str

Изменения

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

werkzeug.wsgi.pop_path_info(environ, charset='utf-8', errors='replace')

Удаляет и возвращает следующий сегмент PATH_INFO, помещая его в SCRIPT_NAME. Возвращает None если в PATH_INFO ничего не осталось.

Если charset установлено в None, возвращаются байты.

Если есть пустые сегменты ('/foo//bar), они игнорируются, но правильно помещаются в SCRIPT_NAME.

>>> env = {'SCRIPT_NAME': '/foo', 'PATH_INFO': '/a/b'}
>>> pop_path_info(env)
'a'
>>> env['SCRIPT_NAME']
'/foo/a'
>>> pop_path_info(env)
'b'
>>> env['SCRIPT_NAME']
'/foo/a/b'

Изменения

Изменено в версии 0.9: Путь теперь декодируется, а параметр charset и encoding можно предоставить.

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

Параметры

environ (WSGIEnvironment) – среда WSGI, которая изменяется.
charset (str) – параметр encoding переданный в bytes.decode().
errors (str) – параметр errors переданный в bytes.decode().

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

Optional[str]

werkzeug.wsgi.peek_path_info(environ, charset='utf-8', errors='replace')

Возвращает следующий сегмент в PATH_INFO или None если такового нет. Работает как pop_path_info() без изменения среды:

>>> env = {'SCRIPT_NAME': '/foo', 'PATH_INFO': '/a/b'}
>>> peek_path_info(env)
'a'
>>> peek_path_info(env)
'a'

Если charset установлено в None байт возвращаются.

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

Изменено в версии 0.9: Путь теперь декодирован, и можно указать параметр кодировки.

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

Параметры

environ (WSGIEnvironment) – окружение WSGI, которое проверяется.
charset (str) –
errors (str) –

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

Optional[str]

werkzeug.wsgi.extract_path_info(environ_or_baseurl, path_or_url, charset='utf-8', errors='werkzeug.url_quote', collapse_http_schemes=True)

Извлекает информацию о пути из заданного URL (или среды WSGI) и пути. Возвращаемая информация о пути — это строка. URL также могут быть IRIs.

Если информация о пути не может быть определена, None возвращается.

Примеры:

>>> extract_path_info('http://example.com/app', '/app/hello')
'/hello'
>>> extract_path_info('http://example.com/app',
...                   'https://example.com/app/hello')
'/hello'
>>> extract_path_info('http://example.com/app',
...                   'https://example.com/app/hello',
...                   collapse_http_schemes=False) is None
True

Вместо указания базового URL вы также можете передать среду WSGI.

Параметры

environ_or_baseurl (Union[str, WSGIEnvironment]) – словарь среды WSGI, базовый URL или базовый IRI. Это корень приложения.
path_or_url (Union[str, werkzeug.urls._URLTuple]) – абсолютный путь от корня сервера, относительный путь (в этом случае это информация о пути) или полный URL.
charset (str) – кодировка набора символов для данных в байтах в URL
errors (str) – обработка ошибок при декодировании
collapse_http_schemes (bool) – если установлено в False, алгоритм не предполагает, что http и https на одном сервере указывают на один и тот же ресурс.

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

Optional[str]

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

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

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

werkzeug.wsgi.host_is_trusted(hostname, trusted_list)

Проверяет, соответствует ли хост списку доверенных имен.

Параметры

hostname (str) – имя для проверки.
trusted_list (Iterable[str]) – список допустимых имен для соответствия. Если имя начинается с точки, оно будет соответствовать всем поддоменам.

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

bool

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

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

Дополнительные вспомогательные функции

werkzeug.wsgi.responder(f)

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

Пример:

@responder
def application(environ, start_response):
    return Response('Hello World!')

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

werkzeug.testapp.test_app(environ, start_response)

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

>>> from werkzeug.serving import run_simple
>>> from werkzeug.testapp import test_app
>>> run_simple('localhost', 3000, test_app)
 * Running on http://localhost:3000/

Приложение отображает важную информацию из среды WSGI, интерпретатора Python и установленных библиотек.

Параметры

environ (WSGIEnvironment) –
start_response (StartResponse) –

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

Iterable[bytes]

Байты, строки и кодировки

Значения в HTTP-запросах поступают в виде байтов, представляющих (или закодированных в) ASCII. Спецификация WSGI (PEP 3333) решила всегда использовать тип str для представления значений. Для этого необработанные байты декодируются с использованием набора символов ISO-8859-1, чтобы получить строку.

Строки в среде WSGI ограничены кодовыми точками набора символов ISO-8859-1. Если строка, считанная из среды, может содержать символы за пределами этого набора символов, она должна быть сначала декодирована в байты как ISO-8859-1, а затем закодирована в строку с использованием соответствующего набора символов (обычно UTF-8). Обратное выполняется при записи в среду. Это известно как «танцы кодирования WSGI».

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

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

Необработанный URI запроса и кодировка пути

PATH_INFO в среде — это значение пути после декодирования процентов. Например, необработанный путь /hello%2fworld будет отображаться сервером WSGI для Werkzeug как /hello/world. Это теряет информацию о том, что косая черта была необработанным символом, а не разделителем пути.

Спецификация WSGI (PEP 3333) не предоставляет способа получить исходное значение, поэтому невозможно маршрутизировать некоторые типы данных в пути. Наиболее совместимый способ обойти это — отправлять проблемные данные в строке запроса вместо пути.

Однако многие серверы WSGI добавляют нестандартный ключ environ с необработанным путем. Для соответствия этому поведению тестовый клиент и сервер разработки Werkzeug добавят необработанное значение как в REQUEST_URI, так и в RAW_URI ключи. Если вы хотите маршрутизировать на основе этого значения, вы можете использовать промежуточное ПО для замены PATH_INFO в среде environ перед тем, как она достигнет приложения. Однако имейте в виду, что эти ключи являются нестандартными и не гарантируется их наличие.