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

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

クラス `CGIHandler`( | )

  `sys.stdin`、`sys.stdout`、`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 ストリームと環境を取得するために使用します。

クラス `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` でなくこれをサブクラス化したいことでしょう。

クラス `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` 属性に保存されています。

クラス `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` サブクラスを作成しようとする前に ドキュメント文字列 (docstrings) やソースコードでさらなる情報を調べてください。

  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 オリジンサーバでないハンドラでは無視されます。

  `get_scheme`( | )

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

  `setup_environ`( | )

    `environ` 属性を、全てを導入済みの WSGI 環境に設定します。 デフォルトの実装は、上記全てのメソッドと属性、加えて `get_stdin()`、 `get_stderr()`、`add_cgi_vars()` メソッドと `wsgi_file_wrapper` 属性を 利用します。これは、キーが存在せず、`origin_server` 属性が true 値で `server_software` 属性も設定されている場合に `SERVER_SOFTWARE` を挿入します。

例外処理のカスタマイズのためのメソッドと属性：

`log_exception`( | exc_info)

  exec_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 333 の "Error Handling" セクションに記述があります）。

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

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

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

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

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

PEP 333 の "オプションのプラットフォーム固有のファイルハンドリング" 機能のための メソッドと属性：

`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"` です。