| \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 |
| \module{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. |
| Typically, this should not be overridden. 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}{} |
| Overrides the superclass' \method{handle()} method to provide the |
| specific handler behavior. This method will parse and dispatch |
| the request to the appropriate \method{do_*()} method. |
| \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 MIME 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 MIME 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}{} |
| Returns the current date and time, formatted for a message header. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{log_data_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} |