| PEP: | 3333 |
|---|---|
| Title: | Python Web Server Gateway Interface v1.0.1 |
| Version: | $Revision:$ |
| Last-Modified: | $Date:$ |
| Author: | P.J. Eby <pje@telecommunity.com> |
| Discussions-To: | Python Web-SIG <web-sig@python.org> |
| Status: | Final |
| Type: | Informational |
| Content-Type: | text/x-rst |
| Created: | 26-Sep-2010 |
| Post-History: | 26-Sep-2010, 04-Oct-2010 |
| Replaces: | 333 |
New in version 1.0.1.
PEP 333 の読者への前書き
これは PEP 333 のアップデートされたバージョンである。 Python 3 でのユー ザビリティをわずかに改良して、 WSGI プロトコルへの長年のいくつかのデファ クトの修正案を取り入れるように変更された。 (また、コードのサンプルを Python 3 に移植した。)
手続き上の理由 [6] で、これは別の PEP である必要がある。 Python 2.x の 下で以前仕様に準拠していたサーバまたはアプリケーションを無効にする変更 は全く行われていない。また、あなたの 2.x アプリケーションまたはサーバが PEP 333 対応であれば、この PEP とも互換性がある。
しかしながら、 Python 3 の下では、あなたのアプリまたはサーバは A Note On String Types および Unicode Issues と題するセクションで概説され た規則にも従わなければならない。
このドキュメントと PEP 333 の間の詳細な行単位の変更点に関しては、SVN リポジトリ [7] を見ることができる、 リビジョン 84854 以前から。
はじめに
この文書は、Web サーバーと Python Web アプリケーション/フレームワークの 間の標準インタフェースの詳細を提案するものである。この提案によって、様々 な Web サーバー間での Web アプリケーションの移植可能性が促進される。
理由と目的
Python には現在、いくつか例を挙げるだけでも、Zope、Quixote、Webware、 SkunkWeb、PSO、Twisted Web といった様々な Web アプリケーション・フレー ムワークが乱立している [1] 。このような幅広い選択肢は、Python を新たに 始める人にとって問題になる。なぜなら、一般に、Web フレームワークの選択 が使用可能な Web サーバーの選択を制限して、逆もまた同様であるからだ。
対照的に、 Java では同様に多くの Web アプリケーション・フレームワークが あるにも関わらず、 Java “servelet” API があることで servelet API をサポー トする任意の Web サーバー上で任意の Java Web アプリケーション・フレーム ワークで書かれたアプリケーションを動かすことができる。
Python においても同様の API が提供され、普及すれば、 Web サーバーが Python で書かれているか (例えば Medusa)、埋め込み Python か (例えば mod_python)、またはゲートウェイプロトコル (例えば CGI、FastCGI など) か ら Python を呼び出すか、といったこととは関係なく、 Web サーバーの選択と フレームワークの選択を切り離し、ユーザは自由な組み合わせで Web サーバー とフレームワークを選ぶことができるようになるだろう。また、フレームワー クやサーバの開発者は、特徴を出したい領域に力を注ぐことができるようにな るだろう。
そのため、この PEP では Web サーバーと Web アプリケーション/フレームワー クの間の、簡単で汎用的なインタフェースを提案する: Python Web Server Gateway Interface (WSGI) である。
しかし、 WSGI 仕様があるだけでは、 Python Web アプリケーションのサーバ やフレームワークの現状の問題を解決することにはならない。それが何らかの 効果を発揮するためには、サーバとフレームワークの作者およびメンテナーが 実際に WSGI を実装する必要がある。
しかしながら、今のところ WSGI をサポートする既存のサーバもフレームワー クも存在しないので、 WSGI サポートを実装する作者に即時の報酬はほとんど ない。そのため、作者の初期投資が十分低くなるように、 WSGI は実装するの が簡単でなければならない (must) 。
したがって、サーバとフレームワークの 両方 でインタフェースの実装が簡 単であることが WSGI に関する実用性にとって絶対的に重要であり、そのため、 それがあらゆるデザイン決定のための主要な評価基準である。
しかしながら、フレームワーク作者のための実装の簡単さは、 Web アプリケー ション作者のための使いやすさと同じものではないことに注意すること。 WSGI は、フレームワーク作者に完全に「余計な飾りのない」インタフェースを 提示する。なぜなら、レスポンスオブジェクトやクッキーの処理のような付属 品は、既存のフレームワークがこれらの課題を取り扱うのを邪魔するものに過 ぎないからだ。繰り返すが、 WSGI の目標は既存のサーバとアプリケーション /フレームワーク間の連携を手助けすることであり、新しい Web フレームワー クを作ることではない。
また、この目標によって WSGI が Python の配布バージョンでまだ利用可能で ない何かを要求することが排除されるということに注意すること。したがって、 この仕様によって新しい標準のライブラリモジュールが提案されるわけではな いし、また必要とされることもない。そして、WSGI において Python 2.2.2 以 上のバージョンを必要としない。 (しかしながら、 Python の将来のバージョ ンで、標準のライブラリによって提供される Web サーバーにこのインタフェー スのサポートを含めるのは良いアイデアだろう。)
既存のまたは将来のフレームワークとサーバにとって実装が容易であることに 加えて、リクエストのプリプロセッサやレスポンスのポストプロセッサ、その 他の WSGI ベースの「ミドルウェア」コンポーネント（サーバに対してはアプ リケーションのように見える一方で、アプリケーションのためにはサーバとし て機能する）を作成するのも簡単であるべきである。
もしミドルウェアが簡単でかつ強健であるなら、そして WSGI がサーバとフレー ムワークで広く利用可能であるなら、完全に新しい種類の Python Web アプリ ケーションフレームワークをもたらす可能性がある: それは、疎結合の WSGI ミドルウェアの部品から構成される Web アプリケーション・フレームワークで ある。実際、既存のフレームワーク作者は彼らのフレームワークの既存のサー ビスを、モノリシックなフレームワークというよりこのような WSGI と共に使 用されるライブラリのような方法で提供するためにリファクタリングすること を選ぶかもしれない。そうなれば、アプリケーション開発者は、単一のフレー ムワークのすべての長所と短所に身を委ねる代わりに、特定の機能性のための 「最善の組み合わせの」コンポーネントを選ぶようになるだろう。
もちろん、これを書いている現在、そのような日は遥か先のことに違いない。 差し当たりは、あらゆるサーバ、あらゆるフレームワークで WSGI が使用でき るようにすることが短期的目標である。
最後に、現在の WSGI ではアプリケーションを Web サーバーまたはサーバゲー トウェイと共に使用するために「配備する」特定のメカニズムは定めないとい うことが言及されるべきである。現在では、これは必ずサーバまたはゲートウェ イの実装毎に定義される。十分な数のサーバとフレームワークが WSGI を実装 し、様々な配備要件を持つ実際の経験が提供されるようになった後で、WSGI サー バとアプリケーションフレームワークの配備仕様について説明する別の PEP を 作成することは価値があるだろう。
仕様の概要
WSGI インタフェースには 2 つの側面がある: 「サーバ」または「ゲートウェ イ」サイドと、「アプリケーション」または「フレームワーク」サイド。サー バサイドはアプリケーションサイドによって提供される callable オブジェク トを呼び出す。そのオブジェクトをどのように提供するかに関する詳細はサー バやゲートウェイによって異なる。ある種のサーバまたはゲートウェイは、ア プリケーションの提供者がサーバまたはゲートウェイのインスタンスを作成し、 そのインスタンスにアプリケーションオブジェクトを提供するための短いスク リプトを書くことを要求するだろう。別のサーバまたはゲートウェイは、アプ リケーションオブジェクトがどこからインポートされるべきであるか、または 別の方法で得られるかを指定するために、設定ファイルや他の仕組みを使用す るかもしれない。
また、「純粋な」サーバ/ゲートウェイとアプリケーション/フレームワークに 加えて、この仕様の両方の側面を実装する「ミドルウェア」コンポーネントを 作成することもできる。そのようなコンポーネントは、サーバに対してはアプ リケーションとして機能すると同時にアプリケーションに対してはサーバとし て機能して、拡張 API 、コンテンツ変換、ナビゲーション、および他の有用な 機能を提供するために使用することができる。
この仕様の全体を通して、 “callable” という用語を、「関数、メソッド、ク ラス、または __call__ メソッドを持つインスタンス」という意味で用い る。callable を実装するサーバ、ゲートウェイ、またはアプリケーションは、 必要に応じて適切な実装のテクニックを選ぶことができる。逆に、 callable を呼び出すサーバ、ゲートウェイ、またはアプリケーションは、どのような callable が提供されるかということに依存してはならない (may not)。 callable は呼び出されるためだけに存在し、その中身を調べるものではない。
New in version 1.0.1.
文字列型に関する注釈
一般に、 HTTP はバイト列を扱う。このことは、この仕様がほとんどバイト列 を扱うことに関するものであることを意味する。
しかしながら、それらのバイト列の内容にはある種のテキスト的な解釈を持つ ことがしばしばある。そして Python では、文字列はテキストを扱う最も便利 な方法である。
しかし、多くの Python バージョンと実装では、文字列はバイト列よりむしろ ユニコードである。これは、使いやすい API と、 HTTP の文脈におけるバイト 列とテキストの正しい変換の間の慎重なバランスを必要とする。特に、異なる str 型を持つ Python 実装の間でコードを移植することをサポートするた めには。
そのため WSGI では、 2種類の「文字列」を定義する:
しかしながら、混乱しないこと: Python の str 型が実際には内部で (under the hood) ユニコードであっても、ネイティブの文字列の 内容 は依 然として Latin-1 エンコードを通してバイトに変換できなければならない! (その他の詳細に関しては本ドキュメントの Unicode Issues セクションを 参照のこと。)
手短かに言えば: 本書で「文字列」という言葉を使った場合、それは「ネイティ ブ」の文字列、すなわち str 型のオブジェクトを指す。それが内部的には バイト列かユニコードとして実装されるか否かに関係なく。「バイト文字列」 に言及している場合、これは「Python 3 では bytes 型、 Python 2では str 型のオブジェクト」と読み替えること。
そして、 HTTP は確かにある意味で「本当にただのバイト列」だが、 Python のデフォルト str 型が何であっても使用することのできる多くの 便利な API がある。
アプリケーション/フレームワークサイド
アプリケーションオブジェクトは、単に2つの引数を受け取る callable オブジェ クトである。「オブジェクト」という用語によって、実際のオブジェクトイン スタンスが必要であると誤解するべきではない: 関数、メソッド、クラス、ま たは __call__ メソッドを持つインスタンスであれば、すべてアプリケー ションオブジェクトとして使用することが許容される。アプリケーションオブ ジェクトは1回以上呼び出すことができなければならない。ほとんどすべての サーバ/ゲートウェイ (CGI を除く) がそのような繰り返された要求をする。
(注意: ここでは「アプリケーション」オブジェクトと呼んでいるが、アプリケー ション開発者が WSGI を Web プログラミング API として使用するという意味 でこれを解釈すべきではない! アプリケーション開発者は、彼らのアプリケー ションを開発するのに、既存のハイレベルなフレームワークサービスを利用し 続けると思われる。 WSGI はフレームワークとサーバ開発者のためのツールで あり、直接アプリケーション開発者をサポートすることを意図していない。)
ここに、2 つのアプリケーションオブジェクトの例がある; 1つは関数であり、 もう片方がクラスである:
HELLO_WORLD = b"Hello world!\n"
def simple_app(environ, start_response):
"""Simplest possible application object"""
status = '200 OK'
response_headers = [('Content-type', 'text/plain')]
start_response(status, response_headers)
return [HELLO_WORLD]
class AppClass:
"""Produce the same output, but using a class
(Note: 'AppClass' is the "application" here, so calling it
returns an instance of 'AppClass', which is then the iterable
return value of the "application callable" as required by
the spec.
If we wanted to use *instances* of 'AppClass' as application
objects instead, we would have to implement a '__call__'
method, which would be invoked to execute the application,
and we would need to create an instance for use by the
server or gateway.
"""
def __init__(self, environ, start_response):
self.environ = environ
self.start = start_response
def __iter__(self):
status = '200 OK'
response_headers = [('Content-type', 'text/plain')]
self.start(status, response_headers)
yield HELLO_WORLD
サーバー/ゲートウェイサイド
アプリケーションに対して HTTP クライアントから要求があると、サーバやゲー トウェイは、アプリケーション callable を呼び出す。例として、ここではア プリケーションオブジェクトを受け取る関数として実装された簡単な CGI ゲー トウェイを示す。この簡単な例ではエラー処理を省いていることに注意するこ と。デフォルトでは捕捉されなかった例外は sys.stderr に出力され、 Web サーバーのログに記録される。
import os, sys
enc, esc = sys.getfilesystemencoding(), 'surrogateescape'
def unicode_to_wsgi(u):
# Convert an environment variable to a WSGI "bytes-as-unicode" string
return u.encode(enc, esc).decode('iso-8859-1')
def wsgi_to_bytes(s):
return s.encode('iso-8859-1')
def run_with_cgi(application):
environ = {k: unicode_to_wsgi(v) for k,v in os.environ.items()}
environ['wsgi.input'] = sys.stdin.buffer
environ['wsgi.errors'] = sys.stderr
environ['wsgi.version'] = (1, 0)
environ['wsgi.multithread'] = False
environ['wsgi.multiprocess'] = True
environ['wsgi.run_once'] = True
if environ.get('HTTPS', 'off') in ('on', '1'):
environ['wsgi.url_scheme'] = 'https'
else:
environ['wsgi.url_scheme'] = 'http'
headers_set = []
headers_sent = []
def write(data):
out = sys.stdout.buffer
if not headers_set:
raise AssertionError("write() before start_response()")
elif not headers_sent:
# Before the first output, send the stored headers
status, response_headers = headers_sent[:] = headers_set
out.write(wsgi_to_bytes('Status: %s\r\n' % status))
for header in response_headers:
out.write(wsgi_to_bytes('%s: %s\r\n' % header))
out.write(wsgi_to_bytes('\r\n'))
out.write(data)
out.flush()
def start_response(status, response_headers, exc_info=None):
if exc_info:
try:
if headers_sent:
# Re-raise original exception if headers sent
raise exc_info[1].with_traceback(exc_info[2])
finally:
exc_info = None # avoid dangling circular ref
elif headers_set:
raise AssertionError("Headers already set!")
headers_set[:] = [status, response_headers]
# Note: error checking on the headers should happen here,
# *after* the headers are set. That way, if an error
# occurs, start_response can only be re-called with
# exc_info set.
return write
result = application(environ, start_response)
try:
for data in result:
if data: # don't send headers until body appears
write(data)
if not headers_sent:
write('') # send headers now if body was empty
finally:
if hasattr(result, 'close'):
result.close()
ミドルウェア: 両サイドを演じるコンポーネント
単一のオブジェクトが何らかのアプリケーションに関してサーバの役割を果た す一方で、何らかのサーバに対してアプリケーションとして機能するかもしれ ないことに注意すること。そのような「ミドルウェア」コンポーネントは、以 下のような機能を実行することができる:
一般に、ミドルウェアの存在はインタフェースの「サーバ/ゲートウェイ」サイ ドと「アプリケーション/フレームワーク」サイドの両方に透過的であり、どん な特別なサポートも必要とするべきではない。ミドルウェアをアプリケーショ ンに組み入れることを望んでいるユーザは、単にミドルウェアコンポーネント を、あたかもそれがアプリケーションであるかのようにサーバに提供する。そ して、ミドルウェアコンポーネントがサーバであるかのように、アプリケーショ ンを呼び出すように設定する。もちろん、ミドルウェアがラップする「アプリ ケーション」は、実際には別のアプリケーションなどをラップする別のミドル ウェアコンポーネントであるかもしれない。それは「ミドルウェアスタック」 と呼ばれるものを作成する。
ほとんどの部分で、ミドルウェアは WSGI のサーバとアプリケーションの両サ イドの制限と要件に従わなければならない。しかしながら、いくつかの場合、 ミドルウェアのための要件は「純粋な」サーバやアプリケーションより厳しい。 これらのポイントは仕様で述べられる。
これは、 Joe Strout の piglatin.py を使用して、 text/plain レス ポンスから偽ラテン語に変換する、 (tongue-in-cheek; 冗談) ミドルウェアコ ンポーネントの例である。 (注意: 「本物」のミドルウェアコンポーネントは、 おそらく content type をチェックするためにより強健な方法を使用する。ま た、 content encoding もチェックすべきである。また、この簡単な例では、 単語がブロック境界を越えて分割される可能性を無視している。)
from piglatin import piglatin
class LatinIter:
"""Transform iterated output to piglatin, if it's okay to do so
Note that the "okayness" can change until the application yields
its first non-empty bytestring, so 'transform_ok' has to be a mutable
truth value.
"""
def __init__(self, result, transform_ok):
if hasattr(result, 'close'):
self.close = result.close
self._next = iter(result).__next__
self.transform_ok = transform_ok
def __iter__(self):
return self
def __next__(self):
if self.transform_ok:
return piglatin(self._next()) # call must be byte-safe on Py3
else:
return self._next()
class Latinator:
# by default, don't transform output
transform = False
def __init__(self, application):
self.application = application
def __call__(self, environ, start_response):
transform_ok = []
def start_latin(status, response_headers, exc_info=None):
# Reset ok flag, in case this is a repeat call
del transform_ok[:]
for name, value in response_headers:
if name.lower() == 'content-type' and value == 'text/plain':
transform_ok.append(True)
# Strip content-length if present, else it'll be wrong
response_headers = [(name, value)
for name, value in response_headers
if name.lower() != 'content-length'
]
break
write = start_response(status, response_headers, exc_info)
if transform_ok:
def write_latin(data):
write(piglatin(data)) # call must be byte-safe on Py3
return write_latin
else:
return write
return LatinIter(self.application(environ, start_latin), transform_ok)
# Run foo_app under a Latinator's control, using the example CGI gateway
from foo_app import foo_app
run_with_cgi(Latinator(foo_app))
仕様の詳細
アプリケーションオブジェクトは2つの固定引数を受け取らなければならない。 説明のためにそれらを environ と start_response と名付けるが、こ れらの名前を持つ必要はない。サーバまたはゲートウェイは、 (キーワード引 数ではなく) 固定引数を使用してアプリケーションオブジェクトを呼び出さ な ければならない (must)。 (例えば、上に示されるように、 result = application(environ, start_response) のようにして呼び出す)
environ パラメータは、CGI スタイルの環境変数を含む辞書オブジェクト である。このオブジェクトは、 builtin の Python 辞書でなければならない (must) (サブクラス、 UserDict 、または他の辞書エミュレーション では ない)、そしてアプリケーションは好きなように辞書を変更することが できる。辞書は、また、いくつかの必須 WSGI 変数 (後のセクションで説明さ れる) を含まなければならず、また、以下で説明される規約に従って命名され る、サーバ特有の拡張変数を含むことができる。
start_response パラメータは、2つの必須の固定引数、および1つの任意引 数を受け付ける callable である。説明のためにこれらの引数を status 、 response_headers 、および exc_info と命名したが、それらの引数は 必ずしもこのような名前である必要はなく、アプリケーションは固定引数を使 用して start_response callable を呼び出さなければならない (must) (例えば start_response(status, response_headers))。
status パラメータは "999 Message here" 形式のステータス文字列で あり、 response_headers は HTTP 応答ヘッダーについて記述する (header_name, header_value) タプルのリストである。任意の exc_info パラメータについては、以下の The start_response() Callable セクションと Error Handling セクションで説明される。それ が使用されるのは、アプリケーションがエラーを捕捉し、ブラウザへエラーメッ セージを表示しようとしたときだけである。
start_response callable は、 write(body_data) callable を返さな ければならない。 write callable は1つの固定パラメータを取る: HTTP レスポンス本体の一部として書かれるべきバイト文字列。 (注意: write() callable は、いくつかの既存のフレームワークで必須の出力 API をサポート するためだけに提供されている; 避けることができるなら、新しいアプリケー ションまたはフレームワークはそれを使用するべきではない。その他の詳細に 関しては、 Buffering and Streaming セクションを参照。)
アプリケーションオブジェクトは、サーバによって呼ばれると、バイト文字列を yield する iterable を返さなければならない。これは、様々な方法で実現す ることができる。例えば、バイト文字列のリストを返すようにする、アプリケーショ ンをジェネレータ関数にしてその関数がバイト文字列を yield するようにする、アプ リケーションをクラスにしてそのインスタンスが iterable であるようにする、 といったような方法である。それがどのように実現されているかにかかわらず、 アプリケーションオブジェクトはいつもバイト文字列を yield する iterable を返さ なければならない。
サーバまたはゲートウェイは、yield されたバイト文字列を非バッファリング形式で クライアントに伝えなければならない。それぞれのバイト文字列の伝達を、別の 1つ を要求する前に終了する。 (言い換えれば、アプリケーションは自身のバッファ リングを実行すべきである (should)。アプリケーション出力をどのように 扱わなければならないかに関して詳しくは、以下の Buffering and Streaming セクションを参照。)
サーバまたはゲートウェイは、yield されたバイト文字列をバイナリのバイト列とし て扱うべきである: 特に、行末の文字が変更されないことを保証しなければな らない。出力されるバイト文字列がクライアントに適当な形式であることを保証する のは、アプリケーションの責任である。 (サーバまたはゲートウェイは、HTTP transfer encoding を適用したり、またはバイト範囲送信などの HTTP 機能を 実行する目的のために他の変更を実行してもよい (may)。その他の詳細に 関して以下の Other HTTP Features を参照。)
len(iterable) に対する呼び出しが成功する場合、サーバはその結果が正 確であることを信頼できなければならない。すなわち、アプリケーションで返 された iterable が正常に機能する __len__() メソッドを提供するなら、 それは正確な結果を返さなければならない (must)。 (通常これがどのよう に使用されるかに関する情報は、 Handling the Content-Length Header セ クションを参照)
もし、アプリケーションで返された iterable が close() メソッドを持っ ているなら、サーバまたはゲートウェイは、現在のリクエストが完了するとき にそのメソッドを呼ばなければならない (must)。これは、リクエストが正 常に処理されたか、イテレーションの間にアプリケーションのエラーのために 途中で停止されたか、ブラウザによって接続が早期に終了したかに関わらず行 われる。(この close() メソッドに対する要求は、アプリケーションによ るリソース解放をサポートするためのものである。このプロトコルは、PEP 342 のジェネレータサポート、および close() メソッドを持つ他の一般的 な iterable の補完となることを意図している)
Changed in version 1.0.1.
ジェネレータや他のカスタムなイテレータを返すアプリケーションは、そのイ テレータ全体が消費されると仮定すべきでない (should not)。なぜなら、 サーバによって早期に閉じられかもしれないので (may)。
(Note: アプリケーションは、サーバがあらゆる body content の前にヘッダー を送ることができるように、 iterable が最初の body バイト文字列を yield する前 に start_response() callable を呼び出さなければならない (must)。 しかし、この呼び出しが iterable の最初のイテレーションの際に実行されて もよい (may) ので、サーバは、iterable 上でイテレーションを始める前 に start_response() が呼ばれたと仮定してはならない (must not)。)
最後に、サーバとゲートウェイは、アプリケーションから返された iterable の他のいかなる属性も直接使用してはならない (must not)。例外は、 wsgi.file_wrapper によって返された「ファイルラッパー」などのように、 iterable がそのサーバまたはゲートウェイに特定の型のインスタンスである場 合である (Optional Platform-Specific File Handling を参照)。一般的な ケースでは、ここで明記された属性か、または例えば PEP 234 の iteration API を通して属性にアクセスすることだけが許容される。
environ 変数
environ 辞書は、Common Gateway Interface 仕様 [2] で定義されるよう に、これらの CGI 環境変数を含まなければならない。以下の変数は存在しなけ ればならない (must) が、それらの値が空の文字列である場合は、以下に 述べられる例外を除き、省略してもよい (may)。
REQUEST_METHOD
The HTTP request method, such as "GET" or "POST". This cannot ever be an empty string, and so is always required."GET" または "POST" などの HTTP リクエストメソッド。これは、 決して空の文字列にならないので、常に必須である。
SCRIPT_NAME
The initial portion of the request URL’s “path” that corresponds to the application object, so that the application knows its virtual “location”. This may be an empty string, if the application corresponds to the “root” of the server.アプリケーションが仮想的な「位置」を知るための、アプリケーションオブ ジェクトに対応するリクエスト URL の「パス」の最初の部分。アプリケーショ ンがサーバの “root” に一致しているなら、これは空の文字列でもよい (may)。
PATH_INFO
The remainder of the request URL’s “path”, designating the virtual “location” of the request’s target within the application. This may be an empty string, if the request URL targets the application root and does not have a trailing slash.アプリケーションの中でのリクエストのターゲットの仮想的な「位置」を指 定する、リクエスト URL の「パス」の残りの部分。リクエスト URL がアプ リケーションルートを対象としていて、終端のスラッシュを持っていないな ら。これは空の文字列でもよい (may)。
QUERY_STRING
The portion of the request URL that follows the "?", if any. May be empty or absent.もしあるならば "?" に続くリクエスト URL の一部。空であるか、また は存在しないかもしれない。
CONTENT_TYPE
The contents of any Content-Type fields in the HTTP request. May be empty or absent.HTTP リクエスト中の Content-Type フィールドの内容。空であるか、または 存在しないかもしれない。
CONTENT_LENGTH
The contents of any Content-Length fields in the HTTP request. May be empty or absent.HTTP リクエスト中の Content-Length フィールドの内容。空であるか、 または存在しないかもしれない。
SERVER_NAME, SERVER_PORT
When combined with SCRIPT_NAME and PATH_INFO, these two strings can be used to complete the URL. Note, however, that HTTP_HOST, if present, should be used in preference to SERVER_NAME for reconstructing the request URL. See the URL Reconstruction section below for more detail. SERVER_NAME and SERVER_PORT can never be empty strings, and so are always required.SCRIPT_NAME と PATH_INFO を結合する場合、 URL を完成するのに これらの2つの変数を使用することができる。しかし、もし存在しているなら HTTP_HOST がリクエスト URL を再構築するために SERVER_NAME よ りも優先して使用されるべきであることに注意。その他の詳細に関しては以 下の URL Reconstruction セクションを参照。 SERVER_NAME と SERVER_PORT は決して空の文字列にならないので、常に必須である。
SERVER_PROTOCOL
The version of the protocol the client used to send the request. Typically this will be something like "HTTP/1.0" or "HTTP/1.1" and may be used by the application to determine how to treat any HTTP request headers. (This variable should probably be called REQUEST_PROTOCOL, since it denotes the protocol used in the request, and is not necessarily the protocol that will be used in the server’s response. However, for compatibility with CGI we have to keep the existing name.)クライアントがリクエストを送るのに使用したプロトコルのバージョン。通 常、これは "HTTP/1.0" または "HTTP/1.1" のようになる。そして、 アプリケーションは HTTP リクエストヘッダーも扱う方法を決定するために これらの変数を使用するかもしれない。 (この変数はおそらく REQUEST_PROTOCOL と呼ばれるべきである。なぜなら、それがリクエスト で使用されるプロトコルを指示しており、必ずしもサーバのレスポンスに使 用されるプロトコルというわけではないので。しかしながら、CGI との互換 性のために、我々は既存の名前を維持する必要がある。)
HTTP_ Variables
Variables corresponding to the client-supplied HTTP request headers (i.e., variables whose names begin with "HTTP_"). The presence or absence of these variables should correspond with the presence or absence of the appropriate HTTP header in the request.クライアントによって提供された HTTP リクエストヘッダ (すなわち、名前 が "HTTP" で始まる変数) これらの変数が存在するかどうかは、リクエ ストにおいて適切な HTTP ヘッダが存在するかどうかに対応するべきである。
サーバまたはゲートウェイは、他の CGI 変数に関しても適切なものはできるだ け多く提供しようと努力すべきである (should)。加えて、SSL が使用中な ら、サーバまたはゲートウェイは Apache SSL 環境変数 [5] のうち適切なも のはできるだけ多く提供すべきである (should)。例えば HTTPS=on や SSL_PROTOCOL など。しかし、上に記載された以外の CGI 変数を使用する アプリケーションは、関連する拡張をサポートしない Web サーバーに必ずしも 移植可能でないことに注意。 (例えば、ファイルを出力しない Web サーバーは、 意味のある DOCUMENT_ROOT や PATH_TRANSLATED を提供することがで きないだろう。)
WSGI 対応のサーバまたはゲートウェイは、どんな変数を提供するかをその定義 と共に適切に文書化すべきである (should)。アプリケーションは、必要と する変数が存在するかどうかをチェックして、そのような変数が存在しない場 合の fallback プランを持つべきである (should)。
注意: 欠けている変数 (認証が行われていない場合の REMOTE_USER など) は、 environ 辞書からは除かれるべきである。また、CGI 定義変数は、も し存在するならネイティブ文字列でなければならないことに注意。 CGI 変数の値が str 以外の どんな 型であっても、この仕様に対する違反である。
CGI 定義変数に加えて、 environ 辞書は、任意の OS「環境変数」を含ん でもよい (may)。そして、以下の WSGI 定義変数を含まなければならない (must):
wsgi.version
The tuple (1, 0), representing WSGI version 1.0.WSGI version 1.0 を表す、タプル (1, 0) 。
wsgi.url_scheme
A string representing the “scheme” portion of the URL at which the application is being invoked. Normally, this will have the value "http" or "https", as appropriate.アプリケーションが呼び出された URL の「スキーム」 部分を表す文字列。通常これは "http" または "https" のどちらか適切な値を持つ。
wsgi.input
An input stream (file-like object) from which the HTTP request body bytes can be read. (The server or gateway may perform reads on-demand as requested by the application, or it may pre- read the client’s request body and buffer it in-memory or on disk, or use any other technique for providing such an input stream, according to its preference.)HTTP リクエスト本体のバイト列を読み出すことができる入力ス トリーム (file-like オブジェクト)。 (サーバまた はゲートウェイは、アプリケーションからの要求に応 じて読み出しを実行するか、またはクライアントのリ クエスト本体を事前に読み出して、メモリまたはディ スクの上にそれをバッファリングするか、あるいはそ のような入力ストリームを提供するための他のいかな るテクニックも、好みに従って使用してもよい。)
wsgi.errors
An output stream (file-like object) to which error output can be written, for the purpose of recording program or other errors in a standardized and possibly centralized location. This should be a “text mode” stream; i.e., applications should use "\n" as a line ending, and assume that it will be converted to the correct line ending by the server/gateway.エラー出力を書き込むことができる出力ストリーム (file-like オブジェクト)。プログラムや他のエラー を、標準化された、場合によっては集約された場所に 記録する目的のために用いられる。これは「テキスト モード」ストリームであるべきである; すなわち、ア プリケーションは行末端として "\n" を使用して、 それがサーバ/ゲートウェイによって正しい行末端に 変換されると仮定すべきである。
Changed in version 1.0.1.
(On platforms where the str type is unicode, the error stream should accept and log arbitrary unicode without raising an error; it is allowed, however, to substitute characters that cannot be rendered in the stream’s encoding.)(str 型がユニコードであるプラットホームでは、 エラーストリームは例外を上げずに任意のユニコード を受け付けて、ログに記録すべきである (should)。しかし、ストリームのエンコードに変 換することができない文字を置き換えることは許可さ れる。)
For many servers, wsgi.errors will be the server’s main error log. Alternatively, this may be sys.stderr, or a log file of some sort. The server’s documentation should include an explanation of how to configure this or where to find the recorded output. A server or gateway may supply different error streams to different applications, if this is desired.多くのサーバでは、 wsgi.errors はサーバ本体 のエラーログになるだろう。代わりに、これは sys.stderr またはある種のログファイルでもよ い。サーバのドキュメンテーションはどのようにこれ を設定するか、または記録された出力をどこで見つけ られるかに関する説明を含むべきである。サーバまた はゲートウェイは、もし望まれているなら、異なった アプリケーションに対して異なったエラーストリーム を提供してもよい。
wsgi.multithread
This value should evaluate true if the application object may be simultaneously invoked by another thread in the same process, and should evaluate false otherwise.アプリケーションオブジェクトが同じプロセスの中で 同時に別のスレッドによって呼び出されることがある なら、この値は true と評価されるべきであり、そう でなければこの値は false と評価されるべきである。
wsgi.multiprocess
This value should evaluate true if an equivalent application object may be simultaneously invoked by another process, and should evaluate false otherwise.等価なアプリケーションオブジェクトが、同時に別の プロセスによって呼び出されることがあるなら、この 値は true と評価されるべきであり、そうでなければ false と評価されるべきである。
wsgi.run_once
This value should evaluate true if the server or gateway expects (but does not guarantee!) that the application will only be invoked this one time during the life of its containing process. Normally, this will only be true for a gateway based on CGI (or something similar).この値は、サーバまたはゲートウェイが、プロセスの 寿命の間にアプリケーションが呼び出されるのはこの 1回だけであると期待する (しかし、保証はしない!) 場合に、true と評価されるべきである。通常、これ は CGI (または同様の何か) に基づくゲートウェイだ けで true になるだろう。
最後に、 environ 辞書はサーバ定義変数を含んでもよい。これらの変数は、 アルファベット小文字、数字、ドット、およびアンダースコアだけを使用して 命名されるべきである。そしてそれを定義するサーバまたはゲートウェイにユ ニークな名前をプリフィックスとして付加すべきである。例えば、 mod_python は mod_python.some_valiable のような名前で変数を定義 するだろう。
入力およびエラーストリーム
サーバによって提供された入力およびエラーストリームは、以下のメソッドを サポートしなければならない:
| Method | Stream | Notes |
| read(size) | input | 1 |
| readline() | input | 1, 2 |
| readlines(hint) | input | 1, 3 |
| __iter__() | input | |
| flush() | errors | 4 |
| write(str) | errors | |
| writelines(seq) | errors |
それぞれのメソッドの意味は、上の表にリストアップされている注記を例外と して、Python Library Reference の中で以下のように文書化されている:
サーバは、クライアントの指定した Content-Length を越えて読み出す 必要はなく、アプリケーションがそのポイントを越えて読み出そうとした場 合に、end-of-file 状態をシミュレートすべきである (should)。アプリケーショ ンは、 CONTENT_LENGTH 変数によって指定されるより多くのデータを読 み出そうとすべきでない (should not)。
Changed in version 1.0.1.
A server should allow read() to be called without an argument, and return the remainder of the client’s input stream.
サーバは、 read() が引数なしで呼ばれることを許可して、クライアン トの入力ストリームの残りを返すべきである (should)。
A server should return empty bytestrings from any attempt to read from an empty or exhausted input stream.
サーバは、空の、あるいは消費された入力ストリームから読み込もうとする あらゆる試みに対して空のバイト文字列を返すべきである (should)。
Changed in version 1.0.1.
サーバは、 readline() に対する任意の “size” 引数をサポートするべ きである (should) が、 WSGI 1.0 ではそのサポートを省略することが 許されていた。
(In WSGI 1.0, the size argument was not supported, on the grounds that it might have been complex to implement, and was not often used in practice... but then the cgi module started using it, and so practical servers had to start supporting it anyway!)
(WSGI 1.0 では、実装が複雑で実際には使われないという理由から size 引 数はサポートされなかった。しかしその後 cgi モジュールがそれを使 い始め、そして、実用的なサーバはとにかくそれをサポートしなければなら なくなった!)
上の表に記載されたメソッドは、この仕様に従うすべてのサーバでサポートさ れなければならない (must)。この仕様に従うアプリケーションは、 input または errors オブジェクトのいかなる他のメソッドまたは属 性も使用してはならない (must not)。特に、それらが close() メソッ ドを持っていても、アプリケーションはこれらのストリームを閉じようとして はならない (must not)。
アプリケーションオブジェクトに渡された 2番目のパラメータは、 start_response(status, response_headers, exc_info=None) 形式の callable である (すべての WSGI callables と同様、引数はキーワード引数で はなく固定引数で提供されなければならない)。 start_response callable は、HTTP レスポンスを開始するために使用される。そして、それは write(body_data) callable を返さなければならない。 (以下の Buffering and Streaming セクションを参照)。
status 引数は、 "200 OK" や "404 Not Found" のような、HTTP 「ステータス」文字列である。すなわち、それは Status-Code と Reason-Phrase をこの順番で含む文字列で、シングルスペースによって分離さ れ、全体を囲む空白または他の文字列を持たない (詳しい情報に関しては RFC 2616 セクション 6.1.1 を参照)。その文字列は、制御文字を含んではならない (must not)。また、復帰、ラインフィード、またはそれらの組み合わせで 終わってはならない。
response_headers 引数は、 (header_name, header_value) タプルの リストである。それは Python リストでなければならない; すなわち、 type(response_headers) is ListType である。そして、サーバはその内容 を自由に変更してもよい (may)。それぞれの header_name は有効な HTTP ヘッダフィールド名 (RFC 2616 セクション 4.2 によって定義されるよう に) でなければならず、末尾のコロンも他の記号も含まない。
それぞれの header_value は、復帰またはラインフィードを含む どんな 制御文字も、埋め込まれているか末尾かどうかに関わらず、含んではならない (must not)。 (これらの要件は、サーバ、ゲートウェイ、およびレスポン スヘッダーを inspect または変更する必要のある中間的レスポンス・プロセッ サで実行しなければならない構文解析の複雑さを最小にするためである。)
一般に、サーバまたはゲートウェイは、正しいヘッダーが確実にクライアント に送られることに対する責任を負う: もしアプリケーションが HTTP (あるいは 効力を持った関連する他の仕様) によって必要とされるヘッダーを省略するな ら、サーバまたはゲートウェイがそれを加えなければならない (must)。例 えば、HTTP Date: や Server: ヘッダーは、通常、サーバまたはゲー トウェイによって提供されるだろう。
(サーバ/ゲートウェイ作者のためのリマインダー: HTTP ヘッダ名は文字の大小 を区別しないので、アプリケーションで提供されたヘッダーを調べるとき、そ れを必ず考慮に入れること!)
アプリケーションとミドルウェアは、HTTP/1.1 の”hop-by-hop”機能またはヘッ ダーや、HTTP/1.0 における同等の機能や、あるいはクライアントから Web サー バーへの接続の永続性に影響するどんなヘッダーも、使用することは禁止され る。これらの機能は、本物の Web サーバーに排他的な領域である。サーバある いはゲートウェイは、アプリケーションがそれらを送ろうとすることは致命的 なエラーであるとみなし、それらが start_response() に提供された場合、 エラーを raise すべきである (should)。 (「hop-by-hop」の機能とヘッ ダーに関してより多くの詳細は、以下の Other HTTP Features セクション を参照。)
Changed in version 1.0.1.
サーバは、 start_response が呼ばれたときにヘッダーの中のエラーを確 認するべきで (should)、そうすればアプリケーションがまだ稼働している 間にエラーを送出することができる。
しかし、 start_response callable は、実際にレスポンスヘッダーを送信してはな らない (must not)。代わりに、空でないバイト文字列を yield するアプリケー ション戻り値の最初の繰り返しの後か、アプリケーションの write() callable の最初の呼び出しの時に だけ 送信するように、レスポンスヘッ ダをサーバまたはゲートウェイに格納しなければならない。言い換えれば、実 際のボディーデータが利用可能になるか、またはアプリケーションの返された iterable が消費されるまで、レスポンスヘッダーを送ってはならない。 (この 規則に対する可能な唯一の例外は、レスポンスヘッダーが明示的に 0 の Content-Length を含む場合である。)
レスポンスヘッダー送信のこの遅延は、バッファリングされる非同期なアプリ ケーションが、元々意図された出力をエラー出力に取り替えることが最後の可 能な瞬間までできることを保証するためである。例えば、アプリケーションバッ ファの中でボディーが生成されている間にエラーが発生するなら、アプリケー ションは、レスポンスステータスを「200 OK」から「500 Internal Error」に 変える必要があるかもしれない。
exc_info 引数は、もし提供されるなら Python の sys.exc_info() タ プルでなければならない。アプリケーションは、エラーハンドラが start_response を呼んでいる場合にだけ、この引数を提供するべきである。 もし exc_info が提供されていて、まだ何も HTTP ヘッダが出力されてい ないなら、 start_response は、現在格納された HTTP レスポンスヘッダー を新たに提供されたものに置き換えるべきである。その結果、エラーが発生し たときにアプリケーションが出力に関して「気が変わる」ことを許容する。
しかし、 exc_info が提供されていて、 HTTP ヘッダが既に送られた後なら、 start_response はエラーを raise しなければならず (must)、 exc_info タプルを使って re-raise すべきである (should)。以下のように:
raise exc_info[1].with_traceback(exc_info[2])
これは、アプリケーションで捕捉された例外を再び送出する。そして原則とし てアプリケーションを中止させるべきである。 (いったん HTTP ヘッダが送ら れると、アプリケーションがブラウザにエラー出力を試みることは安全ではな い。) アプリケーションは、 exc_info を用いて start_response を 呼んだ場合、 start_response で発生したどんな例外も捕捉してはならな い (must not)。代わりに、そのような例外がサーバまたはゲートウェイに 逆伝播することを許すべきである。その他の詳細に関して、以下の Error Handling を参照。
アプリケーションは、 exc_info 引数が提供される場合にだけ、 start_response を複数回呼んでもよい (may)。より正確には、アプリ ケーションの現在の呼び出しの中で既に start_response が呼ばれたなら、 exc_info 引数なしで start_response を呼ぶのは致命的なエラーであ る。これは、 start_response の最初の呼び出しがエラーを送出した場合 も含む。(正しい論理の例証のために、上の CGI ゲートウェイの例を参照。)
注意: start_response を実装するサーバ、ゲートウェイ、またはミドルウェ アは、関係するトレースバックとフレームを通して循環参照を作成するのを避 けるために、関数の実行の持続時間を超えて exc_info パラメータへの参 照を保持しないことを確実にすべきである (should)。これを行う最も簡単 な方法は以下のようになる:
def start_response(status, response_headers, exc_info=None):
if exc_info:
try:
# do stuff w/exc_info here
finally:
exc_info = None # Avoid circular ref.
例の CGI ゲートウェイはこのテクニックの別の例を提供する。
Content-Length ヘッダーの扱い
Changed in version 1.0.1.
アプリケーションが Content-Length ヘッダーを提供する場合、サーバは ヘッダーが許容するより多くのバイト数をクライアントに送るべきでなく (should not)、 十分なデータが送られたらレスポンスに対するイテレーショ ンを止め、アプリケーションがそのポイントを過ぎて write() を試みるな らエラーを上げるべきである (should)。(もちろん、アプリケーションが 宣言した Content-Length を達成できるだけの 十分な データを提供し ないなら、サーバは接続を終了してログに記録するか、または別の方法でエラー を報告するべきである (should)。)
アプリケーションが Content-Length ヘッダーを提供しないなら、サーバ またはゲートウェイは、それを扱うためにいくつかのアプローチの 1つを選ん でもよい。最も簡単なのは、レスポンスが終了したときにクライアント接続を 閉じることである。
しかしながら、いくつかの状況では、サーバまたはゲートウェイが Content-Length ヘッダーを生成するか、または少なくともクライアント接 続を閉じる必要性を避けることができるかもしれない。アプリケーションが write() callable を呼び出して いなくて 、 iterable を返し、その len() が 1 である場合、サーバは、 iterable によって yield された最 初のバイト文字列の長さを取得しながら自動的に Content-Length を決定するこ とができる。
そして、サーバとクライアントがともに HTTP/1.1 “chunked encoding” [3] をサポー トするなら、サーバは各 write() の呼び出しまたは iterable によって yield されたバイト文字列のチャンクを送るのに chunked encoding を使用してもよ い (may)。すなわち、チャンク毎に Content-Length ヘッダーを生成 する。これによって、サーバはもしそれを望むならクライアント接続を持続で きる。これをするとき、サーバが RFC 2616 に完全に従わなければならない (must) ことに注意。そうでなければ、 Content-Length が存在しない ことに対処するための他の戦略の 1 つに fall back すること。
(注意: アプリケーションおよびミドルウェアは、出力に chunking や gzipping などのどんな種類の Transfer-Encoding も適用してはならない (must not); “hop-by-hop” 操作と同様に、これらのエンコーディングは本 物の Web サーバー/ゲートウェイの領域である。その他の詳細に関しては、以 下の Other HTTP Features を参照。)
バッファリングとストリーミング
一般的に、アプリケーションは、自身の (適切なサイズの) 出力をバッファリ ングして、それを一気に送ることによって、最も良い効率を実現するだろう。 これは Zope などの既存のフレームワークで一般的なアプローチである: 出力 は StringIO または同様の物でバッファリングされ、次にレスポンスヘッダー と共に一気に送信される。
WSGI における対応するアプローチは、アプリケーションが単に、単一のバイト文字列 としてレスポンス本体を含む、ただ 1つの要素の iterable (リストなど) を返 すことである。これは、そのテキストが容易にメモリに収まる HTML ページを 描画するような、アプリケーション機能のほとんどの部分におけるお勧めのア プローチである。
しかしながら、大きいファイル、または HTTP ストリーミングの特殊な用途 (複合「サーバプッシュ」など) のために、アプリケーションは出力をより小さ なブロックに提供する必要があるかもしれない (例えばメモリに大きいファイ ルをロードすることを避けるため)。また、応答のある部分を生成するのに時間 がかかる場合も時々あるが、それに先行するレスポンスの部分を前もって送る ことは役に立つだろう。
これらの場合では、通常、アプリケーションはブロックごとの様式で出力を生 成するイテレータ (しばしばジェネレータ・イテレータ) を返すだろう。これ らのブロックは、 mulitpart 境界 (「サーバプッシュ」のための) や、時間の かかるタスク (ディスクに存在するファイルの別のブロックを読むなど) のす ぐ前で分割が起こるかもしれない。
WSGI サーバ、ゲートウェイ、およびミドルウェアは、どんなブロックの送信も 遅延してはならない (must not); ブロックをクライアントに完全に伝える か、またはアプリケーションが次のブロックを作り出している間も送信を続け ることを保証しなければならない (must)。サーバ/ゲートウェイまたはミ ドルウェアは、次の 3つの方法のうちの 1つで、この保証を提供することがで きる:
この保証を提供することによって、WSGI は送信が出力データの任意のポイント で中断しないことをアプリケーションが保証することを可能にする。適切な機 能にとって、これは重要である。例えば、複合「サーバプッシュ」ストリーミ ングでは、複合境界の間のデータはクライアントにすべて送られなければなら ない。
ブロック境界を扱うミドルウェア
非同期のアプリケーションおよびサーバのより良いサポートのために、ミドル ウェアコンポーネントはアプリケーション iterable から複数の値を待ってい る間、イテレーションをブロックしてはならない (must not)。ミドルウェ アが出力を生成できるようになる前に、アプリケーションからより多くのデー タを蓄積する必要があるなら、空のバイト文字列を yield しなければならない (must)。
この要件を言い換えれば、ミドルウェアコンポーネントは内包するアプリケー ションが値を yield する毎に 少なくとも 1つの値を yield しなければなら ない 。ミドルウェアが他の値を yield することができないなら、空のバイト文字 列を yield しなければならない。
この要件は、非同期なアプリケーションとサーバが協力して、与えられた数の アプリケーションインスタンスを同時に実行するのに必要なスレッドの数を減 らすことができることを保証する。
また、この要件が、ミドルウェアは内包するアプリケーションが iterable を 返すとすぐに iterable を返さなければならない (must) ということを意 味することに注意。また、ミドルウェアは、内包するアプリケーションから yield されたデータを送信するために write() callable を使用すること が禁止される。ミドルウェアは、内包するアプリケーションがミドルウェアか ら提供された``write()`` callable を使用して送ったデータを送信するために だけ、親サーバの write() callable を使用することができる。
いくつかの既存のアプリケーション・フレームワーク API は、WSGI と異なっ た方法で非バッファリング出力をサポートする。特に、 “write” 関数またはあ る種のバッファリングされないデータのブロックを書くための方法を提供した り、または、バッファリングされる “write” 関数と、バッファをフラッシュす るための “flush” メカニズムを提供したりする。
残念ながら、そのような API はスレッドや他の特別なメカニズムが使用されて いない限り、WSGI の “iterable” アプリケーション戻り値の方法では実装する ことができない。
したがって、これらのフレームワークが必須の API を使用し続けることを許容 するために、 WSGI は特別な write() callable を含んでいる。それは、 start_response callable によって返される。
新しい WSGI アプリケーションとフレームワークは、可能なら write() callable を使用すべきでない (should not)。 write() callable は、 不可避のストリーミング API をサポートするための完全なハックである。一般 に、アプリケーションはその戻り値の iterable によって出力を生成すべきで ある。これによって Web サーバーは、同じ Python スレッドにおける他のタス クを相互に切り替えることが可能になり、潜在的にサーバ全体でより良い効率 を提供することができる。
write() callable は start_response() callable によって返される。 そして、ただ一つのパラメータを受け付ける: HTTP レスポンスボディの一部と して書き出されるべきバイト文字列。それは、出力 iterable によって yield された 場合と同じように扱われる。言い換えれば、 write() が戻る前に、渡され たバイト文字列をクライアントに完全に送信するか、あるいはアプリケーションが先 に進んでいる間、送信のためにそれをバッファリングすることを保証しなけれ ばならない。
アプリケーションはレスポンスボディのすべてまたは一部を生成するのに write() を使用した場合でも、 iterable オブジェクトを返さなければな らない (must)。返された iterable は空でもよい (may) (すなわち、 空でないバイト文字列を一切 yield しない) が、空でないバイト文字列を yield する な ら、サーバまたはゲートウェイはその出力を通常と同じように扱わなければな らない (すなわち、それをすぐに送信するか、またはキューに入れる)。アプリ ケーションは、自身の返した iterable から write() を呼び出してはなら ない (must not)。そして、したがって、iterable によって yield された どんなバイト文字列も、 write() に渡されたすべてのバイト文字列をクライアントに送っ た後で送信される。
Unicode の問題
HTTP は Unicode を直接サポートしない。そして、このインタフェースも同様 である。すべてのエンコード/デコードは、アプリケーションで扱われなければ ならない; サーバに渡された、またはサーバから渡されたすべての文字列は、 Unicode オブジェクトではなく、 str または bytes 型でなければな らず、 unicode であってはならない。文字列オブジェクトが必要な局面で unicode オブジェクトを使用した結果は、未定義である。
また、 start_response() にステータスまたはレスポンスヘッダーとして 渡された文字列は、コード化に関して RFC 2616 に従わなければならない (must) ことに注意。すなわち、それらは、ISO-8859-1 文字列であるか、 または RFC 2047 のMIME エンコーディングを使用しなければならない。
str 型や StringType 型が実際には Unicode ベースである Python プ ラットホーム (例えば Jython, IronPython, Python 3 など) であっても、 この仕様で言及されたすべての「文字列」は、 ISO-8859-1 エンコーディング で表現可能なコード・ポイント (\u0000 から \u00FF まで) だけで構 成されなければならない。アプリケーションがこの範囲外の Unicode 文字また はコード・ポイントを含む文字列を渡すのは、致命的なエラーである。同様に、 サーバおよびゲートウェイは、この範囲外の Unicode 文字を含む文字列をアプ リケーションに渡してはならない (must not)。
繰り返すが、この仕様で文字列として言及されたすべてのオブジェクトは、 str 型または StringType 型でなければならず (must)、 unicode 型または UnicodeType 型であってはならない (must not)。そして、プラットホー ムが str/StringType オブジェクトに 1文字あたり 8ビット以上を許 可している場合でも、この仕様で「文字列」と呼ばれた値に対しては、下位の 8 ビットだけしか使用することができない。
Changed in version 1.0.1.
この仕様で「バイト文字列」と呼ばれた値 (すなわち、 wsgi.input から 読まれた値や、アプリケーションによって write() または yield に渡さ れた値) については、その値は Python 3 では byte 型、それ以前のバー ジョンでは str 型でなければならない。
エラー処理
一般に、アプリケーションはそれ自身の内部エラーを捕捉し、ブラウザに有用 なメッセージを表示すべきである (should)。 (この文脈において、「有用」 が何を意味するのかを決めるのは、アプリケーション次第である)
しかしながら、そのようなメッセージを表示するためには、アプリケーション は実際にはどんなデータもまだブラウザに送っていない状態でなければならな い。さもなければ、それはレスポンスを崩壊させる危険を冒す。そのため、 WSGI はアプリケーションがエラーメッセージを送るか、または自動的に中止さ れることを許可するための仕組みを提供する: start_response への exc_info 引数。これは、その使用に関する例である:
try:
# regular application code here
status = "200 Froody"
response_headers = [("content-type", "text/plain")]
start_response(status, response_headers)
return ["normal body goes here"]
except:
# XXX should trap runtime issues like MemoryError, KeyboardInterrupt
# in a separate handler before this bare 'except:'...
status = "500 Oops"
response_headers = [("content-type", "text/plain")]
start_response(status, response_headers, sys.exc_info())
return ["error body goes here"]
例外が起こったとき、出力が全く書き出されていない場合は、 start_response への呼び出しは正常に戻る。そして、アプリケーションは ブラウザに送られるエラー本体を返すだろう。しかし、既に何らかの出力をブ ラウザに送った後なら、 start_response は提供された例外を再送出する。 アプリケーションは、この例外を捕捉すべきでない (should not)。そして、 アプリケーションは異常終了 (abort) するだろう。そして、サーバまたはゲー トウェイは、この (致命的) 例外を捕捉して、レスポンスを中止することがで きる。
サーバは、アプリケーションまたはアプリケーションの戻り値のイテレーショ ンを中止するどんな例外も捕捉して、ログに出力すべきである (should)。 アプリケーションエラーが起こるとき、レスポンスの一部が既にブラウザに書 き出されている場合、サーバまたはゲートウェイが、出力にエラーメッセージ を加えようと試みてもよい (may)。これは、既に送られたヘッダーが text/* content type を示し、サーバがそれをどのように安全に変更する かを知っている場合に限る。
ミドルウェアによっては、追加の例外処理サービスを提供したり、アプリケー ションエラーメッセージを傍受して、置き換えることを望むかもしれない。そ のような場合、ミドルウェアは、 start_response に渡された exc_info を再送出 しない ことを選ぶかもしれない。代わりにミドル ウェア特有の例外を送出するか、または提供された引数を格納した後に例外な しで単に戻るだろう。これによって、次に、アプリケーションはエラー本体の iterable を返し (または write() を呼び出し)、ミドルウェアがエラー出 力を得て、変更するのを許容する。これらのテクニックは、アプリケーション 作者が次のことを守る場合に動く:
HTTP 1.1 を実装するサーバおよびゲートウェイは、HTTP 1.1 の “expect/continue” メカニズムの透過的なサポートを提供しなければならない (must)。これはいくつかの方法で行うことができる:
これらの振舞いの制限は、HTTP 1.0 リクエストに対して、またはアプリケーショ ンオブジェクトに向けられていないリクエストに対しては適用されないことに 注意。HTTP1.1 Expect/Continue の詳しい情報に関しては、RFC 2616 セクショ ン 8.2.3、および 10.1.1 を参照。
その他の HTTP 機能
一般に、サーバとゲートウェイは、出力に関して沈黙を守り、アプリケーショ ンに完全なコントロールを許すべきである。それらは、アプリケーションのレ スポンスの有効な意味論を変更しない変更をだけを行うべきである。アプリケー ション開発者は、いつでも付加的な機能を提供するためにミドルウェアのコン ポーネントを加えことができる。そのため サーバ/ゲートウェイ開発者は、彼 らの実装に関して保守的であるべきである。ある意味でサーバは、それ自体が HTTP 「ゲートウェイサーバ」のようなものと考えるべきである。それは HTTP 「オリジナルサーバ」であるアプリケーションを持っている。 (これらの用語 の定義に関して、RFC 2616 セクション 1.3 を参照。)
しかしながら、 WSGI サーバとアプリケーションは HTTP 通信をしないので、 RFC 2616 で “hop-by-hop” ヘッダと呼ばれているものを WSGI の内部の通信に は適用しない。 WSGI アプリケーションは “hop-by-hop”ヘッダー [4] を内部 で生成したり、そのようなヘッダーを生成することを必要とする HTTP 機能を 使用することを試みたり、または入力される environ 辞書の中の “hop-by-hop”ヘッダーの内容も信頼してはならない (must not)。 WSGI サー バは、サポートしている “hop-by-hop” ヘッダの入力を、それ自身で処理しな ければならない (must)。例えば、可能なら chunked encoding を含む Transfer-Encoding をデコードすることによって。
これらの原則をさまざまな HTTP 機能に適用すると、サーバが If-None-Match や If-Modified-Since リクエストヘッダと、 Last-Modified および ETag レスポンスヘッダを通してキャッシュ・ バリデーションを扱ってもよい (may) ことは明確であるべきである。しか しながら、このようにする必要はなく、アプリケーションがこの特徴をサポー トしたいなら、それ自身のキャッシュ・バリデーションを実行するべきである (should)。なぜなら、サーバ/ゲートウェイがそのようなバリデーションを する必要はないので。
同様に、サーバはアプリケーションのレスポンスを再エンコード、または transport-encode してもよい (may) が、アプリケーションはそれ自身で 適当な content encoding を使用すべきであり (should)、 transport encoding を適用してはならない (must not)。アプリケーションがバイト 範囲をネイティブにサポートしないなら、サーバはクライアントの要求に応じ てアプリケーションのレスポンスのバイト範囲を伝えてもよい (may)。し かし、繰り返すが、必要ならアプリケーション自身でこの機能を実行すべきで ある (should)。
これらのアプリケーションに対する制限が、必ずしもあらゆるアプリケーショ ンはあらゆる HTTP 機能を再実装しなければならないということを意味するわ けではないことに注意。多くの HTTP 機能は、ミドルウェアコンポーネントで 部分的または完全に実装することができる。その結果、サーバとアプリケーショ ンの作者の両方が、同じ機能を幾重にも実装することから解放される。
スレッドサポート
スレッドサポート、あるいはその欠如もまた、サーバ依存である。複数の要求 を並列に実行することができるサーバは、スレッド・セーフでないアプリケー ションまたはフレームワークを依然としてそのサーバと共に使用できるように、 シングルスレッド方式でアプリケーションを実行するオプションも提供すべき である (should)。
実装/適用上の注意
サーバ拡張 API
サーバ作者の中には、アプリケーションまたはフレームワークの作者が特定の 目的のために使用することができる、より高度な API を公開したいと考えるか もしれない。例えば、 mod_python に基づくゲートウェイは WSGI 拡張と して Apache API の一部を公開したいと考えるかもしれない。
最も簡単な場合では、これには mod_python.some_api などの environ 変数を定義することだけが必要とされる。しかし、多くの場合、 ミドルウェアの存在の可能性によって、これが難しくなる場合がある。例えば、 environ 変数で見つけられる同じ HTTP ヘッダへのアクセスを提供する API は、 environ がミドルウェアによって変更されたなら異なったデータ を返すかもしれない。
一般に、 WSGI の機能性の何らかの部分を複製したり、置き換えたり、または 迂回させたりするどんな拡張 API も、ミドルウェアコンポーネントと非互換で あるという危険を冒す。サーバ/ゲートウェイ開発者は、だれもミドルウェアを 使用しないと仮定すべきで ない 。なぜなら、何人かのフレームワークの開 発者が、彼らのフレームワークを様々な種類のミドルウェアとしてほぼ完全に 機能するように構成、または再構成することを具体的に予定しているからだ。
したがって、最大の互換性を提供するためには、何らかの WSGI の機能性を置 き換える拡張 API を提供するサーバおよびゲートウェイは、それらが置き換え る API の一部を使用して呼び出すことができるように、それらの API を設計 しなければならない (must)。例えば、 HTTP リクエストヘッダーにアクセ スする拡張 API は、アプリケーションに現在の environ を渡すように要 求して、サーバ/ゲートウェイが API を通してアクセスできる HTTP ヘッダが ミドルウェアによって変更されていないことを検証できるようにしなければな らない。拡張 API が HTTP ヘッダの内容に関して常に environ に同調す ることを保証できないなら、アプリケーションへのサービスを拒否しなければ ならない。例えば、エラーを送出したり、ヘッダーの集合の代わりに None を返したり、または API に適切なことなら何でもすることによって。
同様に、拡張 API がレスポンスデータまたはヘッダーを出力する代替の手段を 提供するなら、アプリケーションが拡張サービスを得ることができる前に start_response callable が渡されることを必要とすべきである。渡され たオブジェクトがサーバ/ゲートウェイが元々アプリケーションに提供したもの と同じでなければ、正しい操作を保証することができないので、アプリケーショ ンへの拡張サービスを提供することを拒否しなければならない。
これらのガイドラインは environ に情報 – 例えば、解析済みの Cookie や、フォーム変数、セッション、および同様のもの – を加えるミドルウェア にも適用される。明らかに、そのようなミドルウェアはこれらの特徴を、単に environ に値を詰めるのではなく、 environ に対して働く関数として 提供するべきである。これによって、あらゆるミドルウェアが URL 書き直しや 他の environ 変更をした 後の environ から情報が計算されることを 確実にする。
サーバ/ゲートウェイとミドルウェア開発者の両方がこれらの「安全な拡張」規 則に従うのは非常に重要である。ミドルウェア開発者が拡張 API を使用してい るアプリケーションから自身の提供する機能が迂回されないことを保証するた めにやむを得ず environ からありとあらゆる拡張 API を削除する未来を 避けるために!
アプリケーション設定
この仕様は、サーバが呼び出すべきアプリケーションをどのように選択または 取得するかについて定義しない。これらの、そして他の設定オプションは極め てサーバ特有の問題である。サーバ/ゲートウェイ作者は、特定のアプリケーショ ンオブジェクトを実行するためにどのように、また何のオプション (スレッド オプションなどの) でサーバを設定するのかを文書化することが期待される。
その一方で、フレームワークの作者はフレームワークの機能性を包含するアプ リケーションオブジェクトの作成方法を文書化すべきである。ユーザ (彼らは サーバとアプリケーションフレームワークの両方を選んだ) は、その 2つを 1 つに接続しなければならない。しかしながら、現在、フレームワークとサーバ の両方には一般的なインタフェースがあるので、これは、それぞれの新しいサー バ/フレームワークの組に対する重大な工学的努力というより、単に機械的な問 題だろう。
最後に、アプリケーション、フレームワーク、およびミドルウェアの中には、 簡単な文字列設定オプションを受け取るために environ 辞書を使用したい と考えるものがあるかもしれない。サーバとゲートウェイは、アプリケーショ ンの配布者が environ に置かれるべき名前-値の組を指定できるようにす ることによって、これをサポートすべきである (should)。最も簡単な場合 では、このサポートは単に OS に提供されたすべての環境変数を os.environ から environ 辞書にコピーすることで成り立つ。なぜな ら、原則として配布者は外部的にこれらをサーバに構成することができるか、 または CGI の場合ではサーバの構成ファイルで設定することができるので。
アプリケーションは、そのような必要な変数を最小に抑えようとすべきである (should)。なぜなら、すべてのサーバがそれらの簡単な構成をサポートす るというわけではないので。もちろん、最悪の場合でも、アプリケーションを 配布する人々は必要な設定値を提供するためのスクリプトを作成することがで きる:
from the_app import application
def new_app(environ, start_response):
environ['the_app.configval1'] = 'something'
return application(environ, start_response)
しかし、既存のアプリケーションやフレームワークは、おそらくただ一つの設 定値を、それらのアプリケーションまたはフレームワーク特有の構成ファイル の位置を示すために environ から必要とするだろう。 (もちろん、アプリ ケーションは起動される度にそれを再読み込みしなければならないのを避ける ために、そのような設定をキャッシュすべきである。)
URL 再構築
アプリケーションがリクエストの完全な URL を再構築したいなら、Ian Bicking によって寄稿された以下のアルゴリズムが使用できるかもしれない:
from urllib import quote
url = environ['wsgi.url_scheme']+'://'
if environ.get('HTTP_HOST'):
url += environ['HTTP_HOST']
else:
url += environ['SERVER_NAME']
if environ['wsgi.url_scheme'] == 'https':
if environ['SERVER_PORT'] != '443':
url += ':' + environ['SERVER_PORT']
else:
if environ['SERVER_PORT'] != '80':
url += ':' + environ['SERVER_PORT']
url += quote(environ.get('SCRIPT_NAME', ''))
url += quote(environ.get('PATH_INFO', ''))
if environ.get('QUERY_STRING'):
url += '?' + environ['QUERY_STRING']
そのような再構築された URL が、クライアントに要求された URI と正確に同 じではないかもしれないことに注意。例えば、サーバによる URL 書き換え規則 は、元々クライアントが要求した URL を標準形になるように変更したかもしれ ない。
古い (<2.2) Python のサポート
いくつかのサーバ、ゲートウェイ、またはアプリケーションでは、古い Python のバージョンをサポートしたいと考えるかもしれない。これは Jython が対象プラットホームであるなら特に重要である。なぜなら、これを書いてい る時点では Jython 2.2 の production-ready のバージョンはまだ利用可能で ないからだ。
サーバとゲートウェイに関しては、これは比較的簡単である: Python 2.2 以下 のバージョンを対象とするサーバとゲートウェイは、単にアプリケーションで 返されたあらゆる iterable に対して標準の “for” ループだけを使用して繰り 返しを行うように制限しなければならない。これが、 2.2 以下のイテレータ・ プロトコル (さらに以下で議論する) と、「今日的な」イテレータ・プロトコ ル (PEP 234 を参照) の両方に対して、ソースレベルの互換性を確実にする唯 一の方法である。
(このテクニックは、Python で書かれているサーバ、ゲートウェイ、またはミ ドルウェアだけに適用する必要があることに注意。他の言語でイテレータ・プ ロトコルをどのように正しく使用するかに関する議論は、このPEPの範囲外であ る。)
アプリケーションにおいて、Python pre-2.2 バージョンをサポートするのは、 わずかに複雑である:
最後に、ミドルウェアが Python pre-2.2 バージョンのサポートを希望してい て、アプリケーション戻り値をイテレートするか、それ自体が iterable を返 す (またはその両方の) 場合、上の適切な推奨に従わなければならない
(言うまでもなく、Python pre-2.2 バージョンをサポートするためにはどんな サーバ、ゲートウェイ、アプリケーション、またはミドルウェアも、対象バー ジョンで利用可能な言語機能だけを使用しなければならない。 True と False の代わりに 1 と 0 を使用するなど)
任意のプラットフォーム特有なファイルの扱い
いくつかのオペレーティング環境は、Unixの sendfile() 呼び出しなどの 特別な高性能ファイル転送機能を提供する。サーバおよびゲートウェイは、 environ の中のオプショナルな wsgi.file_wrapper キーを通して、こ の機能を公開してもよい (may)。アプリケーションは、例えばファイルま たは file-like オブジェクトをその次に返す iterable に変換するのに、この 「ファイルラッパー」を使用してもよい (may):
if 'wsgi.file_wrapper' in environ:
return environ['wsgi.file_wrapper'](filelike, block_size)
else:
return iter(lambda: filelike.read(block_size), '')
サーバまたはゲートウェイが wsgi.file_wrapper を提供するなら、それは、 1つの必須の位置パラメタと 1つの任意の位置パラメタを受け取る callable で なければならない。最初のパラメタは送られる file-like オブジェクトであり、 2番目のパラメタは任意のブロック・サイズ “suggestion” (サーバ/ゲートウェ イが使用する必要はない) である。その callable は、iterable オブジェクト を返さなければならない (must)。そして、サーバ/ゲートウェイが実際に アプリケーションからの戻り値として iterable を受け取るまで、どんなデー タ伝送も実行してはならない (must not) (そうしないと、ミドルウェアが レスポンスデータを解釈またはオーバーライドすることが阻害される)
“file-like” と見なすために、アプリケーションで提供されたオブジェクトは、 任意のサイズ引数を受け取る read() メソッドを持っていなければならな い。それは close() メソッドを持っていてもよく (may)、もしそうな ら wsgi.file_wrapper によって返された iterable は、オリジナルの file-like オブジェクトの close() メソッドを呼び出す close() メ ソッドを持っていなければならない (must)。 file-like オブジェクトが 他の Python built-in のファイルオブジェクトと名前が一致するメソッドまた は属性 (例えば fileno()) を持っている場合、 wsgi.file_wrapper は、これらのメソッドまたは属性が built-in のファイルオブジェクトのもの と同じ意味論を持つと仮定してもよい (may)。
どんなプラットホーム特有のファイル取り扱いの実際の実装も、アプリケーショ ンが戻った 後に 起こらなければならない。そして、サーバまたはゲート ウェイは、ラッパーオブジェクトが返されたかどうかを確かめる。 (繰り返す が、ミドルウェアやエラーハンドラ、および同様のものの存在のために、作成 されたどんなラッパーも実際に使用されるかどうかは保証されない。)
Changed in version 1.0.1.
close() の取り扱いは別として、アプリケーションからファイルラッパー を返すことの意味は、アプリケーションが iter(filelike.read, '') を返 したのと同じであるべきである。言い換えれば、転送が始まる時の「ファイル」 の中の現在の位置から転送が始まり、端に達するまで、または、 Content-Length バイトが出力されるまで続くべきである。アプリケーショ ンが Content-Length を提供しないなら、サーバは背後にあるファイル実 装に関する知識を使用することで、ファイルからそれを生成してもよい (may)。
もちろん、プラットホーム特有のファイル転送 API は通常、任意の “file-like” オブジェクトを受け入れるわけではない。したがって、 wsgi.file_wrapper は、サポートするプラットホーム特有の API に対して file-like オブジェクトを使用するのが適切かどうかを決定するために、提供 されたオブジェクトの fileno() (unix のような OS) や java.nio.FileChannel (Jython の元で) などを introspect しなければな らない。
ファイルラッパーを使用するアプリケーションがプラットホームを越えて移植 性があるように、オブジェクトがプラットホーム API にとって適切で なくて も 、 wsgi.file_wrapper は read() と close() をラップする iterable を返さなければならない (must) ことに注意。これは、古い (2.2 以前の) Python と新しい Pythons で同じように適切な、プラットホーム によらない簡単なファイルラッパーのクラスである:
class FileWrapper:
def __init__(self, filelike, blksize=8192):
self.filelike = filelike
self.blksize = blksize
if hasattr(filelike, 'close'):
self.close = filelike.close
def __getitem__(self, key):
data = self.filelike.read(self.blksize)
if data:
return data
raise IndexError
そしてこれは、プラットホーム特有の API へのアクセスを提供するサーバ/ゲー トウェイで使われているコード片である:
environ['wsgi.file_wrapper'] = FileWrapper
result = application(environ, start_response)
try:
if isinstance(result, FileWrapper):
# check if result.filelike is usable w/platform-specific
# API, and if so, use that API to transmit the result.
# If not, fall through to normal iterable handling
# loop below.
for data in result:
# etc.
finally:
if hasattr(result, 'close'):
result.close()
質疑応答
environ はなぜ辞書でなければならないのか? サブクラスを使用すると 何が問題なのか?
The rationale for requiring a dictionary is to maximize portability between servers. The alternative would be to define some subset of a dictionary’s methods as being the standard and portable interface. In practice, however, most servers will probably find a dictionary adequate to their needs, and thus framework authors will come to expect the full set of dictionary features to be available, since they will be there more often than not. But, if some server chooses not to use a dictionary, then there will be interoperability problems despite that server’s “conformance” to spec. Therefore, making a dictionary mandatory simplifies the specification and guarantees interoperabilty.
辞書を必要とする理由は、サーバ間の移植可能性を最大にすることである。 代替手段は、辞書のメソッドの何らかの部分集合を、標準的な、そして移植 性のあるインタフェースとして定義することだろう。しかしながら、実際に はおそらく、ほとんどのサーバが、彼らの必要性に辞書が適切であることが わかるだろう。そして、その結果、フレームワーク作者は完全なセットの辞 書機能が利用可能であると予想するようになるだろう。なぜなら、しばしば それらがそこにあるので。しかし、何らかのサーバが辞書を使わ ない こ とを選ぶと、そのサーバは仕様に準拠しているにもかかわらず、相互運用性 の問題が生じるだろう。したがって、辞書を必須にすると、仕様が簡素化さ れ、相互運用性が保証される。
Note that this does not prevent server or framework developers from offering specialized services as custom variables inside the environ dictionary. This is the recommended approach for offering any such value-added services.
これは、サーバまたはフレームワーク開発者がカスタム変数として特殊化し たサービスを environ 辞書の 内部に 提供するのを妨げないことに 注意。これは、そのような付加価値サービスを提供することに対するお勧め のアプローチである。
なぜ write() を呼び出すことができ、 かつ バイト文字列を yield する /iterable を返すこともできるのか? ただ 1つの方法を選ぶべきではないか?
If we supported only the iteration approach, then current frameworks that assume the availability of “push” suffer. But, if we only support pushing via write(), then server performance suffers for transmission of e.g. large files (if a worker thread can’t begin work on a new request until all of the output has been sent). Thus, this compromise allows an application framework to support both approaches, as appropriate, but with only a little more burden to the server implementor than a push-only approach would require.
もしイテレーションのアプローチだけをサポートしたなら、 “push” が利用 できることを仮定する現在のフレームワークが被害を受ける。しかし、 write() を通した push だけをサポートするなら、例えば大きいファイ ルの転送でサーバ性能に影響がある (ワーカースレッドが出力のすべてを送 るまで新しい要求に対する仕事を始めることができないなら)。したがって、 この妥協によってアプリケーション・フレームワークが必要に応じて両方の アプローチをサポートできるようになり、しかし、サーバ作成者への負荷は push だけのアプローチで必要になるよりもほんの少し増えるようになる。
close() は何のためにあるのか?
When writes are done during the execution of an application object, the application can ensure that resources are released using a try/finally block. But, if the application returns an iterable, any resources used will not be released until the iterable is garbage collected. The close() idiom allows an application to release critical resources at the end of a request, and it’s forward-compatible with the support for try/finally in generators that’s proposed by PEP 325.
アプリケーション・オブジェクトの実行の間に出力が終了した場合、アプリ ケーションは try/finally ブロックを使ってリソースが確実に解放される ようにすることができる。しかし、アプリケーションが iterable を返すと、 どんなリソースも iterable がガベージコレクトされるまで解放されない。 close() イディオムは、アプリケーションがリクエストの終わりで重要 な資源を解放できるようにする。そして、PEP 325 で提案されたジェネレー タの try/finally サポートの前方互換性をアプリケーションに許容する。
なぜこのインタフェースはこんなに低レベルなのか? 機能 X (Cookie, セッ ション、永続化、など) が欲しい!
This isn’t Yet Another Python Web Framework. It’s just a way for frameworks to talk to web servers, and vice versa. If you want these features, you need to pick a web framework that provides the features you want. And if that framework lets you create a WSGI application, you should be able to run it in most WSGI-supporting servers. Also, some WSGI servers may offer additional services via objects provided in their environ dictionary; see the applicable server documentation for details. (Of course, applications that use such extensions will not be portable to other WSGI-based servers.)
これは Yet Another Python Web フレームワークではない。単にフレームワー クと Web サーバーが会話する方法である。これらの機能が欲しいなら、欲し い機能を提供する Web フレームワークを選ぶ必要がある。そして、そのフレー ムワークで WSGI アプリケーションを作成することができるなら、ほとんど の WSGI をサポートしているサーバでそれを実行することができるはずだ。 また、いくつかの WSGI サーバでは、 environ 辞書に提供されたオブジェ クトを通して追加サービスを提供するかもしれない; 詳細に関して適切なサー バドキュメンテーションを参照のこと。 (もちろん、そのような拡張を使用 するアプリケーションは、他の WSGI ベースのサーバに移植可能ではないだ ろう。)
なぜ古き良き HTTP ヘッダの代わりに CGI 変数を使用するのか? そして、 なぜそれらを WSGI-定義の変数の中に混ぜるのか?
Many existing web frameworks are built heavily upon the CGI spec, and existing web servers know how to generate CGI variables. In contrast, alternative ways of representing inbound HTTP information are fragmented and lack market share. Thus, using the CGI “standard” seems like a good way to leverage existing implementations. As for mixing them with WSGI variables, separating them would just require two dictionary arguments to be passed around, while providing no real benefits.
既存の多くの Web フレームワークが CGI 仕様に極度に基づいている。そし て既存の Web サーバーは CGI 変数を生成する方法を知っている。対照的に、 入力された HTTP 情報を表す代替の方法は、断片化していて、市場のシェア を欠いている。したがって、 CGI 「標準」を使用するのは、既存の実装を 活用する良い方法のように見える。それらを WSGI 変数に混ぜることに関し て、それらを切り離すのはただ 2つの辞書引数をたらい回しにする必要があ るだけで、何の現実的な利点も提供しないだろう。
ステータス文字列についてはどうか? 数字を使うことはできないか? つまり、 "200 OK" の代わりに 200 を渡す
Doing this would complicate the server or gateway, by requiring them to have a table of numeric statuses and corresponding messages. By contrast, it is easy for an application or framework author to type the extra text to go with the specific response code they are using, and existing frameworks often already have a table containing the needed messages. So, on balance it seems better to make the application/framework responsible, rather than the server or gateway.
これをすると、数値の状態と対応するメッセージのテーブルを持つ必要があ るので、サーバまたはゲートウェイが複雑になるだろう。対照的に、アプリ ケーションまたはフレームワーク作者が、使用している特定の応答コードに 伴う付加的なテキストをタイプするのは簡単であり、既存のフレームワーク はしばしば既に必要なメッセージを含むテーブルを持っている。したがって、 バランスの問題で、サーバまたはゲートウェイよりもアプリケーション/フ レームワークが責任を持つ方が良いように思える。
なぜ wsgi.run_once はアプリケーションが 1度だけ実行されることを 保証しないのか?
Because it’s merely a suggestion to the application that it should “rig for infrequent running”. This is intended for application frameworks that have multiple modes of operation for caching, sessions, and so forth. In a “multiple run” mode, such frameworks may preload caches, and may not write e.g. logs or session data to disk after each request. In “single run” mode, such frameworks avoid preloading and flush all necessary writes after each request.
なぜなら、それが単にアプリケーションに対する「通常でない実行への準備」 のための示唆であるからだ。これはキャッシュやセッションなどのための複 数実行モードを持っているアプリケーション・フレームワークのために意図 されている。「複数実行」モードでは、そのようなフレームワークはキャッ シュを事前ロードして、各要求の後では例えばログやセッションデータをディ スクに書かないかもしれない。そのようなフレームワークは、「単一実行」 モードで事前ロードを避けて、各要求の後に必要な書き込みを flush する。
However, in order to test an application or framework to verify correct operation in the latter mode, it may be necessary (or at least expedient) to invoke it more than once. Therefore, an application should not assume that it will definitely not be run again, just because it is called with wsgi.run_once set to True.
しかしながら、後者のモードにおいてアプリケーションまたはフレームワー クが正しい動作をするかテストするために、それを一度より多く呼び出すの は、必要 (そして、少なくとも有益) だろう。したがって、アプリケーショ ンは、 wsgi.run_once が True にセットされて呼び出されたから といって、それが絶対に再び実行されないと仮定すべきではない。
機能 X (辞書、callable、etc.) はアプリケーションコードで使うには醜す ぎる; なぜ代わりにオブジェクトを使わないのか?
All of these implementation choices of WSGI are specifically intended to decouple features from one another; recombining these features into encapsulated objects makes it somewhat harder to write servers or gateways, and an order of magnitude harder to write middleware that replaces or modifies only small portions of the overall functionality.
WSGI のこれらの実装上の選択はすべて、一つの機能を他の機能と 分離 するために明確に意図されている; これらの機能をカプセル化オブジェクト に再結合するのは、サーバまたはゲートウェイをいくらか書きにくくして、 さらに全体の機能の一部だけを置き換える、または変更するミドルウェアを 書くことを大幅に困難にする。
In essence, middleware wants to have a “Chain of Responsibility” pattern, whereby it can act as a “handler” for some functions, while allowing others to remain unchanged. This is difficult to do with ordinary Python objects, if the interface is to remain extensible. For example, one must use __getattr__ or __getattribute__ overrides, to ensure that extensions (such as attributes defined by future WSGI versions) are passed through.
本質的に、ミドルウェアは “Chain of Responsibility” パターンを必要と する。それは、いくつかの機能のために「ハンドラ」として働く一方で、他 の機能に対してはそのまま残すことを許容する。インタフェースが拡張性を 残すなら、これは普通の Python オブジェクトを処理することが難しい。例 えば、拡張 (将来の WSGI バージョンによって定義された属性などの) が通 過することを保証するためには、 __getattr__ または __getattribute__ のオーバーライドを使用しなければならない。
This type of code is notoriously difficult to get 100% correct, and few people will want to write it themselves. They will therefore copy other people’s implementations, but fail to update them when the person they copied from corrects yet another corner case.
このタイプのコードを100%正しく書くのが難しいのはよく知られている。そ して、わずかな人々しか自分たちでそれを書きたくならないだろう。したがっ て、人々は他の人の実装をコピーするだろうが、元にした実装でさらに別の コーナーケースが修正されたとき、それらはアップデートされないだろう。
Further, this necessary boilerplate would be pure excise, a developer tax paid by middleware developers to support a slightly prettier API for application framework developers. But, application framework developers will typically only be updating one framework to support WSGI, and in a very limited part of their framework as a whole. It will likely be their first (and maybe their only) WSGI implementation, and thus they will likely implement with this specification ready to hand. Thus, the effort of making the API “prettier” with object attributes and suchlike would likely be wasted for this audience.
さらに、この必要な定型文は純粋な消費税だろう。ミドルウェア開発者がア プリケーション・フレームワーク開発者のためにわずかにきれいな API を サポートするのに支払った開発者税。しかし、アプリケーション・フレーム ワークの開発者は通常、 WSGIをサポートするために 1つの フレームワーク だけを、そして彼らのフレームワーク全体のとても限定的な部分をアップデー トしている。それがおそらく彼らの最初の (そして多分唯一の) WSGI 実装 であり、彼らはおそらくこの仕様を手の届く範囲で (ready to hand) 実装 するだろう。したがって、 API をオブジェクト属性などに「よりきれいに」 する取り組みは、おそらくこの聴衆によって浪費されるだろう。
We encourage those who want a prettier (or otherwise improved) WSGI interface for use in direct web application programming (as opposed to web framework development) to develop APIs or frameworks that wrap WSGI for convenient use by application developers. In this way, WSGI can remain conveniently low-level for server and middleware authors, while not being “ugly” for application developers.
我々は、(Web フレームワーク開発とは対照的に) 直接 Web アプリケーショ ン・プログラミングに使える、よりきれいな (または別の方法で改良された) WSGI インタフェースを望む人々が、アプリケーション開発者によって便利 に使用できるような、 WSGIをラップする API またはフレームワークを開発 するのを奨励する。このように、 WSGI はサーバとミドルウェア作者には便 利に低レベルであるままで残る一方で、アプリケーション開発者には「醜く」 なくなることができる。
提案された/討議中の話題
これらの項目は、現在 Web-SIG 上やほかの場所で議論しているか、または PEP 作者の “to-do” リストにある:
謝辞
Web-SIG メーリングリスト上のたくさんの仲間に感謝したい。ML上の思慮深い フィードバックによって修正を重ね、このドラフトを書くことができた。特に、 以下の方々には感謝の意を捧げたい:
参考
| [1] | The Python Wiki “Web Programming” topic (http://www.python.org/cgi-bin/moinmoin/WebProgramming) |
| [2] | The Common Gateway Interface Specification, v 1.1, 3rd Draft (http://ken.coar.org/cgi/draft-coar-cgi-v11-03.txt) |
| [3] | “Chunked Transfer Coding” – HTTP/1.1, section 3.6.1 (http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.6.1) |
| [4] | “End-to-end and Hop-by-hop Headers” – HTTP/1.1, Section 13.5.1 (http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.5.1) |
| [5] | mod_ssl Reference, “Environment Variables” (http://www.modssl.org/docs/2.8/ssl_reference.html#ToC25) |
| [6] | Procedural issues regarding modifications to PEP 333 (http://mail.python.org/pipermail/python-dev/2010-September/104114.html) |
| [7] | SVN revision history for PEP 3333, showing differences from PEP 333 (http://svn.python.org/view/peps/trunk/pep-3333.txt?r1=84854&r2=HEAD) |
This document has been placed in the public domain.
このドキュメントは、パブリックドメインです。
(訳注: この翻訳も、パブリックドメインです)