`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 で変更: __getitem__() メソッドのサポートは削除されました。

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

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

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

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

`wsgiref.simple_server` -- シンプルな WSGI HTTP サーバ¶

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

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

`wsgiref.types` -- WSGI types for static type checking¶

使用例¶

目次

前のトピックへ

次のトピックへ

このページ

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

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

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

wsgiref.simple_server -- シンプルな WSGI HTTP サーバ¶

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

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

wsgiref.types -- WSGI types for static type checking¶

使用例¶

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

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

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

`wsgiref.simple_server` -- シンプルな WSGI HTTP サーバ¶

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

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

`wsgiref.types` -- WSGI types for static type checking¶