Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / cpython2 / bc3777d85e9f73bb8e541faf91103fb2374628a3 / . / Doc / library / httplib.rst
blob: bf7e8ef57a4d59e5c06ae02f797fa7f0410536fc [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
Georg Brandl16a57f62009-04-27 15:29:09 +0000[diff] [blame]71 .. note::
Georg Brandl8ec7f652007-08-15 14:28:01 +0000[diff] [blame]72
Georg Brandl16a57f62009-04-27 15:29:09 +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
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
Senthil Kumarane266f252009-05-24 09:14:50 +0000[diff] [blame]431.. method:: HTTPConnection.set_tunnel(host,port=None)
432
433 Set the host and the port for HTTP Connect Tunnelling. Normally used when
434 it is required to do HTTPS Conection through a proxy server.
435
Gregory P. Smithd03e1b42009-05-24 18:00:13 +0000[diff] [blame]436 .. versionadded:: 2.7
437
Senthil Kumarane266f252009-05-24 09:14:50 +0000[diff] [blame]438
Georg Brandl8ec7f652007-08-15 14:28:01 +0000[diff] [blame]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
552Here is an example session that shows how to ``POST`` requests::
553
554 >>> import httplib, urllib
555 >>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
556 >>> headers = {"Content-type": "application/x-www-form-urlencoded",
557 ... "Accept": "text/plain"}
558 >>> conn = httplib.HTTPConnection("musi-cal.mojam.com:80")
559 >>> conn.request("POST", "/cgi-bin/query", params, headers)
560 >>> response = conn.getresponse()
561 >>> print response.status, response.reason
562 200 OK
563 >>> data = response.read()
564 >>> conn.close()
565