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