[Python-checkins] r85214 - peps/trunk/pep-3333.txt
phillip.eby
python-checkins at python.org
Mon Oct 4 17:48:11 CEST 2010
Author: phillip.eby
Date: Mon Oct 4 17:48:11 2010
New Revision: 85214
Log:
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.)
Modified:
peps/trunk/pep-3333.txt
Modified: peps/trunk/pep-3333.txt
==============================================================================
--- peps/trunk/pep-3333.txt (original)
+++ peps/trunk/pep-3333.txt Mon Oct 4 17:48:11 2010
@@ -8,7 +8,7 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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.
+
+ 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. 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.
+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 @@
``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 @@
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 @@
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 @@
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 @@
.. [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
=========
More information about the Python-checkins
mailing list