Amendments and clarifications from:
http://mail.python.org/pipermail/web-sig/2010-September/004655.html (Also, changed revision history link to show a direct diff of changes from PEP 333.)
This commit is contained in:
Phillip J. Eby
parent
d79f6f1a15
commit
e155e9e696
78
pep-3333.txt
78
pep-3333.txt
|
|
@ -8,7 +8,7 @@ Status: Draft
|
|||
Type: Informational
|
||||
Content-Type: text/x-rst
|
||||
Created: 26-Sep-2010
|
||||
Post-History: 27-Sep-2010
|
||||
Post-History: 26-Sep-2010, 04-Oct-2010
|
||||
Replaces: 333
|
||||
|
||||
|
||||
|
|
@ -40,8 +40,8 @@ servers and Python web applications or frameworks, to promote web
|
|||
application portability across a variety of web servers.
|
||||
|
||||
|
||||
Rationale and Goals
|
||||
===================
|
||||
Original Rationale and Goals (from PEP \333)
|
||||
============================================
|
||||
|
||||
Python currently boasts a wide variety of web application frameworks,
|
||||
such as Zope, Quixote, Webware, SkunkWeb, PSO, and Twisted Web -- to
|
||||
|
|
@ -326,6 +326,12 @@ server.
|
|||
raise AssertionError("Headers already set!")
|
||||
|
||||
headers_set[:] = [status, response_headers]
|
||||
|
||||
# Note: error checking on the headers should happen here,
|
||||
# *after* the headers are set. That way, if an error
|
||||
# occurs, start_response can only be re-called with
|
||||
# exc_info set.
|
||||
|
||||
return write
|
||||
|
||||
result = application(environ, start_response)
|
||||
|
|
@ -535,9 +541,15 @@ on how this would normally be used.)
|
|||
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.
|
||||
terminated early due to an application error during iteration or an early
|
||||
disconnect of the browser. (The ``close()`` method requirement is to
|
||||
support resource release by the application. This protocol is intended
|
||||
to complement PEP 342's generator support, and other common iterables
|
||||
with ``close()`` methods.)
|
||||
|
||||
Applications returning a generator or other custom iterator **should not**
|
||||
assume the entire iterator will be consumed, as it **may** be closed early
|
||||
by the server.
|
||||
|
||||
(Note: the application **must** invoke the ``start_response()``
|
||||
callable before the iterable yields its first body bytestring, so that the
|
||||
|
|
@ -593,7 +605,7 @@ unless their value would be an empty string, in which case they
|
|||
May be empty or absent.
|
||||
|
||||
``SERVER_NAME``, ``SERVER_PORT``
|
||||
When combined with ``SCRIPT_NAME`` and ``PATH_INFO``, these variables
|
||||
When combined with ``SCRIPT_NAME`` and ``PATH_INFO``, these two strings
|
||||
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`_
|
||||
|
|
@ -635,7 +647,7 @@ 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 native 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``.
|
||||
for *any* CGI variable's value to be of any type other than ``str``.
|
||||
|
||||
In addition to the CGI-defined variables, the ``environ`` dictionary
|
||||
**may** also contain arbitrary operating-system "environment variables",
|
||||
|
|
@ -733,14 +745,24 @@ The semantics of each method are as documented in the Python Library
|
|||
Reference, except for these notes as listed in the table above:
|
||||
|
||||
1. The server is not required to read past the client's specified
|
||||
``Content-Length``, and is allowed to simulate an end-of-file
|
||||
``Content-Length``, and **should** 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.
|
||||
The application **should not** attempt to read more data than
|
||||
is specified by the ``CONTENT_LENGTH`` variable.
|
||||
|
||||
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.
|
||||
A server **should** allow ``read()`` to be called without an argument,
|
||||
and return the remainder of the client's input stream.
|
||||
|
||||
A server **should** return empty bytestrings from any attempt to
|
||||
read from an empty or exhausted input stream.
|
||||
|
||||
2. Servers **should** support the optional "size" argument to ``readline()``,
|
||||
but as in WSGI 1.0, they are allowed to omit support for it.
|
||||
|
||||
(In WSGI 1.0, the size argument was not supported, on the grounds that
|
||||
it might have been complex to implement, and was not often used in
|
||||
practice... but then the ``cgi`` module started using it, and so
|
||||
practical servers had to start supporting it anyway!)
|
||||
|
||||
3. Note that the ``hint`` argument to ``readlines()`` is optional for
|
||||
both caller and implementer. The application is free not to
|
||||
|
|
@ -816,7 +838,11 @@ 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.)
|
||||
|
||||
The ``start_response`` callable **must not** actually transmit the
|
||||
Servers **should** check for errors in the headers at the time
|
||||
``start_response`` is called, so that an error can be raised while
|
||||
the application is still running.
|
||||
|
||||
However, 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 bytestring, or upon
|
||||
|
|
@ -861,8 +887,9 @@ 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.)
|
||||
current invocation of the application. This includes the case where
|
||||
the first call to ``start_response`` raised an error. (See the example
|
||||
CGI gateway above for an illustration of the correct logic.)
|
||||
|
||||
Note: servers, gateways, or middleware implementing ``start_response``
|
||||
**should** ensure that no reference is held to the ``exc_info``
|
||||
|
|
@ -884,6 +911,14 @@ technique.
|
|||
Handling the ``Content-Length`` Header
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If the application supplies a ``Content-Length`` header, the server
|
||||
**should not** transmit more bytes to the client than the header
|
||||
allows, and **should** stop iterating over the response when enough
|
||||
data has been sent, or raise an error if the application tries to
|
||||
``write()`` past that point.
|
||||
|
||||
XXX What if the application doesn't provide *enough* data?
|
||||
|
||||
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
|
||||
|
|
@ -1454,7 +1489,10 @@ 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.
|
||||
reached, or until ``Content-Length`` bytes have been written. (If
|
||||
the application doesn't supply a ``Content-Length``, the server **may**
|
||||
generate one from the file using its knowledge of the underlying file
|
||||
implementation.)
|
||||
|
||||
Of course, platform-specific file transmission APIs don't usually
|
||||
accept arbitrary "file-like" objects. Therefore, a
|
||||
|
|
@ -1728,8 +1766,8 @@ References
|
|||
.. [6] Procedural issues regarding modifications to PEP \333
|
||||
(http://mail.python.org/pipermail/python-dev/2010-September/104114.html)
|
||||
|
||||
.. [7] SVN revision history for PEP \3333
|
||||
(http://svn.python.org/view/peps/trunk/pep-3333.txt?view=log)
|
||||
.. [7] SVN revision history for PEP \3333, showing differences from PEP 333
|
||||
(http://svn.python.org/view/peps/trunk/pep-3333.txt?r1=85014&r2=HEAD)
|
||||
|
||||
Copyright
|
||||
=========
|
||||
|
|
|
|||
Loading…
Reference in New Issue