Doc/library/httplib.rst

   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
  19 This module defines classes which implement the client side of the HTTP and
  20 HTTPS protocols.  It is normally not used directly --- the module :mod:`urllib`
  21 uses 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
  34 The 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    .. 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
  88 The 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
 177 The 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
 189 and 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
 394 HTTPConnection 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
 440 As an alternative to using the :meth:`request` method described above, you can
 441 also 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
 479 HTTPResponse 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
 525 Examples
 526 --------
 527
 528 Here 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
 544 Here 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