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