Added Greg Stein's docs for BaseHTTPServer.py.

Moved docs for "re" to before docs for "regex".

5 files changed, 447 insertions, 12 deletions

diff --git a/Doc/Makefile b/Doc/Makefile
index 72f5802..5548881 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -119,7 +119,8 @@ LIBFILES = lib.tex \
     libbase64.tex libfnmatch.tex libquopri.tex libzlib.tex libsocksvr.tex \
     libmailbox.tex libcommands.tex libcmath.tex libni.tex libgzip.tex \
     libpprint.tex libcode.tex libmimify.tex libre.tex libmacic.tex \
-    libuserdict.tex libdis.tex libxmllib.tex libqueue.tex liblocale.tex
+    libuserdict.tex libdis.tex libxmllib.tex libqueue.tex \
+    liblocale.tex libbasehttp.tex
 
 # Library document
 lib.dvi: $(LIBFILES)
@@ -182,16 +183,16 @@ lib.info: python-lib.info
 # HTML converter.  For more info on this program, see
 # <URL:http://cbl.leeds.ac.uk/nikos/tex2html/doc/latex2html/latex2html.html>.
 
-# Note that LaTeX2HTML inserts references to an "icons" directory in
-# each page that it generates.  You can customize where these icons
-# are to be found; I generally make it point to "../icons" and then
-# create a symbolic link to the icons directory in the LaTeX2HTML
-# source at the appropriate place.  Change the definition of
-# $ICONSERVER in .latex2html-init to point to a different location.
+# Note that LaTeX2HTML inserts references to an icons directory in
+# each page that it generates.  I have placed a copy of this directory
+# in the distribution to simplify the process of creating a
+# self-contained HTML distribution; for this purpose I have also added
+# a (trivial) index.html.  Change the definition of $ICONSERVER in
+# .latex2html-init to use a different location for the icons directory.
 
-# The sed hack rips out a superfluous comma which I haven't found the source
-# of; the prominent location makes it worth the extra step.  This affects the
-# title pages!
+# The sed hack rips out a superfluous comma which I haven't found the
+# source of.  The prominent location makes it worth the extra step;
+# this affects the title pages!
 
 l2h: l2htut l2hext l2hlib l2hapi
 
diff --git a/Doc/lib.tex b/Doc/lib.tex
index 055e61d..5082464 100644
--- a/Doc/lib.tex
+++ b/Doc/lib.tex
@@ -98,9 +98,9 @@ to Python and how to embed it in other applications.
 
 \input{libstrings}		% String Services
 \input{libstring}
+\input{libre}
 \input{libregex}
 \input{libregsub}
-\input{libre}
 \input{libstruct}
 \input{libstrio}
 \input{libsoundex}
@@ -176,6 +176,7 @@ to Python and how to embed it in other applications.
 \input{libsocksvr}
 \input{libmailbox}
 \input{libmimify}
+\input{libbasehttp}
 
 \input{librestricted}
 \input{librexec}
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index 055e61d..5082464 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -98,9 +98,9 @@ to Python and how to embed it in other applications.
 
 \input{libstrings}		% String Services
 \input{libstring}
+\input{libre}
 \input{libregex}
 \input{libregsub}
-\input{libre}
 \input{libstruct}
 \input{libstrio}
 \input{libsoundex}
@@ -176,6 +176,7 @@ to Python and how to embed it in other applications.
 \input{libsocksvr}
 \input{libmailbox}
 \input{libmimify}
+\input{libbasehttp}
 
 \input{librestricted}
 \input{librexec}
diff --git a/Doc/lib/libbasehttp.tex b/Doc/lib/libbasehttp.tex
new file mode 100644
index 0000000..b9e2edb
--- /dev/null
+++ b/Doc/lib/libbasehttp.tex
@@ -0,0 +1,216 @@
+\section{Standard Module \sectcode{BaseHTTPServer}}
+\label{module-BaseHTTPServer}
+\stmodindex{BaseHTTPServer}
+
+\indexii{WWW}{server}
+\indexii{HTTP}{protocol}
+\index{URL}
+\index{httpd}
+
+\renewcommand{\indexsubitem}{(in module BaseHTTPServer)}
+
+This module defines two classes for implementing HTTP servers
+(web servers). Usually, this module isn't used directly, but is used
+as a basis for building functioning web servers. See the
+\code{SimpleHTTPServer} and \code{CGIHTTPServer} modules.
+\stmodindex{SimpleHTTPServer}
+\stmodindex{CGIHTTPServer}
+
+The first class, \code{HTTPServer}, is a \code{SocketServer.TCPServer}
+subclass. It creates and listens at the web socket, dispatching the
+requests to a handler. Code to create and run the server looks like
+this:
+
+\bcode\begin{verbatim}
+def run(server_class=BaseHTTPServer.HTTPServer,
+        handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
+  server_address = ('', 8000)
+  httpd = server_class(server_address, handler_class)
+  httpd.serve_forever()
+\end{verbatim}\ecode
+%
+The \code{HTTPServer} class builds on the \code{TCPServer} class by
+storing the server address as instance
+variables named \code{server_name} and \code{server_port}. The
+server is accessible by the handler, typically through the handler's
+\code{server} instance variable.
+
+The module's second class, \code{BaseHTTPRequestHandler}, is used
+to handle the HTTP requests that arrive at the server. By itself,
+it cannot respond to any actual HTTP requests; it must be subclassed
+to handle each request method (e.g. GET or POST).
+\code{BaseHTTPRequestHandler} provides a number of class and instance
+variables, and methods for use by subclasses.
+
+The handler will parse the request and the headers, then call a
+method specific to the request type. The method name is constructed
+from the request. For example, for the request \code{SPAM}, the
+\code{do_SPAM} method will be called with no arguments. All of
+the relevant information is stored into instance variables of the
+handler.
+
+\renewcommand{\indexsubitem}{(BaseHTTPRequestHandler instance variables)}
+
+\code{BaseHTTPRequestHandler} has the following instance variables:
+
+\begin{datadesc}{client_address}
+Contains a tuple of the form (host, port) referring to the client's
+address.
+\end{datadesc}
+
+\begin{datadesc}{command}
+Contains the command (request type). For example, \code{"GET"}.
+\end{datadesc}
+
+\begin{datadesc}{path}
+Contains the request path.
+\end{datadesc}
+
+\begin{datadesc}{request_version}
+Contains the version string from the request. For example,
+\code{"HTTP/1.0"}.
+\end{datadesc}
+
+\begin{datadesc}{headers}
+Holds an instance of the class specified by the \var{MessageClass}
+class variable. This instance parses and manages the headers in
+the HTTP request.
+\end{datadesc}
+
+\begin{datadesc}{rfile}
+Contains an input stream, positioned at the start of the optional
+input data.
+\end{datadesc}
+
+\begin{datadesc}{wfile}
+Contains the output stream for writing a response back to the client.
+Proper adherance to the HTTP protocol must be used when writing
+to this stream.
+\end{datadesc}
+
+\renewcommand{\indexsubitem}{(BaseHTTPRequestHandler class variables)}
+
+\code{BaseHTTPRequestHandler} has the following class variables:
+
+\begin{datadesc}{server_version}
+Specifies the server software version.  You may want to override
+this.
+The format is multiple whitespace-separated strings,
+where each string is of the form name[/version].
+For example, \code{"BaseHTTP/0.2"}.
+\end{datadesc}
+
+\begin{datadesc}{sys_version}
+Contains the Python system version, in a form usable by the
+\code{version_string} method and the \code{server_version} class
+variable. For example, \code{"Python/1.4"}.
+\end{datadesc}
+
+\begin{datadesc}{error_message_format}
+Specifies a format string for building an error response to the
+client. It uses parenthesized, keyed format specifiers, so the
+format operand must be a dictionary. The \var{code} key should
+be an integer, specifing the numeric HTTP error code value.
+\var{message} should be a string containing a (detailed) error
+message of what occurred, and \var{explain} should be an
+explanation of the error code number. Default \var{message}
+and \var{explain} values can found in the \var{responses}
+class variable.
+\end{datadesc}
+
+\begin{datadesc}{protocol_version}
+This specifies the HTTP protocol version used in responses.
+Typically, this should not be overridden. Defaults to
+\code{"HTTP/1.0"}.
+\end{datadesc}
+
+\begin{datadesc}{MessageClass}
+Specifies a Message-like class to parse HTTP headers. Typically,
+this is not overridden, and it defaults to \code{mimetools.Message}.
+\end{datadesc}
+
+\begin{datadesc}{responses}
+This variable contains a mapping of error code integers to two-element
+tuples containing a short and long message. For example,
+\code{\{code : (shortmessage, longmessage)\}}. The
+\var{shortmessage} is usually used as the \var{message} key in an
+error response, and \var{longmessage} as the \var{explain} key
+(see the \code{error_message_format} class variable).
+\end{datadesc}
+
+\renewcommand{\indexsubitem}{(BaseHTTPRequestHandler method)}
+
+A \code{BaseHTTPRequestHandler} instance has the following methods:
+
+\begin{funcdesc}{handle}{}
+Overrides the superclass' \code{handle} method to provide the
+specific handler behavior. This method will parse and dispatch
+the request to the appropriate \code{do_}* method.
+\end{funcdesc}
+
+\begin{funcdesc}{send_error}{code\optional{\, message}}
+Sends and logs a complete error reply to the client. The numeric
+\var{code} specifies the HTTP error code, with \var{message} as
+optional, more specific text. A complete set of headers is sent,
+followed by text composed using the \code{error_message_format}
+class variable.
+\end{funcdesc}
+
+\begin{funcdesc}{send_response}{code\optional{\, message}}
+Sends a response header and logs the accepted request. The HTTP
+response line is sent, followed by \emph{Server} and \emph{Date}
+headers. The values for these two headers are picked up from the
+\code{version_string()} and \code{date_time_string()} methods,
+respectively.
+\end{funcdesc}
+
+\begin{funcdesc}{send_header}{keyword\, value}
+Writes a specific MIME header to the output stream. \var{keyword}
+should specify the header keyword, with \var{value} specifying
+its value.
+\end{funcdesc}
+
+\begin{funcdesc}{end_headers}{}
+Sends a blank line, indicating the end of the MIME headers in
+the response.
+\end{funcdesc}
+
+\begin{funcdesc}{log_request}{\optional{code\optional{\, size}}}
+Logs an accepted (successful) request. \var{code} should specify
+the numeric HTTP code associated with the response. If a size of
+the response is available, then it should be passed as the
+\var{size} parameter.
+\end{funcdesc}
+
+\begin{funcdesc}{log_error}{...}
+Logs an error when a request cannot be fulfilled. By default,
+it passes the message to \code{log_message}, so it takes the
+same arguments (\var{format} and additional values).
+\end{funcdesc}
+
+\begin{funcdesc}{log_message}{format, ...}
+Logs an arbitrary message to \code{sys.stderr}. This is typically
+overridden to create custom error logging mechanisms. The
+\var{format} argument is a standard printf-style format string,
+where the additional arguments to \code{log_message} are applied
+as inputs to the formatting. The client address and current date
+and time are prefixed to every message logged.
+\end{funcdesc}
+
+\begin{funcdesc}{version_string}{}
+Returns the server software's version string. This is a combination
+of the \var{server_version} and \var{sys_version} class variables.
+\end{funcdesc}
+
+\begin{funcdesc}{date_time_string}{}
+Returns the current date and time, formatted for a message header.
+\end{funcdesc}
+
+\begin{funcdesc}{log_data_time_string}{}
+Returns the current date and time, formatted for logging.
+\end{funcdesc}
+
+\begin{funcdesc}{address_string}{}
+Returns the client address, formatted for logging. A name lookup
+is performed on the client's IP address.
+\end{funcdesc}
diff --git a/Doc/libbasehttp.tex b/Doc/libbasehttp.tex
new file mode 100644
index 0000000..b9e2edb
--- /dev/null
+++ b/Doc/libbasehttp.tex
@@ -0,0 +1,216 @@
+\section{Standard Module \sectcode{BaseHTTPServer}}
+\label{module-BaseHTTPServer}
+\stmodindex{BaseHTTPServer}
+
+\indexii{WWW}{server}
+\indexii{HTTP}{protocol}
+\index{URL}
+\index{httpd}
+
+\renewcommand{\indexsubitem}{(in module BaseHTTPServer)}
+
+This module defines two classes for implementing HTTP servers
+(web servers). Usually, this module isn't used directly, but is used
+as a basis for building functioning web servers. See the
+\code{SimpleHTTPServer} and \code{CGIHTTPServer} modules.
+\stmodindex{SimpleHTTPServer}
+\stmodindex{CGIHTTPServer}
+
+The first class, \code{HTTPServer}, is a \code{SocketServer.TCPServer}
+subclass. It creates and listens at the web socket, dispatching the
+requests to a handler. Code to create and run the server looks like
+this:
+
+\bcode\begin{verbatim}
+def run(server_class=BaseHTTPServer.HTTPServer,
+        handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
+  server_address = ('', 8000)
+  httpd = server_class(server_address, handler_class)
+  httpd.serve_forever()
+\end{verbatim}\ecode
+%
+The \code{HTTPServer} class builds on the \code{TCPServer} class by
+storing the server address as instance
+variables named \code{server_name} and \code{server_port}. The
+server is accessible by the handler, typically through the handler's
+\code{server} instance variable.
+
+The module's second class, \code{BaseHTTPRequestHandler}, is used
+to handle the HTTP requests that arrive at the server. By itself,
+it cannot respond to any actual HTTP requests; it must be subclassed
+to handle each request method (e.g. GET or POST).
+\code{BaseHTTPRequestHandler} provides a number of class and instance
+variables, and methods for use by subclasses.
+
+The handler will parse the request and the headers, then call a
+method specific to the request type. The method name is constructed
+from the request. For example, for the request \code{SPAM}, the
+\code{do_SPAM} method will be called with no arguments. All of
+the relevant information is stored into instance variables of the
+handler.
+
+\renewcommand{\indexsubitem}{(BaseHTTPRequestHandler instance variables)}
+
+\code{BaseHTTPRequestHandler} has the following instance variables:
+
+\begin{datadesc}{client_address}
+Contains a tuple of the form (host, port) referring to the client's
+address.
+\end{datadesc}
+
+\begin{datadesc}{command}
+Contains the command (request type). For example, \code{"GET"}.
+\end{datadesc}
+
+\begin{datadesc}{path}
+Contains the request path.
+\end{datadesc}
+
+\begin{datadesc}{request_version}
+Contains the version string from the request. For example,
+\code{"HTTP/1.0"}.
+\end{datadesc}
+
+\begin{datadesc}{headers}
+Holds an instance of the class specified by the \var{MessageClass}
+class variable. This instance parses and manages the headers in
+the HTTP request.
+\end{datadesc}
+
+\begin{datadesc}{rfile}
+Contains an input stream, positioned at the start of the optional
+input data.
+\end{datadesc}
+
+\begin{datadesc}{wfile}
+Contains the output stream for writing a response back to the client.
+Proper adherance to the HTTP protocol must be used when writing
+to this stream.
+\end{datadesc}
+
+\renewcommand{\indexsubitem}{(BaseHTTPRequestHandler class variables)}
+
+\code{BaseHTTPRequestHandler} has the following class variables:
+
+\begin{datadesc}{server_version}
+Specifies the server software version.  You may want to override
+this.
+The format is multiple whitespace-separated strings,
+where each string is of the form name[/version].
+For example, \code{"BaseHTTP/0.2"}.
+\end{datadesc}
+
+\begin{datadesc}{sys_version}
+Contains the Python system version, in a form usable by the
+\code{version_string} method and the \code{server_version} class
+variable. For example, \code{"Python/1.4"}.
+\end{datadesc}
+
+\begin{datadesc}{error_message_format}
+Specifies a format string for building an error response to the
+client. It uses parenthesized, keyed format specifiers, so the
+format operand must be a dictionary. The \var{code} key should
+be an integer, specifing the numeric HTTP error code value.
+\var{message} should be a string containing a (detailed) error
+message of what occurred, and \var{explain} should be an
+explanation of the error code number. Default \var{message}
+and \var{explain} values can found in the \var{responses}
+class variable.
+\end{datadesc}
+
+\begin{datadesc}{protocol_version}
+This specifies the HTTP protocol version used in responses.
+Typically, this should not be overridden. Defaults to
+\code{"HTTP/1.0"}.
+\end{datadesc}
+
+\begin{datadesc}{MessageClass}
+Specifies a Message-like class to parse HTTP headers. Typically,
+this is not overridden, and it defaults to \code{mimetools.Message}.
+\end{datadesc}
+
+\begin{datadesc}{responses}
+This variable contains a mapping of error code integers to two-element
+tuples containing a short and long message. For example,
+\code{\{code : (shortmessage, longmessage)\}}. The
+\var{shortmessage} is usually used as the \var{message} key in an
+error response, and \var{longmessage} as the \var{explain} key
+(see the \code{error_message_format} class variable).
+\end{datadesc}
+
+\renewcommand{\indexsubitem}{(BaseHTTPRequestHandler method)}
+
+A \code{BaseHTTPRequestHandler} instance has the following methods:
+
+\begin{funcdesc}{handle}{}
+Overrides the superclass' \code{handle} method to provide the
+specific handler behavior. This method will parse and dispatch
+the request to the appropriate \code{do_}* method.
+\end{funcdesc}
+
+\begin{funcdesc}{send_error}{code\optional{\, message}}
+Sends and logs a complete error reply to the client. The numeric
+\var{code} specifies the HTTP error code, with \var{message} as
+optional, more specific text. A complete set of headers is sent,
+followed by text composed using the \code{error_message_format}
+class variable.
+\end{funcdesc}
+
+\begin{funcdesc}{send_response}{code\optional{\, message}}
+Sends a response header and logs the accepted request. The HTTP
+response line is sent, followed by \emph{Server} and \emph{Date}
+headers. The values for these two headers are picked up from the
+\code{version_string()} and \code{date_time_string()} methods,
+respectively.
+\end{funcdesc}
+
+\begin{funcdesc}{send_header}{keyword\, value}
+Writes a specific MIME header to the output stream. \var{keyword}
+should specify the header keyword, with \var{value} specifying
+its value.
+\end{funcdesc}
+
+\begin{funcdesc}{end_headers}{}
+Sends a blank line, indicating the end of the MIME headers in
+the response.
+\end{funcdesc}
+
+\begin{funcdesc}{log_request}{\optional{code\optional{\, size}}}
+Logs an accepted (successful) request. \var{code} should specify
+the numeric HTTP code associated with the response. If a size of
+the response is available, then it should be passed as the
+\var{size} parameter.
+\end{funcdesc}
+
+\begin{funcdesc}{log_error}{...}
+Logs an error when a request cannot be fulfilled. By default,
+it passes the message to \code{log_message}, so it takes the
+same arguments (\var{format} and additional values).
+\end{funcdesc}
+
+\begin{funcdesc}{log_message}{format, ...}
+Logs an arbitrary message to \code{sys.stderr}. This is typically
+overridden to create custom error logging mechanisms. The
+\var{format} argument is a standard printf-style format string,
+where the additional arguments to \code{log_message} are applied
+as inputs to the formatting. The client address and current date
+and time are prefixed to every message logged.
+\end{funcdesc}
+
+\begin{funcdesc}{version_string}{}
+Returns the server software's version string. This is a combination
+of the \var{server_version} and \var{sys_version} class variables.
+\end{funcdesc}
+
+\begin{funcdesc}{date_time_string}{}
+Returns the current date and time, formatted for a message header.
+\end{funcdesc}
+
+\begin{funcdesc}{log_data_time_string}{}
+Returns the current date and time, formatted for logging.
+\end{funcdesc}
+
+\begin{funcdesc}{address_string}{}
+Returns the client address, formatted for logging. A name lookup
+is performed on the client's IP address.
+\end{funcdesc}