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 (t.Iterable[bytes])
• callbacks (None | (t.Callable[[], None] | t.Iterable[t.Callable[[], None]]))

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

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

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

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

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

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

Параметры:

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

class werkzeug.wsgi.LimitedStream(stream, limit, is_max=False)

Обернуть поток так, чтобы он не считывал больше заданного предела. Это используется для ограничения wsgi.input значением заголовка Content-Length или Request.max_content_length.

При попытке чтения после достижения предела вызывается on_exhausted(). При достижении максимального предела это приводит к поднятию RequestEntityTooLarge.

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

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

Параметры:

• stream (t.IO[bytes]) – поток для чтения. Должен быть читабельным двоичным объектом ввода/вывода.
• limit (int) – предел в байтах, до которого не должно производиться чтение. Должно быть значением заголовка Content-Length или request.max_content_length.
• is_max (bool) – является ли заданный limit request.max_content_length вместо значения заголовка Content-Length. Это изменяет то, как обрабатываются события исчерпания и разрыва соединения.

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

Изменено в версии 2.3: Обрабатывает max_content_length по-другому, чем Content-Length.

Изменено в версии 2.3: Реализует io.RawIOBase вместо io.IOBase.

property is_exhausted: bool

Указывает, достиг ли текущий указатель потока предела.

on_exhausted()

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

По умолчанию ничего не выполняется, если предел не является максимальным, в этом случае поднимается RequestEntityTooLarge.

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

Изменено в версии 2.3: Поднимает RequestEntityTooLarge если предел максимален.

Изменено в версии 2.3: Любое возвращаемое значение игнорируется.

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

None

on_disconnect(error=None)

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

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

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

Изменено в версии 2.3: Добавлен параметр error. Не делать ничего, если предел максимальный и не было поднято исключение.

Изменено в версии 2.3: Любое возвращаемое значение игнорируется.

Параметры:

error (Exception | None)

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

None

exhaust()

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

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

Изменено в версии 2.3: Возвращает оставшиеся данные.

Изменено в версии 2.2.3: Обрабатывает случай, когда обернутый поток возвращает меньше байтов, чем запрошено.

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

bytes

readall()

Чтение до EOF, используя несколько вызовов read().

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

bytes

tell()

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

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

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

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

int

readable()

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

Если False, read() поднимет OSError.

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

bool

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

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

Changelog

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

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

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

Параметры:

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

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

t.Iterable[bytes]

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

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

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

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

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

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

Параметры:

• environ (WSGIEnvironment) – Словарь среды WSGI.
• trusted_hosts (t.Iterable[str] | None) – Список надёжных имён хостов.

Возвращаемое значение:

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

Исключения:

SecurityError – Если хост не надёжен.

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

str

werkzeug.wsgi.get_content_length(environ)

Возвращает значение заголовка Content-Length в виде целого числа. Если заголовок не задан или заголовок Transfer-Encoding равен chunked, возвращается None, чтобы указать на запрос потокового типа. Если значение не является целым числом или отрицательным, возвращается 0.

Параметры:

environ (WSGIEnvironment) – Среда WSGI для получения длины содержимого.

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

int | None

Changelog

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

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

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

Если Content-Length превышает max_content_length, генерируется ошибка RequestEntityTooLarge` 413 Content Too Large.

Если сервер WSGI устанавливает environ["wsgi.input_terminated"], это указывает, что сервер обрабатывает завершение потока, поэтому его безопасно читать напрямую. Например, сервер, который знает, как безопасно обрабатывать запросы с фрагментацией, установит это.

Если max_content_length установлен, его можно применить к потокам, если wsgi.input_terminated установлен. В противном случае возвращается пустой поток, если пользователь явно не отключил этот безопасный резервный вариант.

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

Параметры:

• environ (WSGIEnvironment) – Среда WSGI, содержащая поток.
• safe_fallback (bool) – Возвращает пустой поток, когда Content-Length не установлен. Отключение этого позволяет бесконечные потоки, что может представлять риск отказа в обслуживании.
• max_content_length (int | None) – Максимальная длина, которую длина содержимого или запросы потокового типа не должны превышать.

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

t.IO[bytes]

Changelog

Изменено в версии 2.3.2: max_content_length применяется только к запросам потокового типа, если сервер устанавливает wsgi.input_terminated.

Изменено в версии 2.3: Проверяется max_content_length и генерируется ошибка, если она превышена.

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

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 (t.Iterable[str] | None) – Список надёжных имён хостов для проверки хоста.

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

str

werkzeug.wsgi.host_is_trusted(hostname, trusted_list)

Проверка соответствия имени хоста списку надёжных имён.

Параметры:

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

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

bool

Changelog

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

Утилиты для удобства

werkzeug.wsgi.responder(f)

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

Пример:

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

Параметры:

f (t.Callable[..., WSGIApplication])

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

WSGIApplication

werkzeug.testapp.test_app(req)

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

Параметры:

req (Request)

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

Response

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

Значения в 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 добавляют в окружение ключ со специальным нестандартным именем, содержащий необработанный путь. Для соответствия этому поведению тестовый клиент и сервер разработки Werkzeug добавляют сырое значение в ключи REQUEST_URI и RAW_URI. Если вы хотите маршрутизировать по этому значению, вы можете использовать мидлварь для замены PATH_INFO в окружении перед тем, как оно достигнет приложения. Однако следует помнить, что эти ключи являются нестандартными и не гарантируется их присутствие.