Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / cpython3 / 5a75355792a8667969b5d677f5e4208da8ad2dc4 / . / Doc / library / httplib.rst
blob: 68a014960b06f0682e5cb33bcc39d3625c6c8d17 [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
Senthil Kumaran83cc5122011-10-03 07:37:58 +0800[diff] [blame]495.. method:: HTTPConnection.endheaders(message_body=None)
Georg Brandl8ec7f652007-08-15 14:28:01 +0000[diff] [blame]496
497 Send a blank line to the server, signalling the end of the headers.
Senthil Kumaran83cc5122011-10-03 07:37:58 +0800[diff] [blame]498 The optional message_body argument can be used to pass message body
499 associated with the request. The message body will be sent in
500 the same packet as the message headers if possible. The
501 message_body should be a string.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000[diff] [blame]502
503
504.. method:: HTTPConnection.send(data)
505
506 Send data to the server. This should be used directly only after the
507 :meth:`endheaders` method has been called and before :meth:`getresponse` is
508 called.
509
510
511.. _httpresponse-objects:
512
513HTTPResponse Objects
514--------------------
515
516:class:`HTTPResponse` instances have the following methods and attributes:
517
518
519.. method:: HTTPResponse.read([amt])
520
521 Reads and returns the response body, or up to the next *amt* bytes.
522
523
524.. method:: HTTPResponse.getheader(name[, default])
525
526 Get the contents of the header *name*, or *default* if there is no matching
527 header.
528
529
530.. method:: HTTPResponse.getheaders()
531
532 Return a list of (header, value) tuples.
533
534 .. versionadded:: 2.4
535
Senthil Kumaranc916dd72010-09-21 02:10:45 +0000[diff] [blame]536.. method:: HTTPResponse.fileno()
537
538 Returns the ``fileno`` of the underlying socket.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000[diff] [blame]539
540.. attribute:: HTTPResponse.msg
541
542 A :class:`mimetools.Message` instance containing the response headers.
543
544
545.. attribute:: HTTPResponse.version
546
547 HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1.
548
549
550.. attribute:: HTTPResponse.status
551
552 Status code returned by server.
553
554
555.. attribute:: HTTPResponse.reason
556
557 Reason phrase returned by server.
558
559
560.. _httplib-examples:
561
562Examples
563--------
564
565Here is an example session that uses the ``GET`` method::
566
567 >>> import httplib
568 >>> conn = httplib.HTTPConnection("www.python.org")
569 >>> conn.request("GET", "/index.html")
570 >>> r1 = conn.getresponse()
571 >>> print r1.status, r1.reason
572 200 OK
573 >>> data1 = r1.read()
574 >>> conn.request("GET", "/parrot.spam")
575 >>> r2 = conn.getresponse()
576 >>> print r2.status, r2.reason
577 404 Not Found
578 >>> data2 = r2.read()
579 >>> conn.close()
580
Fred Drake58404692010-05-12 01:22:03 +0000[diff] [blame]581Here is an example session that uses the ``HEAD`` method. Note that the
582``HEAD`` method never returns any data. ::
Senthil Kumaraned9204342010-04-28 17:20:43 +0000[diff] [blame]583
584 >>> import httplib
585 >>> conn = httplib.HTTPConnection("www.python.org")
586 >>> conn.request("HEAD","/index.html")
587 >>> res = conn.getresponse()
588 >>> print res.status, res.reason
589 200 OK
590 >>> data = res.read()
591 >>> print len(data)
592 0
593 >>> data == ''
594 True
595
Georg Brandl8ec7f652007-08-15 14:28:01 +0000[diff] [blame]596Here is an example session that shows how to ``POST`` requests::
597
598 >>> import httplib, urllib
Senthil Kumarancd57ef12011-07-20 22:02:27 +0800[diff] [blame]599 >>> params = urllib.urlencode({'@number': 12524, '@type': 'issue', '@action': 'show'})
Georg Brandl8ec7f652007-08-15 14:28:01 +0000[diff] [blame]600 >>> headers = {"Content-type": "application/x-www-form-urlencoded",
601 ... "Accept": "text/plain"}
Senthil Kumarancd57ef12011-07-20 22:02:27 +0800[diff] [blame]602 >>> conn = httplib.HTTPConnection("bugs.python.org")
603 >>> conn.request("POST", "", params, headers)
Georg Brandl8ec7f652007-08-15 14:28:01 +0000[diff] [blame]604 >>> response = conn.getresponse()
605 >>> print response.status, response.reason
Senthil Kumarancd57ef12011-07-20 22:02:27 +0800[diff] [blame]606 302 Found
Georg Brandl8ec7f652007-08-15 14:28:01 +0000[diff] [blame]607 >>> data = response.read()
Senthil Kumarancd57ef12011-07-20 22:02:27 +0800[diff] [blame]608 >>> data
609 '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]610 >>> conn.close()
611