Remove obsolete \setindexsubitem macros.
Massive migration to methoddesc and memberdesc.
Logical markup as needed.
A sprinkling of index entries for flavor.
diff --git a/Doc/lib/libbasehttp.tex b/Doc/lib/libbasehttp.tex
index 2a4a7d0..7ee55df 100644
--- a/Doc/lib/libbasehttp.tex
+++ b/Doc/lib/libbasehttp.tex
@@ -1,4 +1,4 @@
-\section{Standard Module \sectcode{BaseHTTPServer}}
+\section{Standard Module \module{BaseHTTPServer}}
\label{module-BaseHTTPServer}
\stmodindex{BaseHTTPServer}
@@ -23,18 +23,21 @@
\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()
+ server_address = ('', 8000)
+ httpd = server_class(server_address, handler_class)
+ httpd.serve_forever()
\end{verbatim}
-The \class{HTTPServer} class builds on the \class{TCPServer} class by
+\begin{classdesc}{HTTPServer}{server_address, RequestHandlerClass}
+This class builds on the \class{TCPServer} class by
storing the server address as instance
variables named \member{server_name} and \member{server_port}. The
server is accessible by the handler, typically through the handler's
\member{server} instance variable.
+\end{classdesc}
-The module's second class, \class{BaseHTTPRequestHandler}, is used
+\begin{classdesc}{BaseHTTPRequestHandler}{request, client_address, server}
+This class 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).
@@ -43,69 +46,69 @@
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 \samp{SPAM}, the
+from the request. For example, for the request method \samp{SPAM}, the
\method{do_SPAM()} method will be called with no arguments. All of
-the relevant information is stored into instance variables of the
-handler.
+the relevant information is stored in instance variables of the
+handler. Subclasses should not need to override or extend the
+\method{__init__()} method.
+\end{classdesc}
-\setindexsubitem{(BaseHTTPRequestHandler attribute)}
\class{BaseHTTPRequestHandler} has the following instance variables:
-\begin{datadesc}{client_address}
+\begin{memberdesc}{client_address}
Contains a tuple of the form \code{(\var{host}, \var{port})} referring
to the client's address.
-\end{datadesc}
+\end{memberdesc}
-\begin{datadesc}{command}
+\begin{memberdesc}{command}
Contains the command (request type). For example, \code{'GET'}.
-\end{datadesc}
+\end{memberdesc}
-\begin{datadesc}{path}
+\begin{memberdesc}{path}
Contains the request path.
-\end{datadesc}
+\end{memberdesc}
-\begin{datadesc}{request_version}
+\begin{memberdesc}{request_version}
Contains the version string from the request. For example,
\code{'HTTP/1.0'}.
-\end{datadesc}
+\end{memberdesc}
-\begin{datadesc}{headers}
+\begin{memberdesc}{headers}
Holds an instance of the class specified by the \member{MessageClass}
class variable. This instance parses and manages the headers in
the HTTP request.
-\end{datadesc}
+\end{memberdesc}
-\begin{datadesc}{rfile}
+\begin{memberdesc}{rfile}
Contains an input stream, positioned at the start of the optional
input data.
-\end{datadesc}
+\end{memberdesc}
-\begin{datadesc}{wfile}
+\begin{memberdesc}{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}
+\end{memberdesc}
-\setindexsubitem{(BaseHTTPRequestHandler attribute)}
-\code{BaseHTTPRequestHandler} has the following class variables:
+\class{BaseHTTPRequestHandler} has the following class variables:
-\begin{datadesc}{server_version}
+\begin{memberdesc}{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}
+\end{memberdesc}
-\begin{datadesc}{sys_version}
+\begin{memberdesc}{sys_version}
Contains the Python system version, in a form usable by the
\member{version_string} method and the \member{server_version} class
variable. For example, \code{'Python/1.4'}.
-\end{datadesc}
+\end{memberdesc}
-\begin{datadesc}{error_message_format}
+\begin{memberdesc}{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
@@ -115,103 +118,102 @@
explanation of the error code number. Default \var{message}
and \var{explain} values can found in the \var{responses}
class variable.
-\end{datadesc}
+\end{memberdesc}
-\begin{datadesc}{protocol_version}
+\begin{memberdesc}{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}
+\end{memberdesc}
-\begin{datadesc}{MessageClass}
+\begin{memberdesc}{MessageClass}
Specifies a \class{rfc822.Message}-like class to parse HTTP
headers. Typically, this is not overridden, and it defaults to
\class{mimetools.Message}.
\withsubitem{(in module mimetools)}{\ttindex{Message}}
-\end{datadesc}
+\end{memberdesc}
-\begin{datadesc}{responses}
+\begin{memberdesc}{responses}
This variable contains a mapping of error code integers to two-element
tuples containing a short and long message. For example,
\code{\{\var{code}: (\var{shortmessage}, \var{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 \member{error_message_format} class variable).
-\end{datadesc}
+\end{memberdesc}
-\setindexsubitem{(BaseHTTPRequestHandler method)}
A \class{BaseHTTPRequestHandler} instance has the following methods:
-\begin{funcdesc}{handle}{}
+\begin{methoddesc}{handle}{}
Overrides the superclass' \method{handle()} method to provide the
specific handler behavior. This method will parse and dispatch
-the request to the appropriate \code{do_*()} method.
-\end{funcdesc}
+the request to the appropriate \method{do_*()} method.
+\end{methoddesc}
-\begin{funcdesc}{send_error}{code\optional{, message}}
+\begin{methoddesc}{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 \member{error_message_format}
class variable.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{send_response}{code\optional{, message}}
+\begin{methoddesc}{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
\method{version_string()} and \method{date_time_string()} methods,
respectively.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{send_header}{keyword, value}
+\begin{methoddesc}{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}
+\end{methoddesc}
-\begin{funcdesc}{end_headers}{}
+\begin{methoddesc}{end_headers}{}
Sends a blank line, indicating the end of the MIME headers in
the response.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{log_request}{\optional{code\optional{, size}}}
+\begin{methoddesc}{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}
+\end{methoddesc}
-\begin{funcdesc}{log_error}{...}
+\begin{methoddesc}{log_error}{...}
Logs an error when a request cannot be fulfilled. By default,
it passes the message to \method{log_message()}, so it takes the
same arguments (\var{format} and additional values).
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{log_message}{format, ...}
+\begin{methoddesc}{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 \method{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}
+\end{methoddesc}
-\begin{funcdesc}{version_string}{}
+\begin{methoddesc}{version_string}{}
Returns the server software's version string. This is a combination
of the \member{server_version} and \member{sys_version} class variables.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{date_time_string}{}
+\begin{methoddesc}{date_time_string}{}
Returns the current date and time, formatted for a message header.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{log_data_time_string}{}
+\begin{methoddesc}{log_data_time_string}{}
Returns the current date and time, formatted for logging.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{address_string}{}
+\begin{methoddesc}{address_string}{}
Returns the client address, formatted for logging. A name lookup
is performed on the client's IP address.
-\end{funcdesc}
+\end{methoddesc}