Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / cpython2 / 0732fd952baf34eb0636fd6ce4c7093d2d70e98b / . / Doc / library / httplib.rst
blob: d881968e48b6385356d4de3fc3f7c47d013cbd2e [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 Kumaran0732fd92009-12-20 07:29:31 +0000[diff] [blame^]431.. method:: HTTPConnection.set_tunnel(host,port=None, headers=None)
Senthil Kumarane266f252009-05-24 09:14:50 +0000[diff] [blame]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
Senthil Kumaran0732fd92009-12-20 07:29:31 +0000[diff] [blame^]436 The headers argument should be a mapping of extra HTTP headers to to sent
437 with the CONNECT request.
438
Gregory P. Smithd03e1b42009-05-24 18:00:13 +0000[diff] [blame]439 .. versionadded:: 2.7
440
Senthil Kumarane266f252009-05-24 09:14:50 +0000[diff] [blame]441
Georg Brandl8ec7f652007-08-15 14:28:01 +0000[diff] [blame]442.. method:: HTTPConnection.connect()
443
444 Connect to the server specified when the object was created.
445
446
447.. method:: HTTPConnection.close()
448
449 Close the connection to the server.
450
451As an alternative to using the :meth:`request` method described above, you can
452also send your request step by step, by using the four functions below.
453
454
455.. method:: HTTPConnection.putrequest(request, selector[, skip_host[, skip_accept_encoding]])
456
457 This should be the first call after the connection to the server has been made.
458 It sends a line to the server consisting of the *request* string, the *selector*
459 string, and the HTTP version (``HTTP/1.1``). To disable automatic sending of
460 ``Host:`` or ``Accept-Encoding:`` headers (for example to accept additional
461 content encodings), specify *skip_host* or *skip_accept_encoding* with non-False
462 values.
463
464 .. versionchanged:: 2.4
465 *skip_accept_encoding* argument added.
466
467
468.. method:: HTTPConnection.putheader(header, argument[, ...])
469
470 Send an :rfc:`822`\ -style header to the server. It sends a line to the server
471 consisting of the header, a colon and a space, and the first argument. If more
472 arguments are given, continuation lines are sent, each consisting of a tab and
473 an argument.
474
475
476.. method:: HTTPConnection.endheaders()
477
478 Send a blank line to the server, signalling the end of the headers.
479
480
481.. method:: HTTPConnection.send(data)
482
483 Send data to the server. This should be used directly only after the
484 :meth:`endheaders` method has been called and before :meth:`getresponse` is
485 called.
486
487
488.. _httpresponse-objects:
489
490HTTPResponse Objects
491--------------------
492
493:class:`HTTPResponse` instances have the following methods and attributes:
494
495
496.. method:: HTTPResponse.read([amt])
497
498 Reads and returns the response body, or up to the next *amt* bytes.
499
500
501.. method:: HTTPResponse.getheader(name[, default])
502
503 Get the contents of the header *name*, or *default* if there is no matching
504 header.
505
506
507.. method:: HTTPResponse.getheaders()
508
509 Return a list of (header, value) tuples.
510
511 .. versionadded:: 2.4
512
513
514.. attribute:: HTTPResponse.msg
515
516 A :class:`mimetools.Message` instance containing the response headers.
517
518
519.. attribute:: HTTPResponse.version
520
521 HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1.
522
523
524.. attribute:: HTTPResponse.status
525
526 Status code returned by server.
527
528
529.. attribute:: HTTPResponse.reason
530
531 Reason phrase returned by server.
532
533
534.. _httplib-examples:
535
536Examples
537--------
538
539Here is an example session that uses the ``GET`` method::
540
541 >>> import httplib
542 >>> conn = httplib.HTTPConnection("www.python.org")
543 >>> conn.request("GET", "/index.html")
544 >>> r1 = conn.getresponse()
545 >>> print r1.status, r1.reason
546 200 OK
547 >>> data1 = r1.read()
548 >>> conn.request("GET", "/parrot.spam")
549 >>> r2 = conn.getresponse()
550 >>> print r2.status, r2.reason
551 404 Not Found
552 >>> data2 = r2.read()
553 >>> conn.close()
554
555Here is an example session that shows how to ``POST`` requests::
556
557 >>> import httplib, urllib
558 >>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
559 >>> headers = {"Content-type": "application/x-www-form-urlencoded",
560 ... "Accept": "text/plain"}
561 >>> conn = httplib.HTTPConnection("musi-cal.mojam.com:80")
562 >>> conn.request("POST", "/cgi-bin/query", params, headers)
563 >>> response = conn.getresponse()
564 >>> print response.status, response.reason
565 200 OK
566 >>> data = response.read()
567 >>> conn.close()
568