[Python-checkins] r46006 - sandbox/trunk/wsgiref-docs/wsgiref.tex

[andrew.kuchling]

Author: andrew.kuchling
Date: Mon May 15 22:43:03 2006
New Revision: 46006

Modified:
   sandbox/trunk/wsgiref-docs/wsgiref.tex
Log:
Add some text

Modified: sandbox/trunk/wsgiref-docs/wsgiref.tex
==============================================================================
--- sandbox/trunk/wsgiref-docs/wsgiref.tex	(original)
+++ sandbox/trunk/wsgiref-docs/wsgiref.tex	Mon May 15 22:43:03 2006
@@ -1,17 +1,24 @@
 
 \section{wsgiref}
+\moduleauthor{XXX}
 
-XXX write introduction
+The Web Server Gateway Interface (WSGI) is a standard interface
+between web server software and web applications written in Python.
+Having a standard interface makes it easy to use a WSGI-supporting
+application with a number of different web servers.
+
+Only authors of web servers and programming frameworks need to know
+every detail and corner case of the WSGI design.  You don't need to
+understand every detail of WSGI just to install a WSGI application or
+to write a web application using an existing framework.  
+
+\module{wsgiref} is a reference implementation of the WSGI specification
+that can be used to add WSGI support to a web server or framework.
+If you're just trying to write a web application, 
+% XXX should create a URL on python.org to point people to.
 
-\subsection{Web Server Gateway Interface}
+For the complete WSGI specification, see \pep{333}.
 
-Brief overview of application interface
-
-app(environ, start_response):
-   call start_response(status, header)
-   return iterable w/ text context
-
-Reference to PEP 333
 
 \subsection{wsgiref.handlers}
 
@@ -24,26 +31,58 @@
 CGIHandler
 
 
-\subsection{wsgiref.util}
-
-FileWrapper
+%\subsection{wsgiref.util}
 
-% XXX document guess_scheme, application_uri, request_uri, shift_path_info,
-% setup_testing_defaults?
+% XXX document FileWrapper, guess_scheme, application_uri,
+% request_uri, shift_path_info, setup_testing_defaults?
 
 \subsection{wsgiref.simple_server}
 
-WSGIServer
-
-WSGIRequestHandler
-
-demo_app
+This module contains the \class{WSGIServer} class, 
+a subclass of \class{BaseHTTPServer.HTTPServer} that 
+forwards requests to a WSGI application.   There's also a simple
+hello-world application called \function{demo_app} that's useful for 
+testing when 
+
+\begin{methoddesc}[WSGIServer]{set_app}{application}
+Sets the callable \var{application} as the application 
+that will receive requests.
+\end{methoddesc}
+
+\begin{methoddesc}[WSGIServer]{get_app}{}
+Returns the currently-set application callable.
+\end{methoddesc}
+
+\begin{funcdesc}{demo_app}{environ, start_response}
+This function is a small but complete WSGI application that 
+returns a text page containing the message ``Hello world!''
+and a list of the key/value pairs provided in the 
+\var{environ} parameter.
+\end{funcdesc}
 
 \subsection{Examples}
 
-Simple application: trivial 'hello world'
-
-Set up a server to run one application
+The following example uses the \class{WSGIServer} class 
+to publish the \function{demo_app} example application.  
+You can change the application by modifying the call 
+to \method{set_app()}.
+
+\begin{verbatim}
+from wsgiref import simple_server
+
+server_address = ('', 8000)
+httpd = simple_server.WSGIServer(server_address,
+                                 simple_server.WSGIRequestHandler)
+httpd.set_app(simple_server.demo_app)
+
+print "Serving HTTP on port", server_address[1], "..."
+
+# Respond to requests until process is killed
+httpd.serve_forever()
+
+# Alternative: serve one request, then exit
+##httpd.handle_request()  
+\end{verbatim}
 
 Other ideas?