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[байты]) –
callbacks (Optional[Union[Callable[[], None], Iterable[Callable[[], 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) – количество байтов для одной итерации.

END_OF_DOCUMENT_MARKER

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 (IO[bytes]) – поток для обёртки.
limit (int) – предел для потока, не должен быть длиннее, чем то, что может предоставить строка, если поток не заканчивается на EOF (например, wsgi.input)

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() без аргументов.

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

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

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

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

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

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

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

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

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

Параметры:

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

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

Iterable[bytes]

END_OF_DOCUMENT_MARKER

Справочные функции среды

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

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

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

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

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

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

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

Устарело начиная с версии 2.2: Будет удалено в Werkzeug 2.3.

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

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

Устарело начиная с версии 2.2: Будет удалено в Werkzeug 2.3.

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

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

Устарело начиная с версии 2.2: Будет удалено в Werkzeug 2.3.

Изменения

Изменено в версии 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 байт возвращаются.

Устарело начиная с версии 2.2: Будет удалено в Werkzeug 2.3.

Изменения

Изменено в версии 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, _URLTuple]) – абсолютный путь от корня сервера, относительный путь (в этом случае это информация о пути) или полный URL.
charset (str) – набор символов для байтовых данных в URL
errors (str) – обработка ошибок при декодировании
collapse_http_schemes (bool) – если установлено в False, алгоритм не предполагает, что http и https на одном сервере указывают на один и тот же ресурс.

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

Optional[str]

Устарело начиная с версии 2.2: Будет удалено в Werkzeug 2.3.

Изменения

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

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

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