wsgiref — WSGI Utilities and Reference Implementation

Source code: Lib/wsgiref

---

Інтерфейс шлюзу веб-сервера (WSGI) — це стандартний інтерфейс між програмним забезпеченням веб-сервера та веб-додатками, написаними на Python. Наявність стандартного інтерфейсу дозволяє легко використовувати програму, яка підтримує WSGI, з кількома різними веб-серверами.

Лише автори веб-серверів і фреймворків програмування повинні знати кожну деталь і наріжний випадок дизайну WSGI. Вам не потрібно розуміти кожну деталь WSGI, щоб просто встановити програму WSGI або написати веб-програму за допомогою існуючої структури.

wsgiref is a reference implementation of the WSGI specification that can be used to add WSGI support to a web server or framework. It provides utilities for manipulating WSGI environment variables and response headers, base classes for implementing WSGI servers, a demo HTTP server that serves WSGI applications, types for static type checking, and a validation tool that checks WSGI servers and applications for conformance to the WSGI specification (PEP 3333).

Перегляньте wsgi.readthedocs.io для отримання додаткової інформації про WSGI, а також посилання на навчальні посібники та інші ресурси.

wsgiref.util – утиліти середовища WSGI

This module provides a variety of utility functions for working with WSGI environments. A WSGI environment is a dictionary containing HTTP request variables as described in PEP 3333. All of the functions taking an environ parameter expect a WSGI-compliant dictionary to be supplied; please see PEP 3333 for a detailed specification and WSGIEnvironment for a type alias that can be used in type annotations.

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. Наприклад, якщо за адресою /foo є програма WSGI, а шлях 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)

A concrete implementation of the wsgiref.types.FileWrapper protocol used to convert a file-like object to an iterator. The resulting objects are iterables. As the object is iterated over, the optional blksize parameter will be repeatedly passed to the filelike object’s read() method to obtain bytestrings to yield. When read() returns an empty bytestring, iteration is ended and is not resumable.

Якщо 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: Support for __getitem__() method has been removed.

wsgiref.headers – інструменти заголовків відповідей WSGI

Цей модуль надає єдиний клас, Headers, для зручного керування заголовками відповідей WSGI за допомогою інтерфейсу, схожого на відображення.

class wsgiref.headers.Headers([headers])

Створіть headers об’єкт, схожий на відображення, який має бути списком кортежів імені/значення заголовка, як описано в PEP 3333. Типовим значенням headers є порожній список.

Headers objects support typical mapping operations including __getitem__(), get(), __setitem__(), setdefault(), __delitem__() and __contains__(). For each of these methods, the key is the header name (treated case-insensitively), and the value is the first value associated with that header name. Setting a header deletes any existing values for that header, then adds a new value at the end of the wrapped header list. Headers“ existing order is generally maintained, with new headers added to the end of the wrapped list.

На відміну від словника, об’єкти 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, який прослуховує хост і порт, приймаючи з’єднання для програми. Повернене значення є екземпляром наданого 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. server_address має бути кортежем (host,port), а RequestHandlerClass має бути підкласом http.server.BaseHTTPRequestHandler, який використовуватиметься для обробки запитів.

Зазвичай вам не потрібно викликати цей конструктор, оскільки функція make_server() може обробити всі деталі за вас.

WSGIServer є підкласом http.server.HTTPServer, тому всі його методи (такі як serve_forever() і handle_request()) доступні. WSGIServer також надає ці спеціальні методи WSGI:

set_app(application)

Встановлює викликану програму як програму WSGI, яка отримуватиме запити.

get_app()

Returns the currently set application callable.

Однак зазвичай вам не потрібно використовувати ці додаткові методи, оскільки set_app() зазвичай викликається make_server(), а get_app() існує в основному для вигоди екземплярів обробника запитів.

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

Створіть обробник HTTP для вказаного запиту (тобто сокета), client_address (кортежу (host,port) і server (WSGIServer екземпляр).

Вам не потрібно створювати екземпляри цього класу безпосередньо; вони автоматично створюються за потреби об’єктами WSGIServer. Однак ви можете створити підклас цього класу та надати його як handler_class для функції make_server(). Деякі можливі релевантні методи перевизначення в підкласах:

get_environ()

Return a WSGIEnvironment dictionary for a request. The default implementation copies the contents of the WSGIServer object’s base_environ dictionary attribute and then adds various headers derived from the HTTP request. Each call to this method should return a new dictionary containing all of the relevant CGI environment variables as specified in 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)

Оберніть програму та поверніть новий об’єкт програми WSGI. Повернена програма перенаправлятиме всі запити до оригінальної програми та перевірятиме, чи програма та сервер, який її викликає, відповідають специфікації 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

# 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 без встановлення опції allowPathInfo конфігурації (IIS>=7) або дозволу метабази 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, який ви хочете викликати.

Нове в версії 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.

This class is a subclass of BaseHandler. It overrides the __init__(), get_stdin(), get_stderr(), add_cgi_vars(), _write(), and _flush() methods to support explicitly setting the environment and streams via the constructor. The supplied environment and streams are stored in the stdin, stdout, stderr, and environ attributes.

Метод write() stdout має записувати кожен фрагмент повністю, як io.BufferedIOBase.

class wsgiref.handlers.BaseHandler

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

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

run(app)

Запустіть вказану програму WSGI, app.

Усі інші методи BaseHandler викликаються цим методом у процесі запуску програми, і, отже, існують, перш за все, щоб дозволити налаштувати процес.

Наступні методи ПОВИННІ бути замінені в підкласі:

_write(data)

Буферизуйте байти data для передачі клієнту. Це нормально, якщо цей метод дійсно передає дані; BaseHandler просто розділяє операції запису та очищення для більшої ефективності, коли основна система насправді має таку відмінність.

_flush()

Примусова передача буферизованих даних клієнту. Це нормально, якщо цей метод є безопераційним (тобто якщо _write() справді надсилає дані).

get_stdin()

Return an object compatible with InputStream suitable for use as the wsgi.input of the request currently being processed.

get_stderr()

Return an object compatible with ErrorStream suitable for use as the wsgi.errors of the request currently being processed.

add_cgi_vars()

Вставте змінні CGI для поточного запиту в атрибут environ.

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

Атрибути та методи налаштування середовища WSGI:

wsgi_multithread

Значення, яке буде використовуватися для змінної середовища wsgi.multithread. За замовчуванням у BaseHandler він має значення true, але може мати інше значення за замовчуванням (або бути встановленим конструктором) в інших підкласах.

wsgi_multiprocess

Значення, яке буде використовуватися для змінної середовища wsgi.multiprocess. За замовчуванням у BaseHandler він має значення true, але може мати інше значення за замовчуванням (або бути встановленим конструктором) в інших підкласах.

wsgi_run_once

Значення, яке буде використовуватися для змінної середовища wsgi.run_once. За замовчуванням у BaseHandler встановлено значення false, але 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()

Set the environ attribute to a fully populated WSGI environment. The default implementation uses all of the above methods and attributes, plus the get_stdin(), get_stderr(), and add_cgi_vars() methods and the wsgi_file_wrapper attribute. It also inserts a SERVER_SOFTWARE key if not present, as long as the origin_server attribute is a true value and the server_software attribute is set.

Методи та атрибути для налаштування обробки винятків:

log_exception(exc_info)

Зареєструйте кортеж exc_info у журналі сервера. exc_info — це кортеж (тип, значення, відстеження). Реалізація за замовчуванням просто записує трасування в потік wsgi.errors запиту та очищає його. Підкласи можуть замінити цей метод, щоб змінити формат або перенацілити вивід, надіслати трасування поштою адміністратору або зробити будь-яку іншу дію, яку можна вважати прийнятною.

traceback_limit

Максимальна кількість фреймів, які можна включити у вивід трасування методом log_exception() за замовчуванням. Якщо None, усі кадри включені.

error_output(environ, start_response)

Цей метод є програмою WSGI для створення сторінки помилки для користувача. Він викликається, лише якщо виникає помилка до того, як заголовки будуть надіслані клієнту.

This method can access the current error using sys.exception(), and should pass that information to start_response when calling it (as described in the «Error Handling» section of PEP 3333).

Реалізація за замовчуванням просто використовує атрибути error_status, error_headers і error_body для створення сторінки виводу. Підкласи можуть замінити це, щоб створити більш динамічний вихід помилок.

Однак зауважте, що з точки зору безпеки не рекомендується передавати діагностику старим користувачам; в ідеалі, ви повинні зробити щось особливе, щоб увімкнути діагностичний вихід, тому реалізація за замовчуванням не включає жодного.

error_status

Статус HTTP, який використовується для відповідей на помилки. Це має бути рядок стану, як визначено в PEP 3333; за замовчуванням це код і повідомлення 500.

error_headers

Заголовки HTTP, які використовуються для відповідей на помилки. Це має бути список заголовків відповіді WSGI (кортежі (ім’я, значення)), як описано в PEP 3333. Список за замовчуванням лише встановлює тип вмісту text/plain.

error_body

Тіло відповіді на помилку. Це має бути байтовий рядок тіла відповіді HTTP. За замовчуванням це простий текст: «Сталася помилка сервера. Зверніться до адміністратора».

Методи та атрибути для функції PEP 3333 «Додаткова обробка файлів на певній платформі»:

wsgi_file_wrapper

A wsgi.file_wrapper factory, compatible with wsgiref.types.FileWrapper, or None. The default value of this attribute is the wsgiref.util.FileWrapper class.

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

Якщо ви впроваджуєте власний обробник на основі CGI, ви, ймовірно, захочете використовувати цю процедуру замість того, щоб просто копіювати значення безпосередньо з os.environ.

Нове в версії 3.2.

wsgiref.types – WSGI types for static type checking

This module provides various types for static type checking as described in PEP 3333.

Нове в версії 3.11.

class wsgiref.types.StartResponse

A typing.Protocol describing start_response() callables (PEP 3333).

wsgiref.types.WSGIEnvironment

A type alias describing a WSGI environment dictionary.

wsgiref.types.WSGIApplication

A type alias describing a WSGI application callable.

class wsgiref.types.InputStream

A typing.Protocol describing a WSGI Input Stream.

class wsgiref.types.ErrorStream

A typing.Protocol describing a WSGI Error Stream.

class wsgiref.types.FileWrapper

A typing.Protocol describing a file wrapper. See wsgiref.util.FileWrapper for a concrete implementation of this protocol.

Приклади

Це робоча програма «Hello World» WSGI:

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

Example of a WSGI application serving the current directory, accept optional directory and port number (default: 8000) on the command line:

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