Flesh out CGI variable definitions, and slightly loosen server-side

requirements for providing variables that may be empty.  That's
the last of the open issues, so it's time for another posting, and
a last call for issues prior to finalization.

pep-0333.txt

@@ -350,47 +350,63 @@ APIs are acceptable.
 
 The ``environ`` dictionary is required to contain these CGI
 environment variables, as defined by the Common Gateway Interface
-specification [2]_.  The following variables **must** be present, but
-**may** be an empty string, if there is no more appropriate value for
-them:
+specification [2]_.  The following variables **must** be present,
+unless their value would be an empty string, in which case they
+**may** be omitted, except as otherwise noted below.
 
-* ``REQUEST_METHOD``
+``REQUEST_METHOD``
+  The HTTP request method, such as ``"GET"`` or ``"POST"``.  This 
+  cannot ever be an empty string, and so is always required.
 
-* ``SCRIPT_NAME`` (The initial portion of the request URL's "path"
-  that corresponds to the application object, so that the application
-  knows its virtual "location".)
+``SCRIPT_NAME`` 
+  The initial portion of the request URL's "path" that corresponds to
+  the application object, so that the application knows its virtual 
+  "location".  This **may** be an empty string, if the application
+  corresponds to the "root" of the server.  
 
-* ``PATH_INFO`` (The remainder of the request URL's "path",
-   designating the virtual "location" of the request's target within
-   the application)
+``PATH_INFO``
+  The remainder of the request URL's "path", designating the virtual 
+  "location" of the request's target within the application.  This
+  **may** be an empty string, if the request URL targets the 
+  application root and does not have a trailing slash.
 
-* ``QUERY_STRING``
+``QUERY_STRING``
+  The portion of the request URL that follows the ``"?"``, if any.
+  May be empty or absent.
 
-* ``CONTENT_TYPE``
+``CONTENT_TYPE``
+  The contents of any ``Content-Type`` fields in the HTTP request.
+  May be empty or absent.
 
-* ``CONTENT_LENGTH``
+``CONTENT_LENGTH``
+  The contents of any ``Content-Length`` fields in the HTTP request.
+  May be empty or absent.
 
-* ``SERVER_NAME`` and ``SERVER_PORT`` (which, when combined with
-  ``SCRIPT_NAME`` and ``PATH_INFO``, should complete the URL.  Note,
-  however, that ``HTTP_HOST``, if present, should be used in
-  preference to ``SERVER_NAME`` for constructing the URL.  See the
-  `URL Reconstruction`_ section below for more detail.)
+``SERVER_NAME``, ``SERVER_PORT``
+  When combined with ``SCRIPT_NAME`` and ``PATH_INFO``, these variables
+  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`_
+  section below for more detail.   ``SERVER_NAME`` and ``SERVER_PORT``
+  can never be empty strings, and so are always required.
 
-* Variables corresponding to the client-supplied HTTP headers (i.e.,
-  variables whose names begin with ``"HTTP_"``).
+``HTTP_`` Variables
+  Variables corresponding to the client-supplied HTTP headers (i.e.,
+  variables whose names begin with ``"HTTP_"``).  The presence or
+  absence of these variables should correspond with the presence or
+  absence of the appropriate HTTP header in the request.
 
-In general, a server or gateway should attempt to provide as many
+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.
-However, an application that uses any variables other than the ones
+However, an application that uses any CGI variables other than the ones
 listed above are necessarily non-portable to web servers that do not
 support the relevant extensions.
 
-A WSGI-compliant server or gateway *should* document what variables it
-provides, along with their definitions as appropriate.  Applications
-*should* check for the presence of any nonstandard variables they
-require, and have a fallback plan in the event such a variable is
-absent.
+A WSGI-compliant server or gateway **should** document what variables
+it provides, along with their definitions as appropriate.  Applications
+**should** check for the presence of any variables they require, and 
+have a fallback plan in the event such a variable is absent.
 
 Note: missing variables (such as ``REMOTE_USER`` when no
 authentication has occurred) should be left out of the ``environ``
@@ -867,8 +883,8 @@ may do so using the following algorithm, contributed by Ian Bicking::
         if environ['SERVER_PORT'] != '80':
            url += ':' + environ['SERVER_PORT']
 
-    url += environ['SCRIPT_NAME']
-    url += environ['PATH_INFO']
+    url += environ.get('SCRIPT_NAME','')
+    url += environ.get('PATH_INFO','')
     if environ.get('QUERY_STRING'):
         url += '?' + environ['QUERY_STRING']
 
@@ -1360,13 +1376,6 @@ Questions and Answers
    developers.
 
 
-Open Issues
-===========
-
-* Required CGI variables: should we really be requiring all of the
-  variables named?  Some of them seem reasonable to be optional.
-
-
 Acknowledgements
 ================