Added Greg Stein's docs for BaseHTTPServer.py.
Moved docs for "re" to before docs for "regex".
This commit is contained in:
parent
b0744c5a28
commit
9cb64803aa
21
Doc/Makefile
21
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
|
||||
|
||||
|
|
|
@ -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}
|
||||
|
|
|
@ -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}
|
||||
|
|
|
@ -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}
|
|
@ -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}
|
Loading…
Reference in New Issue