Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / cpython2 / 71b2ded05e55a044cbba9257ed43ed34b5e9648c / . / Doc / library / httplib.rst
blob: 472fa61e13dd10e7f2e0c38af0d572ce5d78584f [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
Ezio Melotti510ff542012-05-03 19:21:40 +0300[diff] [blame]9 3. The :term:`2to3` tool will automatically adapt imports when converting
10 your sources to Python 3.
Georg Brandl8de91192008-05-26 15:01:48 +0000[diff] [blame]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
Hynek Schlawacke58ce012012-05-22 10:27:40 +0200[diff] [blame]92.. class:: HTTPResponse(sock, debuglevel=0, strict=0)
Georg Brandl8ec7f652007-08-15 14:28:01 +0000[diff] [blame]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
Sandro Tosi45262732011-12-25 11:43:37 +0100[diff] [blame]455 The headers argument should be a mapping of extra HTTP headers to send
Senthil Kumaran0732fd92009-12-20 07:29:31 +0000[diff] [blame]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
Senthil Kumaran41d663f2011-10-05 23:52:49 +0800[diff] [blame]497 Send a blank line to the server, signalling the end of the headers. The
498 optional *message_body* argument can be used to pass a message body
499 associated with the request. The message body will be sent in the same
500 packet as the message headers if it is string, otherwise it is sent in a
501 separate packet.
502
503 .. versionchanged:: 2.7
504 *message_body* was added.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000[diff] [blame]505
506
507.. method:: HTTPConnection.send(data)
508
509 Send data to the server. This should be used directly only after the
510 :meth:`endheaders` method has been called and before :meth:`getresponse` is
511 called.
512
513
514.. _httpresponse-objects:
515
516HTTPResponse Objects
517--------------------
518
519:class:`HTTPResponse` instances have the following methods and attributes:
520
521
522.. method:: HTTPResponse.read([amt])
523
524 Reads and returns the response body, or up to the next *amt* bytes.
525
526
527.. method:: HTTPResponse.getheader(name[, default])
528
529 Get the contents of the header *name*, or *default* if there is no matching
530 header.
531
532
533.. method:: HTTPResponse.getheaders()
534
535 Return a list of (header, value) tuples.
536
537 .. versionadded:: 2.4
538
Senthil Kumaranc916dd72010-09-21 02:10:45 +0000[diff] [blame]539.. method:: HTTPResponse.fileno()
540
541 Returns the ``fileno`` of the underlying socket.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000[diff] [blame]542
543.. attribute:: HTTPResponse.msg
544
545 A :class:`mimetools.Message` instance containing the response headers.
546
547
548.. attribute:: HTTPResponse.version
549
550 HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1.
551
552
553.. attribute:: HTTPResponse.status
554
555 Status code returned by server.
556
557
558.. attribute:: HTTPResponse.reason
559
560 Reason phrase returned by server.
561
562
563.. _httplib-examples:
564
565Examples
566--------
567
568Here is an example session that uses the ``GET`` method::
569
570 >>> import httplib
571 >>> conn = httplib.HTTPConnection("www.python.org")
572 >>> conn.request("GET", "/index.html")
573 >>> r1 = conn.getresponse()
574 >>> print r1.status, r1.reason
575 200 OK
576 >>> data1 = r1.read()
577 >>> conn.request("GET", "/parrot.spam")
578 >>> r2 = conn.getresponse()
579 >>> print r2.status, r2.reason
580 404 Not Found
581 >>> data2 = r2.read()
582 >>> conn.close()
583
Fred Drake58404692010-05-12 01:22:03 +0000[diff] [blame]584Here is an example session that uses the ``HEAD`` method. Note that the
585``HEAD`` method never returns any data. ::
Senthil Kumaraned9204342010-04-28 17:20:43 +0000[diff] [blame]586
587 >>> import httplib
588 >>> conn = httplib.HTTPConnection("www.python.org")
589 >>> conn.request("HEAD","/index.html")
590 >>> res = conn.getresponse()
591 >>> print res.status, res.reason
592 200 OK
593 >>> data = res.read()
594 >>> print len(data)
595 0
596 >>> data == ''
597 True
598
Georg Brandl8ec7f652007-08-15 14:28:01 +0000[diff] [blame]599Here is an example session that shows how to ``POST`` requests::
600
601 >>> import httplib, urllib
Senthil Kumarancd57ef12011-07-20 22:02:27 +0800[diff] [blame]602 >>> params = urllib.urlencode({'@number': 12524, '@type': 'issue', '@action': 'show'})
Georg Brandl8ec7f652007-08-15 14:28:01 +0000[diff] [blame]603 >>> headers = {"Content-type": "application/x-www-form-urlencoded",
604 ... "Accept": "text/plain"}
Senthil Kumarancd57ef12011-07-20 22:02:27 +0800[diff] [blame]605 >>> conn = httplib.HTTPConnection("bugs.python.org")
606 >>> conn.request("POST", "", params, headers)
Georg Brandl8ec7f652007-08-15 14:28:01 +0000[diff] [blame]607 >>> response = conn.getresponse()
608 >>> print response.status, response.reason
Senthil Kumarancd57ef12011-07-20 22:02:27 +0800[diff] [blame]609 302 Found
Georg Brandl8ec7f652007-08-15 14:28:01 +0000[diff] [blame]610 >>> data = response.read()
Senthil Kumarancd57ef12011-07-20 22:02:27 +0800[diff] [blame]611 >>> data
612 '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]613 >>> conn.close()
614
Senthil Kumaran69c66f92013-03-13 13:30:25 -0700[diff] [blame]615Client side ``HTTP PUT`` requests are very similar to ``POST`` requests. The
616difference lies only the server side where HTTP server will allow resources to
617be created via ``PUT`` request. Here is an example session that shows how to do
618``PUT`` request using httplib::
619
620 >>> # This creates an HTTP message
621 >>> # with the content of BODY as the enclosed representation
622 >>> # for the resource http://localhost:8080/foobar
623 ...
624 >>> import httplib
625 >>> BODY = "***filecontents***"
626 >>> conn = httplib.HTTPConnection("localhost", 8080)
627 >>> conn.request("PUT", "/file", BODY)
628 >>> response = conn.getresponse()
629 >>> print resp.status, response.reason
630 200, OK
631