wsgiref – утилиты WSGI и эталонная реализация¶wsgiref – WSGI Utilities and Reference Implementation

wsgiref.util – утилиты окружения WSGI¶wsgiref.util – WSGI environment utilities

Этот модуль предоставляет различные утилиты для работы с окружением 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 Reconstruction» 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, от URI, заканчивающихся на /x/, при использовании этой процедуры для обхода объектов.

wsgiref.util.setup_testing_defaults(environ)¶

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

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

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

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

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

# Относительно простое WSGI-приложение. Оно выведет
# словарь окружения после обновления с помощью 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, используемого для преобразования файлоподобного объекта в итератор. Результирующие объекты являются итерируемыми. При итерации по объекту необязательный параметр blksize многократно передаётся методу read() объекта filelike, чтобы получать байтовые строки и возвращать их. Когда read() возвращает пустую байтовую строку, итерация завершается и не может быть возобновлена.

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

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

from io import StringIO
from wsgiref.util import FileWrapper

# В качестве файлоподобного объекта используется буфер StringIO
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¶wsgiref.headers – WSGI response header tools

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

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 – простой WSGI HTTP-сервер¶wsgiref.simple_server – a simple WSGI HTTP server

Этот модуль реализует простой 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...")

    # Отвечать на запросы до завершения процесса
    httpd.serve_forever()

    # Альтернатива: обработать один запрос и завершить работу
    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. server_address должен быть кортежем (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-обработчик для заданного request (т.е. сокета), client_address (кортеж (host,port)) и server (экземпляр WSGIServer).

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

get_environ()¶

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

get_stderr()¶

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

handle()¶

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

wsgiref.validate – средство проверки соответствия WSGI¶wsgiref.validate – WSGI conformance checker

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

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

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

wsgiref.validate.validator(application)¶

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

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

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

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

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

# Наш вызываемый объект, который намеренно не соответствует
# стандарту, поэтому валидатор выдаст ошибку
def simple_app(environ, start_response):
    status = '200 OK'  # HTTP-статус
    headers = [('Content-type', 'text/plain')]  # HTTP-заголовки
    start_response(status, headers)

    # Это приведёт к ошибке, потому что нужно вернуть список, и
    # валидатор сообщит об этом
    return b"Hello World"

# Это приложение, обёрнутое в валидатор
validator_app = validator(simple_app)

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

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

Этот модуль предоставляет базовые классы обработчиков для реализации 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 без установки опции конфигурации allowPathInfo (IIS>=7) или метабазы allowPathInfoForScriptMappings (IIS<7).

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

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

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

Новое в версии 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)¶

Буферизует байты 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. По умолчанию оно равно false в BaseHandler, но CGIHandler устанавливает его в true по умолчанию.

os_environ¶

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

server_software¶

Если атрибут origin_server установлен, его значение используется для установки переменной окружения WSGI SERVER_SOFTWARE по умолчанию, а также для установки заголовка 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 имеет истинное значение, а атрибут 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-ответа. По умолчанию это обычный текст: «A server error occurred. Please contact the administrator.»

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

wsgi_file_wrapper¶

Фабрика wsgi.file_wrapper, совместимая с wsgiref.types.FileWrapper или None. Значение по умолчанию этого атрибута – класс wsgiref.util.FileWrapper.

sendfile()¶

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

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

origin_server¶

Этот атрибут должен быть установлен в истинное значение, если _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 строки «bytes in unicode» и возвращает новый словарь. Эта функция используется CGIHandler и IISCGIHandler вместо прямого использования os.environ, который не обязательно совместим с WSGI на всех платформах и веб-серверах, использующих Python 3 – в частности, на тех, где реальное окружение ОС в Unicode (например, Windows), или на тех, где окружение – байты, но системная кодировка, используемая Python для его декодирования, отлична от ISO-8859-1 (например, Unix-системы с UTF-8).

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

Новое в версии 3.2.

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

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

class wsgiref.types.StartResponse¶

typing.Protocol, описывающий вызываемые объекты start_response() (PEP 3333).

wsgiref.types.WSGIEnvironment¶

Псевдоним типа, описывающий словарь окружения WSGI.

wsgiref.types.WSGIApplication¶

Псевдоним типа, описывающий вызываемый объект приложения WSGI.

class wsgiref.types.InputStream¶

typing.Protocol, описывающий входной поток WSGI.

class wsgiref.types.ErrorStream¶

typing.Protocol, описывающий поток ошибок WSGI.

class wsgiref.types.FileWrapper¶

typing.Protocol, описывающий обёртку файла. Смотрите wsgiref.util.FileWrapper для конкретной реализации этого протокола.

Примеры¶Examples

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

"""
Каждое WSGI-приложение должно иметь объект приложения – вызываемый
объект, который принимает два аргумента. Для этого
можно использовать функцию (обратите внимание: можно не только функцию, но и, например, класс)
использовать, например, класс). Первый аргумент, передаваемый функции,
это словарь, содержащий переменные окружения в стиле CGI, а
второй аргумент – вызываемый объект.
"""
from wsgiref.simple_server import make_server


def hello_world_app(environ, start_response):
    status = "200 OK"  # HTTP-статус
    headers = [("Content-type", "text/plain; charset=utf-8")]  # HTTP-заголовки
    start_response(status, headers)

    # Возвращаемый объект будет выведен
    return [b"Hello World"]

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

    # Обслуживать до завершения процесса
    httpd.serve_forever()

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

"""
Небольшой веб-сервер на основе wsgiref. Принимает путь для раздачи и
необязательный номер порта (по умолчанию 8000), затем пытается раздавать файлы.
MIME-типы определяются по именам файлов, выдаются ошибки 404,
если файл не найден.
"""
import mimetypes
import os
import sys
from wsgiref import simple_server, util


def app(environ, respond):
    # Получить имя файла и MIME-тип
    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_type(fn)[0]

    # Возвращает 200 OK, если файл существует, иначе 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__":
    # Получает путь и порт из аргументов командной строки
    path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
    port = int(sys.argv[2]) if len(sys.argv) > 2 else 8000

    # Создаёт и запускает сервер до нажатия Ctrl+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()