PageRenderTime 46ms CodeModel.GetById 9ms app.highlight 29ms RepoModel.GetById 1ms app.codeStats 1ms

/Doc/library/httplib.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 557 lines | 395 code | 162 blank | 0 comment | 0 complexity | a1c71a35294908e4749dd45767b5e82a MD5 | raw file
  1:mod:`httplib` --- HTTP protocol client
  2=======================================
  3
  4.. module:: httplib
  5   :synopsis: HTTP and HTTPS protocol client (requires sockets).
  6
  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
 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
 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
 43   used.  When True, the optional parameter *strict* (which defaults to a false
 44   value) causes ``BadStatusLine`` to
 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
 48   (if it is not given, the global default timeout setting is used).
 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   .. note::
 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