|
1 :mod:`httplib` --- HTTP protocol client |
|
2 ======================================= |
|
3 |
|
4 .. module:: httplib |
|
5 :synopsis: HTTP and HTTPS protocol client (requires sockets). |
|
6 |
|
7 .. note:: |
|
8 The :mod:`httplib` module has been renamed to :mod:`http.client` in Python |
|
9 3.0. The :term:`2to3` tool will automatically adapt imports when converting |
|
10 your sources to 3.0. |
|
11 |
|
12 |
|
13 .. index:: |
|
14 pair: HTTP; protocol |
|
15 single: HTTP; httplib (standard module) |
|
16 |
|
17 .. index:: module: urllib |
|
18 |
|
19 This module defines classes which implement the client side of the HTTP and |
|
20 HTTPS protocols. It is normally not used directly --- the module :mod:`urllib` |
|
21 uses it to handle URLs that use HTTP and HTTPS. |
|
22 |
|
23 .. note:: |
|
24 |
|
25 HTTPS support is only available if the :mod:`socket` module was compiled with |
|
26 SSL support. |
|
27 |
|
28 .. note:: |
|
29 |
|
30 The public interface for this module changed substantially in Python 2.0. The |
|
31 :class:`HTTP` class is retained only for backward compatibility with 1.5.2. It |
|
32 should not be used in new code. Refer to the online docstrings for usage. |
|
33 |
|
34 The module provides the following classes: |
|
35 |
|
36 |
|
37 .. class:: HTTPConnection(host[, port[, strict[, timeout]]]) |
|
38 |
|
39 An :class:`HTTPConnection` instance represents one transaction with an HTTP |
|
40 server. It should be instantiated passing it a host and optional port |
|
41 number. If no port number is passed, the port is extracted from the host |
|
42 string if it has the form ``host:port``, else the default HTTP port (80) is |
|
43 used. When True, the optional parameter *strict* causes ``BadStatusLine`` to |
|
44 be raised if the status line can't be parsed as a valid HTTP/1.0 or 1.1 |
|
45 status line. If the optional *timeout* parameter is given, blocking |
|
46 operations (like connection attempts) will timeout after that many seconds |
|
47 (if it is not given, the global default timeout setting is used). |
|
48 |
|
49 For example, the following calls all create instances that connect to the server |
|
50 at the same host and port:: |
|
51 |
|
52 >>> h1 = httplib.HTTPConnection('www.cwi.nl') |
|
53 >>> h2 = httplib.HTTPConnection('www.cwi.nl:80') |
|
54 >>> h3 = httplib.HTTPConnection('www.cwi.nl', 80) |
|
55 >>> h3 = httplib.HTTPConnection('www.cwi.nl', 80, timeout=10) |
|
56 |
|
57 .. versionadded:: 2.0 |
|
58 |
|
59 .. versionchanged:: 2.6 |
|
60 *timeout* was added. |
|
61 |
|
62 |
|
63 .. class:: HTTPSConnection(host[, port[, key_file[, cert_file[, strict[, timeout]]]]]) |
|
64 |
|
65 A subclass of :class:`HTTPConnection` that uses SSL for communication with |
|
66 secure servers. Default port is ``443``. *key_file* is the name of a PEM |
|
67 formatted file that contains your private key. *cert_file* is a PEM formatted |
|
68 certificate chain file. |
|
69 |
|
70 .. warning:: |
|
71 |
|
72 This does not do any certificate verification! |
|
73 |
|
74 .. versionadded:: 2.0 |
|
75 |
|
76 .. versionchanged:: 2.6 |
|
77 *timeout* was added. |
|
78 |
|
79 |
|
80 .. class:: HTTPResponse(sock[, debuglevel=0][, strict=0]) |
|
81 |
|
82 Class whose instances are returned upon successful connection. Not instantiated |
|
83 directly by user. |
|
84 |
|
85 .. versionadded:: 2.0 |
|
86 |
|
87 The following exceptions are raised as appropriate: |
|
88 |
|
89 |
|
90 .. exception:: HTTPException |
|
91 |
|
92 The base class of the other exceptions in this module. It is a subclass of |
|
93 :exc:`Exception`. |
|
94 |
|
95 .. versionadded:: 2.0 |
|
96 |
|
97 |
|
98 .. exception:: NotConnected |
|
99 |
|
100 A subclass of :exc:`HTTPException`. |
|
101 |
|
102 .. versionadded:: 2.0 |
|
103 |
|
104 |
|
105 .. exception:: InvalidURL |
|
106 |
|
107 A subclass of :exc:`HTTPException`, raised if a port is given and is either |
|
108 non-numeric or empty. |
|
109 |
|
110 .. versionadded:: 2.3 |
|
111 |
|
112 |
|
113 .. exception:: UnknownProtocol |
|
114 |
|
115 A subclass of :exc:`HTTPException`. |
|
116 |
|
117 .. versionadded:: 2.0 |
|
118 |
|
119 |
|
120 .. exception:: UnknownTransferEncoding |
|
121 |
|
122 A subclass of :exc:`HTTPException`. |
|
123 |
|
124 .. versionadded:: 2.0 |
|
125 |
|
126 |
|
127 .. exception:: UnimplementedFileMode |
|
128 |
|
129 A subclass of :exc:`HTTPException`. |
|
130 |
|
131 .. versionadded:: 2.0 |
|
132 |
|
133 |
|
134 .. exception:: IncompleteRead |
|
135 |
|
136 A subclass of :exc:`HTTPException`. |
|
137 |
|
138 .. versionadded:: 2.0 |
|
139 |
|
140 |
|
141 .. exception:: ImproperConnectionState |
|
142 |
|
143 A subclass of :exc:`HTTPException`. |
|
144 |
|
145 .. versionadded:: 2.0 |
|
146 |
|
147 |
|
148 .. exception:: CannotSendRequest |
|
149 |
|
150 A subclass of :exc:`ImproperConnectionState`. |
|
151 |
|
152 .. versionadded:: 2.0 |
|
153 |
|
154 |
|
155 .. exception:: CannotSendHeader |
|
156 |
|
157 A subclass of :exc:`ImproperConnectionState`. |
|
158 |
|
159 .. versionadded:: 2.0 |
|
160 |
|
161 |
|
162 .. exception:: ResponseNotReady |
|
163 |
|
164 A subclass of :exc:`ImproperConnectionState`. |
|
165 |
|
166 .. versionadded:: 2.0 |
|
167 |
|
168 |
|
169 .. exception:: BadStatusLine |
|
170 |
|
171 A subclass of :exc:`HTTPException`. Raised if a server responds with a HTTP |
|
172 status code that we don't understand. |
|
173 |
|
174 .. versionadded:: 2.0 |
|
175 |
|
176 The constants defined in this module are: |
|
177 |
|
178 |
|
179 .. data:: HTTP_PORT |
|
180 |
|
181 The default port for the HTTP protocol (always ``80``). |
|
182 |
|
183 |
|
184 .. data:: HTTPS_PORT |
|
185 |
|
186 The default port for the HTTPS protocol (always ``443``). |
|
187 |
|
188 and also the following constants for integer status codes: |
|
189 |
|
190 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
191 | Constant | Value | Definition | |
|
192 +==========================================+=========+=======================================================================+ |
|
193 | :const:`CONTINUE` | ``100`` | HTTP/1.1, `RFC 2616, Section | |
|
194 | | | 10.1.1 | |
|
195 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.1>`_ | |
|
196 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
197 | :const:`SWITCHING_PROTOCOLS` | ``101`` | HTTP/1.1, `RFC 2616, Section | |
|
198 | | | 10.1.2 | |
|
199 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.2>`_ | |
|
200 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
201 | :const:`PROCESSING` | ``102`` | WEBDAV, `RFC 2518, Section 10.1 | |
|
202 | | | <http://www.webdav.org/specs/rfc2518.html#STATUS_102>`_ | |
|
203 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
204 | :const:`OK` | ``200`` | HTTP/1.1, `RFC 2616, Section | |
|
205 | | | 10.2.1 | |
|
206 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1>`_ | |
|
207 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
208 | :const:`CREATED` | ``201`` | HTTP/1.1, `RFC 2616, Section | |
|
209 | | | 10.2.2 | |
|
210 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2>`_ | |
|
211 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
212 | :const:`ACCEPTED` | ``202`` | HTTP/1.1, `RFC 2616, Section | |
|
213 | | | 10.2.3 | |
|
214 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3>`_ | |
|
215 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
216 | :const:`NON_AUTHORITATIVE_INFORMATION` | ``203`` | HTTP/1.1, `RFC 2616, Section | |
|
217 | | | 10.2.4 | |
|
218 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.4>`_ | |
|
219 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
220 | :const:`NO_CONTENT` | ``204`` | HTTP/1.1, `RFC 2616, Section | |
|
221 | | | 10.2.5 | |
|
222 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5>`_ | |
|
223 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
224 | :const:`RESET_CONTENT` | ``205`` | HTTP/1.1, `RFC 2616, Section | |
|
225 | | | 10.2.6 | |
|
226 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.6>`_ | |
|
227 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
228 | :const:`PARTIAL_CONTENT` | ``206`` | HTTP/1.1, `RFC 2616, Section | |
|
229 | | | 10.2.7 | |
|
230 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.7>`_ | |
|
231 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
232 | :const:`MULTI_STATUS` | ``207`` | WEBDAV `RFC 2518, Section 10.2 | |
|
233 | | | <http://www.webdav.org/specs/rfc2518.html#STATUS_207>`_ | |
|
234 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
235 | :const:`IM_USED` | ``226`` | Delta encoding in HTTP, | |
|
236 | | | :rfc:`3229`, Section 10.4.1 | |
|
237 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
238 | :const:`MULTIPLE_CHOICES` | ``300`` | HTTP/1.1, `RFC 2616, Section | |
|
239 | | | 10.3.1 | |
|
240 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.1>`_ | |
|
241 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
242 | :const:`MOVED_PERMANENTLY` | ``301`` | HTTP/1.1, `RFC 2616, Section | |
|
243 | | | 10.3.2 | |
|
244 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.2>`_ | |
|
245 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
246 | :const:`FOUND` | ``302`` | HTTP/1.1, `RFC 2616, Section | |
|
247 | | | 10.3.3 | |
|
248 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.3>`_ | |
|
249 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
250 | :const:`SEE_OTHER` | ``303`` | HTTP/1.1, `RFC 2616, Section | |
|
251 | | | 10.3.4 | |
|
252 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.4>`_ | |
|
253 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
254 | :const:`NOT_MODIFIED` | ``304`` | HTTP/1.1, `RFC 2616, Section | |
|
255 | | | 10.3.5 | |
|
256 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.5>`_ | |
|
257 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
258 | :const:`USE_PROXY` | ``305`` | HTTP/1.1, `RFC 2616, Section | |
|
259 | | | 10.3.6 | |
|
260 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.6>`_ | |
|
261 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
262 | :const:`TEMPORARY_REDIRECT` | ``307`` | HTTP/1.1, `RFC 2616, Section | |
|
263 | | | 10.3.8 | |
|
264 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.8>`_ | |
|
265 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
266 | :const:`BAD_REQUEST` | ``400`` | HTTP/1.1, `RFC 2616, Section | |
|
267 | | | 10.4.1 | |
|
268 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1>`_ | |
|
269 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
270 | :const:`UNAUTHORIZED` | ``401`` | HTTP/1.1, `RFC 2616, Section | |
|
271 | | | 10.4.2 | |
|
272 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2>`_ | |
|
273 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
274 | :const:`PAYMENT_REQUIRED` | ``402`` | HTTP/1.1, `RFC 2616, Section | |
|
275 | | | 10.4.3 | |
|
276 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.3>`_ | |
|
277 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
278 | :const:`FORBIDDEN` | ``403`` | HTTP/1.1, `RFC 2616, Section | |
|
279 | | | 10.4.4 | |
|
280 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4>`_ | |
|
281 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
282 | :const:`NOT_FOUND` | ``404`` | HTTP/1.1, `RFC 2616, Section | |
|
283 | | | 10.4.5 | |
|
284 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5>`_ | |
|
285 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
286 | :const:`METHOD_NOT_ALLOWED` | ``405`` | HTTP/1.1, `RFC 2616, Section | |
|
287 | | | 10.4.6 | |
|
288 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.6>`_ | |
|
289 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
290 | :const:`NOT_ACCEPTABLE` | ``406`` | HTTP/1.1, `RFC 2616, Section | |
|
291 | | | 10.4.7 | |
|
292 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7>`_ | |
|
293 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
294 | :const:`PROXY_AUTHENTICATION_REQUIRED` | ``407`` | HTTP/1.1, `RFC 2616, Section | |
|
295 | | | 10.4.8 | |
|
296 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.8>`_ | |
|
297 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
298 | :const:`REQUEST_TIMEOUT` | ``408`` | HTTP/1.1, `RFC 2616, Section | |
|
299 | | | 10.4.9 | |
|
300 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.9>`_ | |
|
301 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
302 | :const:`CONFLICT` | ``409`` | HTTP/1.1, `RFC 2616, Section | |
|
303 | | | 10.4.10 | |
|
304 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10>`_ | |
|
305 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
306 | :const:`GONE` | ``410`` | HTTP/1.1, `RFC 2616, Section | |
|
307 | | | 10.4.11 | |
|
308 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.11>`_ | |
|
309 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
310 | :const:`LENGTH_REQUIRED` | ``411`` | HTTP/1.1, `RFC 2616, Section | |
|
311 | | | 10.4.12 | |
|
312 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.12>`_ | |
|
313 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
314 | :const:`PRECONDITION_FAILED` | ``412`` | HTTP/1.1, `RFC 2616, Section | |
|
315 | | | 10.4.13 | |
|
316 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.13>`_ | |
|
317 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
318 | :const:`REQUEST_ENTITY_TOO_LARGE` | ``413`` | HTTP/1.1, `RFC 2616, Section | |
|
319 | | | 10.4.14 | |
|
320 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.14>`_ | |
|
321 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
322 | :const:`REQUEST_URI_TOO_LONG` | ``414`` | HTTP/1.1, `RFC 2616, Section | |
|
323 | | | 10.4.15 | |
|
324 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.15>`_ | |
|
325 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
326 | :const:`UNSUPPORTED_MEDIA_TYPE` | ``415`` | HTTP/1.1, `RFC 2616, Section | |
|
327 | | | 10.4.16 | |
|
328 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16>`_ | |
|
329 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
330 | :const:`REQUESTED_RANGE_NOT_SATISFIABLE` | ``416`` | HTTP/1.1, `RFC 2616, Section | |
|
331 | | | 10.4.17 | |
|
332 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.17>`_ | |
|
333 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
334 | :const:`EXPECTATION_FAILED` | ``417`` | HTTP/1.1, `RFC 2616, Section | |
|
335 | | | 10.4.18 | |
|
336 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.18>`_ | |
|
337 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
338 | :const:`UNPROCESSABLE_ENTITY` | ``422`` | WEBDAV, `RFC 2518, Section 10.3 | |
|
339 | | | <http://www.webdav.org/specs/rfc2518.html#STATUS_422>`_ | |
|
340 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
341 | :const:`LOCKED` | ``423`` | WEBDAV `RFC 2518, Section 10.4 | |
|
342 | | | <http://www.webdav.org/specs/rfc2518.html#STATUS_423>`_ | |
|
343 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
344 | :const:`FAILED_DEPENDENCY` | ``424`` | WEBDAV, `RFC 2518, Section 10.5 | |
|
345 | | | <http://www.webdav.org/specs/rfc2518.html#STATUS_424>`_ | |
|
346 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
347 | :const:`UPGRADE_REQUIRED` | ``426`` | HTTP Upgrade to TLS, | |
|
348 | | | :rfc:`2817`, Section 6 | |
|
349 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
350 | :const:`INTERNAL_SERVER_ERROR` | ``500`` | HTTP/1.1, `RFC 2616, Section | |
|
351 | | | 10.5.1 | |
|
352 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1>`_ | |
|
353 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
354 | :const:`NOT_IMPLEMENTED` | ``501`` | HTTP/1.1, `RFC 2616, Section | |
|
355 | | | 10.5.2 | |
|
356 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2>`_ | |
|
357 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
358 | :const:`BAD_GATEWAY` | ``502`` | HTTP/1.1 `RFC 2616, Section | |
|
359 | | | 10.5.3 | |
|
360 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.3>`_ | |
|
361 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
362 | :const:`SERVICE_UNAVAILABLE` | ``503`` | HTTP/1.1, `RFC 2616, Section | |
|
363 | | | 10.5.4 | |
|
364 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4>`_ | |
|
365 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
366 | :const:`GATEWAY_TIMEOUT` | ``504`` | HTTP/1.1 `RFC 2616, Section | |
|
367 | | | 10.5.5 | |
|
368 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.5>`_ | |
|
369 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
370 | :const:`HTTP_VERSION_NOT_SUPPORTED` | ``505`` | HTTP/1.1, `RFC 2616, Section | |
|
371 | | | 10.5.6 | |
|
372 | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.6>`_ | |
|
373 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
374 | :const:`INSUFFICIENT_STORAGE` | ``507`` | WEBDAV, `RFC 2518, Section 10.6 | |
|
375 | | | <http://www.webdav.org/specs/rfc2518.html#STATUS_507>`_ | |
|
376 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
377 | :const:`NOT_EXTENDED` | ``510`` | An HTTP Extension Framework, | |
|
378 | | | :rfc:`2774`, Section 7 | |
|
379 +------------------------------------------+---------+-----------------------------------------------------------------------+ |
|
380 |
|
381 |
|
382 .. data:: responses |
|
383 |
|
384 This dictionary maps the HTTP 1.1 status codes to the W3C names. |
|
385 |
|
386 Example: ``httplib.responses[httplib.NOT_FOUND]`` is ``'Not Found'``. |
|
387 |
|
388 .. versionadded:: 2.5 |
|
389 |
|
390 |
|
391 .. _httpconnection-objects: |
|
392 |
|
393 HTTPConnection Objects |
|
394 ---------------------- |
|
395 |
|
396 :class:`HTTPConnection` instances have the following methods: |
|
397 |
|
398 |
|
399 .. method:: HTTPConnection.request(method, url[, body[, headers]]) |
|
400 |
|
401 This will send a request to the server using the HTTP request method *method* |
|
402 and the selector *url*. If the *body* argument is present, it should be a |
|
403 string of data to send after the headers are finished. Alternatively, it may |
|
404 be an open file object, in which case the contents of the file is sent; this |
|
405 file object should support ``fileno()`` and ``read()`` methods. The header |
|
406 Content-Length is automatically set to the correct value. The *headers* |
|
407 argument should be a mapping of extra HTTP headers to send with the request. |
|
408 |
|
409 .. versionchanged:: 2.6 |
|
410 *body* can be a file object. |
|
411 |
|
412 |
|
413 .. method:: HTTPConnection.getresponse() |
|
414 |
|
415 Should be called after a request is sent to get the response from the server. |
|
416 Returns an :class:`HTTPResponse` instance. |
|
417 |
|
418 .. note:: |
|
419 |
|
420 Note that you must have read the whole response before you can send a new |
|
421 request to the server. |
|
422 |
|
423 |
|
424 .. method:: HTTPConnection.set_debuglevel(level) |
|
425 |
|
426 Set the debugging level (the amount of debugging output printed). The default |
|
427 debug level is ``0``, meaning no debugging output is printed. |
|
428 |
|
429 |
|
430 .. method:: HTTPConnection.connect() |
|
431 |
|
432 Connect to the server specified when the object was created. |
|
433 |
|
434 |
|
435 .. method:: HTTPConnection.close() |
|
436 |
|
437 Close the connection to the server. |
|
438 |
|
439 As an alternative to using the :meth:`request` method described above, you can |
|
440 also send your request step by step, by using the four functions below. |
|
441 |
|
442 |
|
443 .. method:: HTTPConnection.putrequest(request, selector[, skip_host[, skip_accept_encoding]]) |
|
444 |
|
445 This should be the first call after the connection to the server has been made. |
|
446 It sends a line to the server consisting of the *request* string, the *selector* |
|
447 string, and the HTTP version (``HTTP/1.1``). To disable automatic sending of |
|
448 ``Host:`` or ``Accept-Encoding:`` headers (for example to accept additional |
|
449 content encodings), specify *skip_host* or *skip_accept_encoding* with non-False |
|
450 values. |
|
451 |
|
452 .. versionchanged:: 2.4 |
|
453 *skip_accept_encoding* argument added. |
|
454 |
|
455 |
|
456 .. method:: HTTPConnection.putheader(header, argument[, ...]) |
|
457 |
|
458 Send an :rfc:`822`\ -style header to the server. It sends a line to the server |
|
459 consisting of the header, a colon and a space, and the first argument. If more |
|
460 arguments are given, continuation lines are sent, each consisting of a tab and |
|
461 an argument. |
|
462 |
|
463 |
|
464 .. method:: HTTPConnection.endheaders() |
|
465 |
|
466 Send a blank line to the server, signalling the end of the headers. |
|
467 |
|
468 |
|
469 .. method:: HTTPConnection.send(data) |
|
470 |
|
471 Send data to the server. This should be used directly only after the |
|
472 :meth:`endheaders` method has been called and before :meth:`getresponse` is |
|
473 called. |
|
474 |
|
475 |
|
476 .. _httpresponse-objects: |
|
477 |
|
478 HTTPResponse Objects |
|
479 -------------------- |
|
480 |
|
481 :class:`HTTPResponse` instances have the following methods and attributes: |
|
482 |
|
483 |
|
484 .. method:: HTTPResponse.read([amt]) |
|
485 |
|
486 Reads and returns the response body, or up to the next *amt* bytes. |
|
487 |
|
488 |
|
489 .. method:: HTTPResponse.getheader(name[, default]) |
|
490 |
|
491 Get the contents of the header *name*, or *default* if there is no matching |
|
492 header. |
|
493 |
|
494 |
|
495 .. method:: HTTPResponse.getheaders() |
|
496 |
|
497 Return a list of (header, value) tuples. |
|
498 |
|
499 .. versionadded:: 2.4 |
|
500 |
|
501 |
|
502 .. attribute:: HTTPResponse.msg |
|
503 |
|
504 A :class:`mimetools.Message` instance containing the response headers. |
|
505 |
|
506 |
|
507 .. attribute:: HTTPResponse.version |
|
508 |
|
509 HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1. |
|
510 |
|
511 |
|
512 .. attribute:: HTTPResponse.status |
|
513 |
|
514 Status code returned by server. |
|
515 |
|
516 |
|
517 .. attribute:: HTTPResponse.reason |
|
518 |
|
519 Reason phrase returned by server. |
|
520 |
|
521 |
|
522 .. _httplib-examples: |
|
523 |
|
524 Examples |
|
525 -------- |
|
526 |
|
527 Here is an example session that uses the ``GET`` method:: |
|
528 |
|
529 >>> import httplib |
|
530 >>> conn = httplib.HTTPConnection("www.python.org") |
|
531 >>> conn.request("GET", "/index.html") |
|
532 >>> r1 = conn.getresponse() |
|
533 >>> print r1.status, r1.reason |
|
534 200 OK |
|
535 >>> data1 = r1.read() |
|
536 >>> conn.request("GET", "/parrot.spam") |
|
537 >>> r2 = conn.getresponse() |
|
538 >>> print r2.status, r2.reason |
|
539 404 Not Found |
|
540 >>> data2 = r2.read() |
|
541 >>> conn.close() |
|
542 |
|
543 Here is an example session that shows how to ``POST`` requests:: |
|
544 |
|
545 >>> import httplib, urllib |
|
546 >>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0}) |
|
547 >>> headers = {"Content-type": "application/x-www-form-urlencoded", |
|
548 ... "Accept": "text/plain"} |
|
549 >>> conn = httplib.HTTPConnection("musi-cal.mojam.com:80") |
|
550 >>> conn.request("POST", "/cgi-bin/query", params, headers) |
|
551 >>> response = conn.getresponse() |
|
552 >>> print response.status, response.reason |
|
553 200 OK |
|
554 >>> data = response.read() |
|
555 >>> conn.close() |
|
556 |