Abstract
はじめに
This document specifies a proposed standard interface between web servers and Python web applications or frameworks, to promote web application portability across a variety of web servers.
この文書は、Web サーバーと Python Web アプリケーション/フレームワークの間の標準インタフェースの詳細を提案するものである。この提案によって、様々な Web サーバー間での Web アプリケーションの移植可能性が促進される。
Rationale and Goals
Python currently boasts a wide variety of web application frameworks, such as Zope, Quixote, Webware, SkunkWeb, PSO, and Twisted Web – to name just a few [1]. This wide variety of choices can be a problem for new Python users, because generally speaking, their choice of web framework will limit their choice of usable web servers, and vice versa.
Python には現在、いくつか例を挙げるだけでも、Zope、Quixote、Webware、SkunkWeb、PSO、Twisted Web といった様々な Web アプリケーション・フレームワークが乱立している [1]。このような幅広い選択肢は、Python を新たに始める人にとって問題になる。なぜなら、一般に、Web フレームワークの選択が使用可能な Web サーバーの選択を制限して、逆もまた同様であるからだ。
By contrast, although Java has just as many web application frameworks available, Java's "servlet" API makes it possible for applications written with any Java web application framework to run in any web server that supports the servlet API.
対照的に、Java では同様に多くの Web アプリケーション・フレームワークがあるにも関わらず、Java 「servelet」 API があることで、servelet API をサポートする任意の Web サーバー上で、任意の Java Web アプリケーション・フレームワークで書かれたアプリケーションを動かすことが可能になる。
The availability and widespread use of such an API in web servers for Python – whether those servers are written in Python (e.g. Medusa), embed Python (e.g. mod_python), or invoke Python via a gateway protocol (e.g. CGI, FastCGI, etc.) – would separate choice of framework from choice of web server, freeing users to choose a pairing that suits them, while freeing framework and server developers to focus on their preferred area of specialization.
Python においても同様の API が提供され、普及すれば、Web サーバーが Python で書かれているか (例えば Medusa)、埋め込み Python か (例えば mod_python)、またはゲートウェイプロトコル (例えば CGI、FastCGI など) から Python を呼び出すか、といったこととは関係なく、Web サーバーの選択とフレームワークの選択を切り離し、ユーザは自由な組み合わせで Web サーバーとフレームワークを選ぶことができる。また、フレームワークやサーバの開発者は、特徴を出したい領域に力を注ぐことができる。
This PEP, therefore, proposes a simple and universal interface between web servers and web applications or frameworks: the Python Web Server Gateway Interface (WSGI).
そのため、この PEP では Web サーバーと Web アプリケーション/フレームワークの間の、簡単で汎用的なインタフェースを提案する: Python Web Server Gateway Interface (WSGI) である。
But the mere existence of a WSGI spec does nothing to address the existing state of servers and frameworks for Python web applications. Server and framework authors and maintainers must actually implement WSGI for there to be any effect.
しかし、WSGI 仕様があるだけでは、Python Web アプリケーションのサーバやフレームワークの現状の問題を解決することにはならない。それが何らかの効果を発揮するためには、サーバとフレームワークの作者およびメンテナーが、実際に WSGI を実装する必要がある。
However, since no existing servers or frameworks support WSGI, there is little immediate reward for an author who implements WSGI support. Thus, WSGI must be easy to implement, so that an author's initial investment in the interface can be reasonably low.
しかしながら、今のところ WSGI をサポートする既存のサーバもフレームワークも存在しないので、WSGI サポートを実装する作者に即時の報酬はほとんどない。そのため、作者の初期投資が十分低くなるように、WSGI は実装するのが簡単で なければならない。
Thus, simplicity of implementation on both the server and framework sides of the interface is absolutely critical to the utility of the WSGI interface, and is therefore the principal criterion for any design decisions.
したがって、サーバとフレームワークの両方でインタフェースの実装が簡単であることが WSGI に関する実用性に絶対的に重要であり、そのため、それがあらゆるデザイン決定のための主要な評価基準である。
Note, however, that simplicity of implementation for a framework author is not the same thing as ease of use for a web application author. WSGI presents an absolutely "no frills" interface to the framework author, because bells and whistles like response objects and cookie handling would just get in the way of existing frameworks' handling of these issues. Again, the goal of WSGI is to facilitate easy interconnection of existing servers and applications or frameworks, not to create a new web framework.
しかしながら、フレームワーク作者のための実装の簡単さは、Web アプリケーション作者のための使いやすさと同じものではないことに注意すること。WSGI は、フレームワーク作者に完全に「余計な飾りのない」インタフェースを提示する。なぜなら、レスポンスオブジェクトやクッキーの処理のような付属品は、既存のフレームワークがこれらの課題を取り扱うのを邪魔するものに過ぎないからだ。繰り返すが、WSGI の目標は既存のサーバとアプリケーション/フレームワーク間の連携を手助けすることであり、新しい Web フレームワークを作ることではない。
Note also that this goal precludes WSGI from requiring anything that is not already available in deployed versions of Python. Therefore, new standard library modules are not proposed or required by this specification, and nothing in WSGI requires a Python version greater than 2.2.2. (It would be a good idea, however, for future versions of Python to include support for this interface in web servers provided by the standard library.)
また、この目標によって、WSGI が Python の配布バージョンでまだ利用可能でない何かを要求することが排除されるということに注意すること。したがって、この仕様によって新しい標準のライブラリモジュールが提案されるわけではないし、または必要とされることもない。そして、WSGI の中で、Python 2.2.2 以上のバージョンを必要としない。 (しかしながら、Python の将来のバージョンで、標準のライブラリによって提供される Web サーバーにこのインタフェースのサポートを含めるのは良いアイデアだろう。)
In addition to ease of implementation for existing and future frameworks and servers, it should also be easy to create request preprocessors, response postprocessors, and other WSGI-based "middleware" components that look like an application to their containing server, while acting as a server for their contained applications.
既存のまたは将来のフレームワークとサーバにとって実装が容易であることに加えて、リクエストのプリプロセッサやレスポンスのポストプロセッサ、その他の WSGI ベースの「ミドルウェア」コンポーネント（サーバに対してはアプリケーションのように見える一方で、アプリケーションのためにはサーバとして機能する）を作成するのも簡単であるべきである。
If middleware can be both simple and robust, and WSGI is widely available in servers and frameworks, it allows for the possibility of an entirely new kind of Python web application framework: one consisting of loosely-coupled WSGI middleware components. Indeed, existing framework authors may even choose to refactor their frameworks' existing services to be provided in this way, becoming more like libraries used with WSGI, and less like monolithic frameworks. This would then allow application developers to choose "best-of-breed" components for specific functionality, rather than having to commit to all the pros and cons of a single framework.
もしミドルウェアが簡単でかつ強健であるなら、そして WSGI がサーバとフレームワークで広く利用可能であるなら、完全に新しい種類の Python Web アプリケーションフレームワークをもたらす可能性がある: それは、緩く結合した WSGI ミドルウェアの部品から構成される Web アプリケーションフレームワークである。実際、既存のフレームワーク作者は彼らのフレームワークの既存のサービスを、一枚岩的なフレームワークというよりこのような WSGI と共に使用されるライブラリのような方法で提供するためにリファクタリングすることを選ぶかもしれない。そうなれば、アプリケーション開発者は、単一のフレームワークのすべての良い点と悪い点に力を注がなければならないというより、むしろ特定の機能性のための「最善の組み合わせの」コンポーネントを選ぶようになるだろう。
Of course, as of this writing, that day is doubtless quite far off. In the meantime, it is a sufficient short-term goal for WSGI to enable the use of any framework with any server.
もちろん、これを書いている現在、そのような日は遥か先のことに違いない。差し当たりは、あらゆるサーバ、あらゆるフレームワークで WSGI が使用できるようにすることが短期的目標である。
Finally, it should be mentioned that the current version of WSGI does not prescribe any particular mechanism for "deploying" an application for use with a web server or server gateway. At the present time, this is necessarily implementation-defined by the server or gateway. After a sufficient number of servers and frameworks have implemented WSGI to provide field experience with varying deployment requirements, it may make sense to create another PEP, describing a deployment standard for WSGI servers and application frameworks.
最後に、現在の WSGI ではアプリケーションを Web サーバーまたはサーバゲートウェイと共に使用するために「配布する」特定のメカニズムは定めないということが言及されるべきである。現在では、これは必ずサーバまたはゲートウェイによって実装で定義されている。十分な数のサーバとフレームワークが WSGI を実装し、異なった配布要件を持つ実地経験が提供されるようになった後で、WSGI サーバとアプリケーションフレームワークの配布仕様について説明する別の PEP を作成することは価値があるだろう。
Specification Overview
仕様の概要
The WSGI interface has two sides: the "server" or "gateway" side, and the "application" or "framework" side. The server side invokes a callable object that is provided by the application side. The specifics of how that object is provided are up to the server or gateway. It is assumed that some servers or gateways will require an application's deployer to write a short script to create an instance of the server or gateway, and supply it with the application object. Other servers and gateways may use configuration files or other mechanisms to specify where an application object should be imported from, or otherwise obtained.
WSGI インタフェースには、2 つの側面がある: 「サーバ」または「ゲートウェイ」サイドと、「アプリケーション」または「フレームワーク」サイド。サーバサイドはアプリケーションサイドによって提供される callable オブジェクトを呼び出す。そのオブジェクトをどのように提供するかに関する詳細は、サーバやゲートウェイによって異なる。ある種のサーバまたはゲートウェイは、アプリケーションの提供者がサーバまたはゲートウェイのインスタンスを作成し、そのインスタンスにアプリケーションオブジェクトを提供するための短いスクリプトを書くことを要求するだろう。他のサーバまたはゲートウェイは、アプリケーションオブジェクトがどこからインポートされるべきであるか、または別の方法で得られるかを指定するために、設定ファイルや他の仕組みを使用するかもしれない。
In addition to "pure" servers/gateways and applications/frameworks, it is also possible to create "middleware" components that implement both sides of this specification. Such components act as an application to their containing server, and as a server to a contained application, and can be used to provide extended APIs, content transformation, navigation, and other useful functions.
また、「純粋な」サーバ/ゲートウェイとアプリケーション/フレームワークに加えて、この仕様の両方の側面を実装する「ミドルウェア」コンポーネントを作成することもできる。そのようなコンポーネントは、サーバに対してはアプリケーションとして機能すると同時にアプリケーションに対してはサーバとして機能して、拡張 API、コンテンツ変換、ナビゲーション、および他の有用な機能を提供するために使用することができる。
Throughout this specification, we will use the term "a callable" to mean "a function, method, class, or an instance with a __call__ method". It is up to the server, gateway, or application implementing the callable to choose the appropriate implementation technique for their needs. Conversely, a server, gateway, or application that is invoking a callable must not have any dependency on what kind of callable was provided to it. Callables are only to be called, not introspected upon.
この仕様の全体を通して、「callable」という用語を、「関数、メソッド、クラス、または __call__ メソッドを持つインスタンス」という意味で用いる。callable を実装するサーバ、ゲートウェイ、またはアプリケーションは、必要に応じて適切な実装のテクニックを選ぶことができる。逆に、callable を呼び出すサーバ、ゲートウェイ、またはアプリケーションは、どのような callable が提供されるかということに依存 してはならない。callable は呼び出されるためだけに存在し、その中身を調べるものではない。
The Application/Framework Side
アプリケーション/フレームワークサイド
The application object is simply a callable object that accepts two arguments. The term "object" should not be misconstrued as requiring an actual object instance: a function, method, class, or instance with a __call__ method are all acceptable for use as an application object. Application objects must be able to be invoked more than once, as virtually all servers/gateways (other than CGI) will make such repeated requests.
アプリケーションオブジェクトは、単に 2つの引数を受け付ける callable オブジェクトである。「オブジェクト」という用語によって、実際のオブジェクトインスタンスが必要であると誤解するべきではない: 関数、メソッド、クラス、または __call__ メソッドを持つインスタンスであれば、すべてアプリケーションオブジェクトとして使用することが許容される。アプリケーションオブジェクトは 1回以上呼び出すことができなければならない。ほとんどすべてのサーバ/ゲートウェイ (CGI を除く) がそのような繰り返された要求をする。
(Note: although we refer to it as an "application" object, this should not be construed to mean that application developers will use WSGI as a web programming API! It is assumed that application developers will continue to use existing, high-level framework services to develop their applications. WSGI is a tool for framework and server developers, and is not intended to directly support application developers.)
(注意: ここでは「アプリケーション」オブジェクトと呼んでいるが、アプリケーション開発者が WSGI を Web プログラミング API として使用するという意味でこれを解釈すべきではない! アプリケーション開発者は、彼らのアプリケーションを開発するのに、既存のハイレベルなフレームワークサービスを利用し続けると思われる。WSGI はフレームワークとサーバ開発者のためのツールであり、直接アプリケーション開発者をサポートすることを意図していない。)
Here are two example application objects; one is a function, and the other is a class:
ここに、2 つのアプリケーションオブジェクトの例がある; 1つは関数であり、もう片方がクラスである:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32 | 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!\n']
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!\n"
|
The Server/Gateway Side
サーバー/ゲートウェイサイド
The server or gateway invokes the application callable once for each request it receives from an HTTP client, that is directed at the application. To illustrate, here is a simple CGI gateway, implemented as a function taking an application object. Note that this simple example has limited error handling, because by default an uncaught exception will be dumped to sys.stderr and logged by the web server.
アプリケーションに対して HTTP クライアントから要求があると、サーバやゲートウェイは、アプリケーション callable を呼び出す。例として、ここではアプリケーションオブジェクトを受け取る関数として実装された簡単な CGI ゲートウェイを示す。この簡単な例ではエラー処理を省いていることに注意すること。デフォルトでは捕捉されなかった例外は sys.stderr に出力され、Web サーバーのログに記録される。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59 | import os, sys
def run_with_cgi(application):
environ = dict(os.environ.items())
environ['wsgi.input'] = sys.stdin
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):
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
sys.stdout.write('Status: %s\r\n' % status)
for header in response_headers:
sys.stdout.write('%s: %s\r\n' % header)
sys.stdout.write('\r\n')
sys.stdout.write(data)
sys.stdout.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[0], exc_info[1], exc_info[2]
finally:
exc_info = None # avoid dangling circular ref
elif headers_set:
raise AssertionError("Headers already set!")
headers_set[:] = [status,response_headers]
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()
|
Middleware: Components that Play Both Sides
ミドルウェア: 両サイドを演じるコンポーネント
Note that a single object may play the role of a server with respect to some application(s), while also acting as an application with respect to some server(s). Such "middleware" components can perform such functions as:
単一のオブジェクトが何らかのアプリケーションに関してサーバの役割を果たす一方で、何らかのサーバに対してアプリケーションとして機能するかもしれないことに注意すること。そのような「ミドルウェア」コンポーネントは、以下のような機能を実行することができる:
- Routing a request to different application objects based on the target URL, after rewriting the environ accordingly.
- Allowing multiple applications or frameworks to run side-by-side in the same process
- Load balancing and remote processing, by forwarding requests and responses over a network
- Perform content postprocessing, such as applying XSL stylesheets
- 異なるアプリケーションオブジェクトへの要求を、適宜 environ を書き換えた後で目標 URL に応じてルーティングする
- 複数のアプリケーションまたはフレームワークが同じプロセス内で並列に稼働できるようにする
- リクエストとレスポンスをネットワークの上に転送することによって、負荷バランスとリモート処理を行う
- XSL スタイルシートの適用など、コンテンツのポストプロセスを行う
The presence of middleware in general is transparent to both the "server/gateway" and the "application/framework" sides of the interface, and should require no special support. A user who desires to incorporate middleware into an application simply provides the middleware component to the server, as if it were an application, and configures the middleware component to invoke the application, as if the middleware component were a server. Of course, the "application" that the middleware wraps may in fact be another middleware component wrapping another application, and so on, creating what is referred to as a "middleware stack".
一般に、ミドルウェアの存在は、インタフェースの「サーバ/ゲートウェイ」サイドと「アプリケーション/フレームワーク」サイドの両方に透明であり、どんな特別なサポートも必要とするべきではない。ミドルウェアをアプリケーションに組み入れることを望んでいるユーザは、単にミドルウェアコンポーネントを、あたかもそれがアプリケーションであるかのようにサーバに提供する。そして、ミドルウェアコンポーネントがサーバであるかのように、アプリケーションを呼び出すように設定する。もちろん、ミドルウェアがラップする「アプリケーション」は、実際には別のアプリケーションなどをラップする別のミドルウェアコンポーネントであるかもしれない。それは「ミドルウェアスタック」と呼ばれるものを作成する。
For the most part, middleware must conform to the restrictions and requirements of both the server and application sides of WSGI. In some cases, however, requirements for middleware are more stringent than for a "pure" server or application, and these points will be noted in the specification.
ほとんどの部分で、ミドルウェアは WSGI のサーバとアプリケーションの両サイドの制限と要件に従わなければならない。しかしながら、いくつかの場合、ミドルウェアのための要件は「純粋な」サーバやアプリケーションより厳しい。これらのポイントは仕様で述べられる。
Here is a (tongue-in-cheek) example of a middleware component that converts text/plain responses to pig latin, using Joe Strout's piglatin.py. (Note: a "real" middleware component would probably use a more robust way of checking the content type, and should also check for a content encoding. Also, this simple example ignores the possibility that a word might be split across a block boundary.)
これは、Joe Strout の piglatin.py を使用して、text/plain レスポンスから偽ラテン語に変換する、(tongue-in-cheek; 冗談) ミドルウェアコンポーネントの例である。 (注意: 「本物」のミドルウェアコンポーネントは、おそらく content type をチェックするためにより強健な方法を使用する。また、content encoding もチェックすべきである。また、この簡単な例では、単語がブロック境界を越えて分割される可能性を無視している。)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67 | 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 string, 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())
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
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))
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))
|
Specification Details
仕様の詳細
The application object must accept two positional arguments. For the sake of illustration, we have named them environ and start_response, but they are not required to have these names. A server or gateway must invoke the application object using positional (not keyword) arguments. (E.g. by calling result = application(environ,start_response) as shown above.)
アプリケーションオブジェクトは 2つの固定引数を受け付けなければならない。例証のために、それらを environ と start_response と名付けるが、これらの名前を持つ必要はない。サーバまたはゲートウェイは、固定引数 (キーワード引数ではなく) を使用してアプリケーションオブジェクトを呼び出さ なければならない。 (例えば、上に示されるように、result = application(environ, start_response) のようにして呼び出す)
The environ parameter is a dictionary object, containing CGI-style environment variables. This object must be a builtin Python dictionary (not a subclass, UserDict or other dictionary emulation), and the application is allowed to modify the dictionary in any way it desires. The dictionary must also include certain WSGI-required variables (described in a later section), and may also include server-specific extension variables, named according to a convention that will be described below.
environ パラメータは、CGI スタイルの環境変数を含む辞書オブジェクトである。このオブジェクトは、builtin の Python 辞書で なければならない (サブクラス、UserDict、または他の辞書エミュレーションでは ない)、そしてアプリケーションは好きなように辞書を変更することができる。辞書は、また、いくつかの WSGI 必須の変数 (後のセクションで説明される) を含まなければならず、また、以下で説明される規約に従って命名される、サーバ特有の拡張変数を含むことができる。
The start_response parameter is a callable accepting two required positional arguments, and one optional argument. For the sake of illustration, we have named these arguments status, response_headers, and exc_info, but they are not required to have these names, and the application must invoke the start_response callable using positional arguments (e.g. start_response(status, response_headers)).
start_response パラメータは、2 つの必須の固定引数、および 1つの任意引数を受け付ける callable である。例証のためにこれらの引数を status、response_headers、および exc_info と命名したが、それらの引数は必ずしもこのような名前である必要はなく、アプリケーションは固定引数を使用して start_response callable を呼び出さ なければならない (例えば、start_response(status, response_headers))。
The status parameter is a status string of the form "999 Message here", and response_headers is a list of (header_name,header_value) tuples describing the HTTP response header. The optional exc_info parameter is described below in the sections on The start_response() Callable and Error Handling. It is used only when the application has trapped an error and is attempting to display an error message to the browser.
status パラメータは "999 Message here" 形式の状態文字列であり、response_headers は HTTP 応答ヘッダーについて記述する (header_name, header_value) タプルのリストである。任意の exc_info パラメタについては、以下の"The start_response() Callable" セクションと "Error Handling" セクションで説明される。それが使用されるのは、アプリケーションがエラーを捕捉し、ブラウザへエラーメッセージを表示しようとしたときだけである。
The start_response callable must return a write(body_data) callable that takes one positional parameter: a string to be written as part of the HTTP response body. (Note: the write() callable is provided only to support certain existing frameworks' imperative output APIs; it should not be used by new applications or frameworks if it can be avoided. See the Buffering and Streaming section for more details.)
start_response callable は、write(body_data) callable を返さなければならない。write callable は 1つの固定パラメータを取る: HTTP レスポンス本体の一部として書かれるべき文字列。 (注意: write() callable は、いくつかの既存のフレームワークで必須の出力 API をサポートするためだけに提供されている; 避けることができるなら、新しいアプリケーションまたはフレームワークはそれを使用するべきではない。その他の詳細に関しては、"Buffering and Streaming" セクションを参照。)
When called by the server, the application object must return an iterable yielding zero or more strings. This can be accomplished in a variety of ways, such as by returning a list of strings, or by the application being a generator function that yields strings, or by the application being a class whose instances are iterable. Regardless of how it is accomplished, the application object must always return an iterable yielding zero or more strings.
アプリケーションオブジェクトは、サーバによって呼ばれると、文字列を yield する iterable を返さなければならない。これは、様々な方法で実現することができる。例えば、文字列のリストを返すようにする、アプリケーションをジェネレータ関数にしてその関数が文字列を yield するようにする、アプリケーションをクラスにしてそのインスタンスが iterable であるようにする、といったような方法である。それがどのように実現されているかにかかわらず、アプリケーションオブジェクトはいつも文字列を yield する iterable を返さなければならない。
The server or gateway must transmit the yielded strings to the client in an unbuffered fashion, completing the transmission of each string before requesting another one. (In other words, applications should perform their own buffering. See the Buffering and Streaming section below for more on how application output must be handled.)
サーバまたはゲートウェイは、yield された文字列を非バッファリング形式でクライアントに伝えなければならない。それぞれの文字列の伝達を、別の 1つを要求する前に終了する。 (言い換えれば、アプリケーションは自身のバッファリングを実行 すべきである。アプリケーション出力をどのように扱わなければならないかに関して詳しくは、以下の "Buffering and Streaming" セクションを参照。)
The server or gateway should treat the yielded strings as binary byte sequences: in particular, it should ensure that line endings are not altered. The application is responsible for ensuring that the string(s) to be written are in a format suitable for the client. (The server or gateway may apply HTTP transfer encodings, or perform other transformations for the purpose of implementing HTTP features such as byte-range transmission. See Other HTTP Features, below, for more details.)
サーバまたはゲートウェイは、yield された文字列をバイナリのバイト列として扱うべきである: 特に、行末の文字が変更されないことを保証しなければならない。出力される文字列がクライアントに適当な形式であることを保証するのは、アプリケーションの責任である。 (サーバまたはゲートウェイは、HTTP transfer encoding を適用したり、またはバイト範囲送信などの HTTP 機能を実行する目的のために他の変更を実行 してもよい。その他の詳細に関して以下の "Other HTTP Features" を参照。)
If a call to len(iterable) succeeds, the server must be able to rely on the result being accurate. That is, if the iterable returned by the application provides a working __len__() method, it must return an accurate result. (See the Handling the Content-Length Header section for information on how this would normally be used.)
len(iterable) に対する呼び出しが成功する場合、サーバはその結果が正確であることを信頼できなければならない。すなわち、アプリケーションで返された iterable が正常に機能する __len__() メソッドを提供するなら、それは正確な結果を返さ なければならない。 (通常これがどのように使用されるかに関する情報は、"Handling Content-Length Header" セクションを参照)
If the iterable returned by the application has a close() method, the server or gateway must call that method upon completion of the current request, whether the request was completed normally, or terminated early due to an error. (This is to support resource release by the application. This protocol is intended to complement PEP 325
's generator support, and other common iterables with close() methods.
もし、アプリケーションで返された iterable が close() メソッドを持っているなら、サーバまたはゲートウェイは、現在のリクエストが完了するときにそのメソッドを呼ば なければならない。これは、リクエストが正常に処理されたか、またはエラーのために途中で停止されたかに関わらず行われる。 (これは、アプリケーションによるリソース解放をサポートするためのものである。このプロトコルは、PEP 325 のジェネレータサポート、および close() メソッドを持つ他の一般的な iterable の補完となることを意図している)
(Note: the application must invoke the start_response() callable before the iterable yields its first body string, so that the server can send the headers before any body content. However, this invocation may be performed by the iterable's first iteration, so servers must not assume that start_response() has been called before they begin iterating over the iterable.)
(Note: アプリケーションは、サーバがあらゆる body content の前にヘッダーを送ることができるように、iterable が最初の body 文字列を yield する前に start_response() callable を呼び出さ なければならない。しかし、この呼び出しが iterable の最初のイテレーションの際に実行 されてもよい ので、サーバは、iterable 上でイテレーションを始める前に start_response() が呼ばれたと仮定 してはならない。)
Finally, servers and gateways must not directly use any other attributes of the iterable returned by the application, unless it is an instance of a type specific to that server or gateway, such as a "file wrapper" returned by wsgi.file_wrapper (see Optional Platform-Specific File Handling). In the general case, only attributes specified here, or accessed via e.g. the PEP 234 iteration APIs are acceptable.
最後に、サーバとゲートウェイは、アプリケーションから返された iterable の他のいかなる属性も直接使用 してはならない。例外は、wsgi.file_wrapper によって返された「ファイルラッパー」などのように、iterable がそのサーバまたはゲートウェイに特定の型のインスタンスである場合である ("Optional Platform-Specific File Handling" を参照)。一般的なケースでは、ここで明記された属性か、または例えば PEP 234 の iteration API を通して属性にアクセスすることだけが許容される。
environ Variables
environ 変数
The environ dictionary is required to contain these CGI environment variables, as defined by the Common Gateway Interface specification [2]. The following variables must be present, unless their value would be an empty string, in which case they may be omitted, except as otherwise noted below.
environ 辞書は、Common Gateway Interface 仕様 [2] で定義されるように、これらの CGI 環境変数を含まなければならない。以下の変数は存在 しなければならない が、それらの値が空の文字列である場合は、以下に述べられる例外を除き、省略 してもよい。
- 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」に一致しているなら、これは空の文字列 でもよい。
- 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 がアプリケーションルートを対象としていて、終端のスラッシュを持っていないなら。これは空の文字列 でもよい。
- 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 variables 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 を完成するのにこれらの変数を使用することができる。しかし、もし存在しているなら 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 ヘッダが存在するかどうかに対応するべきである。
A server or gateway should attempt to provide as many other CGI variables as are applicable. In addition, if SSL is in use, the server or gateway should also provide as many of the Apache SSL environment variables [5] as are applicable, such as HTTPS=on and SSL_PROTOCOL. Note, however, that an application that uses any CGI variables other than the ones listed above are necessarily non-portable to web servers that do not support the relevant extensions. (For example, web servers that do not publish files will not be able to provide a meaningful DOCUMENT_ROOT or PATH_TRANSLATED.)
サーバまたはゲートウェイは、他の CGI 変数に関しても適切なものはできるだけ多く提供しようと努力 すべきである。加えて、SSL が使用中なら、サーバまたはゲートウェイは Apache SSL 環境変数 [5] のうち適切なものはできるだけ多く提供 すべきである。例えば、HTTPS=on や SSL_PROTOCOL など。しかし、上に記載された以外の CGI 変数を使用するアプリケーションは、関連する拡張をサポートしない Web サーバーに必ずしも移植可能でないことに注意。 (例えば、ファイルを出力しない Web サーバーは、意味のある DOCUMENT_ROOT や PATH_TRANSLATED を提供することができないだろう。)
A WSGI-compliant server or gateway should document what variables it provides, along with their definitions as appropriate. Applications should check for the presence of any variables they require, and have a fallback plan in the event such a variable is absent.
WSGI 対応のサーバまたはゲートウェイは、どんな変数を提供するかをその定義と共に適切に文書化 すべきである。アプリケーションは、必要とする変数が存在するかどうかをチェック すべきである。そして、そのような変数が存在しない場合の fallback プランを持つ べきである。
Note: missing variables (such as REMOTE_USER when no authentication has occurred) should be left out of the environ dictionary. Also note that CGI-defined variables must be strings, if they are present at all. It is a violation of this specification for a CGI variable's value to be of any type other than str.
注意: 欠けている変数 (認証が行われていない場合の REMOTE_USER など) は、environ 辞書からは除かれるべきである。また、CGI 定義変数は、もし存在するなら文字列でなければならないことに注意。CGI 変数の値が str 以外のどんな型であっても、この仕様に対する違反である。
In addition to the CGI-defined variables, the environ dictionary may also contain arbitrary operating-system "environment variables", and must contain the following WSGI-defined variables:
CGI 定義変数に加えて、environ 辞書は、任意の OS「環境変数」を含ん でもよい。そして、以下の WSGI 定義変数を含ま なければならない:
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 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" を使用して、それがサーバ/ゲートウェイによって正しい行末端に変換されると仮定すべきである。
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 になるだろう。
|
Finally, the environ dictionary may also contain server-defined variables. These variables should be named using only lower-case letters, numbers, dots, and underscores, and should be prefixed with a name that is unique to the defining server or gateway. For example, mod_python might define variables with names like mod_python.some_variable.
最後に、environ 辞書はサーバ定義変数を含んでもよい。これらの変数は、アルファベット小文字、数字、ドット、およびアンダースコアだけを使用して命名されるべきである。そしてそれを定義するサーバまたはゲートウェイにユニークな名前をプリフィックスとして付加すべきである。例えば、mod_python は mod_python.some_valiable のような名前で変数を定義するだろう。
Input and Error Streams
入出力ストリーム
The input and error streams provided by the server must support the following methods:
サーバによって提供された入力およびエラーストリームは、以下のメソッドをサポートしなければならない:
| 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 |
|
The semantics of each method are as documented in the Python Library Reference, except for these notes as listed in the table above:
それぞれのメソッドの意味は、上の表にリストアップされている注記を例外として、Python Library Reference の中で以下のように文書化されている:
1. The server is not required to read past the client's specified Content-Length, and is allowed to simulate an end-of-file condition if the application attempts to read past that point. The application should not attempt to read more data than is specified by the CONTENT_LENGTH variable.
サーバは、クライアントの指定した Content-Length を越えて読み出す必要はなく、アプリケーションがそのポイントを越えて読み出そうとした場合に、end-of-file 状態をシミュレートすることが許される。アプリケーションは、CONTENT_LENGTH 変数によって指定されるより多くのデータを読み出そうと すべきでない。
2. The optional "size" argument to readline() is not supported, as it may be complex for server authors to implement, and is not often used in practice.
readline() への任意の「サイズ」引数はサポートされない。なぜなら、それはサーバ作者が実装するには複雑で、しかも実際にはしばしば使用されないためだ。
3. Note that the hint argument to readlines() is optional for both caller and implementer. The application is free not to supply it, and the server or gateway is free to ignore it.
readlines() への hint 引数は、それを呼ぶ側と実装する側の両方に対して任意であることに注意。アプリケーションがそれを提供しないのは自由であり、そしてサーバまたはゲートウェイは自由にそれを無視することができる。
4. Since the errors stream may not be rewound, servers and gateways are free to forward write operations immediately, without buffering. In this case, the flush() method may be a no-op. Portable applications, however, cannot assume that output is unbuffered or that flush() is a no-op. They must call flush() if they need to ensure that output has in fact been written. (For example, to minimize intermingling of data from multiple processes writing to the same error log.)
errors ストリームは巻き戻されないので、サーバやゲートウェイは書き込み操作をバッファリングなしで即座に進めることができる。この場合、flush() メソッドは no-op かもしれない。しかし、移植性のあるアプリケーションでは、出力がバッファリングされないことや、flush() が no-op であることを仮定することはできない。出力が実際に書かれていることを保証する必要があるなら、flush() を呼ばなければならない。 (例えば、同じエラーログに書いている複数のプロセスから、データの混り合いを最小にするために。)
The methods listed in the table above must be supported by all servers conforming to this specification. Applications conforming to this specification must not use any other methods or attributes of the input or errors objects. In particular, applications must not attempt to close these streams, even if they possess close() methods.
上の表に記載されたメソッドは、この仕様に従うすべてのサーバでサポートされ なければならない。この仕様に従うアプリケーションは、input または errors オブジェクトのいかなる他のメソッドまたは属性も使用 してはならない。特に、それらが close() メソッドを持っていても、アプリケーションはこれらのストリームを閉じようと してはならない。
start_response() Callable
The second parameter passed to the application object is a callable of the form start_response(status, response_headers, exc_info=None). (As with all WSGI callables, the arguments must be supplied positionally, not by keyword.) The start_response callable is used to begin the HTTP response, and it must return a write(body_data) callable (see the Buffering and Streaming section, below).
アプリケーションオブジェクトに渡された 2番目のパラメータは、start_response(status, response_headers, exc_info=None) 形式の callable である (すべての WSGI callables と同様、引数はキーワード引数ではなく固定引数で提供されなければならない)。start_response callable は、HTTP レスポンスを開始するために使用される。そして、それは write(body_data) callable を返さなければならない。 (以下の "Buffering and Streaming" セクションを参照)。
The status argument is an HTTP "status" string like "200 OK" or "404 Not Found". That is, it is a string consisting of a Status-Code and a Reason-Phrase, in that order and separated by a single space, with no surrounding whitespace or other characters. (See RFC 2616, Section 6.1.1 for more information.) The string must not contain control characters, and must not be terminated with a carriage return, linefeed, or combination thereof.
status 引数は、"200 OK" や "404 Not Found" のような、HTTP 「状態」文字列である。すなわち、それは Status-Code と Reason-Phrase をこの順番で含む文字列で、シングルスペースによって分離され、全体を囲む空白または他の文字列を持たない (詳しい情報に関しては RFC 2616 セクション 6.1.1 を参照)。その文字列は、制御文字を含んでは ならない。また、復帰、ラインフィード、またはそれらの組み合わせで終わってはならない。
The response_headers argument is a list of (header_name, header_value) tuples. It must be a Python list; i.e. type(response_headers) is ListType, and the server may change its contents in any way it desires. Each header_name must be a valid HTTP header field-name (as defined by RFC 2616, Section 4.2), without a trailing colon or other punctuation.
response_headers 引数は、(header_name、header_value) タプルのリストである。それは Python リストでなければならない; すなわち、type(response_headers) は ListType である。そして、サーバはその内容を自由に変更 してもよい。各 header_name は有効な HTTP ヘッダフィールド名 (RFC 2616 セクション 4.2 によって定義されるように) でなければならず、末尾のコロンも他の記号も含まない。
Each header_value must not include any control characters, including carriage returns or linefeeds, either embedded or at the end. (These requirements are to minimize the complexity of any parsing that must be performed by servers, gateways, and intermediate response processors that need to inspect or modify response headers.)
各 header_value は、復帰またはラインフィードを含むどんな制御文字も、埋め込まれているか末尾かどうかに関わらず、含んでは ならない。 (これらの要件は、サーバ、ゲートウェイ、およびレスポンスヘッダーを inspect または変更する必要のある中間的レスポンス・プロセッサで実行しなければならない構文解析の複雑さを最小にするためである。)
In general, the server or gateway is responsible for ensuring that correct headers are sent to the client: if the application omits a header required by HTTP (or other relevant specifications that are in effect), the server or gateway must add it. For example, the HTTP Date: and Server: headers would normally be supplied by the server or gateway.
一般に、サーバまたはゲートウェイは、正しいヘッダーが確実にクライアントに送られることに対する責任を負う: もしアプリケーションが HTTP (あるいは効力を持った関連する他の仕様) によって必要とされるヘッダーを省略するなら、サーバまたはゲートウェイがそれを加え なければならない。例えば、HTTP Date: や Server: ヘッダーは、通常、サーバまたはゲートウェイによって提供されるだろう。
(A reminder for server/gateway authors: HTTP header names are case-insensitive, so be sure to take that into consideration when examining application-supplied headers!)
(サーバ/ゲートウェイ作者のためのリマインダー: HTTP ヘッダ名は文字の大小を区別しないので、アプリケーションで供給されたヘッダーを調べるとき、それを必ず考慮に入れること!)
Applications and middleware are forbidden from using HTTP/1.1 "hop-by-hop" features or headers, any equivalent features in HTTP/1.0, or any headers that would affect the persistence of the client's connection to the web server. These features are the exclusive province of the actual web server, and a server or gateway should consider it a fatal error for an application to attempt sending them, and raise an error if they are supplied to start_response(). (For more specifics on "hop-by-hop" features and headers, please see the Other HTTP Features section below.)
アプリケーションとミドルウェアは、HTTP/1.1 の"hop-by-hop"機能またはヘッダーや、HTTP/1.0 における同等の機能や、あるいはクライアントから Web サーバーへの接続の永続性に影響するどんなヘッダーも、使用することは禁止される。これらの機能は、本物の Web サーバーに排他的な領域である。サーバあるいはゲートウェイは、アプリケーションがそれらを送ろうとすることは致命的なエラーであるとみなし、それらが start_response() に提供された場合、エラーを raise すべきである。 (「hop-by-hop」の機能とヘッダーに関してより多くの詳細は、以下の "Other HTTP Features" セクションを参照。)
The start_response callable must not actually transmit the response headers. Instead, it must store them for the server or gateway to transmit only after the first iteration of the application return value that yields a non-empty string, or upon the application's first invocation of the write() callable. In other words, response headers must not be sent until there is actual body data available, or until the application's returned iterable is exhausted. (The only possible exception to this rule is if the response headers explicitly include a Content-Length of zero.)
start_response callable は、実際にレスポンスヘッダーを送信 してはならない。代わりに、空でない文字列を yield するアプリケーション戻り値の最初の繰り返しの後か、アプリケーションの write() callable の最初の呼び出しの時に だけ 送信するように、レスポンスヘッダをサーバまたはゲートウェイに格納しなければならない。言い換えれば、実際のボディーデータが利用可能になるか、またはアプリケーションの返された iterable が消費されるまで、レスポンスヘッダーを送ってはならない。 (この規則に対する可能な唯一の例外は、レスポンスヘッダーが明示的に 0 の Content-Length を含む場合である。)
This delaying of response header transmission is to ensure that buffered and asynchronous applications can replace their originally intended output with error output, up until the last possible moment. For example, the application may need to change the response status from "200 OK" to "500 Internal Error", if an error occurs while the body is being generated within an application buffer.
レスポンスヘッダー送信のこの遅延は、バッファリングされる非同期なアプリケーションが、元々意図された出力をエラー出力に取り替えることが最後の可能な瞬間までできることを保証するためである。例えば、アプリケーションバッファの中でボディーが生成されている間にエラーが発生するなら、アプリケーションは、レスポンスステータスを「200 OK」から「500 Internal Error」に変える必要があるかもしれない。
The exc_info argument, if supplied, must be a Python sys.exc_info() tuple. This argument should be supplied by the application only if start_response is being called by an error handler. If exc_info is supplied, and no HTTP headers have been output yet, start_response should replace the currently-stored HTTP response headers with the newly-supplied ones, thus allowing the application to "change its mind" about the output when an error has occurred.
exc_info 引数は、もし提供されるなら Python の sys.exc_info() タプルでなければならない。アプリケーションは、エラーハンドラが start_response を呼んでいる場合にだけ、この引数を供給するべきである。もし exc_info が提供されていて、まだ何も HTTP ヘッダが出力されていないなら、start_response は、現在格納された HTTP レスポンスヘッダーを新たに提供されたものに置き換えるべきである。その結果、エラーが発生したときにアプリケーションが出力に関して「気が変わる」ことを許容する。
However, if exc_info is provided, and the HTTP headers have already been sent, start_response must raise an error, and should raise the exc_info tuple. That is:
しかし、exc_info が提供されていて、HTTP ヘッダを既に送った後なら、start_response は、エラーを raise しなければならず、exc_info タプルを raise すべきである。以下のように:
1 | raise exc_info[0], exc_info[1], exc_info[2]
|
This will re-raise the exception trapped by the application, and in principle should abort the application. (It is not safe for the application to attempt error output to the browser once the HTTP headers have already been sent.) The application must not trap any exceptions raised by start_response, if it called start_response with exc_info. Instead, it should allow such exceptions to propagate back to the server or gateway. See Error Handling below, for more details.
これは、アプリケーションで捕捉された例外を再び送出する。そして原則としてアプリケーションを中止すべきである。 (いったん HTTP ヘッダを送ると、アプリケーションがブラウザにエラー出力を試みるのは、安全ではない。) アプリケーションは、exc_info を用いて start_response を呼んだ場合、start_response で発生したどんな例外も捕捉 してはならない。代わりに、そのような例外がサーバまたはゲートウェイに逆伝播することを許すべきである。その他の詳細に関して、以下の "Error Handling" を参照。
The application may call start_response more than once, if and only if the exc_info argument is provided. More precisely, it is a fatal error to call start_response without the exc_info argument if start_response has already been called within the current invocation of the application. (See the example CGI gateway above for an illustration of the correct logic.)
アプリケーションは、exc_info 引数が提供される場合にだけ、start_response を複数回呼ん でもよい。より正確には、アプリケーションの現在の呼び出しの中で既に start_response が呼ばれたなら、exc_info 引数なしで start_response を呼ぶのは、致命的なエラーである。 (正しい論理の例証のために、上の CGI ゲートウェイの例を参照。)
Note: servers, gateways, or middleware implementing start_response should ensure that no refere
