[Python-checkins] python/nondist/peps pep-0333.txt,1.18,1.19
pje at users.sourceforge.net
pje at users.sourceforge.net
Sun Sep 19 21:49:40 CEST 2004
Update of /cvsroot/python/python/nondist/peps
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv21020
Modified Files:
pep-0333.txt
Log Message:
Move subsections on HTTP features, error handling, unicode, and
threading to the main "Specification Details" section. Juggle
order of implementation notes to better match their importance and
pedagogic sequence. Add current open issues re: async app
frameworks.
Index: pep-0333.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0333.txt,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -d -r1.18 -r1.19
--- pep-0333.txt 18 Sep 2004 23:46:50 -0000 1.18
+++ pep-0333.txt 19 Sep 2004 19:49:37 -0000 1.19
@@ -916,11 +916,8 @@
from within their return iterable.
-Implementation/Application Notes
-================================
-
-Unicode
--------
+Unicode Issues
+--------------
HTTP does not directly support Unicode, and neither does this
interface. All encoding/decoding must be handled by the application;
@@ -1009,6 +1006,77 @@
being provided
+HTTP 1.1 Expect/Continue
+------------------------
+
+Servers and gateways that implement HTTP 1.1 **must** provide
+transparent support for HTTP 1.1's "expect/continue" mechanism. This
+may be done in any of several ways:
+
+1. Respond to requests containing an ``Expect: 100-continue`` request
+ with an immediate "100 Continue" response, and proceed normally.
+
+2. Proceed with the request normally, but provide the application
+ with a ``wsgi.input`` stream that will send the "100 Continue"
+ response if/when the application first attempts to read from the
+ input stream. The read request must then remain blocked until the
+ client responds.
+
+3. Wait until the client decides that the server does not support
+ expect/continue, and sends the request body on its own. (This
+ is suboptimal, and is not recommended.)
+
+Note that these behavior restrictions do not apply for HTTP 1.0
+requests, or for requests that are not directed to an application
+object. For more information on HTTP 1.1 Expect/Continue, see RFC
+2616, sections 8.2.3 and 10.1.1.
+
+
+Other HTTP Features
+-------------------
+
+In general, servers and gateways should "play dumb" and allow the
+application complete control over its output. They should only make
+changes that do not alter the effective semantics of the application's
+response. It is always possible for the application developer to add
+middleware components to supply additional features, so server/gateway
+developers should be conservative in their implementation. In a sense,
+a server should consider itself to be like an HTTP "proxy server", with
+the application being an HTTP "origin server".
+
+However, because WSGI servers and applications do not communicate via
+HTTP, what RFC 2616 calls "hop-by-hop" headers do not apply to WSGI
+internal communications. WSGI applications **must not** generate any
+"hop-by-hop" headers [4]_, attempt to use HTTP features that would
+require them to generate such headers, or rely on the content of
+any incoming "hop-by-hop" headers in the ``environ`` dictionary.
+WSGI servers **must** handle any supported inbound "hop-by-hop" headers
+on their own, such as by decoding any inbound ``Transfer-Encoding``,
+including chunked encoding if applicable.
+
+Applying these principles to a variety of HTTP features, it should be
+clear that a server **may** handle cache validation via the
+``If-None-Match`` and ``If-Modified-Since`` request headers and the
+``Last-Modified`` and ``ETag`` response headers. However, it is
+not required to do this, and the application **should** perform its
+own cache validation if it wants to support that feature, since
+the server/gateway is not required to do such validation.
+
+Similarly, a server **may** re-encode or transport-encode an
+application's response, but the application **should** use a
+suitable content encoding on its own, and **must not** apply a
+transport encoding. A server **may** transmit byte ranges of the
+application's response if requested by the client, and the
+application doesn't natively support byte ranges. Again, however,
+the application **should** perform this function on its own if desired.
+
+Note that these restrictions on applications do not necessarily mean
+that every application must reimplement every HTTP feature; many HTTP
+features can be partially or fully implemented by middleware
+components, thus freeing both server and application authors from
+implementing the same features over and over again.
+
+
Thread Support
--------------
@@ -1019,35 +1087,66 @@
may still be used with that server.
-URL Reconstruction
-------------------
-If an application wishes to reconstruct a request's complete URL, it
-may do so using the following algorithm, contributed by Ian Bicking::
+Implementation/Application Notes
+================================
- url = environ['wsgi.url_scheme']+'://'
- if environ.get('HTTP_HOST'):
- url += environ['HTTP_HOST']
- else:
- url += environ['SERVER_NAME']
+Server Extension APIs
+---------------------
- if environ['wsgi.url_scheme'] == 'https':
- if environ['SERVER_PORT'] != '443'
- url += ':' + environ['SERVER_PORT']
- else:
- if environ['SERVER_PORT'] != '80':
- url += ':' + environ['SERVER_PORT']
+Some server authors may wish to expose more advanced APIs, that
+application or framework authors can use for specialized purposes.
+For example, a gateway based on ``mod_python`` might wish to expose
+part of the Apache API as a WSGI extension.
- url += environ.get('SCRIPT_NAME','')
- url += environ.get('PATH_INFO','')
- if environ.get('QUERY_STRING'):
- url += '?' + environ['QUERY_STRING']
+In the simplest case, this requires nothing more than defining an
+``environ`` variable, such as ``mod_python.some_api``. But, in many
+cases, the possible presence of middleware can make this difficult.
+For example, an API that offers access to the same HTTP headers that
+are found in ``environ`` variables, might return different data if
+``environ`` has been modified by middleware.
-Note that such a reconstructed URL may not be precisely the same URI
-as requested by the client. Server rewrite rules, for example, may
-have modified the client's originally requested URL to place it in a
-canonical form.
+In general, any extension API that duplicates, supplants, or bypasses
+some portion of WSGI functionality runs the risk of being incompatible
+with middleware components. Server/gateway developers should *not*
+assume that nobody will use middleware, because some framework
+developers specifically intend to organize or reorganize their
+frameworks to function almost entirely as middleware of various kinds.
+
+So, to provide maximum compatibility, servers and gateways that
+provide extension APIs that replace some WSGI functionality, **must**
+design those APIs so that they are invoked using the portion of the
+API that they replace. For example, an extension API to access HTTP
+request headers must require the application to pass in its current
+``environ``, so that the server/gateway may verify that HTTP headers
+accessible via the API have not been altered by middleware. If the
+extension API cannot guarantee that it will always agree with
+``environ`` about the contents of HTTP headers, it must refuse service
+to the application, e.g. by raising an error, returning ``None``
+instead of a header collection, or whatever is appropriate to the API.
+
+Similarly, if an extension API provides an alternate means of writing
+response data or headers, it should require the ``start_response``
+callable to be passed in, before the application can obtain the
+extended service. If the object passed in is not the same one that
+the server/gateway originally supplied to the application, it cannot
+guarantee correct operation and must refuse to provide the extended
+service to the application.
+
+These guidelines also apply to middleware that adds information such
+as parsed cookies, form variables, sessions, and the like to
+``environ``. Specifically, such middleware should provide these
+features as functions which operate on ``environ``, rather than simply
+stuffing values into ``environ``. This helps ensure that information
+is calculated from ``environ`` *after* any middleware has done any URL
+rewrites or other ``environ`` modifications.
+
+It is very important that these "safe extension" rules be followed by
+both server/gateway and middleware developers, in order to avoid a
+future in which middleware developers are forced to delete any and all
+extension APIs from ``environ`` to ensure that their mediation isn't
+being bypassed by applications using those extensions!
Application Configuration
@@ -1098,6 +1197,37 @@
to re-read it upon each invocation.)
+URL Reconstruction
+------------------
+
+If an application wishes to reconstruct a request's complete URL, it
+may do so using the following algorithm, contributed by Ian Bicking::
+
+ url = environ['wsgi.url_scheme']+'://'
+
+ if environ.get('HTTP_HOST'):
+ url += environ['HTTP_HOST']
+ else:
+ url += environ['SERVER_NAME']
+
+ if environ['wsgi.url_scheme'] == 'https':
+ if environ['SERVER_PORT'] != '443'
+ url += ':' + environ['SERVER_PORT']
+ else:
+ if environ['SERVER_PORT'] != '80':
+ url += ':' + environ['SERVER_PORT']
+
+ url += environ.get('SCRIPT_NAME','')
+ url += environ.get('PATH_INFO','')
+ if environ.get('QUERY_STRING'):
+ url += '?' + environ['QUERY_STRING']
+
+Note that such a reconstructed URL may not be precisely the same URI
+as requested by the client. Server rewrite rules, for example, may
+have modified the client's originally requested URL to place it in a
+canonical form.
+
+
Supporting Older (<2.2) Versions of Python
------------------------------------------
@@ -1146,64 +1276,6 @@
1 and 0 instead of ``True`` and ``False``, etc.)
-
-Server Extension APIs
----------------------
-
-Some server authors may wish to expose more advanced APIs, that
-application or framework authors can use for specialized purposes.
-For example, a gateway based on ``mod_python`` might wish to expose
-part of the Apache API as a WSGI extension.
-
-In the simplest case, this requires nothing more than defining an
-``environ`` variable, such as ``mod_python.some_api``. But, in many
-cases, the possible presence of middleware can make this difficult.
-For example, an API that offers access to the same HTTP headers that
-are found in ``environ`` variables, might return different data if
-``environ`` has been modified by middleware.
-
-In general, any extension API that duplicates, supplants, or bypasses
-some portion of WSGI functionality runs the risk of being incompatible
-with middleware components. Server/gateway developers should *not*
-assume that nobody will use middleware, because some framework
-developers specifically intend to organize or reorganize their
-frameworks to function almost entirely as middleware of various kinds.
-
-So, to provide maximum compatibility, servers and gateways that
-provide extension APIs that replace some WSGI functionality, **must**
-design those APIs so that they are invoked using the portion of the
-API that they replace. For example, an extension API to access HTTP
-request headers must require the application to pass in its current
-``environ``, so that the server/gateway may verify that HTTP headers
-accessible via the API have not been altered by middleware. If the
-extension API cannot guarantee that it will always agree with
-``environ`` about the contents of HTTP headers, it must refuse service
-to the application, e.g. by raising an error, returning ``None``
-instead of a header collection, or whatever is appropriate to the API.
-
-Similarly, if an extension API provides an alternate means of writing
-response data or headers, it should require the ``start_response``
-callable to be passed in, before the application can obtain the
-extended service. If the object passed in is not the same one that
-the server/gateway originally supplied to the application, it cannot
-guarantee correct operation and must refuse to provide the extended
-service to the application.
-
-These guidelines also apply to middleware that adds information such
-as parsed cookies, form variables, sessions, and the like to
-``environ``. Specifically, such middleware should provide these
-features as functions which operate on ``environ``, rather than simply
-stuffing values into ``environ``. This helps ensure that information
-is calculated from ``environ`` *after* any middleware has done any URL
-rewrites or other ``environ`` modifications.
-
-It is very important that these "safe extension" rules be followed by
-both server/gateway and middleware developers, in order to avoid a
-future in which middleware developers are forced to delete any and all
-extension APIs from ``environ`` to ensure that their mediation isn't
-being bypassed by applications using those extensions!
-
-
Optional Platform-Specific File Handling
----------------------------------------
@@ -1302,77 +1374,6 @@
result.close()
-HTTP 1.1 Expect/Continue
-------------------------
-
-Servers and gateways that implement HTTP 1.1 **must** provide
-transparent support for HTTP 1.1's "expect/continue" mechanism. This
-may be done in any of several ways:
-
-1. Respond to requests containing an ``Expect: 100-continue`` request
- with an immediate "100 Continue" response, and proceed normally.
-
-2. Proceed with the request normally, but provide the application
- with a ``wsgi.input`` stream that will send the "100 Continue"
- response if/when the application first attempts to read from the
- input stream. The read request must then remain blocked until the
- client responds.
-
-3. Wait until the client decides that the server does not support
- expect/continue, and sends the request body on its own. (This
- is suboptimal, and is not recommended.)
-
-Note that these behavior restrictions do not apply for HTTP 1.0
-requests, or for requests that are not directed to an application
-object. For more information on HTTP 1.1 Expect/Continue, see RFC
-2616, sections 8.2.3 and 10.1.1.
-
-
-Other HTTP Features
--------------------
-
-In general, servers and gateways should "play dumb" and allow the
-application complete control over its output. They should only make
-changes that do not alter the effective semantics of the application's
-response. It is always possible for the application developer to add
-middleware components to supply additional features, so server/gateway
-developers should be conservative in their implementation. In a sense,
-a server should consider itself to be like an HTTP "proxy server", with
-the application being an HTTP "origin server".
-
-However, because WSGI servers and applications do not communicate via
-HTTP, what RFC 2616 calls "hop-by-hop" headers do not apply to WSGI
-internal communications. WSGI applications **must not** generate any
-"hop-by-hop" headers [4]_, attempt to use HTTP features that would
-require them to generate such headers, or rely on the content of
-any incoming "hop-by-hop" headers in the ``environ`` dictionary.
-WSGI servers **must** handle any supported inbound "hop-by-hop" headers
-on their own, such as by decoding any inbound ``Transfer-Encoding``,
-including chunked encoding if applicable.
-
-Applying these principles to a variety of HTTP features, it should be
-clear that a server **may** handle cache validation via the
-``If-None-Match`` and ``If-Modified-Since`` request headers and the
-``Last-Modified`` and ``ETag`` response headers. However, it is
-not required to do this, and the application **should** perform its
-own cache validation if it wants to support that feature, since
-the server/gateway is not required to do such validation.
-
-Similarly, a server **may** re-encode or transport-encode an
-application's response, but the application **should** use a
-suitable content encoding on its own, and **must not** apply a
-transport encoding. A server **may** transmit byte ranges of the
-application's response if requested by the client, and the
-application doesn't natively support byte ranges. Again, however,
-the application **should** perform this function on its own if desired.
-
-Note that these restrictions on applications do not necessarily mean
-that every application must reimplement every HTTP feature; many HTTP
-features can be partially or fully implemented by middleware
-components, thus freeing both server and application authors from
-implementing the same features over and over again.
-
-
Questions and Answers
=====================
@@ -1518,6 +1519,25 @@
developers.
+Proposed/Under Discussion
+=========================
+
+These items are currently being discussed on the Web-SIG and elsewhere,
+or are on the PEP author's "to-do" list:
+
+* Should ``wsgi.input`` be an iterator instead of a file? This would
+ help for asynchronous applications and chunked-encoding input
+ streams.
+
+* Optional extensions are being discussed for pausing iteration of an
+ application's ouptut until input is available or until a callback
+ occurs.
+
+* Add a section about synchronous vs. asynchronous apps and servers,
+ the relevant threading models, and issues/design goals in these
+ areas.
+
+
Acknowledgements
================
More information about the Python-checkins
mailing list