# `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, оскільки дані підроблені!

  Example usage (see also `demo_app()` for another example):

      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.

  The start_response callable should follow the `StartResponse` protocol.

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, який ви хочете викликати.

  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`.

  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). In particular, the start_response callable should follow the `StartResponse` protocol.

    Реалізація за замовчуванням просто використовує атрибути `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`.

  Added in version 3.2.

## `wsgiref.types` – WSGI types for static type checking

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

Added in version 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.

## Приклади

This is a working «Hello World» WSGI application, where the start_response callable should follow the `StartResponse` protocol:

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