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

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[байты]) – Поток для чтения. Должен быть читаемым двоичным объектом ввода-вывода.
• limit (целое число) – Предел в байтах, до которого не следует читать. Должен быть либо значением заголовка Content-Length, либо request.max_content_length.
• is_max (булево значение) – Является ли данный limit request.max_content_length вместо значения заголовка Content-Length. Это меняет то, как обрабатываются события исчерпания и отключения.

Изменения

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

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

exhaust()

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

Изменения

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

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

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

байты

property is_exhausted: bool

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

on_disconnect(error=None)

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

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

Изменения

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

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

Параметры:

error (Исключение | None) –

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

None

on_exhausted()

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

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

Изменения

Изменено в версии 2.3: Вызывает исключение RequestEntityTooLarge если предел максимальный.

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

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

None

readable()

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

Если False, read() вызовет OSError.

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

булево значение

readall()

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

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

байты

tell()

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

Изменения

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

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

целое число

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

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

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

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

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

Новая в версии 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) – Максимальная длина, которую content-length или запросы потокового типа не должны превышать.

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

t.IO[bytes]

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

Изменено в версии 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) – Имя для проверки.
• trusted_list (Iterable[str]) – Список допустимых имён для сопоставления. Если имя начинается с точки, оно будет соответствовать всем поддоменам.

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

bool

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

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

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

Ответ

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

Значения в 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 в environ — это значение пути после декодирования процентов. Например, необработанный путь /hello%2fworld отобразится в Werkzeug от сервера WSGI как /hello/world. Это теряет информацию о том, что слеш был сырым символом, а не разделителем пути.

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

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