PEP333 wsgi规范1.0不靠谱翻译稿(2)

详细说明

 

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

 

 

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一个为start_response( = res),但他们并不要求一定是这个名字.服务端必须使用位置参数(而不是关键字参数)来调用应用程序对象.

 

例如得调用 result = application(environ, start_response)

 

environ是一个字典, 包括了CGI环境变量.environ必须是 python内建的字典对象dict(不是其子类, 用户字典或其他模拟的字典), 应用程序可以以任何方式改变environ. environ必须包含来一些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)).

 

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.

 

res参数是一个包含了两个位置参数,一个可选参数的可调用对象. 为了说明, 我们叫这三个参数分别为 status, response_headers 和 exc_info, 当然他们也不是必需使用这个名字.应用程序必须使用位置参数来调用他们.

 

status参数是一个类似"999 Message here"格式的状态字符串, reponse_headers是一个包含描述HTTP响应头的(header_name, header_value)元祖的列表, 可选参数exc_info 仅仅被使用在应用程序捕获到错误并试图把错误信息显示到浏览器的时候.

 

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

 

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.

 

res对象必须返回一个接受一个位参(一个写成HTTP响应体的字符串)的可写可调用对象.(注意: write()现在仅提供给一些已存在的框架来支持其需要的输出接口.在编写新的应用或框架时如果可以避免就不要使用它.更多细节可参考Buffering and Streaming 部分)

 

 

当服务端调用时, 应用程序对象必须返回一个可迭代的对象以生成零到多个字符串.这可以以多种方式实现,比如返回一个字符串列表,或者制作一个生成器函数来生成字符串(yield), 或者返回一个可迭代的实例.不论如何实现,应用程序对象必须返回一个可迭代输出零到多个字符串的迭代器.

 

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

 

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

 

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

 

服务端必须把生成的字符串以无缓冲的方式传递给客户端, 在另一个请求到来前完成每个字符串的传输.参见下面的Buffering and Streaming章节了解关于应用程序如何处理输出.

 

服务端应该将这些字符串视为二进制字节序列,尤其要确保行结束符没有改动.应用程序有责任确定字符串格式适用于客户端.(服务端可能会队HTTP传输编码,或者为了实现服务器特性执行其他转换例如字节范围内传输. 更多细节参见下面

Other HTTP Features章节.)

 

如果对于返回的迭代器求长(len)成功了,服务端应该相信这个结果是精确的.就是说,如果从应用程序返回的迭代器提供了__len__()方法, 它肯定会返回一个精确地结果.(参看如何处理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.

 

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

 

 

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.

如果迭代器还提供了close()方法,服务端必须在当前请求完成时调用该方法,无论该请求是正常的结束了还是由于错误提早终止了.(这是为了能释放应用程序资源. 该协议试图完成PEP325的生成器支持, 和其他平常的带有close()f方法的迭代器.)

 

注意: 应用程序必须在该迭代器生成第一个字符串前调用start_response对象, 以使得服务端能在发送任何具体内容前发送头内容.然而, 这个调用可以再迭代器首次迭代前被执行, 所以服务端必须假定start_response()在迭代前被调用了.

 

最后, 服务端不应该使用迭代器的任何其他属性, 除非它对服务端是一个专门制定的实例,例如由 wsgi.file_wrapper返回的"file_wrapper"(请看可选的特定平台文件处理Platform-Specific File Handling). 一般情况下, 只是用这里指定的属性, 或者是PEP234规定的迭代器接口.