summaryrefslogtreecommitdiffstats
path: root/Doc/lib/libbasehttp.tex
blob: 82714b1f7343c47dcbe2f018b829ed96c2ad921b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
\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
web 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 adherance 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, 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{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}