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