18.4.5 wsgiref.handlers - サーバ/ゲートウェイのベースクラス

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

クラス CGIHandler( )
sys.stdinsys.stdoutstderr そして os.environ 経由での CGI ベースの呼び出しです。これは、もしあなたが WSGI アプリケーションを持っていて、 これを CGI スクリプトとして実行したい場合に有用です。単に CGIHandler().run(app) を 起動してください。app はあなたが起動したい WSGI アプリケーションオブジェクトです。

このクラスは BaseCGIHandler のサブクラスで、これは wsgi.run_once を true、 wsgi.multithread を false、そして wsgi.multiprocess を true にセットし、 常に sysos を、必要な CGI ストリームと環境を取得するために使用します。

クラス BaseCGIHandler( stdin, stdout, stderr, environ [, multithread=True [, multiprocess=False]])

CGIHandler に似ていますが、sysos モジュールを 使う代わりに CGI 環境と I/O ストリームを明示的に指定します。multithreadmultiprocess の値は、ハンドラインスタンスにより実行されるアプリケーションの wsgi.multithreadwsgi.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() をオーバーライドして、コンストラクタから明示的に環境とストリームを 設定するようにしています。与えられた環境とストリームは stdinstdoutstderr それに 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: ヘッダの設定に使われます。これは(BaseCGIHandlerCGIHandler のような)HTTP オリジンサーバでないハンドラでは無視されます。

get_scheme( )
現在のリクエストで使われている URL スキームを返します。デフォルト実装は wsgiref.utilguess_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_statuserror_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.utilFileWrapper クラスです。

sendfile( )
オーバーライドしてプラットフォーム固有のファイル転送を実装します。 このメソッドはアプリケーションの戻り値が wsgi_file_wrapper 属性で 指定されたクラスのインスタンスの場合にのみ呼ばれます。これは ファイルの転送が成功できた場合には true を返して、デフォルトの転送コードが 実行されないようにするべきです。このデフォルトの実装は単に false 値を返します。

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

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

この属性のデフォルト値は BaseHandler では true ですが、 BaseCGIHandlerCGIHandler では false です。

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

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。