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