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[байты]) –
• 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 (IO[байты]) – объект, похожий на file, с методом read().
• buffer_size (int) – число байтов для одной итерации.

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

None

class werkzeug.wsgi.LimitedStream(stream, limit)

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

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

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

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

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

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

Параметры

• stream (IO[bytes]) – поток, который нужно обернуть.
• 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

New in version 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: Теперь функция гарантирует, что предел был достигнут.

Параметры

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

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

Iterator[bytes]

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.

Параметры

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

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

Iterator[bytes]

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

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

Changelog

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

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

Более подробная информация об оболочках файлов доступна в PEP 333.

Параметры

• file (IO[bytes]) – объект, похожий на file, с методом read().
• buffer_size (int) – количество байт для одной итерации.
• environ (WSGIEnvironment) –

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

Iterable[bytes]

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

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

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

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

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

При необходимости можно проверить, является ли хост надёжным, используя host_is_trusted(), и поднять исключение SecurityError, если он ненадёжен.

Параметры

• environ (WSGIEnvironment) – Словарь среды WSGI.
• trusted_hosts (Optional[Iterable[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) – использовать пустой поток в качестве безопасного варианта по умолчанию, когда длина содержимого не задана. Отключение этого параметра позволяет использовать бесконечные потоки, что может представлять угрозу отказ в обслуживании.

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

IO[bytes]

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 (Optional[Iterable[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: Путь теперь декодируется, и можно указать параметр кодировки.

Добавлена в версии 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). Обратное выполняется при записи в environ. Это известно как «танец кодирования WSGI».

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

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

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

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

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

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