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