Home | History | Annotate | Download | only in httplib2 
      1 Introduction
      2 ============
      3 
      4 httplib2 is a comprehensive HTTP client library, httplib2.py supports many
      5 features left out of other HTTP libraries.
      6 
      7 ### HTTP and HTTPS
      8 
      9 HTTPS support is only available if the socket module was
     10 compiled with SSL support.
     11     
     12 ### Keep-Alive
     13 
     14 Supports HTTP 1.1 Keep-Alive, keeping the socket open and
     15 performing multiple requests over the same connection if
     16 possible.
     17     
     18 ### Authentication
     19 
     20 The following three types of HTTP Authentication are
     21 supported. These can be used over both HTTP and HTTPS.
     22 
     23 * Digest
     24 * Basic
     25 * WSSE
     26 
     27 ### Caching
     28 
     29 The module can optionally operate with a private cache that
     30 understands the Cache-Control: header and uses both the ETag
     31 and Last-Modified cache validators.
     32     
     33 ### All Methods
     34 
     35 The module can handle any HTTP request method, not just GET
     36 and POST.
     37     
     38 ### Redirects
     39 
     40 Automatically follows 3XX redirects on GETs.
     41     
     42 ### Compression
     43 
     44 Handles both 'deflate' and 'gzip' types of compression.
     45     
     46 ### Lost update support
     47 
     48 Automatically adds back ETags into PUT requests to resources
     49 we have already cached. This implements Section 3.2 of
     50 Detecting the Lost Update Problem Using Unreserved Checkout.
     51     
     52 ### Unit Tested
     53 
     54 A large and growing set of unit tests.
     55 
     56 
     57 Installation
     58 ============
     59 
     60 
     61     $ pip install httplib2
     62 
     63 
     64 Usage
     65 =====
     66 
     67 A simple retrieval:
     68 
     69 ```python
     70 import httplib2
     71 h = httplib2.Http(".cache")
     72 (resp_headers, content) = h.request("http://example.org/", "GET")
     73 ```
     74 
     75 The 'content' is the content retrieved from the URL. The content
     76 is already decompressed or unzipped if necessary.
     77 
     78 To PUT some content to a server that uses SSL and Basic authentication:
     79 
     80 ```python
     81 import httplib2
     82 h = httplib2.Http(".cache")
     83 h.add_credentials('name', 'password')
     84 (resp, content) = h.request("https://example.org/chapter/2",
     85                             "PUT", body="This is text",
     86                             headers={'content-type':'text/plain'} )
     87 ```
     88 
     89 Use the Cache-Control: header to control how the caching operates.
     90 
     91 ```python
     92 import httplib2
     93 h = httplib2.Http(".cache")
     94 (resp, content) = h.request("http://bitworking.org/", "GET")
     95 ...
     96 (resp, content) = h.request("http://bitworking.org/", "GET",
     97                             headers={'cache-control':'no-cache'})
     98 ```
     99 
    100 The first request will be cached and since this is a request
    101 to bitworking.org it will be set to be cached for two hours,
    102 because that is how I have my server configured. Any subsequent
    103 GET to that URI will return the value from the on-disk cache
    104 and no request will be made to the server. You can use the
    105 Cache-Control: header to change the caches behavior and in
    106 this example the second request adds the Cache-Control:
    107 header with a value of 'no-cache' which tells the library
    108 that the cached copy must not be used when handling this request.
    109 
    110 More example usage can be found at:
    111 
    112  * https://github.com/httplib2/httplib2/wiki/Examples
    113  * https://github.com/httplib2/httplib2/wiki/Examples-Python3
    114