|
| 1 | +\section{Standard Module \sectcode{BaseHTTPServer}} |
| 2 | +\label{module-BaseHTTPServer} |
| 3 | +\stmodindex{BaseHTTPServer} |
| 4 | + |
| 5 | +\indexii{WWW}{server} |
| 6 | +\indexii{HTTP}{protocol} |
| 7 | +\index{URL} |
| 8 | +\index{httpd} |
| 9 | + |
| 10 | +\renewcommand{\indexsubitem}{(in module BaseHTTPServer)} |
| 11 | + |
| 12 | +This module defines two classes for implementing HTTP servers |
| 13 | +(web servers). Usually, this module isn't used directly, but is used |
| 14 | +as a basis for building functioning web servers. See the |
| 15 | +\code{SimpleHTTPServer} and \code{CGIHTTPServer} modules. |
| 16 | +\stmodindex{SimpleHTTPServer} |
| 17 | +\stmodindex{CGIHTTPServer} |
| 18 | + |
| 19 | +The first class, \code{HTTPServer}, is a \code{SocketServer.TCPServer} |
| 20 | +subclass. It creates and listens at the web socket, dispatching the |
| 21 | +requests to a handler. Code to create and run the server looks like |
| 22 | +this: |
| 23 | + |
| 24 | +\bcode\begin{verbatim} |
| 25 | +def run(server_class=BaseHTTPServer.HTTPServer, |
| 26 | + handler_class=BaseHTTPServer.BaseHTTPRequestHandler): |
| 27 | + server_address = ('', 8000) |
| 28 | + httpd = server_class(server_address, handler_class) |
| 29 | + httpd.serve_forever() |
| 30 | +\end{verbatim}\ecode |
| 31 | +% |
| 32 | +The \code{HTTPServer} class builds on the \code{TCPServer} class by |
| 33 | +storing the server address as instance |
| 34 | +variables named \code{server_name} and \code{server_port}. The |
| 35 | +server is accessible by the handler, typically through the handler's |
| 36 | +\code{server} instance variable. |
| 37 | + |
| 38 | +The module's second class, \code{BaseHTTPRequestHandler}, is used |
| 39 | +to handle the HTTP requests that arrive at the server. By itself, |
| 40 | +it cannot respond to any actual HTTP requests; it must be subclassed |
| 41 | +to handle each request method (e.g. GET or POST). |
| 42 | +\code{BaseHTTPRequestHandler} provides a number of class and instance |
| 43 | +variables, and methods for use by subclasses. |
| 44 | + |
| 45 | +The handler will parse the request and the headers, then call a |
| 46 | +method specific to the request type. The method name is constructed |
| 47 | +from the request. For example, for the request \code{SPAM}, the |
| 48 | +\code{do_SPAM} method will be called with no arguments. All of |
| 49 | +the relevant information is stored into instance variables of the |
| 50 | +handler. |
| 51 | + |
| 52 | +\renewcommand{\indexsubitem}{(BaseHTTPRequestHandler instance variables)} |
| 53 | + |
| 54 | +\code{BaseHTTPRequestHandler} has the following instance variables: |
| 55 | + |
| 56 | +\begin{datadesc}{client_address} |
| 57 | +Contains a tuple of the form (host, port) referring to the client's |
| 58 | +address. |
| 59 | +\end{datadesc} |
| 60 | + |
| 61 | +\begin{datadesc}{command} |
| 62 | +Contains the command (request type). For example, \code{"GET"}. |
| 63 | +\end{datadesc} |
| 64 | + |
| 65 | +\begin{datadesc}{path} |
| 66 | +Contains the request path. |
| 67 | +\end{datadesc} |
| 68 | + |
| 69 | +\begin{datadesc}{request_version} |
| 70 | +Contains the version string from the request. For example, |
| 71 | +\code{"HTTP/1.0"}. |
| 72 | +\end{datadesc} |
| 73 | + |
| 74 | +\begin{datadesc}{headers} |
| 75 | +Holds an instance of the class specified by the \var{MessageClass} |
| 76 | +class variable. This instance parses and manages the headers in |
| 77 | +the HTTP request. |
| 78 | +\end{datadesc} |
| 79 | + |
| 80 | +\begin{datadesc}{rfile} |
| 81 | +Contains an input stream, positioned at the start of the optional |
| 82 | +input data. |
| 83 | +\end{datadesc} |
| 84 | + |
| 85 | +\begin{datadesc}{wfile} |
| 86 | +Contains the output stream for writing a response back to the client. |
| 87 | +Proper adherance to the HTTP protocol must be used when writing |
| 88 | +to this stream. |
| 89 | +\end{datadesc} |
| 90 | + |
| 91 | +\renewcommand{\indexsubitem}{(BaseHTTPRequestHandler class variables)} |
| 92 | + |
| 93 | +\code{BaseHTTPRequestHandler} has the following class variables: |
| 94 | + |
| 95 | +\begin{datadesc}{server_version} |
| 96 | +Specifies the server software version. You may want to override |
| 97 | +this. |
| 98 | +The format is multiple whitespace-separated strings, |
| 99 | +where each string is of the form name[/version]. |
| 100 | +For example, \code{"BaseHTTP/0.2"}. |
| 101 | +\end{datadesc} |
| 102 | + |
| 103 | +\begin{datadesc}{sys_version} |
| 104 | +Contains the Python system version, in a form usable by the |
| 105 | +\code{version_string} method and the \code{server_version} class |
| 106 | +variable. For example, \code{"Python/1.4"}. |
| 107 | +\end{datadesc} |
| 108 | + |
| 109 | +\begin{datadesc}{error_message_format} |
| 110 | +Specifies a format string for building an error response to the |
| 111 | +client. It uses parenthesized, keyed format specifiers, so the |
| 112 | +format operand must be a dictionary. The \var{code} key should |
| 113 | +be an integer, specifing the numeric HTTP error code value. |
| 114 | +\var{message} should be a string containing a (detailed) error |
| 115 | +message of what occurred, and \var{explain} should be an |
| 116 | +explanation of the error code number. Default \var{message} |
| 117 | +and \var{explain} values can found in the \var{responses} |
| 118 | +class variable. |
| 119 | +\end{datadesc} |
| 120 | + |
| 121 | +\begin{datadesc}{protocol_version} |
| 122 | +This specifies the HTTP protocol version used in responses. |
| 123 | +Typically, this should not be overridden. Defaults to |
| 124 | +\code{"HTTP/1.0"}. |
| 125 | +\end{datadesc} |
| 126 | + |
| 127 | +\begin{datadesc}{MessageClass} |
| 128 | +Specifies a Message-like class to parse HTTP headers. Typically, |
| 129 | +this is not overridden, and it defaults to \code{mimetools.Message}. |
| 130 | +\end{datadesc} |
| 131 | + |
| 132 | +\begin{datadesc}{responses} |
| 133 | +This variable contains a mapping of error code integers to two-element |
| 134 | +tuples containing a short and long message. For example, |
| 135 | +\code{\{code : (shortmessage, longmessage)\}}. The |
| 136 | +\var{shortmessage} is usually used as the \var{message} key in an |
| 137 | +error response, and \var{longmessage} as the \var{explain} key |
| 138 | +(see the \code{error_message_format} class variable). |
| 139 | +\end{datadesc} |
| 140 | + |
| 141 | +\renewcommand{\indexsubitem}{(BaseHTTPRequestHandler method)} |
| 142 | + |
| 143 | +A \code{BaseHTTPRequestHandler} instance has the following methods: |
| 144 | + |
| 145 | +\begin{funcdesc}{handle}{} |
| 146 | +Overrides the superclass' \code{handle} method to provide the |
| 147 | +specific handler behavior. This method will parse and dispatch |
| 148 | +the request to the appropriate \code{do_}* method. |
| 149 | +\end{funcdesc} |
| 150 | + |
| 151 | +\begin{funcdesc}{send_error}{code\optional{\, message}} |
| 152 | +Sends and logs a complete error reply to the client. The numeric |
| 153 | +\var{code} specifies the HTTP error code, with \var{message} as |
| 154 | +optional, more specific text. A complete set of headers is sent, |
| 155 | +followed by text composed using the \code{error_message_format} |
| 156 | +class variable. |
| 157 | +\end{funcdesc} |
| 158 | + |
| 159 | +\begin{funcdesc}{send_response}{code\optional{\, message}} |
| 160 | +Sends a response header and logs the accepted request. The HTTP |
| 161 | +response line is sent, followed by \emph{Server} and \emph{Date} |
| 162 | +headers. The values for these two headers are picked up from the |
| 163 | +\code{version_string()} and \code{date_time_string()} methods, |
| 164 | +respectively. |
| 165 | +\end{funcdesc} |
| 166 | + |
| 167 | +\begin{funcdesc}{send_header}{keyword\, value} |
| 168 | +Writes a specific MIME header to the output stream. \var{keyword} |
| 169 | +should specify the header keyword, with \var{value} specifying |
| 170 | +its value. |
| 171 | +\end{funcdesc} |
| 172 | + |
| 173 | +\begin{funcdesc}{end_headers}{} |
| 174 | +Sends a blank line, indicating the end of the MIME headers in |
| 175 | +the response. |
| 176 | +\end{funcdesc} |
| 177 | + |
| 178 | +\begin{funcdesc}{log_request}{\optional{code\optional{\, size}}} |
| 179 | +Logs an accepted (successful) request. \var{code} should specify |
| 180 | +the numeric HTTP code associated with the response. If a size of |
| 181 | +the response is available, then it should be passed as the |
| 182 | +\var{size} parameter. |
| 183 | +\end{funcdesc} |
| 184 | + |
| 185 | +\begin{funcdesc}{log_error}{...} |
| 186 | +Logs an error when a request cannot be fulfilled. By default, |
| 187 | +it passes the message to \code{log_message}, so it takes the |
| 188 | +same arguments (\var{format} and additional values). |
| 189 | +\end{funcdesc} |
| 190 | + |
| 191 | +\begin{funcdesc}{log_message}{format, ...} |
| 192 | +Logs an arbitrary message to \code{sys.stderr}. This is typically |
| 193 | +overridden to create custom error logging mechanisms. The |
| 194 | +\var{format} argument is a standard printf-style format string, |
| 195 | +where the additional arguments to \code{log_message} are applied |
| 196 | +as inputs to the formatting. The client address and current date |
| 197 | +and time are prefixed to every message logged. |
| 198 | +\end{funcdesc} |
| 199 | + |
| 200 | +\begin{funcdesc}{version_string}{} |
| 201 | +Returns the server software's version string. This is a combination |
| 202 | +of the \var{server_version} and \var{sys_version} class variables. |
| 203 | +\end{funcdesc} |
| 204 | + |
| 205 | +\begin{funcdesc}{date_time_string}{} |
| 206 | +Returns the current date and time, formatted for a message header. |
| 207 | +\end{funcdesc} |
| 208 | + |
| 209 | +\begin{funcdesc}{log_data_time_string}{} |
| 210 | +Returns the current date and time, formatted for logging. |
| 211 | +\end{funcdesc} |
| 212 | + |
| 213 | +\begin{funcdesc}{address_string}{} |
| 214 | +Returns the client address, formatted for logging. A name lookup |
| 215 | +is performed on the client's IP address. |
| 216 | +\end{funcdesc} |
0 commit comments