# `wsgiref` --- WSGI ユーティリティとリファレンス実装

ソースコード: Lib/wsgiref

Web Server Gateway Interface (WSGI) は、Web サーバソフトウェアと Python で記述された Web アプリケーションとの標準インターフェースです。標準インターフェースを持つことで、WSGI をサポートするアプリケーションを幾つもの異なる Web サーバで使うことが容易になります。

Web サーバとプログラミングフレームワークの作者だけが、WSGI デザインのあらゆる細部や特例などを知る必要があります。WSGI アプリケーションをインストールしたり、既存のフレームワークを使ったアプリケーションを記述するだけの皆さんは、すべてについて理解する必要はありません。

`wsgiref` は WSGI 仕様のリファレンス実装で、これは Web サーバやフレームワークに WSGI サポートを加えるのに利用できます。これは WSGI 環境変数やレスポンスヘッダを操作するユーティリティ、 WSGI サーバ実装時のベースクラス、WSGI アプリケーションを提供するデモ用 HTTP サーバ、静的型チェック用の型、それと WSGI サーバとアプリケーションの WSGI 仕様 (PEP 3333) 準拠のバリデーションツールを提供します。

wsgi.readthedocs.io に、WSGIに関するさらなる情報と、チュートリアルやその他のリソースへのリンクがあります。

## `wsgiref.util` -- WSGI 環境のユーティリティ

このモジュールは WSGI 環境で使う様々なユーティリティ関数を提供します。 WSGI 環境は PEP 3333 で記述されているような HTTP リクエスト変数を含む辞書です。environ パラメータを取るすべての関数は WSGI 準拠の辞書を与えられることを期待しています; 細かい仕様については PEP 3333 を、型アノテーションに使える型エイリアスについては `WSGIEnvironment` を参照してください。

wsgiref.util.guess_scheme(environ)

  environ 辞書の `HTTPS` 環境変数を調べることで `wsgi.url_scheme` が "http" か "https" のどちらであるべきか推測し、その結果を返します。戻り値は文字列です。

  この関数は、CGI や FastCGI のような CGI に似たプロトコルをラップするゲートウェイを作成する場合に便利です。典型的には、それらのプロトコルを提供するサーバが SSL 経由でリクエストを受け取った場合には `HTTPS` 変数に値 "1", "yes" または "on" を持つでしょう。そのため、この関数はそのような値が見つかった場合には "https" を返し、そうでなければ "http" を返します。

wsgiref.util.request_uri(environ, include_query=True)

  リクエスト URI 全体 (オプションでクエリ文字列を含む) を、 PEP 3333 の "URL 再構築(URL Reconstruction)" にあるアルゴリズムを使って返します。 include_query が false の場合、クエリ文字列は結果となる文字列には含まれません。

wsgiref.util.application_uri(environ)

  `PATH_INFO` と `QUERY_STRING` 変数が無視されることを除けば `request_uri()` に似ています。結果はリクエストによって指定されたアプリケーションオブジェクトのベース URI です。

wsgiref.util.shift_path_info(environ)

  `PATH_INFO` から `SCRIPT_NAME` に一つの名前をシフトしてその名前を返します。environ 辞書は 変更されます 。`PATH_INFO` や `SCRIPT_NAME` のオリジナルをそのまま残したい場合にはコピーを使ってください。

  `PATH_INFO` にパスセグメントが何も残っていなければ、`None` が返されます。

  典型的なこのルーチンの使い方はリクエスト URI のそれぞれの要素の処理で、例えばパスを一連の辞書のキーとして取り扱う場合です。このルーチンは、渡された環境を、ターゲット URL で示される別の WSGI アプリケーションの呼び出しに合うように調整します。例えば、 `/foo` に WSGI アプリケーションがあったとして、そしてリクエスト URL パスが `/foo/bar/baz` で、 `/foo` の WSGI アプリケーションが `shift_path_info()` を呼んだ場合、これは "bar" 文字列を受け取り、 environ は `/foo/bar` の WSGI アプリケーションへの受け渡しに適するように更新されます。つまり、 `SCRIPT_NAME` は `/foo` から `/foo/bar` に変わって、 `PATH_INFO` は `/bar/baz` から `/baz` に変化するのです。

  `PATH_INFO` が単に "/" の場合、このルーチンは空の文字列を返し、`SCRIPT_NAME` の末尾にスラッシュを加えます、これはたとえ空のパスセグメントが通常は無視され、そして `SCRIPT_NAME` は通常スラッシュで終わる事が無かったとしてもです。これは意図的な振る舞いで、このルーチンでオブジェクト巡回(object traversal) をした場合に `/x` で終わる URI と `/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)

  'header_name' が RFC 2616 で定義されている HTTP/1.1 の "Hop-by-Hop" ヘッダの場合に `True` を返します。

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()` メソッドを持ち、これが呼ばれた場合には filelike オブジェクトの `close()` メソッドを呼び出します。

  使用例:

      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()` で返されるリストは同じキーを一つ以上含むことがあります。 `Headers` オブジェクトの `len()` は、その `items()` の長さと同じであり、ラップされたヘッダリストの長さと同じです。実際、 `items()` メソッドは単にラップされたヘッダリストのコピーを返しているだけです。

  `Headers` オブジェクトに対して `bytes()` を呼ぶと、HTTP レスポンスヘッダとして送信するのに適した形に整形されたバイト文字列を返します。それぞれのヘッダはコロンとスペースで区切られた値と共に一列に並んでいます。それぞれの行はキャリッジリターンとラインフィードで終了し、バイト文字列は空行で終了しています。

  これらのマッピングインターフェースと整形機能に加えて、 `Headers` オブジェクトは複数の値を持つヘッダの取得と追加、MIME パラメータでヘッダを追加するための以下のようなメソッド群も持っています:

  get_all(name)

    指定されたヘッダのすべての値のリストを返します。

    返されるリストは、元々のヘッダリストに現れる順、またはこのインスタンスに追加された順に並んでいて、重複を含む場合があります。削除されて加えられたフィールドはすべてヘッダリストの末尾に付きます。与えられた 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 サーバ

このモジュールは WSGI アプリケーションを提供するシンプルな HTTP サーバです (`http.server` がベースです)。個々のサーバインスタンスは単一の WSGI アプリケーションを、特定のホストとポート上で提供します。もし一つのホストとポート上で複数のアプリケーションを提供したいならば、 `PATH_INFO` をパースして個々のリクエストでどのアプリケーションを呼び出すか選択するような WSGI アプリケーションを作る必要があります。（例えば、 `wsgiref.util` から `shift_path_info()` を利用します。）

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

  host と port 上で待機し、 app へのコネクションを受け付ける WSGI サーバを作成します。戻り値は与えられた server_class のインスタンスで、指定された handler_class を使ってリクエストを処理します。 app は PEP 3333 で定義されるところの WSGI アプリケーションでなければいけません。

  使用例:

      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)

    呼び出し可能 (callable) な 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)

  与えられた request （すなわちソケット）の HTTP ハンドラ、 client_address (`(host,port)` のタプル)、 server (`WSGIServer` インスタンス) の HTTP ハンドラを作成します。

  このクラスのインスタンスを直接生成する必要はありません; これらは必要に応じて `WSGIServer` オブジェクトによって自動的に生成されます。しかしながら、このクラスをサブクラス化し、 `make_server()` 関数に handler_class として与えることは可能でしょう。サブクラスにおいてオーバーライドする意味のありそうなものは:

  get_environ()

    リクエストに対する `WSGIEnvironment` 辞書を返します。デフォルト実装では `WSGIServer` オブジェクトの `base_environ` 辞書属性のコンテンツをコピーし、それから HTTP リクエスト由来の様々なヘッダを追加しています。このメソッド呼び出し毎に、 PEP 3333 に指定されている関連する CGI 環境変数をすべて含む新規の辞書を返さなければいけません。

  get_stderr()

    `wsgi.errors` ストリームとして使われるオブジェクトを返します。デフォルト実装では単に `sys.stderr` を返します。

  handle()

    HTTP リクエストを処理します。デフォルト実装では実際の WGI アプリケーションインターフェースを実装するのに `wsgiref.handlers` クラスを使ってハンドラインスタンスを作成します。

## `wsgiref.validate` --- WSGI 準拠チェッカー

WSGI アプリケーションのオブジェクト、フレームワーク、サーバまたはミドルウェアの作成時には、その新規のコードを `wsgiref.validate` を使って準拠の検証をすると便利です。このモジュールは WSGI サーバやゲートウェイと WSGI アプリケーションオブジェクト間の通信を検証する WSGI アプリケーションオブジェクトを作成する関数を提供し、双方のプロトコル準拠をチェックします。

このユーティリティは完全な PEP 3333 準拠を保証するものでないことは注意してください; このモジュールでエラーが出ないことは必ずしもエラーが存在しないことを意味しません。しかしこのモジュールがエラーを出したならば、ほぼ確実にサーバかアプリケーションのどちらかが 100% 準拠ではありません。

このモジュールは lan Bicking の "Python Paste" ライブラリの `paste.lint` モジュールをベースにしています。

wsgiref.validate.validator(application)

  application をラップし、新しい WSGI アプリケーションオブジェクトを返します。返されたアプリケーションは全てのリクエストを元々の application に転送し、application とそれを呼び出すサーバの両方が WSGI 仕様と RFC 2616 の両方に準拠しているかをチェックします。

  何らかの非準拠が検出されると、 `AssertionError` 例外が送出されます; しかし、このエラーがどう扱われるかはサーバ依存であることに注意してください。例えば、 `wsgiref.simple_server` とその他 `wsgiref.handlers` ベースのサーバ（エラー処理メソッドが他のことをするようにオーバライドしていないもの）は単純にエラーが発生したというメッセージとトレースバックのダンプを `sys.stderr` やその他のエラーストリームに出力します。

  このラッパーは、疑わしいものの実際には PEP 3333 で禁止されていないかもしれない挙動を指摘するために `warnings` モジュールを使って出力を生成します。これらは Python のコマンドラインオプションや `warnings` API で抑制されなければ、 `sys.stderr` (`wsgi.errors` では ありません 。ただし、たまたま同一のオブジェクトだった場合を除く)に書き出されます。

  使用例:

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

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

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

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

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

## `wsgiref.handlers` -- サーバ／ゲートウェイのベースクラス

このモジュールは WSGI サーバとゲートウェイ実装のベースハンドラクラスを提供します。これらのベースクラスは、CGI 風の環境と、それに加えて入力、出力そしてエラーストリームが与えられることで、WSGI アプリケーションとの通信の大部分を処理します。

class wsgiref.handlers.CGIHandler

  `sys.stdin`、`sys.stdout`、`sys.stderr` そして `os.environ` 経由での CGI ベースの呼び出しです。これは、もしあなたが 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

  (IIS 7 以降の) 設定オプションの allowPathInfo や (IIS 7 より前の) メタベースの allowPathInfoForScriptMappings を設定せずに Microsoft の IIS Web サーバにデプロイするときに使う、 `CGIHandler` クラス以外の専用の選択肢です。

  By default, IIS gives a `PATH_INFO` that duplicates the `SCRIPT_NAME` at the front, causing problems for WSGI applications that wish to implement routing. This handler strips any such duplicated path.

  IIS can be configured to pass the correct `PATH_INFO`, but this causes another bug where `PATH_TRANSLATED` is wrong. Luckily this variable is rarely used and is not guaranteed by WSGI. On IIS<7, though, the setting can only be made on a vhost level, affecting all other script mappings, many of which break when exposed to the `PATH_TRANSLATED` bug. For this reason IIS<7 is almost never deployed with the fix (Even IIS7 rarely uses it because there is still no UI for it.).

  There is no way for CGI code to tell whether the option was set, so a separate handler class is provided. It is used in the same way as `CGIHandler`, i.e., by calling `IISCGIHandler().run(app)`, where `app` is the WSGI application object you wish to invoke.

  Added in version 3.2.

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

  `CGIHandler` に似ていますが、 `sys` と `os` モジュールを使う代わりに CGI 環境と I/O ストリームを明示的に指定します。 multithread と multiprocess の値は、ハンドラインスタンスにより実行されるアプリケーションの `wsgi.multithread` と `wsgi.multiprocess` フラグの設定に使われます。

  このクラスは `SimpleHandler` のサブクラスで、HTTP の "本サーバ" でないソフトウェアと使うことを意図しています。もしあなたが `Status:` ヘッダを HTTP ステータスを送信するのに使うようなゲートウェイプロトコルの実装（CGI、FastCGI、SCGIなど）を書いている場合、おそらく `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.

  The `write()` method of stdout should write each chunk in full, like `io.BufferedIOBase`.

class wsgiref.handlers.BaseHandler

  これは WSGI アプリケーションを実行するための抽象ベースクラスです。それぞれのインスタンスは一つの HTTP リクエストを処理します。しかし原理上は複数のリクエスト用に再利用可能なサブクラスを作成することができます。

  `BaseHandler` インスタンスは外部から利用されるたった一つのメソッドを持ちます:

  run(app)

    指定された WSGI アプリケーション、app を実行します。

  その他のすべての `BaseHandler` のメソッドはアプリケーション実行プロセスでこのメソッドから呼ばれます。したがって、それらは主にそのプロセスのカスタマイズのために存在しています。

  以下のメソッドはサブクラスでオーバーライドされなければいけません:

  _write(data)

    バイト列の data をクライアントへの転送用にバッファします。このメソッドが実際にデータを転送しても OK です: 下部システムが実際にそのような区別をしている場合に効率をより良くするために、 `BaseHandler` は書き出しとフラッシュ操作を分けているからです。

  _flush()

    バッファされたデータをクライアントに強制的に転送します。このメソッドは何もしなくても OK です（すなわち、 `_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` サブクラスを作成しようとする前に docstring やソースコードでさらなる情報を調べてください。

  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 環境に含まれるデフォルトの環境変数。デフォルトでは `wsgiref.handlers` がインポートされた時点の `os.environ` のコピーですが、サブクラスはクラスまたはインスタンスレベルでそれら自身のものを作ることができます。デフォルト値は複数のクラスとインスタンスで共有されるため、この辞書は読み出し専用と考えるべきだという点に注意してください。

  server_software

    `origin_server` 属性が設定されている場合、この属性の値がデフォルトの `SERVER_SOFTWARE` WSGI 環境変数の設定や HTTP レスポンス中のデフォルトの `Server:` ヘッダの設定に使われます。これは (`BaseCGIHandler` や `CGIHandler` のような) HTTP オリジンサーバでないハンドラでは無視されます。

    バージョン 3.3 で変更: "Python" という語は "CPython" や "Jython" などのような個別実装の語に置き換えられました。

  get_scheme()

    現在のリクエストで使われている URL スキームを返します。デフォルト実装は `wsgiref.util` の `guess_scheme()` を使い、現在のリクエストの `environ` 変数に基づいてスキームが"http" か "https" かを推測します。

  setup_environ()

    `environ` 属性を、フル実装 (fully populated) の WSGI 環境に設定します。デフォルトの実装は、上記すべてのメソッドと属性、加えて `get_stdin()` 、 `get_stderr()` 、 `add_cgi_vars()` メソッドと `wsgi_file_wrapper` 属性を利用します。これは、キーが存在せず、 `origin_server` 属性が true 値で `server_software` 属性も設定されている場合に `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 Handling" セクションに記述があります)。

    デフォルト実装は単に `error_status` 、 `error_headers` 、 `error_body` 属性を出力ページの生成に使います。サブクラスではこれをオーバーライドしてもっと動的なエラー出力をすることができます。

    しかし、セキュリティの観点からは診断をあらゆるユーザに吐き出すことは推奨されないことに気をつけてください; 理想的には、診断的な出力を有効にするには何らかの特別なことをする必要があるようにすべきで、これがデフォルト実装では何も含まれていない理由です。

  error_status

    エラーレスポンスで使われる HTTP ステータスです。これは PEP 3333 で定義されているステータス文字列です; デフォルトは 500 コードとメッセージです。

  error_headers

    エラーレスポンスで使われる HTTP ヘッダです。これは PEP 3333 で述べられているような、 WSGI レスポンスヘッダ (`(name, value)` タプル) のリストであるべきです。デフォルトのリストはコンテントタイプを `text/plain` にセットしているだけです。

  error_body

    エラーレスポンスボディ。これは HTTP レスポンスのボディバイト文字列であるべきです。これはデフォルトではプレーンテキストで "A server error occurred. Please contact the administrator." です。

  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` 属性で指定されたクラスのインスタンスの場合にのみ呼ばれます。これはファイルの転送が成功できた場合には true を返して、デフォルトの転送コードが実行されないようにするべきです。このデフォルトの実装は単に false 値を返します。

  その他のメソッドと属性:

  origin_server

    この属性はハンドラの `_write()` と `_flush()` が、特別に `Status:` ヘッダに HTTP ステータスを求めるような CGI 風のゲートウェイプロトコル経由でなく、クライアントと直接通信をするような場合には true 値に設定されているべきです。

    この属性のデフォルト値は `BaseHandler` では true ですが、 `BaseCGIHandler` と `CGIHandler` では false です。

  http_version

    `origin_server` が true の場合、この文字列属性はクライアントへのレスポンスセットの HTTP バージョンの設定に使われます。デフォルトは `"1.0"` です。

wsgiref.handlers.read_environ()

  Transcode CGI variables from `os.environ` to PEP 3333 "bytes in unicode" strings, returning a new dictionary. This function is used by `CGIHandler` and `IISCGIHandler` in place of directly using `os.environ`, which is not necessarily WSGI-compliant on all platforms and web servers using Python 3 -- specifically, ones where the OS's actual environment is Unicode (i.e. Windows), or ones where the environment is bytes, but the system encoding used by Python to decode it is anything other than ISO-8859-1 (e.g. Unix systems using UTF-8).

  If you are implementing a CGI-based handler of your own, you probably want to use this routine instead of just copying values out of `os.environ` directly.

  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.

## 使用例

これは動作する "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()