246 lines
9.0 KiB
TeX
246 lines
9.0 KiB
TeX
\section{\module{BaseHTTPServer} ---
|
|
Basic HTTP server}
|
|
|
|
\declaremodule{standard}{BaseHTTPServer}
|
|
\modulesynopsis{Basic HTTP server (base class for
|
|
\class{SimpleHTTPServer} and \class{CGIHTTPServer}).}
|
|
|
|
|
|
\indexii{WWW}{server}
|
|
\indexii{HTTP}{protocol}
|
|
\index{URL}
|
|
\index{httpd}
|
|
|
|
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
|
|
\refmodule{SimpleHTTPServer}\refstmodindex{SimpleHTTPServer} and
|
|
\refmodule{CGIHTTPServer}\refstmodindex{CGIHTTPServer} modules.
|
|
|
|
The first class, \class{HTTPServer}, is a
|
|
\class{SocketServer.TCPServer} subclass. It creates and listens at the
|
|
HTTP socket, dispatching the requests to a handler. Code to create and
|
|
run the server looks like this:
|
|
|
|
\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}
|
|
|
|
\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}
|
|
|
|
\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).
|
|
\class{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 method \samp{SPAM}, the
|
|
\method{do_SPAM()} method will be called with no arguments. All of
|
|
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}
|
|
|
|
|
|
\class{BaseHTTPRequestHandler} has the following instance variables:
|
|
|
|
\begin{memberdesc}{client_address}
|
|
Contains a tuple of the form \code{(\var{host}, \var{port})} referring
|
|
to the client's address.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{command}
|
|
Contains the command (request type). For example, \code{'GET'}.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{path}
|
|
Contains the request path.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{request_version}
|
|
Contains the version string from the request. For example,
|
|
\code{'HTTP/1.0'}.
|
|
\end{memberdesc}
|
|
|
|
\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{memberdesc}
|
|
|
|
\begin{memberdesc}{rfile}
|
|
Contains an input stream, positioned at the start of the optional
|
|
input data.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{wfile}
|
|
Contains the output stream for writing a response back to the client.
|
|
Proper adherence to the HTTP protocol must be used when writing
|
|
to this stream.
|
|
\end{memberdesc}
|
|
|
|
|
|
\class{BaseHTTPRequestHandler} has the following class variables:
|
|
|
|
\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{memberdesc}
|
|
|
|
\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{memberdesc}
|
|
|
|
\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
|
|
be an integer, specifying 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{memberdesc}
|
|
|
|
\begin{memberdesc}{protocol_version}
|
|
This specifies the HTTP protocol version used in responses. If set
|
|
to \code{'HTTP/1.1'}, the server will permit HTTP persistent
|
|
connections; however, your server \emph{must} then include an
|
|
accurate \code{Content-Length} header (using \method{send_header()})
|
|
in all of its responses to clients. For backwards compatibility,
|
|
the setting defaults to \code{'HTTP/1.0'}.
|
|
\end{memberdesc}
|
|
|
|
\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{memberdesc}
|
|
|
|
\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{memberdesc}
|
|
|
|
|
|
A \class{BaseHTTPRequestHandler} instance has the following methods:
|
|
|
|
\begin{methoddesc}{handle}{}
|
|
Calls \method{handle_one_request()} once (or, if persistent connections
|
|
are enabled, multiple times) to handle incoming HTTP requests.
|
|
You should never need to override it; instead, implement appropriate
|
|
\method{do_*()} methods.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_one_request}{}
|
|
This method will parse and dispatch
|
|
the request to the appropriate \method{do_*()} method. You should
|
|
never need to override it.
|
|
\end{methoddesc}
|
|
|
|
\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{methoddesc}
|
|
|
|
\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{methoddesc}
|
|
|
|
\begin{methoddesc}{send_header}{keyword, value}
|
|
Writes a specific HTTP header to the output stream. \var{keyword}
|
|
should specify the header keyword, with \var{value} specifying
|
|
its value.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{end_headers}{}
|
|
Sends a blank line, indicating the end of the HTTP headers in
|
|
the response.
|
|
\end{methoddesc}
|
|
|
|
\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{methoddesc}
|
|
|
|
\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{methoddesc}
|
|
|
|
\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{methoddesc}
|
|
|
|
\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{methoddesc}
|
|
|
|
\begin{methoddesc}{date_time_string}{\optional{timestamp}}
|
|
Returns the date and time given by \var{timestamp} (which must be in the
|
|
format returned by \function{time.time()}), formatted for a message header.
|
|
If \var{timestamp} is omitted, it uses the current date and time.
|
|
|
|
The result looks like \code{'Sun, 06 Nov 1994 08:49:37 GMT'}.
|
|
\versionadded[The \var{timestamp} parameter]{2.5}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{log_date_time_string}{}
|
|
Returns the current date and time, formatted for logging.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{address_string}{}
|
|
Returns the client address, formatted for logging. A name lookup
|
|
is performed on the client's IP address.
|
|
\end{methoddesc}
|
|
|
|
|
|
\begin{seealso}
|
|
\seemodule{CGIHTTPServer}{Extended request handler that supports CGI
|
|
scripts.}
|
|
|
|
\seemodule{SimpleHTTPServer}{Basic request handler that limits response
|
|
to files actually under the document root.}
|
|
\end{seealso}
|