18.7 httplib -- HTTP protocol client

# 18.7 `httplib` -- HTTP protocol client

This module defines classes which implement the client side of the HTTP and HTTPS protocols. It is normally not used directly -- the module `urllib` uses it to handle URLs that use HTTP and HTTPS.

Note: HTTPS support is only available if the `socket` module was compiled with SSL support.

Note: The public interface for this module changed substantially in Python 2.0. The `HTTP` class is retained only for backward compatibility with 1.5.2. It should not be used in new code. Refer to the online docstrings for usage.

The module provides the following classes:

class `HTTPConnection`( | host[, port[, strict]])

  An `HTTPConnection` instance represents one transaction with an HTTP server. It should be instantiated passing it a host and optional port number. If no port number is passed, the port is extracted from the host string if it has the form `host:port`, else the default HTTP port (80) is used. When True, the optional parameter strict causes `BadStatusLine` to be raised if the status line can't be parsed as a valid HTTP/1.0 or 1.1 status line.

  For example, the following calls all create instances that connect to the server at the same host and port:

      >>> h1 = httplib.HTTPConnection('www.cwi.nl')
      >>> h2 = httplib.HTTPConnection('www.cwi.nl:80')
      >>> h3 = httplib.HTTPConnection('www.cwi.nl', 80)

  New in version 2.0.

class `HTTPSConnection`( | host[, port[, key_file[, cert_file[, strict]]]])

  A subclass of `HTTPConnection` that uses SSL for communication with secure servers. Default port is `443`. key_file is the name of a PEM formatted file that contains your private key. cert_file is a PEM formatted certificate chain file.

  Warning: This does not do any certificate verification!

  New in version 2.0.

class `HTTPResponse`( | sock[, debuglevel=0][, strict=0])

  Class whose instances are returned upon successful connection. Not instantiated directly by user. New in version 2.0.

The following exceptions are raised as appropriate:

exception `HTTPException`
  The base class of the other exceptions in this module. It is a subclass of `Exception`. New in version 2.0.

exception `NotConnected`
  A subclass of `HTTPException`. New in version 2.0.

exception `InvalidURL`
  A subclass of `HTTPException`, raised if a port is given and is either non-numeric or empty. New in version 2.3.

exception `UnknownProtocol`
  A subclass of `HTTPException`. New in version 2.0.

exception `UnknownTransferEncoding`
  A subclass of `HTTPException`. New in version 2.0.

exception `UnimplementedFileMode`
  A subclass of `HTTPException`. New in version 2.0.

exception `IncompleteRead`
  A subclass of `HTTPException`. New in version 2.0.

exception `ImproperConnectionState`
  A subclass of `HTTPException`. New in version 2.0.

exception `CannotSendRequest`
  A subclass of `ImproperConnectionState`. New in version 2.0.

exception `CannotSendHeader`
  A subclass of `ImproperConnectionState`. New in version 2.0.

exception `ResponseNotReady`
  A subclass of `ImproperConnectionState`. New in version 2.0.

exception `BadStatusLine`
  A subclass of `HTTPException`. Raised if a server responds with a HTTP status code that we don't understand. New in version 2.0.

The constants defined in this module are:

`HTTP_PORT`
  The default port for the HTTP protocol (always `80`).

`HTTPS_PORT`
  The default port for the HTTPS protocol (always `443`).

and also the following constants for integer status codes:

Constant | Value | Definition
--- | --- | ---
`CONTINUE` | `100` | HTTP/1.1, RFC 2616, Section 10.1.1
`SWITCHING_PROTOCOLS` | `101` | HTTP/1.1, RFC 2616, Section 10.1.2
`PROCESSING` | `102` | WEBDAV, RFC 2518, Section 10.1

`OK` | `200` | HTTP/1.1, RFC 2616, Section 10.2.1
`CREATED` | `201` | HTTP/1.1, RFC 2616, Section 10.2.2
`ACCEPTED` | `202` | HTTP/1.1, RFC 2616, Section 10.2.3
`NON_AUTHORITATIVE_INFORMATION` | `203` | HTTP/1.1, RFC 2616, Section 10.2.4
`NO_CONTENT` | `204` | HTTP/1.1, RFC 2616, Section 10.2.5
`RESET_CONTENT` | `205` | HTTP/1.1, RFC 2616, Section 10.2.6
`PARTIAL_CONTENT` | `206` | HTTP/1.1, RFC 2616, Section 10.2.7
`MULTI_STATUS` | `207` | WEBDAV RFC 2518, Section 10.2
`IM_USED` | `226` | Delta encoding in HTTP, RFC 3229, Section 10.4.1

`MULTIPLE_CHOICES` | `300` | HTTP/1.1, RFC 2616, Section 10.3.1
`MOVED_PERMANENTLY` | `301` | HTTP/1.1, RFC 2616, Section 10.3.2
`FOUND` | `302` | HTTP/1.1, RFC 2616, Section 10.3.3
`SEE_OTHER` | `303` | HTTP/1.1, RFC 2616, Section 10.3.4
`NOT_MODIFIED` | `304` | HTTP/1.1, RFC 2616, Section 10.3.5
`USE_PROXY` | `305` | HTTP/1.1, RFC 2616, Section 10.3.6
`TEMPORARY_REDIRECT` | `307` | HTTP/1.1, RFC 2616, Section 10.3.8

`BAD_REQUEST` | `400` | HTTP/1.1, RFC 2616, Section 10.4.1
`UNAUTHORIZED` | `401` | HTTP/1.1, RFC 2616, Section 10.4.2
`PAYMENT_REQUIRED` | `402` | HTTP/1.1, RFC 2616, Section 10.4.3
`FORBIDDEN` | `403` | HTTP/1.1, RFC 2616, Section 10.4.4
`NOT_FOUND` | `404` | HTTP/1.1, RFC 2616, Section 10.4.5
`METHOD_NOT_ALLOWED` | `405` | HTTP/1.1, RFC 2616, Section 10.4.6
`NOT_ACCEPTABLE` | `406` | HTTP/1.1, RFC 2616, Section 10.4.7
`PROXY_AUTHENTICATION_REQUIRED` | `407` | HTTP/1.1, RFC 2616, Section 10.4.8
`REQUEST_TIMEOUT` | `408` | HTTP/1.1, RFC 2616, Section 10.4.9
`CONFLICT` | `409` | HTTP/1.1, RFC 2616, Section 10.4.10
`GONE` | `410` | HTTP/1.1, RFC 2616, Section 10.4.11
`LENGTH_REQUIRED` | `411` | HTTP/1.1, RFC 2616, Section 10.4.12
`PRECONDITION_FAILED` | `412` | HTTP/1.1, RFC 2616, Section 10.4.13
`REQUEST_ENTITY_TOO_LARGE` | `413` | HTTP/1.1, RFC 2616, Section 10.4.14
`REQUEST_URI_TOO_LONG` | `414` | HTTP/1.1, RFC 2616, Section 10.4.15
`UNSUPPORTED_MEDIA_TYPE` | `415` | HTTP/1.1, RFC 2616, Section 10.4.16
`REQUESTED_RANGE_NOT_SATISFIABLE` | `416` | HTTP/1.1, RFC 2616, Section 10.4.17
`EXPECTATION_FAILED` | `417` | HTTP/1.1, RFC 2616, Section 10.4.18
`UNPROCESSABLE_ENTITY` | `422` | WEBDAV, RFC 2518, Section 10.3
`LOCKED` | `423` | WEBDAV RFC 2518, Section 10.4
`FAILED_DEPENDENCY` | `424` | WEBDAV, RFC 2518, Section 10.5
`UPGRADE_REQUIRED` | `426` | HTTP Upgrade to TLS, RFC 2817, Section 6

`INTERNAL_SERVER_ERROR` | `500` | HTTP/1.1, RFC 2616, Section 10.5.1
`NOT_IMPLEMENTED` | `501` | HTTP/1.1, RFC 2616, Section 10.5.2
`BAD_GATEWAY` | `502` | HTTP/1.1 RFC 2616, Section 10.5.3
`SERVICE_UNAVAILABLE` | `503` | HTTP/1.1, RFC 2616, Section 10.5.4
`GATEWAY_TIMEOUT` | `504` | HTTP/1.1 RFC 2616, Section 10.5.5
`HTTP_VERSION_NOT_SUPPORTED` | `505` | HTTP/1.1, RFC 2616, Section 10.5.6
`INSUFFICIENT_STORAGE` | `507` | WEBDAV, RFC 2518, Section 10.6
`NOT_EXTENDED` | `510` | An HTTP Extension Framework, RFC 2774, Section 7

`responses`
  This dictionary maps the HTTP 1.1 status codes to the W3C names.

  Example: `httplib.responses[httplib.NOT_FOUND]` is `'Not Found'`. New in version 2.5.