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()

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

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

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

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

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

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

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

exhaust(chunk_size=65536)

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

Параметры:	chunk_size – размер блока. Он будет читать блок до тех пор, пока поток не будет исчерпан, а результаты будут удалены.

is_exhausted

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

on_disconnect()

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

on_exhausted()

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

read(size=None)

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

Параметры:	size – количество байтов для чтения.

readable()

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

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

readline(size=None)

Читает одну строку из потока.

readlines(size=None)

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

tell()

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

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

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

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

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

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

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

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

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

Параметры:	stream – поток или итератор для итерации. limit – предел в байтах для потока. (Обычно длина содержимого. Не требуется, если stream — это LimitedStream. buffer_size – необязательный размер буфера. cap_at_buffer – если это установлено, блоки разделяются, если они длиннее размера буфера. Внутренне это реализовано так, что размер буфера может быть исчерпан в два раза.

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

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

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

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

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

Параметры:

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

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

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

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

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

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

Параметры:	file – объект, похожий на file, с методом read(). buffer_size – количество байтов для одной итерации.

Справочные данные по окружению

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

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

Возвращает хост для данного окружения WSGI. Сначала проверяется заголовок Host. Если его нет, используются SERVER_NAME и SERVER_PORT. Хост будет содержать порт только в том случае, если он отличается от стандартного порта для протокола.

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

Параметры:	environ – окружение WSGI для получения хоста. trusted_hosts – список доверенных хостов.
Возвращает:	Хост, с портом, если необходимо.
Исключения:	SecurityError – если хост недоверен.

werkzeug.wsgi.get_content_length(environ)

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

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

Параметры:	environ – окружение WSGI для извлечения длины содержимого.

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

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

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

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

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

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

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

>>> from werkzeug.test import create_environ
>>> env = create_environ("/?param=foo", "http://localhost/script")
>>> get_current_url(env)
'http://localhost/script/?param=foo'
>>> get_current_url(env, root_only=True)
'http://localhost/script/'
>>> get_current_url(env, host_only=True)
'http://localhost/'
>>> get_current_url(env, strip_querystring=True)
'http://localhost/script/'

Это также проверяет, входит ли хост в список доверенных хостов. Если хост там нет, он выбросит SecurityError.

Обратите внимание, что возвращаемая строка может содержать символы Юникода, так как представление является IRI, а не URI. Если вам нужно представление только в ASCII, вы можете использовать функцию iri_to_uri():

>>> from werkzeug.urls import iri_to_uri
>>> iri_to_uri(get_current_url(env))
'http://localhost/script/?param=foo'

Параметры:	environ – окружение WSGI для получения текущего URL. root_only – установите True, если нужен только корневой URL. strip_querystring – установите в True, если не нужна строка запроса. host_only – установите в True, если должен быть возвращён только хост URL. trusted_hosts – список доверенных хостов, см. host_is_trusted() для получения дополнительной информации.

werkzeug.wsgi.get_query_string(environ)

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

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

Параметры:	environ – объект окружения WSGI для получения строки запроса.

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

Возвращает имя скрипта из окружения WSGI и правильно его декодирует. Это также учитывает WSGI-процесс декодирования в средах Python 3. Если charset установлено в None, возвращается строка байтов.

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

Параметры:	environ – объект окружения WSGI для получения пути. charset – кодировка для пути, или None, если декодирование не должно выполняться. errors – обработка ошибок при декодировании.

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

Возвращает информацию о пути из окружения WSGI и правильно её декодирует. Это также учитывает WSGI-процесс декодирования в средах Python 3. Если charset установлено в None, возвращается строка байтов.

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

Параметры:	environ – объект окружения WSGI для получения пути. charset – кодировка для информации о пути, или None если декодирование не должно выполняться. errors – обработка ошибок при декодировании.

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.5.

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

Параметры:	environ – среда WSGI, которая изменяется.

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.5.

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

Параметры:	environ – проверяемая среда WSGI.

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

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

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

Примеры:

>>> extract_path_info('http://example.com/app', '/app/hello')
u'/hello'
>>> extract_path_info('http://example.com/app',
...                   'https://example.com/app/hello')
u'/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 – словарь среды WSGI, базовый URL или базовый IRI. Это корень приложения. path_or_url – абсолютный путь от корня сервера, относительный путь (в этом случае это информация о пути) или полный URL. Также принимает IRIs и параметры Юникод. charset – кодировка символов для данных в байтах в URL errors – обработка ошибок при декодировании collapse_http_schemes – если установлено в False , алгоритм не предполагает, что http и https на одном сервере указывают на один и тот же ресурс.

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

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

werkzeug.wsgi.host_is_trusted(hostname, trusted_list)

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

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

Параметры:	hostname – хост, который нужно проверить trusted_list – список хостов для проверки. Если имя хоста начинается с точки, оно будет соответствовать всем поддоменам.

Удобные помощники

werkzeug.wsgi.responder(f)

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

Пример:

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

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 и установленных библиотек.

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

Среда WSGI в Python 3 работает немного по-другому, чем в Python 2. Werkzeug скрывает эти различия от вас, если вы используете API более высокого уровня.

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

Строки Юникод Python 3 в среде 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 перед тем, как она достигнет приложения. Однако имейте в виду, что эти ключи нестандартны и не гарантируется, что они будут присутствовать.