Spec-Zone.ru › Werkzeug 1.0

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.11.10: добавлена поддержка параметра cap_at_buffer.

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

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

Параметры:
  • 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.11.10: добавлена поддержка параметра cap_at_buffer.

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

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

Параметры:
  • 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)

Возвращает 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 – кодировка символов для path info, или 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'
Changelog

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

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

Параметры: 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, возвращается строка байтов.

Changelog

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

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

Параметры: 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) и пути. Возвращаемая информация о пути — строка Unicode, а не строка байтов, подходящая для среды 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 и параметры Unicode.
  • charset – набор символов для данных байтов в URL
  • errors – обработка ошибок при декодировании
  • collapse_http_schemes – если установлено в False, алгоритм не предполагает, что http и https на одном сервере указывают на один и тот же ресурс.
Changelog

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

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

werkzeug.wsgi.host_is_trusted(hostname, trusted_list)

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

Changelog

Добавлен в версии 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 скрывает эти различия от вас, если вы используете интерфейсы высокого уровня.

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

Строки Unicode в среде WSGI в Python 3 ограничены кодами символов ISO-8859-1. Если строка, считанная из среды, может содержать символы за пределами этого набора символов, она должна быть сначала декодирована в байты как ISO-8859-1, а затем закодирована в строку Unicode с использованием правильного набора символов (обычно 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. Если вы хотите маршрутизировать на основе этого значения, вы можете использовать middleware, чтобы заменить PATH_INFO в environ перед передачей его приложению. Однако имейте в виду, что эти ключи нестандартные и не гарантируются.

© 2007–2020 Pallets
Licensed under the BSD 3-clause License.
https://werkzeug.palletsprojects.com/en/1.0.x/wsgi/

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API