## Httplib2

A comprehensive HTTP client library, `httplib2.py` supports many features left out of other HTTP libraries.

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 types of HTTP Authentication are supported. These can be used over both HTTP and HTTPS.
  - Digest
  - Basic
  - WSSE
  - HMAC Digest
  - Google Account Authentication
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.
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
Unit Tested
  A large and growing set of unit tests.

### Usage

A simple retrieval:

    import httplib2
    h = httplib2.Http(".cache")
    resp, content = h.request("http://example.org/", "GET")

The 'content' is the content retrieved from the URL. The content is already decompressed or unzipped if necessary. The 'resp' contains all the response headers.

To PUT some content to a server that uses SSL and Basic authentication:

    import httplib2
    h = httplib2.Http(".cache")
    h.add_credentials('name', 'password')
    resp, content = h.request("https://example.org/chap/2",
        "PUT", body="This is text",
        headers={'content-type':'text/plain'} )

Use the Cache-Control: header to control how the caching operates.

    import httplib2
    h = httplib2.Http(".cache")
    resp, content = h.request("http://bitworking.org/")
     ...
    resp, content = h.request("http://bitworking.org/",
        headers={'cache-control':'no-cache'})

The first request will be cached and since this is a request to bitworking.org it will be set to be cached for two hours, because that is how I have my server configured. Any subsequent GET to that URI will return the value from the on-disk cache and no request will be made to the server. You can use the Cache-Control: header to change the caches behavior and in this example the second request adds the Cache-Control: header with a value of 'no-cache' which tells the library that the cached copy must not be used when handling this request.

### Requirements

Requires Python 2.7, 3.4, or later. Does not require any libraries beyond what is found in the core library.

### Download/Installation

The latest release of httplib2 is 0.3.0 and can be downloaded from the from the dist directory. See the CHANGELOG for what's new in this version.

The httplib2 module is shipped as a distutils package. To install the library, first unpack the distribution archive, and issue the following command:

    $ python setup.py install

Download the distribution archives from here.

The resources used in the unit test cases are available also. More documentation on them will be forthcoming.

You can also get the sources directly from the SourceForge hosted subversion repository.

    svn co https://httplib2.svn.sourceforge.net/svnroot/httplib2/trunk httplib2

### Documentation

In addition to the Python library style documentation there are also two articles on XML.com, Doing HTTP Caching Right: Introducing httplib2 and httplib2: HTTP Persistence and Authentication .

### Feedback

Bugs and enhancement requests are handled through SourceForge, and anything is up for discussion on the httplib2 mailing list.

### To Do

This module is not perfect and needs the following:

- Support for Proxies
- A pluggable store for the cache is in place, with plugins for flat files and memcached. I eventually want to have plugins that allow keeping the cache in Berkeley DB, MySQL, etc.
- More unit tests

### Project Goal

To become a worthy addition to the Python core library.

### Additional Information

Author
  Joe Gregorio
License
  MIT
Contributors
  Thomas Broyer (t.broyer@ltgt.net)
  James Antill
  Xavier Verges Farrero
  Jonathan Feinberg
  Blair Zajac
  Sam Ruby
  Louis Nyffenegger
  (Your Name Here)

This page last updated on: $LastChangedDate$.