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