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

ソースコード: Lib/wsgiref

警告

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 サーバやアプリケーションで使うべきではありません。なぜならこのデータは偽物なのです！

使用例を示します (別の例は demo_app() を参照)。

from wsgiref.util import setup_testing_defaults
from wsgiref.simple_server import make_server

# 比較的単純な WSGI アプリケーション。
# 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

# ファイル類似オブジェクトとして StringIO バッファを使う。
filelike = StringIO("This is an example file-like object"*10)
wrapper = FileWrapper(filelike, blksize=5)

for chunk in wrapper:
    print(chunk)

バージョン 3.11 で変更: __getitem__() メソッドのサポートは削除されました。

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

    # プロセスが終了させられるまでリクエストに応答する。
    httpd.serve_forever()

    # 別の方法: リクエストを 1 件処理して終了する。
    httpd.handle_request()

wsgiref.simple_server.demo_app(environ, start_response)¶

この関数は、小さいながら完全な WSGI アプリケーションです。「Hello world!」というメッセージと、environ 引数で渡されたキーと値のペアのリストを含むテキストページを返します。 wsgiref.simple_server などの WSGI サーバが、単純な WSGI アプリケーションを正しく実行できるか確認するのに役立ちます。

呼び出し可能オブジェクト start_response は、StartResponse プロトコルに従う必要があります。

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()¶: 現在設定されているアプリケーションの呼び出し可能オブジェクトを返します。

しかしながら、通常はこれらの追加されたメソッドを使う必要はありません。 set_app() は普通は make_server() によって呼ばれ、 get_app() は主にリクエストハンドラインスタンスの便宜上存在するからです。

class wsgiref.simple_server.WSGIRequestHandler(request, client_address, server)¶

指定された request (ソケット)、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 リクエストを処理します。デフォルトの実装では、wsgiref.handlers のクラスでハンドラインスタンスを作成し、実際の WSGI アプリケーションインターフェースを実装します。

`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 クラス以外の専用の選択肢です。

デフォルトでは、IIS は SCRIPT_NAME を先頭に重複して含む PATH_INFO を渡します。このため、ルーティングを実装する WSGI アプリケーションで問題が起こります。このハンドラは、そうした重複部分を取り除きます。

IIS を設定して正しい PATH_INFO を渡すこともできますが、その場合は PATH_TRANSLATED が不正になる別のバグが起こります。幸い、この変数はほとんど使われず、WSGI でも保証されていません。ただし、IIS 7 より前では仮想ホスト単位でしか設定できず、他のすべてのスクリプトマッピングに影響し、その多くは PATH_TRANSLATED のバグによって動作しなくなります。このため、IIS 7 より前では、この修正を適用した構成でデプロイされることはほぼありません (IIS 7 でも、設定用の UI がまだないため、ほとんど使われません)。

CGI コードからは、このオプションが設定されているかどうかを判別できないため、別のハンドラクラスを用意しています。使い方は CGIHandler と同じで、実行したい WSGI アプリケーションオブジェクトを app として IISCGIHandler().run(app) を呼び出します。

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

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

stdout の write() メソッドは、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 として使うのに適した、InputStream と互換性のあるオブジェクトを返します。

get_stderr()¶: 現在処理しているリクエストの wsgi.errors として使うのに適した、ErrorStream と互換性のあるオブジェクトを返します。

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() で現在のエラーにアクセスできます。 PEP 3333 の「Error Handling」節に記載されているとおり、start_response を呼び出す際にその情報を渡す必要があります。特に、呼び出し可能オブジェクト start_response は StartResponse プロトコルに従う必要があります。

デフォルト実装は単に 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¶: wsgiref.types.FileWrapper と互換性のある 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()¶

os.environ の CGI 変数を、PEP 3333 の「bytes in unicode」形式の文字列に変換し、新しい辞書を返します。 CGIHandler と IISCGIHandler は、os.environ を直接使う代わりにこの関数を使います。 Python 3 を使うすべてのプラットフォームや Web サーバで、os.environ が WSGI に準拠しているとは限らないためです。具体的には、OS の実際の環境変数が Unicode である場合 (Windows) や、環境変数がバイト列であっても、Python がそのデコードに使うシステムエンコーディングが ISO-8859-1 以外である場合 (UTF-8 を使う Unix システムなど) が該当します。

独自の CGI ベースのハンドラを実装する場合は、os.environ から直接値をコピーする代わりに、このルーチンを使うとよいでしょう。

Added in version 3.2.

`wsgiref.types` -- 静的型検査用の WSGI の型¶

このモジュールは、PEP 3333 に記載されたインターフェースの静的型検査用に、さまざまな型を提供します。

Added in version 3.11.

class wsgiref.types.StartResponse¶: start_response() の呼び出し可能オブジェクト (PEP 3333) を記述する typing.Protocol です。

wsgiref.types.WSGIEnvironment¶: WSGI 環境辞書を記述する型エイリアスです。

wsgiref.types.WSGIApplication¶: WSGI アプリケーションの呼び出し可能オブジェクトを記述する型エイリアスです。

class wsgiref.types.InputStream¶: WSGI 入力ストリーム を記述する typing.Protocol です。

class wsgiref.types.ErrorStream¶: WSGI エラーストリーム を記述する typing.Protocol です。

class wsgiref.types.FileWrapper¶: ファイルラッパー を記述する typing.Protocol です。このプロトコルの具体的な実装は wsgiref.util.FileWrapper を参照してください。

使用例¶

実際に動作する「Hello World」WSGI アプリケーションです。呼び出し可能オブジェクト start_response は StartResponse プロトコルに従う必要があります。

"""
すべての WSGI アプリケーションには、2 つの引数を受け取る呼び出し可能な
アプリケーションオブジェクトが必要です。
ここでは関数を使います (関数に限らず、例えばクラスも使えます)。
関数に渡す最初の引数は CGI 形式の環境変数を含む辞書で、
2 番目の引数は呼び出し可能オブジェクトです。
"""
from wsgiref.simple_server import make_server


def hello_world_app(environ, start_response):
    status = "200 OK"  # HTTP ステータス
    headers = [("Content-type", "text/plain; charset=utf-8")]  # HTTP ヘッダ
    start_response(status, headers)

    # 戻り値のオブジェクトが出力される。
    return [b"Hello World"]

with make_server("", 8000, hello_world_app) as httpd:
    print("Serving on port 8000...")

    # プロセスが終了させられるまで処理する。
    httpd.serve_forever()

カレントディレクトリのファイルを配信する WSGI アプリケーションの例です。コマンドラインでディレクトリとポート番号 (デフォルトは 8000) を指定することもできます。

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

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

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

`wsgiref.headers` -- WSGI レスポンスヘッダ用のツール¶

`wsgiref.simple_server` -- 単純な WSGI HTTP サーバ¶

`wsgiref.validate` --- WSGI 準拠の検査¶

`wsgiref.handlers` -- サーバとゲートウェイの基底クラス¶

`wsgiref.types` -- 静的型検査用の WSGI の型¶

使用例¶

目次

前のトピックへ

次のトピックへ

このページ

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

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

wsgiref.headers -- WSGI レスポンスヘッダ用のツール¶

wsgiref.simple_server -- 単純な WSGI HTTP サーバ¶

wsgiref.validate --- WSGI 準拠の検査¶

wsgiref.handlers -- サーバとゲートウェイの基底クラス¶

wsgiref.types -- 静的型検査用の WSGI の型¶

使用例¶

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

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

`wsgiref.headers` -- WSGI レスポンスヘッダ用のツール¶

`wsgiref.simple_server` -- 単純な WSGI HTTP サーバ¶

`wsgiref.validate` --- WSGI 準拠の検査¶

`wsgiref.handlers` -- サーバとゲートウェイの基底クラス¶

`wsgiref.types` -- 静的型検査用の WSGI の型¶