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