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