`wsgiref` — Утилиты WSGI и эталонная реализация¶

Источник: Lib/wsgiref

Интерфейс шлюза веб-сервера (WSGI) - это стандартный интерфейс между программным обеспечением веб-сервера и веб-приложениями, написанными на языке Python. Наличие стандартного интерфейса позволяет легко использовать приложение, поддерживающее WSGI, с различными веб-серверами.

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

wsgiref - это эталонная реализация спецификации WSGI, которая может быть использована для добавления поддержки WSGI в веб-сервер или фреймворк. Он предоставляет утилиты для работы с переменными окружения WSGI и заголовками ответов, базовые классы для реализации серверов WSGI, демонстрационный HTTP-сервер, обслуживающий приложения WSGI, типы для статической проверки типов, а также инструмент проверки, который проверяет серверы и приложения WSGI на соответствие спецификации WSGI (PEP 3333).

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

`wsgiref.util` – Утилиты среды WSGI¶

Этот модуль предоставляет множество полезных функций для работы со средами WSGI. Среда WSGI - это словарь, содержащий переменные HTTP-запроса, как описано в PEP 3333. Все функции, принимающие параметр environ, ожидают предоставления WSGI-совместимого словаря; смотрите PEP 3333 для подробной спецификации и WSGIEnvironment для псевдонима типа, который может быть использован в аннотациях типов.

wsgiref.util.guess_scheme(environ)¶

Возвращает предположение о том, должен ли wsgi.url_scheme быть «http» или «https», проверяя наличие переменной окружения HTTPS в словаре environ. Возвращаемое значение - строка.

Эта функция полезна при создании шлюза, который оборачивает CGI или CGI-подобный протокол, такой как FastCGI. Обычно серверы, предоставляющие такие протоколы, включают переменную HTTPS со значением «1», «yes» или «on», когда запрос поступает по протоколу SSL. Таким образом, эта функция возвращает «https», если такое значение найдено, и «http» в противном случае.

wsgiref.util.request_uri(environ, include_query=True)¶: Возвращает полный URI запроса, по желанию включая строку запроса, используя алгоритм, описанный в разделе «Реконструкция URL» в PEP 3333. Если include_query равно false, строка запроса не будет включена в результирующий URI.

wsgiref.util.application_uri(environ)¶: Аналогично request_uri(), за исключением того, что переменные PATH_INFO и QUERY_STRING игнорируются. Результатом является базовый URI объекта приложения, к которому обращен запрос.

wsgiref.util.shift_path_info(environ)¶

Переместите одно имя из PATH_INFO в SCRIPT_NAME и верните это имя. Словарь environ изменяется на месте; используйте копию, если вам нужно сохранить исходный PATH_INFO или SCRIPT_NAME.

Если в PATH_INFO нет оставшихся сегментов пути, возвращается None.

Обычно эта процедура используется для обработки каждой части пути URI запроса, например, для обработки пути как серии ключей словаря. Эта процедура изменяет переданное окружение, чтобы сделать его пригодным для вызова другого приложения WSGI, расположенного по целевому URI. Например, если есть WSGI-приложение по адресу /foo, путь URI запроса - /foo/bar/baz, и WSGI-приложение по адресу /foo вызывает shift_path_info(), оно получит строку «bar», и окружение будет обновлено, чтобы стать пригодным для передачи WSGI-приложению по адресу /foo/bar. То есть SCRIPT_NAME сменит /foo на /foo/bar, а PATH_INFO сменит /bar/baz на /baz.

Когда PATH_INFO - это просто «/», эта процедура возвращает пустую строку и добавляет к SCRIPT_NAME косую черту, хотя пустые сегменты пути обычно игнорируются, а SCRIPT_NAME обычно не заканчивается косой чертой. Это намеренное поведение, чтобы приложение могло отличить URI, заканчивающиеся на /x, от тех, что заканчиваются на /x/, когда использует эту процедуру для обхода объектов.

wsgiref.util.setup_testing_defaults(environ)¶

Обновите environ с тривиальными значениями по умолчанию для целей тестирования.

Эта процедура добавляет различные параметры, необходимые для WSGI, включая HTTP_HOST, SERVER_NAME, SERVER_PORT, REQUEST_METHOD, SCRIPT_NAME, PATH_INFO и все PEP 3333-определенные wsgi.* переменные. Она предоставляет только значения по умолчанию и не заменяет никаких существующих настроек для этих переменных.

Эта процедура предназначена для того, чтобы облегчить модульным тестам серверов и приложений WSGI создание фиктивных сред. Она НЕ должна использоваться настоящими WSGI-серверами или приложениями, поскольку данные в ней фальшивые!

Пример использования:

from wsgiref.util import setup_testing_defaults
from wsgiref.simple_server import make_server

# A relatively simple WSGI application. It's going to print out the
# environment dictionary after being updated by setup_testing_defaults
def simple_app(environ, start_response):
    setup_testing_defaults(environ)

    status = '200 OK'
    headers = [('Content-type', 'text/plain; charset=utf-8')]

    start_response(status, headers)

    ret = [("%s: %s\n" % (key, value)).encode("utf-8")
           for key, value in environ.items()]
    return ret

with make_server('', 8000, simple_app) as httpd:
    print("Serving on port 8000...")
    httpd.serve_forever()

Помимо вышеперечисленных функций окружения, модуль wsgiref.util также предоставляет следующие различные утилиты:

wsgiref.util.is_hop_by_hop(header_name)¶: Возвращает True, если „header_name“ является заголовком HTTP/1.1 «Hop-by-Hop», как определено в RFC 2616.

class wsgiref.util.FileWrapper(filelike, blksize=8192)¶

Конкретная реализация протокола wsgiref.types.FileWrapper, используемого для преобразования файлоподобного объекта в iterator. Результирующими объектами являются iterables. По мере итерации объекта необязательный параметр blksize будет неоднократно передаваться в метод read() объекта filelike для получения байтстрингов для выдачи. Если read() возвращает пустой байтстринг, итерация завершается и не возобновляется.

Если у filelike есть метод close(), то у возвращаемого объекта также будет метод close(), и при вызове он будет вызывать метод close() объекта filelike.

Пример использования:

from io import StringIO
from wsgiref.util import FileWrapper

# We're using a StringIO-buffer for as the file-like object
filelike = StringIO("This is an example file-like object"*10)
wrapper = FileWrapper(filelike, blksize=5)

for chunk in wrapper:
    print(chunk)

Изменено в версии 3.11: Поддержка метода __getitem__() была удалена.

`wsgiref.headers` – Инструменты для заголовков ответов WSGI¶

Этот модуль предоставляет один класс Headers для удобной работы с заголовками ответов WSGI с помощью интерфейса, подобного маппингу.

class wsgiref.headers.Headers([headers])¶

Создайте маппинг-подобный объект, оборачивающий headers, который должен быть списком кортежей имя/значение заголовка, как описано в PEP 3333. По умолчанию значение headers - пустой список.

Объекты Headers поддерживают типичные операции отображения, включая __getitem__(), get(), __setitem__(), setdefault(), __delitem__() и __contains__(). Для каждого из этих методов ключом является имя заголовка (с учетом регистра), а значением - первое значение, связанное с этим именем заголовка. Установка заголовка удаляет все существующие значения для этого заголовка, а затем добавляет новое значение в конец обернутого списка заголовков. Существующий порядок заголовков обычно сохраняется, а новые заголовки добавляются в конец обернутого списка.

В отличие от словаря, объекты Headers не выдают ошибку при попытке получить или удалить ключ, которого нет в обернутом списке заголовков. Получение несуществующего заголовка просто возвращает None, а удаление несуществующего заголовка ничего не дает.

Объекты Headers также поддерживают методы keys(), values() и items(). Списки, возвращаемые методами keys() и items(), могут включать один и тот же ключ более одного раза при наличии многозначного заголовка. Длина len() объекта Headers равна длине его items(), которая равна длине обернутого списка заголовков. Фактически, метод items() просто возвращает копию обернутого списка заголовков.

Вызов bytes() на объекте Headers возвращает отформатированную строку байт, пригодную для передачи в качестве заголовков HTTP-ответа. Каждый заголовок размещается в строке вместе со своим значением, разделяясь двоеточием и пробелом. Каждая строка завершается возвратом каретки и переводом строки, а байтовая строка завершается пустой строкой.

Помимо интерфейса отображения и возможностей форматирования, объекты Headers также имеют следующие методы для запроса и добавления многозначных заголовков, а также для добавления заголовков с параметрами MIME:

get_all(name)¶

Возвращает список всех значений для именованного заголовка.

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

add_header(name, value, **_params)¶

Добавляет заголовок (возможно, многозначный) с дополнительными MIME-параметрами, указанными с помощью аргументов-ключей.

name - поле заголовка, которое нужно добавить. Аргументы ключевых слов могут использоваться для задания параметров MIME для поля заголовка. Каждый параметр должен быть строкой или None. Подчеркивания в именах параметров преобразуются в тире, поскольку тире недопустимо в идентификаторах Python, но многие имена параметров MIME содержат тире. Если значение параметра является строкой, оно добавляется к параметрам значения заголовка в виде name="value". Если это None, добавляется только имя параметра. (Это используется для параметров MIME без значения.) Пример использования:

h.add_header('content-disposition', 'attachment', filename='bud.gif')

Вышеописанное добавит заголовок, который будет выглядеть следующим образом:

Content-Disposition: attachment; filename="bud.gif"

Изменено в версии 3.5: Параметр headers является необязательным.

`wsgiref.simple_server` – простой HTTP-сервер WSGI¶

Этот модуль реализует простой HTTP-сервер (основанный на http.server), который обслуживает WSGI-приложения. Каждый экземпляр сервера обслуживает одно WSGI-приложение на заданном хосте и порту. Если вы хотите обслуживать несколько приложений на одном хосте и порту, вам следует создать WSGI-приложение, которое будет анализировать PATH_INFO, чтобы выбрать, какое приложение вызывать для каждого запроса. (Например, с помощью функции shift_path_info() из wsgiref.util).

wsgiref.simple_server.make_server(host, port, app, server_class=WSGIServer, handler_class=WSGIRequestHandler)¶

Создает новый WSGI-сервер, слушающий на host и port, принимающий соединения для app. Возвращаемое значение - экземпляр указанного класса server_class, который будет обрабатывать запросы, используя указанный класс handler_class. app должен быть объектом приложения WSGI, как определено в PEP 3333.

Пример использования:

from wsgiref.simple_server import make_server, demo_app

with make_server('', 8000, demo_app) as httpd:
    print("Serving HTTP on port 8000...")

    # Respond to requests until process is killed
    httpd.serve_forever()

    # Alternative: serve one request, then exit
    httpd.handle_request()

wsgiref.simple_server.demo_app(environ, start_response)¶: Эта функция представляет собой небольшое, но полноценное WSGI-приложение, которое возвращает текстовую страницу, содержащую сообщение «Hello world!» и список пар ключ/значение, указанных в параметре environ. Она полезна для проверки того, что WSGI-сервер (например, wsgiref.simple_server) способен корректно запустить простое WSGI-приложение.

class wsgiref.simple_server.WSGIServer(server_address, RequestHandlerClass)¶

Создайте экземпляр WSGIServer. адрес_сервера должен быть кортежем (host,port), а RequestHandlerClass должен быть подклассом http.server.BaseHTTPRequestHandler, который будет использоваться для обработки запросов.

Обычно вам не нужно вызывать этот конструктор, так как функция make_server() может обработать все детали за вас.

WSGIServer является подклассом http.server.HTTPServer, поэтому все его методы (такие как serve_forever() и handle_request()) доступны. WSGIServer также предоставляет эти специфические для WSGI методы:

set_app(application)¶: Устанавливает вызываемое application в качестве приложения WSGI, которое будет принимать запросы.

get_app()¶: Возвращает установленный в данный момент вызываемый элемент приложения.

Обычно, однако, вам не нужно использовать эти дополнительные методы, поскольку set_app() обычно вызывается make_server(), а get_app() существует в основном в интересах экземпляров обработчиков запросов.

class wsgiref.simple_server.WSGIRequestHandler(request, client_address, server)¶

Создайте HTTP-обработчик для заданного запроса (т.е. сокета), адрес_клиента (кортеж (host,port)) и сервер (экземпляр:class:WSGIServer).

Вам не нужно создавать экземпляры этого класса напрямую; они автоматически создаются по мере необходимости объектами WSGIServer. Однако вы можете создать подкласс этого класса и передать его в качестве класса_обработчика в функцию make_server(). Некоторые методы, которые могут быть переопределены в подклассах:

get_environ()¶: Возвращает словарь WSGIEnvironment для запроса. Реализация по умолчанию копирует содержимое атрибута WSGIServer словаря объекта base_environ, а затем добавляет различные заголовки, полученные из HTTP-запроса. Каждый вызов этого метода должен возвращать новый словарь, содержащий все соответствующие переменные окружения CGI, как указано в PEP 3333.

get_stderr()¶: Возвращает объект, который должен использоваться в качестве потока wsgi.errors. Реализация по умолчанию просто возвращает sys.stderr.

handle()¶: Обработка HTTP-запроса. Реализация по умолчанию создает экземпляр обработчика, используя класс wsgiref.handlers для реализации фактического интерфейса приложения WSGI.

`wsgiref.validate` — Программа проверки соответствия WSGI¶

При создании новых объектов приложений WSGI, фреймворков, серверов или промежуточного программного обеспечения может быть полезно проверить соответствие нового кода с помощью wsgiref.validate. Этот модуль предоставляет функцию, создающую объекты приложений WSGI, которые проверяют связь между сервером или шлюзом WSGI и объектом приложения WSGI, чтобы проверить обе стороны на соответствие протоколу.

Обратите внимание, что эта утилита не гарантирует полного соответствия PEP 3333; отсутствие ошибок в этом модуле не обязательно означает, что ошибок не существует. Однако если этот модуль выдает ошибку, то практически наверняка сервер или приложение не соответствуют требованиям на 100 %.

Этот модуль основан на модуле paste.lint из библиотеки «Python Paste» Яна Бикинга.

wsgiref.validate.validator(application)¶

Оберните application и верните новый объект приложения WSGI. Возвращаемое приложение будет пересылать все запросы исходному приложению и проверять, что и приложение, и вызывающий его сервер соответствуют спецификации WSGI и RFC 2616.

Любое обнаруженное несоответствие приводит к появлению сообщения AssertionError; обратите внимание, однако, что способ обработки этих ошибок зависит от сервера. Например, wsgiref.simple_server и другие серверы, основанные на wsgiref.handlers (которые не переопределяют методы обработки ошибок для выполнения других действий), будут просто выводить сообщение о том, что произошла ошибка, и сбрасывать трассировку в sys.stderr или другой поток ошибок.

Эта обертка также может генерировать вывод с помощью модуля warnings, чтобы указать на поведение, которое вызывает сомнения, но на самом деле может быть не запрещено PEP 3333. Если они не подавлены с помощью опций командной строки Python или warnings API, любые такие предупреждения будут записываться в sys.stderr (не wsgi.errors, если только это не один и тот же объект).

Пример использования:

from wsgiref.validate import validator
from wsgiref.simple_server import make_server

# Our callable object which is intentionally not compliant to the
# standard, so the validator is going to break
def simple_app(environ, start_response):
    status = '200 OK'  # HTTP Status
    headers = [('Content-type', 'text/plain')]  # HTTP Headers
    start_response(status, headers)

    # This is going to break because we need to return a list, and
    # the validator is going to inform us
    return b"Hello World"

# This is the application wrapped in a validator
validator_app = validator(simple_app)

with make_server('', 8000, validator_app) as httpd:
    print("Listening on port 8000....")
    httpd.serve_forever()

`wsgiref.handlers` – базовые классы сервера/шлюза¶

Этот модуль предоставляет базовые классы-обработчики для реализации серверов и шлюзов WSGI. Эти базовые классы выполняют большую часть работы по взаимодействию с WSGI-приложением, если им предоставлена CGI-подобная среда, а также потоки ввода, вывода и ошибок.

class wsgiref.handlers.CGIHandler¶

Вызов на основе CGI через sys.stdin, sys.stdout, sys.stderr и os.environ. Это удобно, когда у вас есть WSGI-приложение и вы хотите запустить его как CGI-сценарий. Просто вызовите CGIHandler().run(app), где app - объект WSGI-приложения, который вы хотите вызвать.

Этот класс является подклассом BaseCGIHandler, который устанавливает wsgi.run_once в true, wsgi.multithread в false и wsgi.multiprocess в true, и всегда использует sys и os для получения необходимых CGI-потоков и окружения.

class wsgiref.handlers.IISCGIHandler¶

Специализированная альтернатива CGIHandler для использования при развертывании на веб-сервере Microsoft IIS без установки опции config allowPathInfo (IIS>=7) или metabase allowPathInfoForScriptMappings (IIS<7).

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

IIS можно настроить на передачу правильного PATH_INFO, но это приводит к другой ошибке, когда PATH_TRANSLATED оказывается неверным. К счастью, эта переменная используется редко и не гарантируется WSGI. Однако в IIS<7 настройка может быть выполнена только на уровне vhost, что влияет на все остальные сопоставления скриптов, многие из которых ломаются при обнаружении ошибки PATH_TRANSLATED. По этой причине IIS<7 почти никогда не развертывается с этим исправлением (даже в IIS7 оно редко используется, поскольку для него до сих пор нет пользовательского интерфейса).

Код CGI не может определить, была ли установлена опция, поэтому для него предусмотрен отдельный класс-обработчик. Он используется так же, как и CGIHandler, то есть путем вызова IISCGIHandler().run(app), где app - это объект приложения WSGI, который вы хотите вызвать.

Added in version 3.2.

class wsgiref.handlers.BaseCGIHandler(stdin, stdout, stderr, environ, multithread=True, multiprocess=False)¶

Аналогично CGIHandler, но вместо использования модулей sys и os среда CGI и потоки ввода-вывода указываются явно. Значения multithread и multiprocess используются для установки флагов wsgi.multithread и wsgi.multiprocess для любых приложений, запускаемых экземпляром обработчика.

Этот класс является подклассом SimpleHandler, предназначенным для использования с программным обеспечением, отличным от «серверов происхождения» HTTP. Если вы пишете реализацию шлюзового протокола (например, CGI, FastCGI, SCGI и т. д.), которая использует заголовок Status: для отправки HTTP-статуса, вам, вероятно, стоит использовать этот подкласс вместо SimpleHandler.

class wsgiref.handlers.SimpleHandler(stdin, stdout, stderr, environ, multithread=True, multiprocess=False)¶

Аналогичен BaseCGIHandler, но предназначен для использования с исходными серверами HTTP. Если вы пишете реализацию HTTP-сервера, вы, вероятно, захотите использовать этот подкласс вместо BaseCGIHandler.

Этот класс является подклассом BaseHandler. Он переопределяет методы __init__(), get_stdin(), get_stderr(), add_cgi_vars(), _write() и _flush() для поддержки явного задания окружения и потоков через конструктор. Заданные окружение и потоки хранятся в атрибутах stdin, stdout, stderr и environ.

Метод write() в stdout должен записывать каждый чанк полностью, как io.BufferedIOBase.

class wsgiref.handlers.BaseHandler¶

Это абстрактный базовый класс для запуска приложений WSGI. Каждый экземпляр будет обрабатывать один HTTP-запрос, хотя в принципе вы можете создать подкласс, который можно использовать для нескольких запросов.

У экземпляров BaseHandler есть только один метод, предназначенный для внешнего использования:

run(app)¶: Запустите указанное приложение WSGI, app.

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

Следующие методы ДОЛЖНЫ быть переопределены в подклассе:

_write(data)¶: Буферизация байтов данных для передачи клиенту. Ничего страшного, если этот метод действительно передает данные; BaseHandler просто разделяет операции записи и смывания для большей эффективности, когда базовая система действительно имеет такое различие.

_flush()¶: Принудительная передача буферизованных данных клиенту. Ничего страшного, если этот метод не работает (т.е. если _write() действительно отправляет данные).

get_stdin()¶: Возвращает объект, совместимый с InputStream, который можно использовать в качестве wsgi.input обрабатываемого запроса.

get_stderr()¶: Возвращает объект, совместимый с ErrorStream, который можно использовать в качестве wsgi.errors обрабатываемого запроса.

add_cgi_vars()¶: Вставьте переменные CGI для текущего запроса в атрибут environ.

Вот некоторые другие методы и атрибуты, которые вы, возможно, захотите переопределить. Однако этот список является лишь кратким изложением и не включает все методы, которые могут быть переопределены. Прежде чем пытаться создать собственный подкласс BaseHandler, обратитесь к документам и исходному коду за дополнительной информацией.

Атрибуты и методы для настройки среды WSGI:

wsgi_multithread¶: Значение, которое будет использоваться для переменной окружения wsgi.multithread. По умолчанию оно равно true в BaseHandler, но может иметь другое значение по умолчанию (или задаваться конструктором) в других подклассах.

wsgi_multiprocess¶: Значение, которое будет использоваться для переменной окружения wsgi.multiprocess. По умолчанию оно равно true в BaseHandler, но может иметь другое значение по умолчанию (или задаваться конструктором) в других подклассах.

wsgi_run_once¶: Значение, которое будет использоваться для переменной окружения wsgi.run_once. В BaseHandler оно по умолчанию равно false, но CGIHandler по умолчанию устанавливает его в true.

os_environ¶: Переменные окружения по умолчанию, которые должны быть включены в окружение WSGI каждого запроса. По умолчанию это копия os.environ на момент импорта wsgiref.handlers, но подклассы могут создавать свои собственные на уровне класса или экземпляра. Обратите внимание, что словарь следует рассматривать как доступный только для чтения, поскольку значение по умолчанию является общим для нескольких классов и экземпляров.

server_software¶: Если установлен атрибут origin_server, значение этого атрибута используется для установки переменной окружения WSGI по умолчанию SERVER_SOFTWARE. переменной окружения WSGI, а также для установки заголовка по умолчанию Server: в ответах HTTP. Он игнорируется для обработчиков (таких как BaseCGIHandler и CGIHandler), которые не являются исходными серверами HTTP.

Изменено в версии 3.3: Термин «Python» заменяется терминами, специфичными для конкретной реализации, такими как «CPython», «Jython» и т.д.

get_scheme()¶: Возвращает схему URL, используемую для текущего запроса. Реализация по умолчанию использует функцию guess_scheme() из wsgiref.util, чтобы определить, какой должна быть схема - «http» или «https», основываясь на переменных environ текущего запроса.

setup_environ()¶: Установите атрибут environ на полностью заполненную среду WSGI. Реализация по умолчанию использует все вышеперечисленные методы и атрибуты, а также методы get_stdin(), get_stderr() и add_cgi_vars() и атрибут wsgi_file_wrapper. Она также вставляет ключ SERVER_SOFTWARE, если он отсутствует, при условии, что атрибут origin_server имеет значение true, а атрибут server_software установлен.

Методы и атрибуты для настройки обработки исключений:

log_exception(exc_info)¶: Запишите кортеж exc_info в журнал сервера. exc_info - это кортеж (type, value, traceback). Реализация по умолчанию просто записывает трассировку в поток wsgi.errors запроса и смывает его. Подклассы могут переопределить этот метод, чтобы изменить формат или перенацелить вывод, отправить трассировку администратору или выполнить любое другое действие, которое сочтут подходящим.

traceback_limit¶: Максимальное количество кадров, включаемых в трассировку, выводимую методом log_exception() по умолчанию. Если None, то включаются все кадры.

error_output(environ, start_response)¶

Этот метод представляет собой WSGI-приложение для генерации страницы ошибки для пользователя. Он вызывается только в том случае, если ошибка произошла до того, как заголовки были отправлены клиенту.

Этот метод может получить доступ к текущей ошибке, используя sys.exception(), и должен передать эту информацию в start_response при его вызове (как описано в разделе «Обработка ошибок» в PEP 3333).

Реализация по умолчанию просто использует атрибуты error_status, error_headers и error_body для создания страницы вывода. Подклассы могут переопределить эту реализацию для создания более динамичного вывода ошибок.

Обратите внимание, однако, что с точки зрения безопасности не рекомендуется выплескивать диагностику любому старому пользователю; в идеале, чтобы включить вывод диагностики, нужно сделать что-то особенное, поэтому реализация по умолчанию не включает ее.

error_status¶: Статус HTTP, используемый для ответов об ошибках. Это должна быть строка состояния, как определено в PEP 3333; по умолчанию это код 500 и сообщение.

error_headers¶: HTTP-заголовки, используемые для ответов об ошибках. Это должен быть список заголовков ответов WSGI (кортежи``(name, value)``), как описано в PEP 3333. Список по умолчанию просто устанавливает тип содержимого в text/plain.

error_body¶: Тело ответа на ошибку. Это должна быть байтовая строка тела ответа HTTP. По умолчанию это простой текст: «Произошла ошибка сервера. Пожалуйста, свяжитесь с администратором».

Методы и атрибуты для функции PEP 3333 «Optional Platform-Specific File Handling»:

wsgi_file_wrapper¶: Фабрика wsgi.file_wrapper, совместимая с wsgiref.types.FileWrapper или None. По умолчанию этот атрибут имеет значение класса wsgiref.util.FileWrapper.

sendfile()¶: Переопределение для реализации передачи файлов в зависимости от платформы. Этот метод вызывается только в том случае, если возвращаемое приложением значение является экземпляром класса, указанного атрибутом wsgi_file_wrapper. Он должен возвращать значение true, если удалось успешно передать файл, чтобы не выполнялся код передачи по умолчанию. Реализация этого метода по умолчанию просто возвращает значение false.

Различные методы и атрибуты:

origin_server¶

Этот атрибут должен иметь значение true, если параметры _write() и _flush() обработчика используются для прямой связи с клиентом, а не через CGI-подобный шлюзовой протокол, который хочет получить статус HTTP в специальном заголовке Status:.

По умолчанию этот атрибут имеет значение true в BaseHandler, но false в BaseCGIHandler и CGIHandler.

http_version¶: Если значение origin_server равно true, этот строковый атрибут используется для задания версии HTTP-ответа, отправляемого клиенту. По умолчанию он принимает значение "1.0".

wsgiref.handlers.read_environ()¶

Перекодирует переменные CGI из os.environ в PEP 3333 строки «байты в юникоде», возвращая новый словарь. Эта функция используется в CGIHandler и IISCGIHandler вместо прямого использования os.environ, которая не обязательно совместима с WSGI на всех платформах и веб-серверах, использующих Python 3 - в частности, на тех, где фактическая среда ОС - Unicode (например, Windows), или на тех, где среда - байты, но системная кодировка, используемая Python для их декодирования, отлична от ISO-8859-1 (например, Unix-системы используют UTF-8).

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

Added in version 3.2.

`wsgiref.types` – типы WSGI для статической проверки типов¶

Этот модуль предоставляет различные типы для статической проверки типов, как описано в PEP 3333.

Added in version 3.11.

class wsgiref.types.StartResponse¶: A typing.Protocol, описывающие start_response() вызываемые (PEP 3333).

wsgiref.types.WSGIEnvironment¶: Псевдоним типа, описывающий словарь среды WSGI.

wsgiref.types.WSGIApplication¶: Псевдоним типа, описывающий вызываемое приложение WSGI.

class wsgiref.types.InputStream¶: Описания typing.Protocol, описывающие WSGI Input Stream.

class wsgiref.types.ErrorStream¶: Описания typing.Protocol, описывающие WSGI Error Stream.

class wsgiref.types.FileWrapper¶: Описания typing.Protocol, описывающие file wrapper. Конкретную реализацию этого протокола см. в wsgiref.util.FileWrapper.

Примеры¶

Это рабочее WSGI-приложение «Hello World»:

"""
Every WSGI application must have an application object - a callable
object that accepts two arguments. For that purpose, we're going to
use a function (note that you're not limited to a function, you can
use a class for example). The first argument passed to the function
is a dictionary containing CGI-style environment variables and the
second variable is the callable object.
"""
from wsgiref.simple_server import make_server


def hello_world_app(environ, start_response):
    status = "200 OK"  # HTTP Status
    headers = [("Content-type", "text/plain; charset=utf-8")]  # HTTP Headers
    start_response(status, headers)

    # The returned object is going to be printed
    return [b"Hello World"]

with make_server("", 8000, hello_world_app) as httpd:
    print("Serving on port 8000...")

    # Serve until process is killed
    httpd.serve_forever()

Пример WSGI-приложения, обслуживающего текущий каталог, принимающего необязательный каталог и номер порта (по умолчанию: 8000) в командной строке:

"""
Small wsgiref based web server. Takes a path to serve from and an
optional port number (defaults to 8000), then tries to serve files.
MIME types are guessed from the file names, 404 errors are raised
if the file is not found.
"""
import mimetypes
import os
import sys
from wsgiref import simple_server, util


def app(environ, respond):
    # Get the file name and MIME type
    fn = os.path.join(path, environ["PATH_INFO"][1:])
    if "." not in fn.split(os.path.sep)[-1]:
        fn = os.path.join(fn, "index.html")
    mime_type = mimetypes.guess_file_type(fn)[0]

    # Return 200 OK if file exists, otherwise 404 Not Found
    if os.path.exists(fn):
        respond("200 OK", [("Content-Type", mime_type)])
        return util.FileWrapper(open(fn, "rb"))
    else:
        respond("404 Not Found", [("Content-Type", "text/plain")])
        return [b"not found"]


if __name__ == "__main__":
    # Get the path and port from command-line arguments
    path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
    port = int(sys.argv[2]) if len(sys.argv) > 2 else 8000

    # Make and start the server until control-c
    httpd = simple_server.make_server("", port, app)
    print(f"Serving {path} on port {port}, control-C to stop")
    try:
        httpd.serve_forever()
    except KeyboardInterrupt:
        print("Shutting down.")
        httpd.server_close()

`wsgiref` — Утилиты WSGI и эталонная реализация¶

`wsgiref.util` – Утилиты среды WSGI¶

`wsgiref.headers` – Инструменты для заголовков ответов WSGI¶

`wsgiref.simple_server` – простой HTTP-сервер WSGI¶

`wsgiref.validate` — Программа проверки соответствия WSGI¶

`wsgiref.handlers` – базовые классы сервера/шлюза¶

`wsgiref.types` – типы WSGI для статической проверки типов¶

Примеры¶

Оглавление

Предыдущий раздел

Следующий раздел

wsgiref — Утилиты WSGI и эталонная реализация¶

wsgiref.util – Утилиты среды WSGI¶

wsgiref.headers – Инструменты для заголовков ответов WSGI¶

wsgiref.simple_server – простой HTTP-сервер WSGI¶

wsgiref.validate — Программа проверки соответствия WSGI¶

wsgiref.handlers – базовые классы сервера/шлюза¶

wsgiref.types – типы WSGI для статической проверки типов¶

Примеры¶

`wsgiref` — Утилиты WSGI и эталонная реализация¶

`wsgiref.util` – Утилиты среды WSGI¶

`wsgiref.headers` – Инструменты для заголовков ответов WSGI¶

`wsgiref.simple_server` – простой HTTP-сервер WSGI¶

`wsgiref.validate` — Программа проверки соответствия WSGI¶

`wsgiref.handlers` – базовые классы сервера/шлюза¶

`wsgiref.types` – типы WSGI для статической проверки типов¶