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

======================================================================

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**
を参照してください。

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)

   ファイル風オブジェクトを *イテレータ* に変換するラッパーです。結果
   のオブジェクトは "__getitem__()" と "__iter__()" 両方をサポートしま
   すが、これは Python 2.1 と Jython の互換性のためです。オブジェクト
   がイテレートされる間、オプションの *blksize* パラメータがくり返し
   *filelike* オブジェクトの "read()" メソッドに渡されて受け渡すバイト
   文字列を取得します。 "read()" が空バイト文字列を返した場合、イテレ
   ーションは終了して再開されることはありません。

   *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.8 で非推奨: "シーケンスプロトコル" のサポートは非推奨
   になりました。


"wsgiref.headers" -- WSGI レスポンスヘッダツール群
==================================================

このモジュールは単一のクラス、 "Headers" を提供し、WSGI レスポンスヘッ
ダの操作をマップに似たインターフェースで便利にします。

class wsgiref.headers.Headers([headers])

   *headers* をラップするマップ風オブジェクトを生成します。これは
   **PEP 3333** に定義されるようなヘッダの名前／値のタプルのリストです
   。 *headers* のデフォルト値は空のリストです。

   "Headers" オブジェクトは典型的なマッピング操作をサポートし、これに
   は "__getitem__()" 、 "get()" 、 "__setitem__()" 、 "setdefault()"
   、 "__delitem__()" 、 "__contains__()" を含みます。これらメソッドの
   それぞれにおいて、キーはヘッダ名で（大文字小文字は区別しません）、
   値はそのヘッダ名に関連づけられた最初の値です。ヘッダを設定すると既
   存のヘッダ値は削除され、ラップされたヘッダのリストの末尾に新しい値
   が加えられます。既存のヘッダの順番は一般に維持され、ラップされたリ
   ストの最後に新しいヘッダが追加されます。

   辞書とは違って、 "Headers" オブジェクトはラップされたヘッダリストに
   存在しないキーを取得または削除しようとした場合にもエラーを発生しま
   せん。単に、存在しないヘッダの取得は "None" を返し、存在しないヘッ
   ダの削除は何もしません。

   "Headers" オブジェクトは "keys()" 、 "values()" 、 "items()" メソッ
   ドもサポートします。複数の値を持つヘッダがある場合には、 "keys()"
   と "items()" で返されるリストは同じキーを一つ以上含むことがあります
   。 "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()

      現在設定されている呼び出し可能 (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()

      リクエストに対する WSGI 環境を含む辞書を返します。デフォルト実装
      では "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.

   バージョン 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" ではなくこのクラスをサブクラス化するとよいで
   しょう。

   このクラスは "BaseHandler" のサブクラスです。これは "__init__()" 、
   "get_stdin()" 、 "get_stderr()" 、 "add_cgi_vars()" 、 "_write()"
   、 "_flush()" をオーバーライドして、コンストラクタから明示的に環境
   とストリームを設定するようにしています。与えられた環境とストリーム
   は "stdin" 、 "stdout" 、 "stderr" それに "environ" 属性に保存され
   ています。

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

      現在処理中のリクエストの "wsgi.input" としての利用に適当な入力ス
      トリームオブジェクトを返します。

   get_stderr()

      現在処理中のリクエストの "wsgi.errors" としての利用に適当な出力
      ストリームオブジェクトを返します。

   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.exc_info()" を使って現在のエラー情報にアクセ
      スでき、その情報はこれを呼ぶときに *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

      "wsgi.file_wrapper" ファクトリ、または "None" です。この属性のデ
      フォルト値は "wsgiref.util.FileWrapper" クラスです。

   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.

   バージョン 3.2 で追加.


使用例
======

これは動作する "Hello World" WSGIアプリケーションです:

   from wsgiref.simple_server import make_server

   # 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.
   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:

   #!/usr/bin/env python3
   '''
   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. Used for the make serve target in Doc.
   '''
   import sys
   import os
   import mimetypes
   from wsgiref import simple_server, util

   def app(environ, respond):

       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')
       type = mimetypes.guess_type(fn)[0]

       if os.path.exists(fn):
           respond('200 OK', [('Content-Type', 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
       httpd = simple_server.make_server('', port, app)
       print("Serving {} on port {}, control-C to stop".format(path, port))
       try:
           httpd.serve_forever()
       except KeyboardInterrupt:
           print("Shutting down.")
           httpd.server_close()
