PEP:            333
Title:          Python Web Server Gateway Interface v1.0
Version:        43603
Last-Modified:  2006-04-03 21:07:07 +0200 (Mon, 03 Apr 2006)
Author:         Phillip J. Eby <pje at telecommunity.com>
Discussions-To: Python Web-SIG <web-sig at python.org>
Status:         Draft
Type:           Informational
Content-Type:   text/x-rst
Created:        07-Dec-2003
Post-History:   07-Dec-2003, 08-Aug-2004, 20-Aug-2004, 27-Aug-2004

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 定義変数を含ま なければならない:

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:

サーバによって提供された入力およびエラーストリームは、以下のメソッドをサポートしなければならない:

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 reference is held to the exc_info parameter beyond the duration of the function's execution, to avoid creating a circular reference through the traceback and frames involved. The simplest way to do this is something like:

注意: start_response を実装するサーバ、ゲートウェイ、またはミドルウェアは、traceback と巻き込まれたフレームを通して循環参照を作成するのを避けるために、関数の実行の持続時間を超えて exc_info パラメータへの参照を保持しないことを確実に すべきである。これを行う最も簡単な方法は以下のようになる:

1
2
3
4
5
6

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.

The example CGI gateway provides another illustration of this technique.

例の CGI ゲートウェイはこのテクニックの別の例を提供する。

Handling the Content-Length Header

Content-Length ヘッダーの扱い

If the application does not supply a Content-Length header, a server or gateway may choose one of several approaches to handling it. The simplest of these is to close the client connection when the response is completed.

アプリケーションが Content-Length ヘッダーを提供しないなら、サーバまたはゲートウェイは、それを扱うためにいくつかのアプローチの 1つを選んでもよい。最も簡単なのは、レスポンスが終了したときにクライアント接続を閉じることである。

Under some circumstances, however, the server or gateway may be able to either generate a Content-Length header, or at least avoid the need to close the client connection. If the application does not call the write() callable, and returns an iterable whose len() is 1, then the server can automatically determine Content-Length by taking the length of the first string yielded by the iterable.

しかしながら、いくつかの状況では、サーバまたはゲートウェイが Content-Length ヘッダーを生成するか、または少なくともクライアント接続を閉じる必要性を避けることができるかもしれない。アプリケーションが write() callable を呼び出して いなくて、iterable を返し、その len() が 1 である場合、サーバは、iterable によって yield された最初の文字列の長さを取得しながら自動的に Content-Length を決定することができる。

And, if the server and client both support HTTP/1.1 "chunked encoding" [3], then the server may use chunked encoding to send a chunk for each write() call or string yielded by the iterable, thus generating a Content-Length header for each chunk. This allows the server to keep the client connection alive, if it wishes to do so. Note that the server must comply fully with RFC 2616 when doing this, or else fall back to one of the other strategies for dealing with the absence of Content-Length.

そして、サーバとクライアントがともに HTTP/1.1「chunked encoding」をサポートするなら、サーバは各 write() の呼び出しまたは iterable によって yield された文字列のチャンクを送るのに chunked encoding を使用 してもよい。すなわち、チャンク毎に Content-Length ヘッダーを生成する。これによって、サーバはもしそれを望むならクライアント接続を持続できる。これをするとき、サーバが RFC 2616 に完全に従わ なければならない ことに注意。そうでなければ、Content-Length が存在しないことに対処するための他の戦略の 1つに fall back すること。

(Note: applications and middleware must not apply any kind of Transfer-Encoding to their output, such as chunking or gzipping; as "hop-by-hop" operations, these encodings are the province of the actual web server/gateway. See Other HTTP Features below, for more details.)

(注意: アプリケーションおよびミドルウェアは、出力に chunking や gzipping などのどんな種類の Transfer-Encoding も適用 してはならない; 「hop-by-hop」操作と同様に、これらのエンコーディングは本物の Web サーバー/ゲートウェイの領域である。その他の詳細に関しては、以下の "Other HTTP Features" を参照。)

Buffering and Streaming

バッファリングとストリーミング

Generally speaking, applications will achieve the best throughput by buffering their (modestly-sized) output and sending it all at once. This is a common approach in existing frameworks such as Zope: the output is buffered in a StringIO or similar object, then transmitted all at once, along with the response headers.

一般的に、アプリケーションは、自身の (適切なサイズの) 出力をバッファリングして、それを一気に送ることによって、最も良い効率を実現するだろう。これは Zope などの既存のフレームワークで一般的なアプローチである: 出力は StringIO または同様の物でバッファリングされ、次にレスポンスヘッダーと共に一気に送信される。

The corresponding approach in WSGI is for the application to simply return a single-element iterable (such as a list) containing the response body as a single string. This is the recommended approach for the vast majority of application functions, that render HTML pages whose text easily fits in memory.

WSGI における対応するアプローチは、アプリケーションが単に、単一の文字列としてレスポンス本体を含む、ただ 1つの要素の iterable (リストなど) を返すことである。これは、そのテキストが容易にメモリに収まる HTML ページを描画するような、アプリケーション機能のほとんどの部分におけるお勧めのアプローチである。

For large files, however, or for specialized uses of HTTP streaming (such as multipart "server push"), an application may need to provide output in smaller blocks (e.g. to avoid loading a large file into memory). It's also sometimes the case that part of a response may be time-consuming to produce, but it would be useful to send ahead the portion of the response that precedes it.

しかしながら、大きいファイル、または HTTP ストリーミングの特殊な用途 (複合「サーバプッシュ」など) のために、アプリケーションは出力をより小さなブロックに供給する必要があるかもしれない (例えばメモリに大きいファイルをロードすることを避けるため)。また、応答のある部分を生成するのに時間がかかる場合も時々あるが、それに先行するレスポンスの部分を前もって送ることは役に立つだろう。

In these cases, applications will usually return an iterator (often a generator-iterator) that produces the output in a block-by-block fashion. These blocks may be broken to coincide with mulitpart boundaries (for "server push"), or just before time-consuming tasks (such as reading another block of an on-disk file).

これらの場合では、通常、アプリケーションはブロックごとの様式で出力を生成するイテレータ (しばしばジェネレータ・イテレータ) を返すだろう。これらのブロックは、mulitpart 境界 (「サーバプッシュ」のための) や、時間のかかるタスク (ディスクに存在するファイルの別のブロックを読むなど) のすぐ前で分割が起こるかもしれない。

WSGI servers, gateways, and middleware must not delay the transmission of any block; they must either fully transmit the block to the client, or guarantee that they will continue transmission even while the application is producing its next block. A server/gateway or middleware may provide this guarantee in one of three ways:

WSGI サーバ、ゲートウェイ、およびミドルウェアは、どんなブロックの送信も遅延 してはならない; ブロックをクライアントに完全に伝えるか、またはアプリケーションが次のブロックを作り出している間も送信を続けることを保証 しなければならない。サーバ/ゲートウェイまたはミドルウェアは、次の 3つの方法のうちの 1つで、この保証を提供することができる:

1. Send the entire block to the operating system (and request that any O/S buffers be flushed) before returning control to the application, OR

制御をアプリケーションに返す前に、ブロック全体を OS に送る (そして、あらゆる OS バッファが flush されることを要求する)。

2. Use a different thread to ensure that the block continues to be transmitted while the application produces the next block.

別のスレッドを使用して、アプリケーションが次のブロックを作り出している間もブロックの送信が続けられることを保証する。

3. (Middleware only) send the entire block to its parent gateway/server

(ミドルウェアのみ) ブロック全体を、親のゲートウェイまたはサーバに送る

By providing this guarantee, WSGI allows applications to ensure that transmission will not become stalled at an arbitrary point in their output data. This is critical for proper functioning of e.g. multipart "server push" streaming, where data between multipart boundaries should be transmitted in full to the client.

この保証を提供することによって、WSGI は送信が出力データの任意のポイントで中断しないことをアプリケーションが保証することを可能にする。適切な機能にとって、これは重要である。例えば、複合「サーバプッシュ」ストリーミングでは、複合境界の間のデータはクライアントにすべて送られなければならない。

Middleware Handling of Block Boundaries

ブロック境界を扱うミドルウェア

In order to better support asynchronous applications and servers, middleware components must not block iteration waiting for multiple values from an application iterable. If the middleware needs to accumulate more data from the application before it can produce any output, it must yield an empty string.

非同期のアプリケーションおよびサーバのより良いサポートのために、ミドルウェアコンポーネントはアプリケーション iterable から複数の値を待っている間、イテレーションをブロック してはならない。ミドルウェアが出力を生成できるようになる前に、アプリケーションからより多くのデータを蓄積する必要があるなら、空の文字列を yield しなければならない。

To put this requirement another way, a middleware component must yield at least one value each time its underlying application yields a value. If the middleware cannot yield any other value, it must yield an empty string.

この要件を言い換えれば、ミドルウェアコンポーネントは内包するアプリケーションが値を yield する毎に 少なくとも 1つの値を yield しなければならない。ミドルウェアが他の値を yield することができないなら、空の文字列を yield しなければならない。

This requirement ensures that asynchronous applications and servers can conspire to reduce the number of threads that are required to run a given number of application instances simultaneously.

この要件は、非同期なアプリケーションとサーバが協力して、与えられた数のアプリケーションインスタンスを同時に実行するのに必要なスレッドの数を減らすことができることを保証する。

Note also that this requirement means that middleware must return an iterable as soon as its underlying application returns an iterable. It is also forbidden for middleware to use the write() callable to transmit data that is yielded by an underlying application. Middleware may only use their parent server's write() callable to transmit data that the underlying application sent using a middleware-provided write() callable.

また、この要件が、ミドルウェアは内包するアプリケーションが iterable を返すとすぐに iterable を返さ なければならない ということを意味することに注意。また、ミドルウェアは、内包するアプリケーションから yield されたデータを送信するために write() callable を使用することが禁止される。ミドルウェアは、内包するアプリケーションがミドルウェアから提供された write() callable を使用して送ったデータを送信するためにだけ、親サーバの write() callable を使用することができる。

write() callable

Some existing application framework APIs support unbuffered output in a different manner than WSGI. Specifically, they provide a "write" function or method of some kind to write an unbuffered block of data, or else they provide a buffered "write" function and a "flush" mechanism to flush the buffer.

いくつかの既存のアプリケーション・フレームワーク API は、WSGI と異なった方法で非バッファリング出力をサポートする。特に、バッファリングされないデータのブロックを書くために、「write」関数またはある種の方法を提供したり、または、バッファリングされる「write」関数と、バッファを flush するための「flush」メカニズムを提供したりする。

Unfortunately, such APIs cannot be implemented in terms of WSGI's "iterable" application return value, unless threads or other special mechanisms are used.

残念ながら、そのような API はスレッドや他の特別なメカニズムが使用されていない限り、WSGI の"iterable"アプリケーション戻り値の方法では実装することができない。

Therefore, to allow these frameworks to continue using an imperative API, WSGI includes a special write() callable, returned by the start_response callable.

したがって、これらのフレームワークが必須の API を使用し続けることを許容するために、WSGI は特別な write() callable を含んでいる。それは、start_response callable によって返される。

New WSGI applications and frameworks should not use the write() callable if it is possible to avoid doing so. The write() callable is strictly a hack to support imperative streaming APIs. In general, applications should produce their output via their returned iterable, as this makes it possible for web servers to interleave other tasks in the same Python thread, potentially providing better throughput for the server as a whole.

新しい WSGI アプリケーションとフレームワークは、可能なら write() callable を使用 すべきでない。write() callable は、必須のストリーミング API をサポートするための完全なハックである。一般に、アプリケーションはその戻り値の iterable によって出力を生成すべきである。これによって Web サーバーは、同じ Python スレッドにおける他のタスクを相互に切り替えることが可能になり、潜在的にサーバ全体でより良い効率を提供することができる。

The write() callable is returned by the start_response() callable, and it accepts a single parameter: a string to be written as part of the HTTP response body, that is treated exactly as though it had been yielded by the output iterable. In other words, before write() returns, it must guarantee that the passed-in string was either completely sent to the client, or that it is buffered for transmission while the application proceeds onward.

write() callable は start_response() callable によって返される。そして、ただ一つのパラメータを受け付ける: HTTP レスポンスボディの一部として書き出されるべき文字列。それは、出力 iterable によって yield された場合と同じように扱われる。言い換えれば、write() が戻る前に、渡された文字列をクライアントに完全に送信するか、あるいはアプリケーションが先に進んでいる間、送信のためにそれをバッファリングすることを保証しなければならない。

An application must return an iterable object, even if it uses write() to produce all or part of its response body. The returned iterable may be empty (i.e. yield no non-empty strings), but if it does yield non-empty strings, that output must be treated normally by the server or gateway (i.e., it must be sent or queued immediately). Applications must not invoke write() from within their return iterable, and therefore any strings yielded by the iterable are transmitted after all strings passed to write() have been sent to the client.

アプリケーションはレスポンスボディのすべてまたは一部を生成するのに write() を使用した場合でも、iterable オブジェクトを返さ なければならない。返された iterable は空 でもよい (すなわち、空でない文字列を何も yield しない) が、空でない文字列を yield する なら、サーバまたはゲートウェイはその出力を通常と同じように扱わなければならない (すなわち、それをすぐに送信するか、またはキューに入れる)。アプリケーションは、自身の返した iterable から write() を呼び出し てはならない。そして、したがって、iterable によって yield されたどんな文字列も、write() に渡されたすべての文字列をクライアントに送った後で送信される。

Unicode Issues

Unicode の問題

HTTP does not directly support Unicode, and neither does this interface. All encoding/decoding must be handled by the application; all strings passed to or from the server must be standard Python byte strings, not Unicode objects. The result of using a Unicode object where a string object is required, is undefined.

HTTP は Unicode を直接サポートしない。そして、このインタフェースも同様である。すべてのエンコード/デコードは、アプリケーションで扱われなければならない; サーバに渡された、またはサーバから渡されたすべての文字列は、Unicode オブジェクトではなく、Python の標準バイト文字列でなければならない。文字列オブジェクトが必要な局面で Unicode オブジェクトを使用した結果は、未定義である。

Note also that strings passed to start_response() as a status or as response headers must follow RFC 2616 with respect to encoding. That is, they must either be ISO-8859-1 characters, or use RFC 2047 MIME encoding.

また、start_response() にステータスまたはレスポンスヘッダーとして渡された文字列は、コード化に関して RFC 2616 に従わ なければならない ことに注意。すなわち、それらは、ISO-8859-1 文字列であるか、または RFC 2047 の MIME エンコーディングを使用しなければならない。

On Python platforms where the str or StringType type is in fact Unicode-based (e.g. Jython, IronPython, Python 3000, etc.), all "strings" referred to in this specification must contain only code points representable in ISO-8859-1 encoding (\u0000 through \u00FF, inclusive). It is a fatal error for an application to supply strings containing any other Unicode character or code point. Similarly, servers and gateways must not supply strings to an application containing any other Unicode characters.

str 型や StringType 型が実際には Unicode ベースである Python プラットホーム (例えば、Jython、IronPython、Python 3000 など) であっても、この仕様で言及されたすべての「文字列」は、ISO-8859-1 エンコーディングで表現可能なコード・ポイント (\u0000 から \u00FF まで) だけで構成されなければならない。アプリケーションがこの範囲外の Unicode 文字またはコード・ポイントを含む文字列を渡すのは、致命的な誤りである。同様に、サーバおよびゲートウェイは、この範囲外の Unicode 文字を含む文字列をアプリケーションに渡し てはならない。

Again, all strings referred to in this specification must be of type str or StringType, and must not be of type unicode or UnicodeType. And, even if a given platform allows for more than 8 bits per character in str/StringType objects, only the lower 8 bits may be used, for any value referred to in this specification as a "string".

繰り返すが、この仕様で言及されたすべての文字列は、str 型または StringType 型で なければならず、unicode 型または UnicodeType 型であっては ならない。そして、プラットホームが str/StringType オブジェクトに 1キャラクタあたり 8ビット以上を許可している場合でも、この仕様で「文字列」と呼ばれた値に対しては、下位の 8ビットだけしか使用することができない。

Error Handling

エラー処理

In general, applications should try to trap their own, internal errors, and display a helpful message in the browser. (It is up to the application to decide what "helpful" means in this context.)

一般に、アプリケーションはそれ自身の内部エラーを捕捉し、ブラウザに有用なメッセージを表示 すべきである。 (この文脈において、「有用」が何を意味するのかを決めるのは、アプリケーション次第である)

However, to display such a message, the application must not have actually sent any data to the browser yet, or else it risks corrupting the response. WSGI therefore provides a mechanism to either allow the application to send its error message, or be automatically aborted: the exc_info argument to start_response. Here is an example of its use:

しかしながら、そのようなメッセージを表示するためには、アプリケーションは実際にはどんなデータもまだブラウザに送っていない状態でなければならない。さもなければ、それはレスポンスを崩壊させる危険を冒す。そのため、WSGI はアプリケーションがエラーメッセージを送るか、または自動的に中止されることを許可するための仕組みを提供する: start_response への exc_info 引数。これは、その使用に関する例である:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

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"]

If no output has been written when an exception occurs, the call to start_response will return normally, and the application will return an error body to be sent to the browser. However, if any output has already been sent to the browser, start_response will reraise the provided exception. This exception should not be trapped by the application, and so the application will abort. The server or gateway can then trap this (fatal) exception and abort the response.

例外が起こったとき、出力が全く書き出されていない場合は、start_response への呼び出しは正常に戻る。そして、アプリケーションはブラウザに送られるエラー本体を返すだろう。しかし、既に何らかの出力をブラウザに送った後なら、start_response は提供された例外を再送出する。アプリケーションは、この例外を捕捉 すべきでない。そして、アプリケーションは異常終了 (abort) するだろう。そして、サーバまたはゲートウェイは、この (致命的) 例外を捕捉して、レスポンスを中止することができる。

Servers should trap and log any exception that aborts an application or the iteration of its return value. If a partial response has already been written to the browser when an application error occurs, the server or gateway may attempt to add an error message to the output, if the already-sent headers indicate a text/* content type that the server knows how to modify cleanly.

サーバは、アプリケーションまたはアプリケーションの戻り値のイテレーションを中止するどんな例外も捕捉して、ログに出力 すべきである。アプリケーションエラーが起こるとき、レスポンスの一部が既にブラウザに書き出されている場合、サーバまたはゲートウェイが、出力にエラーメッセージを加えようと試み てもよい。これは、既に送られたヘッダーが text/* content type を示し、サーバがそれをどのように安全に変更するかを知っている場合に限る。

Some middleware may wish to provide additional exception handling services, or intercept and replace application error messages. In such cases, middleware may choose to not re-raise the exc_info supplied to start_response, but instead raise a middleware-specific exception, or simply return without an exception after storing the supplied arguments. This will then cause the application to return its error body iterable (or invoke write()), allowing the middleware to capture and modify the error output. These techniques will work as long as application authors:

ミドルウェアによっては、追加の例外処理サービスを提供したり、アプリケーションエラーメッセージを傍受して、置き換えることを望むかもしれない。そのような場合、ミドルウェアは、start_response に渡された exc_info を再送出 しない ことを選ぶかもしれない。代わりにミドルウェア特有の例外を送出するか、または提供された引数を格納した後に例外なしで単に戻るだろう。これによって、次に、アプリケーションはエラー本体の iterable を返し (または write() を呼び出し)、ミドルウェアがエラー出力を得て、変更するのを許容する。これらのテクニックは、アプリケーション作者が次のことを守る場合に動く:

1. Always provide exc_info when beginning an error response
2. Never trap errors raised by start_response when exc_info is being provided

1. エラーレスポンスの開始時に常に exc_info を提供する
2. exc_info が提供されているときに、start_response によって送出されたエラーを捕捉しない

HTTP 1.1 Expect/Continue

Servers and gateways that implement HTTP 1.1 must provide transparent support for HTTP 1.1's "expect/continue" mechanism. This may be done in any of several ways:

HTTP 1.1 を実装するサーバおよびゲートウェイは、HTTP 1.1 の 「expect/continue」 メカニズムの透過的なサポートを提供 しなければならない。これはいくつかの方法で行うことができる:

1. Respond to requests containing an Expect: 100-continue request with an immediate "100 Continue" response, and proceed normally.

Expect: 100-continue リクエストを含むリクエストに対して即座に「100 continue」レスポンスを返し、あとは通常通り処理を続ける。

2. Proceed with the request normally, but provide the application with a wsgi.input stream that will send the "100 Continue" response if/when the application first attempts to read from the input stream. The read request must then remain blocked until the client responds.

通常通りリクエストを処理する。ただし、アプリケーションが最初に入力ストリームから読むことを試みるならそのときに、"100 Continue"レスポンスを送信する wsgi.input ストリームをアプリケーションに渡す。そして、読み出された要求は、クライアントが応答するまで、ブロックされたままで残らなければならない。

3. Wait until the client decides that the server does not support expect/continue, and sends the request body on its own. (This is suboptimal, and is not recommended.)

クライアントが、サーバが expect/continue をサポートしないと決定するまで待ち、その後自分自身のリクエスト本体を送る。 (これは準最適であり、推奨されない)

Note that these behavior restrictions do not apply for HTTP 1.0 requests, or for requests that are not directed to an application object. For more information on HTTP 1.1 Expect/Continue, see RFC 2616, sections 8.2.3 and 10.1.1.

これらの振舞いの制限は、HTTP 1.0 リクエストに対して、またはアプリケーションオブジェクトに向けられていないリクエストに対しては適用されないことに注意。HTTP1.1 Expect/Continue の詳しい情報に関しては、RFC 2616 セクション 8.2.3、および 10.1.1 を参照。

Other HTTP Features

その他の HTTP 機能

In general, servers and gateways should "play dumb" and allow the application complete control over its output. They should only make changes that do not alter the effective semantics of the application's response. It is always possible for the application developer to add middleware components to supply additional features, so server/gateway developers should be conservative in their implementation. In a sense, a server should consider itself to be like an HTTP "gateway server", with the application being an HTTP "origin server". (See RFC 2616, section 1.3, for the definition of these terms.)

一般に、サーバとゲートウェイは、出力に関して沈黙を守り、アプリケーションに完全なコントロールを許すべきである。それらは、アプリケーションのレスポンスの有効な意味論を変更しない変更をだけを行うべきである。アプリケーション開発者は、いつでも付加的な機能を供給するためにミドルウェアのコンポーネントを加えことができる。そのため サーバ/ゲートウェイ開発者は、彼らの実装に関して保守的であるべきである。ある意味でサーバは、それ自体が HTTP 「ゲートウェイサーバ」のようなものと考えるべきである。それは HTTP 「オリジナルサーバ」であるアプリケーションを持っている。 (これらの用語の定義に関して、RFC 2616 セクション 1.3 を参照。)

However, because WSGI servers and applications do not communicate via HTTP, what RFC 2616 calls "hop-by-hop" headers do not apply to WSGI internal communications. WSGI applications must not generate any "hop-by-hop" headers [4], attempt to use HTTP features that would require them to generate such headers, or rely on the content of any incoming "hop-by-hop" headers in the environ dictionary. WSGI servers must handle any supported inbound "hop-by-hop" headers on their own, such as by decoding any inbound Transfer-Encoding, including chunked encoding if applicable.

しかしながら、WSGI サーバとアプリケーションが、HTTP で通信しないので、RFC 2616 が「hop-by-hop」ヘッダと呼ぶものを WSGI の内部の通信に適用しない。WSGI アプリケーションは、"hop-by-hop"ヘッダー [4] を内部で生成したり、そのようなヘッダーを生成することを必要とする HTTP 機能を使用することを試みたり、または入力される environ 辞書の中の"hop-by-hop"ヘッダーの内容も信頼 してはならない。WSGI サーバは、サポートしている"hop-by-hop"ヘッダの入力を、それ自身で処理 しなければならない。例えば、可能なら chunked encoding を含む Transfer-Encoding をデコードすることによって。

Applying these principles to a variety of HTTP features, it should be clear that a server may handle cache validation via the If-None-Match and If-Modified-Since request headers and the Last-Modified and ETag response headers. However, it is not required to do this, and the application should perform its own cache validation if it wants to support that feature, since the server/gateway is not required to do such validation.

これらの原則をさまざまな HTTP 機能に適用すると、サーバが If-None-Match や If-Modified-Since リクエストヘッダと、Last-Modified および ETag レスポンスヘッダを通してキャッシュ バリデーションを扱っ てもよい ことは明確であるべきである。しかしながら、このようにする必要はなく、アプリケーションがこの特徴をサポートしたいなら、それ自身のキャッシュ バリデーションを実行するべきである。なぜなら、サーバ/ゲートウェイがそのようなバリデーションをする必要はないので。

Similarly, a server may re-encode or transport-encode an application's response, but the application should use a suitable content encoding on its own, and must not apply a transport encoding. A server may transmit byte ranges of the application's response if requested by the client, and the application doesn't natively support byte ranges. Again, however, the application should perform this function on its own if desired.

同様に、サーバはアプリケーションのレスポンスを再エンコード、または transport-encode してもよい が、アプリケーションはそれ自身で適当な content encoding を使用 すべきであり、transport encoding を適用 してはならない。アプリケーションがバイト範囲をネイティブにサポートしないなら、サーバはクライアントの要求に応じてアプリケーションのレスポンスのバイト範囲を伝え てもよい。しかし、繰り返すが、必要ならアプリケーション自身でこの機能を実行 すべきである。

Note that these restrictions on applications do not necessarily mean that every application must reimplement every HTTP feature; many HTTP features can be partially or fully implemented by middleware components, thus freeing both server and application authors from implementing the same features over and over again.

これらのアプリケーションに対する制限が、必ずしもあらゆるアプリケーションはあらゆる HTTP 機能を再実装しなければならないということを意味するわけではないことに注意。多くの HTTP 機能は、ミドルウェアコンポーネントで部分的または完全に実装することができる。その結果、サーバとアプリケーションの作者の両方が、同じ特徴を幾重にも実装することから解放される。

Thread Support

スレッドサポート

Thread support, or lack thereof, is also server-dependent. Servers that can run multiple requests in parallel, should also provide the option of running an application in a single-threaded fashion, so that applications or frameworks that are not thread-safe may still be used with that server.

スレッドサポート、あるいはその欠如もまた、サーバ依存である。複数の要求を並列に実行することができるサーバは、スレッド・セーフでないアプリケーションまたはフレームワークを依然としてそのサーバと共に使用できるように、シングルスレッド方式でアプリケーションを実行するオプションも提供 すべきである。

Implementation/Application Notes

実装/適用上の注意

Server Extension APIs

サーバ拡張 API

Some server authors may wish to expose more advanced APIs, that application or framework authors can use for specialized purposes. For example, a gateway based on mod_python might wish to expose part of the Apache API as a WSGI extension.

サーバ作者の中には、アプリケーションまたはフレームワークの作者が特定の目的のために使用することができる、より高度な API を公開したいと考えるかもしれない。例えば、mod_python に基づくゲートウェイは WSGI 拡張として Apache API の一部を公開したいと考えるかもしれない。

In the simplest case, this requires nothing more than defining an environ variable, such as mod_python.some_api. But, in many cases, the possible presence of middleware can make this difficult. For example, an API that offers access to the same HTTP headers that are found in environ variables, might return different data if environ has been modified by middleware.

最も簡単な場合では、これは、mod_python.some_api などの environ 変数を定義することだけを必要とする。しかし、多くの場合、ミドルウェアの存在の可能性によって、これが難しくなる場合がある。例えば、environ 変数で見つけられる同じ HTTP ヘッダへのアクセスを提供する API は、environ がミドルウェアによって変更されたなら異なったデータを返すかもしれない。

In general, any extension API that duplicates, supplants, or bypasses some portion of WSGI functionality runs the risk of being incompatible with middleware components. Server/gateway developers should not assume that nobody will use middleware, because some framework developers specifically intend to organize or reorganize their frameworks to function almost entirely as middleware of various kinds.

一般に、WSGI の機能性の何らかの部分を複製したり、置き換えたり、または迂回させたりするどんな拡張 API も、ミドルウェアコンポーネントと非互換であるという危険を冒す。サーバ/ゲートウェイ開発者は、だれもミドルウェアを使用しないと仮定すべきで ない。なぜなら、何人かのフレームワークの開発者が、彼らのフレームワークを様々な種類のミドルウェアとしてほぼ完全に機能するように構成、または再構成することを具体的に予定しているからだ。

So, to provide maximum compatibility, servers and gateways that provide extension APIs that replace some WSGI functionality, must design those APIs so that they are invoked using the portion of the API that they replace. For example, an extension API to access HTTP request headers must require the application to pass in its current environ, so that the server/gateway may verify that HTTP headers accessible via the API have not been altered by middleware. If the extension API cannot guarantee that it will always agree with environ about the contents of HTTP headers, it must refuse service to the application, e.g. by raising an error, returning None instead of a header collection, or whatever is appropriate to the API.

したがって、最大の互換性を提供するためには、何らかの WSGI の機能性を置き換える拡張 API を提供するサーバおよびゲートウェイは、それらが置き換える API の一部を使用して呼び出すことができるように、それらの API を設計 しなければならない。例えば、HTTP リクエストヘッダーにアクセスする拡張 API は、アプリケーションに現在の environ を渡すように要求して、サーバ/ゲートウェイが API を通してアクセスできる HTTP ヘッダがミドルウェアによって変更されていないことを検証できるようにしなければならない。拡張 API が、HTTP ヘッダの内容に関して常に environ に同意することを保証できないなら、アプリケーションへのサービスを拒否しなければならない。例えば、エラーを送出したり、ヘッダー collection の代わりに None を返したり、または API に適切なことなら何でもすることによって。

Similarly, if an extension API provides an alternate means of writing response data or headers, it should require the start_response callable to be passed in, before the application can obtain the extended service. If the object passed in is not the same one that the server/gateway originally supplied to the application, it cannot guarantee correct operation and must refuse to provide the extended service to the application.

同様に、拡張 API がレスポンスデータまたはヘッダーを出力する代替の手段を提供するなら、アプリケーションが拡張サービスを得ることができる前に start_response callable が渡されることを必要とすべきである。渡されたオブジェクトがサーバ/ゲートウェイが元々アプリケーションに提供したものと同じでなければ、正しい操作を保証することができないので、アプリケーションへの拡張サービスを提供することを拒否しなければならない。

These guidelines also apply to middleware that adds information such as parsed cookies, form variables, sessions, and the like to environ. Specifically, such middleware should provide these features as functions which operate on environ, rather than simply stuffing values into environ. This helps ensure that information is calculated from environ after any middleware has done any URL rewrites or other environ modifications.

これらのガイドラインは environ に情報 – 例えば、解析済みの Cookie や、フォーム変数、セッション、および同様のもの – を加えるミドルウェアにも適用される。明らかに、そのようなミドルウェアはこれらの特徴を、単に environ に値を詰めるのではなく、environ に対して働く関数として提供するべきである。これによって、あらゆるミドルウェアが URL 書き直しや他の environ 変更をした 後の environ から情報が計算されることを確実にする。

It is very important that these "safe extension" rules be followed by both server/gateway and middleware developers, in order to avoid a future in which middleware developers are forced to delete any and all extension APIs from environ to ensure that their mediation isn't being bypassed by applications using those extensions!

サーバ/ゲートウェイとミドルウェア開発者の両方がこれらの「安全な拡張」規則に従うのは非常に重要である。ミドルウェア開発者が拡張 API を使用しているアプリケーションから自身の提供する機能が迂回されないことを保証するためにやむを得ず environ からありとあらゆる拡張 API を削除する未来を避けるために!

Application Configuration

アプリケーション設定

This specification does not define how a server selects or obtains an application to invoke. These and other configuration options are highly server-specific matters. It is expected that server/gateway authors will document how to configure the server to execute a particular application object, and with what options (such as threading options).

この仕様は、サーバが呼び出すべきアプリケーションをどのように選択または取得するかについて定義しない。これらの、そして他の設定オプションは極めてサーバ特有の問題である。サーバ/ゲートウェイ作者は、特定のアプリケーションオブジェクトを実行するためにどのように、また何のオプション (スレッドオプションなどの) でサーバを設定するのかを文書化することが期待される。

Framework authors, on the other hand, should document how to create an application object that wraps their framework's functionality. The user, who has chosen both the server and the application framework, must connect the two together. However, since both the framework and the server now have a common interface, this should be merely a mechanical matter, rather than a significant engineering effort for each new server/framework pair.

その一方で、フレームワークの作者はフレームワークの機能性を包含するアプリケーションオブジェクトの作成方法を文書化すべきである。ユーザ (彼らはサーバとアプリケーションフレームワークの両方を選んだ) は、その 2つを 1つに接続しなければならない。しかしながら、現在、フレームワークとサーバの両方には一般的なインタフェースがあるので、これは、それぞれの新しいサーバ/フレームワークの組に対する重大な工学的努力というより、単に機械的な問題だろう。

Finally, some applications, frameworks, and middleware may wish to use the environ dictionary to receive simple string configuration options. Servers and gateways should support this by allowing an application's deployer to specify name-value pairs to be placed in environ. In the simplest case, this support can consist merely of copying all operating system-supplied environment variables from os.environ into the environ dictionary, since the deployer in principle can configure these externally to the server, or in the CGI case they may be able to be set via the server's configuration files.

最後に、アプリケーション、フレームワーク、およびミドルウェアの中には、簡単な文字列設定オプションを受け取るために environ 辞書を使用したいと考えるものがあるかもしれない。サーバとゲートウェイは、アプリケーションの配布者が environ に置かれるべき名前-値の組を指定できるようにすることによって、これをサポート すべきである。最も簡単な場合では、このサポートは単に OS に供給されたすべての環境変数を os.environ から environ 辞書にコピーすることで成り立つ。なぜなら、原則として配布者は外部的にこれらをサーバに構成することができるか、または CGI の場合ではサーバの構成ファイルで設定することができるので。

Applications should try to keep such required variables to a minimum, since not all servers will support easy configuration of them. Of course, even in the worst case, persons deploying an application can create a script to supply the necessary configuration values:

アプリケーションは、そのような必要な変数を最小に抑えようと すべきである。なぜなら、すべてのサーバがそれらの簡単な構成をサポートするというわけではないので。もちろん、最悪の場合でも、アプリケーションを配布する人々は必要な設定値を提供するためのスクリプトを作成することができる:

1
2
3
4
5

from the_app import application

def new_app(environ,start_response):
    environ['the_app.configval1'] = 'something'
    return application(environ,start_response)

But, most existing applications and frameworks will probably only need a single configuration value from environ, to indicate the location of their application or framework-specific configuration file(s). (Of course, applications should cache such configuration, to avoid having to re-read it upon each invocation.)

しかし、既存のアプリケーションやフレームワークは、おそらくただ一つの設定値を、それらのアプリケーションまたはフレームワーク特有の構成ファイルの位置を示すために environ から必要とするだろう。 (もちろん、アプリケーションは起動される度にそれを再読み込みしなければならないのを避けるために、そのような設定をキャッシュすべきである。)

URL Reconstruction

URL 再構築

If an application wishes to reconstruct a request's complete URL, it may do so using the following algorithm, contributed by Ian Bicking:

アプリケーションがリクエストの完全な URL を再構築したいなら、Ian Bicking によって寄稿された以下のアルゴリズムが使用できるかもしれない:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

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']

Note that such a reconstructed URL may not be precisely the same URI as requested by the client. Server rewrite rules, for example, may have modified the client's originally requested URL to place it in a canonical form.

そのような再構築された URL が、クライアントに要求された URI と正確に同じではないかもしれないことに注意。例えば、サーバによる URL 書き換え規則は、元々クライアントが要求した URL を標準形になるように変更したかもしれない。

Supporting Older (<2.2) Versions of Python

古い (<2.2) Python のサポート

Some servers, gateways, or applications may wish to support older (<2.2) versions of Python. This is especially important if Jython is a target platform, since as of this writing a production-ready version of Jython 2.2 is not yet available.

いくつかのサーバ、ゲートウェイ、またはアプリケーションでは、古い Python のバージョンをサポートしたいと考えるかもしれない。これは Jython が対象プラットホームであるなら特に重要である。なぜなら、これを書いている時点では Jython 2.2 の production-ready のバージョンはまだ利用可能でないからだ。

For servers and gateways, this is relatively straightforward: servers and gateways targeting pre-2.2 versions of Python must simply restrict themselves to using only a standard "for" loop to iterate over any iterable returned by an application. This is the only way to ensure source-level compatibility with both the pre-2.2 iterator protocol (discussed further below) and "today's" iterator protocol (see PEP 234).

サーバとゲートウェイに関しては、これは比較的簡単である: Python 2.2 以下のバージョンを対象とするサーバとゲートウェイは、単にアプリケーションで返されたあらゆる iterable に対して標準の"for"ループだけを使用して繰り返しを行うように制限しなければならない。これが、2.2 以下のイテレータ・プロトコル (さらに以下で議論する) と、「今日的な」イテレータ・プロトコル (PEP 234 を参照) の両方に対して、ソースレベルの互換性を確実にする唯一の方法である。

(Note that this technique necessarily applies only to servers, gateways, or middleware that are written in Python. Discussion of how to use iterator protocol(s) correctly from other languages is outside the scope of this PEP.)

(このテクニックは、Python で書かれているサーバ、ゲートウェイ、またはミドルウェアだけに適用する必要があることに注意。他の言語でイテレータ・プロトコルをどのように正しく使用するかに関する議論は、このPEPの範囲外である。)

For applications, supporting pre-2.2 versions of Python is slightly more complex:

アプリケーションにおいて、Python pre-2.2 バージョンをサポートするのは、わずかに複雑である:

- You may not return a file object and expect it to work as an iterable, since before Python 2.2, files were not iterable. (In general, you shouldn't do this anyway, because it will peform quite poorly most of the time!) Use wsgi.file_wrapper or an application-specific file wrapper class. (See Optional Platform-Specific File Handling for more on wsgi.file_wrapper, and an example class you can use to wrap a file as an iterable.)

ファイルオブジェクトを返して、それが iterable として働くと期待することはできない。なぜなら、Python 2.2 以前では、ファイルは iterable ではなかったので。 (たいてい全く不十分に実行されるので、一般に、とにかくあなたはこれをするべきではない!) wsgi.file_wrapper またはアプリケーション特有のファイルラッパーのクラスを使用する。 (wsgi.file_wrapper についての詳しい情報と、ファイルを iterable としてラップするために使用できるクラスの例については、"Optional Platform-Specific File Handling" を参照。)

- If you return a custom iterable, it must implement the pre-2.2 iterator protocol. That is, provide a __getitem__ method that accepts an integer key, and raises IndexError when exhausted. (Note that built-in sequence types are also acceptable, since they also implement this protocol.)

もしカスタムの iterable を返すなら、それは pre-2.2 イテレータ・プロトコルを実装しなければならない。すなわち、整数キーを受け取って、もし消費されていたら IndexError を raise する __getitem__ メソッドを提供する。 (built-inのシーケンスタイプもこのプロトコルを実装しているので、それらも許容されることに注意。)

Finally, middleware that wishes to support pre-2.2 versions of Python, and iterates over application return values or itself returns an iterable (or both), must follow the appropriate recommendations above.

最後に、ミドルウェアが Python pre-2.2 バージョンのサポートを希望していて、アプリケーション戻り値をイテレートするか、それ自体が iterable を返す (またはその両方の) 場合、上の適切な推奨に従わなければならない

(Note: It should go without saying that to support pre-2.2 versions of Python, any server, gateway, application, or middleware must also use only language features available in the target version, use 1 and 0 instead of True and False, etc.)

(言うまでもなく、Python pre-2.2 バージョンをサポートするためにはどんなサーバ、ゲートウェイ、アプリケーション、またはミドルウェアも、対象バージョンで利用可能な言語機能だけを使用しなければならない。True と False の代わりに 1 と 0 を使用するなど)

Optional Platform-Specific File Handling

Some operating environments provide special high-performance file-transmission facilities, such as the Unix sendfile() call. Servers and gateways may expose this functionality via an optional wsgi.file_wrapper key in the environ. An application may use this "file wrapper" to convert a file or file-like object into an iterable that it then returns, e.g.:

いくつかのオペレーティング環境は、Unixの sendfile() 呼び出しなどの特別な高性能ファイル転送機能を提供する。サーバおよびゲートウェイは、environ の中のオプショナルな wsgi.file_wrapper キーを通して、この機能を公開 してもよい。アプリケーションは、例えばファイルまたは file-like オブジェクトをその次に返す iterable に変換するのに、この「ファイルラッパー」を使用 してもよい:

1
2
3
4

if 'wsgi.file_wrapper' in environ:
    return environ['wsgi.file_wrapper'](filelike, block_size)
else:
    return iter(lambda: filelike.read(block_size), '')

If the server or gateway supplies wsgi.file_wrapper, it must be a callable that accepts one required positional parameter, and one optional positional parameter. The first parameter is the file-like object to be sent, and the second parameter is an optional block size "suggestion" (which the server/gateway need not use). The callable must return an iterable object, and must not perform any data transmission until and unless the server/gateway actually receives the iterable as a return value from the application. (To do otherwise would prevent middleware from being able to interpret or override the response data.)

サーバまたはゲートウェイが wsgi.file_wrapper を提供するなら、それは、1つの必須の位置パラメタと 1つの任意の位置パラメタを受け取る callable でなければならない。最初のパラメタは送られる file-like オブジェクトであり、2番目のパラメタは任意のブロック・サイズ「suggestion」 (サーバ/ゲートウェイが使用する必要はない) である。その callable は、iterable オブジェクトを返さ なければならない。そして、サーバ/ゲートウェイが実際にアプリケーションからの戻り値として iterable を受け取るまで、どんなデータ伝送も実行してはならない (そうしないと、ミドルウェアがレスポンスデータを解釈またはオーバーライドすることが阻害される)

To be considered "file-like", the object supplied by the application must have a read() method that takes an optional size argument. It may have a close() method, and if so, the iterable returned by wsgi.file_wrapper must have a close() method that invokes the original file-like object's close() method. If the "file-like" object has any other methods or attributes with names matching those of Python built-in file objects (e.g. fileno()), the wsgi.file_wrapper may assume that these methods or attributes have the same semantics as those of a built-in file object.

"file-like" と見なすために、アプリケーションで提供されたオブジェクトは、任意のサイズ引数を受け取る read() メソッドを持っていなければならない。それは close() メソッドを持って いてもよく、もしそうなら、wsgi.file_wrapper によって返された iterable は、オリジナルの file-like オブジェクトの close() メソッドを呼び出す close() メソッドを持って いなければならない。file-like オブジェクトが他のPython built-in のファイルオブジェクトと名前が一致するメソッドまたは属性 (例えば fileno()) を持っている場合、wsgi.file_wrapper は、これらのメソッドまたは属性が built-in のファイルオブジェクトのものと同じ意味論を持つと仮定 してもよい。

The actual implementation of any platform-specific file handling must occur after the application returns, and the server or gateway checks to see if a wrapper object was returned. (Again, because of the presence of middleware, error handlers, and the like, it is not guaranteed that any wrapper created will actually be used.)

どんなプラットホーム特有のファイル取り扱いの実際の実装も、アプリケーションが戻った 後に 起こらなければならない。そして、サーバまたはゲートウェイは、ラッパーオブジェクトが返されたかどうかを確かめる。 (繰り返すが、ミドルウェアやエラーハンドラ、および同様のものの存在のために、作成されたどんなラッパーも実際に使用されるかどうかは保証されない。)

Apart from the handling of close(), the semantics of returning a file wrapper from the application should be the same as if the application had returned iter(filelike.read, ''). In other words, transmission should begin at the current position within the "file" at the time that transmission begins, and continue until the end is reached.

close() の取り扱いは別として、アプリケーションからファイルラッパーを返すことの意味は、アプリケーションが iter(filelike.read, '') を返したのと同じであるべきである。言い換えれば、転送が始まる時の「ファイル」の中の現在の位置から転送が始まり、端に達するまで続くべきである。

Of course, platform-specific file transmission APIs don't usually accept arbitrary "file-like" objects. Therefore, a wsgi.file_wrapper has to introspect the supplied object for things such as a fileno() (Unix-like OSes) or a java.nio.FileChannel (under Jython) in order to determine if the file-like object is suitable for use with the platform-specific API it supports.

もちろん、プラットホーム特有のファイル転送 API は通常、任意の「file-like」オブジェクトを受け入れるわけではない。したがって、wsgi.file_wrapper は、サポートするプラットホーム特有の API に対して file-like オブジェクトを使用するのが適切かどうかを決定するために、提供されたオブジェクトの fileno() (unix のような OS) や java.nio.FileChannel (Jython の元で) などを introspect しなければならない。

Note that even if the object is not suitable for the platform API, the wsgi.file_wrapper must still return an iterable that wraps read() and close(), so that applications using file wrappers are portable across platforms. Here's a simple platform-agnostic file wrapper class, suitable for old (pre 2.2) and new Pythons alike:

ファイルラッパーを使用するアプリケーションがプラットホームを越えて移植性があるように、オブジェクトがプラットホーム API にとって適切でなくても、wsgi.file_wrapper は read() と close() をラップする iterable を返さ なければならない ことに注意。これは、古い (2.2 以前の) Python と新しい Pythons で同じように適切な、プラットホームによらない簡単なファイルラッパーのクラスである:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

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

and here is a snippet from a server/gateway that uses it to provide access to a platform-specific API:

そしてこれは、プラットホーム特有の API へのアクセスを提供するサーバ/ゲートウェイで使われているコード片である:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

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

Questions and Answers

1. Why must environ be a dictionary? What's wrong with using a subclass?

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 辞書に提供するのを妨げないことに注意。これは、そのような付加価値サービスを提供することに対するお勧めのアプローチである。

2. Why can you call write() and yield strings/return an iterable? Shouldn't we pick just one way?

なぜ 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 だけのアプローチで必要になるよりもほんの少し増えるようになる。

3. What's the close() for?

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 サポートの前方互換性をアプリケーションに許容する。

4. Why is this interface so low-level? I want feature X! (e.g. cookies, sessions, persistence, ...)

なぜこのインタフェースはこんなに低レベルなのか? 機能 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 ベースのサーバに移植可能ではないだろう。)

5. Why use CGI variables instead of good old HTTP headers? And why mix them in with WSGI-defined variables?

なぜ古き良き 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つの辞書引数をたらい回しにする必要があるだけで、何の現実的な利点も提供しないだろう。

6. What about the status string? Can't we just use the number, passing in 200 instead of "200 OK"?

ステータス文字列についてはどうか? 数字を使うことはできないか? つまり、"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.

これをすると、数値の状態と対応するメッセージのテーブルを持つ必要があるので、サーバまたはゲートウェイが複雑になるだろう。対照的に、アプリケーションまたはフレームワーク作者が、使用している特定の応答コードに伴う付加的なテキストをタイプするのは簡単であり、既存のフレームワークはしばしば既に必要なメッセージを含むテーブルを持っている。したがって、バランスの問題で、サーバまたはゲートウェイよりもアプリケーション/フレームワークが責任を持つ方が良いように思える。

7. Why is wsgi.run_once not guaranteed to run the app only once?

なぜ 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 にセットされて呼び出されたからといって、それが絶対に再び実行されないと仮定すべきではない。

8. Feature X (dictionaries, callables, etc.) are ugly for use in application code; why don't we use objects instead?

機能 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 実装であり、彼らはおそらくこの仕様が手渡す準備ができている状態で実装するだろう。したがって、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はサーバとミドルウェア作者には便利に低レベルであるままで残る一方で、アプリケーション開発者には「醜く」なくなることができる。

Proposed/Under Discussion

These items are currently being discussed on the Web-SIG and elsewhere, or are on the PEP author's "to-do" list:

これらの項目は、現在 Web-SIG 上やほかの場所で議論しているか、または PEP 作者の「to-do」リストにある:

- Should wsgi.input be an iterator instead of a file? This would help for asynchronous applications and chunked-encoding input streams.
- Optional extensions are being discussed for pausing iteration of an application's ouptut until input is available or until a callback occurs.
- Add a section about synchronous vs. asynchronous apps and servers, the relevant threading models, and issues/design goals in these areas.

• wsgi.input はファイルではなくイテレータの方が良いのではないか? そうすることで、非同期アプリケーションや chunked encoding 入力ストリームで役立つだろう。
• 入力が利用可能になるか、またはコールバックが起こるまで、アプリケーション出力のイテレーションを中断するためのオプショナルな拡張について議論されている。
• 同期 vs. 非同期に関するセクションを加える。アプリケーションとサーバ、関連するスレッドモデル、およびこれらの領域の問題/デザイン目標。

Acknowledgements

Thanks go to the many folks on the Web-SIG mailing list whose thoughtful feedback made this revised draft possible. Especially:

Web-SIG メーリングリスト上のたくさんの仲間に感謝したい。ML上の思慮深いフィードバックによって修正を重ね、このドラフトを書くことができた。特に、以下の方々には感謝の意を捧げたい:

- Gregory "Grisha" Trubetskoy, author of mod_python, who beat up on the first draft as not offering any advantages over "plain old CGI", thus encouraging me to look for a better approach.
- Ian Bicking, who helped nag me into properly specifying the multithreading and multiprocess options, as well as badgering me to provide a mechanism for servers to supply custom extension data to an application.
- Tony Lownds, who came up with the concept of a start_response function that took the status and headers, returning a write function. His input also guided the design of the exception handling facilities, especially in the area of allowing for middleware that overrides application error messages.
- Alan Kennedy, whose courageous attempts to implement WSGI-on-Jython (well before the spec was finalized) helped to shape the "supporting older versions of Python" section, as well as the optional wsgi.file_wrapper facility.
- Mark Nottingham, who reviewed the spec extensively for issues with HTTP RFC compliance, especially with regard to HTTP/1.1 features that I didn't even know existed until he pointed them out.

• mod_python の作者である Gregory "Grisha" Trubetskoy は、はじめのドラフトに対して、「従来のただの CGI」と比べてなんら利点がないと指摘し、私を打ちのめしてくれた。おかげでより良い方法に目を向ける勇気を得られた。
• Ian Bicking は、マルチスレッドやマルチプロセスのオプションを適切に定めるよう、口うるさく言ってくれた。そして、サーバが独自のデータ拡張をアプリケーションに提供するような仕組みを提供するよう、しつこく言ってくれた。
• Tony Lownds は、status と ヘッダ情報を引数として取り、write 関数を返す start_response 関数のコンセプトを考え出してくれた。また彼の言葉によって、便利な例外処理の設計、特にアプリケーションのエラーメッセージをミドルウェアが上書きすることを許可するという部分、が導かれた。
• Mark Nottingham は、HTTP RFC の規則に則っているかを広範囲でレビューしてくれた。特に、HTTP/1.1 の機能は、彼が指摘するまで私は存在すら知らなかった。

References

[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://cgi-spec.golux.com/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)

Copyright

This document has been placed in the public domain.

このドキュメントは、パブリックドメインです。

(訳注: この翻訳も、パブリックドメインです)