[Web-SIG] PEP 333 (19-Sep-04) Feedback

[Mark Nottingham]

Overall, this PEP looks really good; these comments are mostly nits and 
editorial points to make it more precise, clear, etc.

* In "Specification Details," the start_response callable has 
illustrative arguments of "status" and "headers." It would be *very* 
helpful if the latter were called "response_headers," for clarity.

* The same section later states "The application object must return an 
iterable yielding strings." Return when? We're cautioned that the 
write() callable should not be used; how is the iterable returned, 
then?

* Later, "The server or gateway must not modify supplied strings in any 
way..." This effectively rules out the server/gateway implementing 
transfer-encodings, range requests, delta encoding, automatic content 
encoding, etc. Suggest dropping this paragraph; it doesn't really add 
any value, as servers that are malicious or incorrect in this respect 
won't really be stopped by it anyway.

* In "environ Variables," it is specified that "In general, a server or 
gateway should attempt to provide as many other CGI variables as are 
applicable, including e.g. the nonstandard SSL variables such as 
HTTPS=on , if an SSL connection is in effect." This sentence hedges in 
four different ways; "In general," "should," "attempt," "as many... as 
are applicable." Besides the redundancy, I'm concerned about the 
inclusion of nonstandard variables; how will people know which ones to 
include? I'd suggest listing those that aren't in the CGI standard, so 
there's an even playing field.

* Later in the same section, a construct called a 'stream' is defined. 
It would be good to directly relate this to a 'file-like object,' for 
the benefit of readers familiar with the terms used in the 
documentation of Python's standard library.

* The same section defines a number of environment variables with 
Boolean values (e.g., wsgi.multithread). When these definitions say 
"This value should be true if..." does it mean that they should be a 
Python types.BooleanType, or that it should evaluate to true (e.g., if 
wgsi.multithread: ...)?

* In 'Input and Error Streams', item 4 in the numbered list of notes to 
the table says 'Since the errors stream may not be rewound, a 
container..." This is the first instance of the term 'container'; could 
an existing term be used?

* In "The start_response() Callable", it says "The status argument is 
an HTTP "status" string like "200 OK" or "404 Not Found." This should 
reference the definition of status strings in the specification; 
suggest "The status argument 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 RFC2616, 
Section 6.1.1 for more information."

* In the next paragraph, "Each header_name must be a valid HTTP header 
name." For the same reasons as above, suggest "Each header_name must be 
a HTTP header field-name, as defined in RFC2616 Section 4.2."

* In the next paragraph, "If the application omits a needed header, the 
server or gateway should add it." Who determines whether it's needed? 
Suggest "If the application omits a header required by HTTP or other 
relevant
specifications in effect, the server or gateway must add it." (note 
must, not should)

* The next paragraph is confusingly worded; I'd suggest "The server or 
gateway must not actually transmit the HTTP headers until the first 
write call, or until after the first iteration of the application 
return value that yeilds a non-empty string...."

* "Buffering and Streaming," is, again, confusing about when an 
iterator is supposed to be returned.

* Finally, "Other HTTP Features" states that "In a sense, a server 
should consider itself to be like an HTTP 'proxy server'..." This isn't 
a good analogy; the function it performs is much closer to an HTTP 
gateway; See the terminology section of RFC2616.

Cheers,

--
Mark Nottingham     http://www.mnot.net/