WSGI Помощники

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

Помощники итератора/потока

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

class werkzeug.wsgi.ClosingIterator(iterable, callbacks=None)

Спецификация WSGI требует, чтобы все промежуточные программные модули и шлюзы соблюдали close обратный вызов итерируемого объекта, возвращаемого приложением. Поскольку полезно добавить еще один закрывающий action к возвращаемому итерируемому объекту, а добавление пользовательского итерируемого объекта является утомительной задачей, для этого можно использовать этот класс:

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, если она доступна.

New in version 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. К сожалению, WSGI PEP не может быть безопасно реализован без аргумента размера для 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()

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

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

New in version 0.9: добавлена поддержка итераторов как входных потоков.

New in version 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 – количество байтов для одной итерации.

Environ Helpers

Эти функции работают с окружением 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 transfer, возвращается 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)

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

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

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

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

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

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

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

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

Возвращает PATH_INFO из окружения 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 также могут быть IRI.

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

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