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