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

[Phillip J. Eby]

At 05:24 PM 9/28/04 -0700, Mark Nottingham wrote:
>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.

Will do.


>* The same section later states "The application object must return an 
>iterable yielding strings." Return when?

When it's called, of course.  I'll change that to, "When called, the 
application object must..."


>  We're cautioned that the write() callable should not be used; how is the 
> iterable returned, then?

Huh?


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

I'll take out the modify supplied strings in any way part, but I think it's 
important to point out that the strings are binary byte sequences.  I'll 
consider some alternatives here.


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

Is there a standard for SSL extensions to CGI?  These are really the only 
"non-standard" variables I actually care about.  I'll tweak the rest of 
this more or less as you suggest.


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

Will do.


>* 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: ...)?

The latter; I thought this was obvious by virtue of the fact that it 
doesn't say ``True`` in typewriter font.  Good Python style (and 
performance) demands that one never perform truth tests by comparing 
directly to ``True`` or ``False``, so in theory it shouldn't matter unless 
you want to be tricky and use the value as an index.

Were you actually confused by this bit, or are you just looking for 
ambiguities?  I'd like to avoid cluttering these definitions further, if 
possible.


>* 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?

Argh.  Pollution carried through from the original December 2003 
draft...  will fix.


>* 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."

Okay.


>* 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."

Okay.


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

Sure.


>* 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...."

Your phrasing doesn't work either, because 'start_response()' can't wait 
around until those things happen; it has to return immediately.  I'll try 
another phrasing.


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

An application always returns an iterable when called, as per "The 
application object must return an iterable yielding strings." in 
"Specification Details".

I'll put another note about this under "The Application/Framework Side".

Keep in mind that applications *always always always* MUST return an 
iterable, with absolutely no exceptions ever.  Use of 'write()' does not 
absolve an application from returning an iterable.  (I'll add a note to 
this effect in the section on 'write()'.


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

Will do.