Document wsgiref.validate and (partially) wsgiref.handlers. Add __all__

to wsgiref.handlers and rename wsgiref.validate.middleware to 
wsgiref.validate.validator.


git-svn-id: svn://svn.eby-sarna.com/svnroot/wsgiref@2175 571e12c6-e1fa-0310-aee7-ff1267fa46bd

4 files changed, 89 insertions, 33 deletions

diff --git a/docs/libwsgiref.tex b/docs/libwsgiref.tex
index ba9f194..3f021c5 100755
--- a/docs/libwsgiref.tex
+++ b/docs/libwsgiref.tex
@@ -370,51 +370,107 @@ WSGI application interface.
 \subsection{\module{wsgiref.validate} -- WSGI conformance checker}
 \declaremodule{}{wsgiref.validate}
 
-\begin{funcdesc}{middleware}{application}
+When creating new WSGI application objects, frameworks, servers, or
+middleware, it can be useful to validate the new code's conformance
+using \module{wsgiref.validate}.  This module provides a function that
+creates WSGI application objects that validate communications between
+a WSGI server or gateway and a WSGI application object, to check both
+sides for protocol conformance.
+
+Note that this utility does not guarantee complete \pep{333} compliance;
+an absence of errors from this module does not necessarily mean that
+errors do not exist.  However, if this module does produce an error,
+then it is virtually certain that either the server or application is
+not 100\% compliant.
+
+\begin{funcdesc}{validator}{application}
+Wrap \var{application} and return a new WSGI application object.  The
+returned application will forward all requests to the original
+\var{application}, and will check that both the \var{application} and
+the server invoking it are conforming to the WSGI specification and to
+RFC 2616.
+
+Any detected nonconformance results in an AssertionError being raised;
+note, however, that how these errors are handled is server-dependent.
+For example, \module{wsgiref.simple_server} and other servers based on
+\module{wsgiref.handlers} (that don't override the error handling
+methods to do something else) will simply output a message that an error
+has occurred, and dump the traceback to \code{sys.stderr} or some other
+error stream.
+
+This wrapper may also generate output using the \module{warnings} module
+to indicate behaviors that are questionable but which may not actually
+be prohibited by \pep{333}.  Unless they are suppressed using Python
+command-line options or the \module{warnings} API, any such warnings
+will be written to \code{sys.stderr} (NOT \code{wsgi.errors}, unless
+they happen to be the same object).
 \end{funcdesc}
 
 
 
+\subsection{\module{wsgiref.handlers} -- server/gateway base classes}
+\declaremodule{}{wsgiref.handlers}
 
+This module provides base handler classes for implementing WSGI servers
+and gateways.  These base classes handle most of the work of
+communicating with a WSGI application, as long as they are given a
+CGI-like environment, along with input, output, and error streams.
 
 
+\begin{classdesc}{CGIHandler}{}
+CGI-based invocation via \code{sys.stdin}, \code{sys.stdout},
+\code{sys.stderr} and \code{os.environ}.  This is useful when you have
+a WSGI application and want to run it as a CGI script.  Simply invoke
+\code{CGIHandler().run(app)}, where \code{app} is the WSGI application
+object you wish to invoke.
 
+This class is a subclass of \class{BaseCGIHandler} that sets
+\code{wsgi.run_once} to true, \code{wsgi.multithread} to false, and
+\code{wsgi.multiprocess} to true, and always uses \module{sys} and
+\module{os} to obtain the necessary CGI streams and environment.
+\end{classdesc}
 
 
+\begin{classdesc}{BaseCGIHandler}{stdin, stdout, stderr, environ
+\optional{,multithread=True \optional{, multiprocess=False}}}
 
+Similar to \class{CGIHandler}, but instead of using the \module{sys} and
+\module{os} modules, the CGI environment and I/O streams are specified
+explicitly.  The \var{multithread} and \var{multiprocess} values are
+used to set the \code{wsgi.multithread} and \code{wsgi.multiprocess}
+flags for any applications run by the handler instance.
 
+This class is a subclass of \class{SimpleHandler} intended for use with
+software other than HTTP ``origin servers''.  If you are writing a
+gateway protocol implementation (such as CGI, FastCGI, SCGI, etc.) that
+uses a \code{Status:} header to send an HTTP status, you probably want
+to subclass this instead of \class{SimpleHandler}.
+\end{classdesc}
 
 
 
 
+\begin{classdesc}{SimpleHandler}{stdin, stdout, stderr, environ
+\optional{,multithread=True \optional{, multiprocess=False}}}
 
+Similar to \class{BaseCGIHandler}, but designed for use with HTTP origin
+servers.  If you are writing an HTTP server implementation, you will
+probably want to subclass this instead of \class{BaseCGIHandler}
 
+This class is a subclass of \class{BaseHandler}.  It overrides the
+\method{__init__()}, \method{get_stdin()}, \method{get_stderr()},
+\method{add_cgi_vars()}, \method{_write()}, and \method{_flush()}
+methods to support explicitly setting the environment and streams via
+the constructor.  The supplied environment and streams are stored in
+the \member{stdin}, \member{stdout}, \member{stderr}, and
+\member{environ} attributes.
+\end{classdesc}
 
+\begin{classdesc}{BaseHandler}{}
+This is an abstract base class for running WSGI applications.
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-\subsection{\module{wsgiref.handlers} -- server/gateway base classes}
-\declaremodule{}{wsgiref.handlers}
-
-
-
-
-
+XXX lots of stuff here  :(
+\end{classdesc}
 
 
 
diff --git a/test_wsgiref.py b/test_wsgiref.py
index da9b180..ffcabe4 100755
--- a/test_wsgiref.py
+++ b/test_wsgiref.py
@@ -4,7 +4,7 @@ from wsgiref.util import setup_testing_defaults
 from wsgiref.headers import Headers
 from wsgiref.handlers import BaseHandler, BaseCGIHandler
 from wsgiref import util
-from wsgiref.validate import middleware
+from wsgiref.validate import validator
 from wsgiref.simple_server import WSGIServer, WSGIRequestHandler, demo_app
 from wsgiref.simple_server import make_server
 from StringIO import StringIO
@@ -139,7 +139,7 @@ class IntegrationTests(TestCase):
         self.check_hello(out)
 
     def test_validated_hello(self):
-        out, err = run_amock(middleware(hello_app))
+        out, err = run_amock(validator(hello_app))
         # the middleware doesn't support len(), so content-length isn't there
         self.check_hello(out, has_length=False)
 
@@ -147,7 +147,7 @@ class IntegrationTests(TestCase):
         def bad_app(environ,start_response):
             start_response("200 OK", ('Content-Type','text/plain'))
             return ["Hello, world!"]
-        out, err = run_amock(middleware(bad_app))
+        out, err = run_amock(validator(bad_app))
         self.failUnless(out.endswith(
             "A server error occurred.  Please contact the administrator."
         ))
diff --git a/wsgiref/handlers.py b/wsgiref/handlers.py
index 572cf0d..d4478c7 100644
--- a/wsgiref/handlers.py
+++ b/wsgiref/handlers.py
@@ -6,6 +6,8 @@ from headers import Headers
 
 import sys, os, time
 
+__all__ = ['BaseHandler', 'SimpleHandler', 'BaseCGIHandler', 'CGIHandler']
+
 try:
     dict
 except NameError:
@@ -37,8 +39,6 @@ def format_date_time(timestamp):
 
 
 
-
-
 class BaseHandler:
     """Manage the invocation of a WSGI application"""
 
@@ -375,7 +375,7 @@ class SimpleHandler(BaseHandler):
 
     Usage::
 
-        handler = BaseCGIHandler(
+        handler = SimpleHandler(
             inp,out,err,env, multithread=False, multiprocess=True
         )
         handler.run(app)"""
diff --git a/wsgiref/validate.py b/wsgiref/validate.py
index af903df..e72c507 100755
--- a/wsgiref/validate.py
+++ b/wsgiref/validate.py
@@ -108,7 +108,7 @@ Some of the things this checks:
     sys.stderr, because we only know it isn't called when the object
     is garbage collected).
 """
-__all__ = ['middleware']
+__all__ = ['validator']
 
 
 import re
@@ -124,7 +124,7 @@ class WSGIWarning(Warning):
     Raised in response to WSGI-spec-related warnings
     """
 
-def middleware(application):
+def validator(application):
 
     """
     When applied between a WSGI server and a WSGI application, this