1.1 httplib2 A comprehensive HTTP client library.

# 1.1 `httplib2` A comprehensive HTTP client library.

The `httplib2` module is a comprehensive HTTP client library with the following features:

HTTP and HTTPS
  HTTPS support is only available if the socket module was compiled with SSL support.
Keep-Alive
  Supports HTTP 1.1 Keep-Alive, keeping the socket open and performing multiple requests over the same connection if possible.
Authentication
  The following three types of HTTP Authentication are supported. These can be used over both HTTP and HTTPS.
  - Digest
  - Basic
  - WSSE
Caching
  The module can optionally operate with a private cache that understands the Cache-Control: header and uses both the ETag and Last-Modified cache validators.
All Methods
  The module can handle any HTTP request method, not just GET and POST.
Redirects
  Automatically follows 3XX redirects on GETs.
Compression
  Handles both 'deflate' and 'gzip' types of compression.
Proxies
  If the Socksipy module is installed then httplib2 can handle sock4, sock5 and http proxies.
Lost update support
  Automatically adds back ETags into PUT requests to resources we have already cached. This implements Section 3.2 of Detecting the Lost Update Problem Using Unreserved Checkout

The `httplib2` module defines the following variables:

`debuglevel`
  The amount of debugging information to print. The default is 0.

The `httplib2` module may raise the following Exceptions. Note that there is an option that turns exceptions into normal responses with an HTTP status code indicating an error occured. See `Http.force_exception_to_status_code`

exception `HttpLib2Error`
  The Base Exception for all exceptions raised by httplib2.

exception `RedirectMissingLocation`
  A 3xx redirect response code was provided but no Location: header was provided to point to the new location.

exception `RedirectLimit`
  The maximum number of redirections was reached without coming to a final URI.

exception `ServerNotFoundError`
  Unable to resolve the host name given.

exception `RelativeURIError`
  A relative, as opposed to an absolute URI, was passed into request().

exception `FailedToDecompressContent`
  The headers claimed that the content of the response was compressed but the decompression algorithm applied to the content failed.

exception `UnimplementedDigestAuthOptionError`
  The server requested a type of Digest authentication that we are unfamiliar with.

exception `UnimplementedHmacDigestAuthOptionError`
  The server requested a type of HMACDigest authentication that we are unfamiliar with.

class `Http`( | [cache=None], [timeout=None], [proxy_info=None])

  The class that represents a client HTTP interface. The cache parameter is either the name of a directory to be used as a flat file cache, or it must an object that implements the required caching interface. The timeout parameter is the socket level timeout. The proxy_info is an instance of `ProxyInfo` and is supplied if a proxy is to be used. Note that the Socksipy module must be installed for proxy support to work.

class `Response`( | info)

  Response is a subclass of `dict` and instances of this class are returned from calls to Http.request. The info parameter is either an `rfc822.Message` or an `httplib.HTTPResponse` object.

class `FileCache`( | dir_name, [safe=safename])

  FileCache implements a Cache as a directory of files. The dir_name parameter is the name of the directory to use. If the directory does not exist then FileCache attempts to create the directory. The optional safe parameter is a funtion which generates the cache filename for each URI. A FileCache object is constructed and used for caching when you pass a directory name into the constructor of `Http`.

class `ProxyInfo`( | proxy_type, proxy_host, proxy_port, [proxy_rdns=None], [proxy_user=None], [proxy_pass=None])

  The parameter proxy_type must be set to one of socks.PROXY_TYPE_XXX constants. The proxy_host and proxy_port must be set to the location of the proxy. The optional proxy_rdns should be set to True if the DNS server on the proxy should be used. The proxy_user and proxy_pass are supplied when the proxy is protected by authentication.