[Web-SIG] PEP 333 (19-Sep-04) Feedback
mnot at mnot.net
Wed Sep 29 02:24:59 CEST 2004
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,
* 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
* 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
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.
Mark Nottingham http://www.mnot.net/
More information about the Web-SIG