1<html>
2<head>
3     <!--#include virtual="header.html" -->
4    <title>Joe Gregorio | BitWorking | Projects | httplib2.py</title>
5</head>
6<body class='main' id="top" name="top" >
7    <div class="body">
8        <!--#include virtual="titlebar.html" -->
9
10        <div class="content">
11
12            <div>
13
14                <h2>Httplib2</h2>
15                <p>A comprehensive HTTP client library, <code>httplib2.py</code>
16                supports many features left out of other HTTP libraries.
17                </p>
18                <dl>
19                    <dt>HTTP and HTTPS</dt>
20                    <dd>HTTPS support is only available if the socket module was compiled with SSL support.
21                    </dd>
22
23                    <dt>Keep-Alive</dt>
24                    <dd>Supports HTTP 1.1 Keep-Alive, keeping the socket
25                    open and performing multiple requests over the same connection
26                    if possible.
27                    </dd>
28
29                    <dt>Authentication</dt>
30                    <dd>The following types of HTTP Authentication are supported.
31                    These can be used over both HTTP and HTTPS.
32                    <ul>
33                        <li><a href="http://www.faqs.org/rfcs/rfc2617.html">Digest</a></li>
34                        <li><a href="http://www.faqs.org/rfcs/rfc2617.html">Basic</a></li>
35                        <li><a href="http://www.xml.com/pub/a/2003/12/17/dive.html">WSSE</a></li>
36                        <li><a href="http://franklinmint.fm/2006/02/28/draft-sayre-http-hmac-digest.html">HMAC Digest</a></li>
37                        <li><a href="http://code.google.com/apis/accounts/AuthForInstalledApps.html">Google Account Authentication</a></li>
38                    </ul>
39                    </dd>
40
41                    <dt>Caching</dt>
42                    <dd>The module can optionally operate with a private
43                    cache that understands the Cache-Control: header and
44                    uses both the ETag and Last-Modified cache validators.
45                    </dd>
46
47                    <dt>All Methods</dt>
48                    <dd>The module can handle any HTTP request method, not just GET and POST.</dd>
49
50                    <dt>Redirects</dt>
51                    <dd>Automatically follows 3XX redirects on GETs.</dd>
52
53                    <dt>Compression</dt>
54                    <dd>Handles both 'deflate' and 'gzip' types of compression.</dd>
55
56                    <dt>Lost update support</dt>
57                    <dd>Automatically adds back ETags into PUT requests to resources
58                    we have already cached. This implements Section 3.2 of
59                    <a href="http://www.w3.org/1999/04/Editing/#Table">Detecting the Lost Update Problem Using Unreserved Checkout</a></dd>
60
61                    <dt>Unit Tested</dt>
62                    <dd>A large and growing set of unit tests.</dd>
63
64                </dl>
65
66<h3>Usage</h3>
67
68<p>A simple retrieval:</p>
69
70<pre><code>import httplib2
71h = httplib2.Http(".cache")
72resp, content = h.request("http://example.org/", "GET")
73</code></pre>
74
75<p>The 'content' is the content retrieved from the URL.
76The content is already decompressed or unzipped if necessary.
77The 'resp' contains all the response headers.
78</p>
79
80<p>To PUT some content to a server that uses SSL
81and Basic authentication:</p>
82
83<pre><code>import httplib2
84h = httplib2.Http(".cache")
85h.add_credentials('name', 'password')
86resp, content = h.request("https://example.org/chap/2",
87    "PUT", body="This is text",
88    headers={'content-type':'text/plain'} )
89</code></pre>
90
91<p>Use the Cache-Control: header to control
92   how the caching operates.</p>
93
94<pre><code>import httplib2
95h = httplib2.Http(".cache")
96resp, content = h.request("http://bitworking.org/")
97 ...
98resp, content = h.request("http://bitworking.org/",
99    headers={'cache-control':'no-cache'})
100</code></pre>
101
102<p>The first request will be cached and since this is a request to
103bitworking.org it will be set to be cached for two hours, because
104that is how I have my server configured.
105Any subsequent GET to that URI will return the value from the
106on-disk cache and no request will be made to the server.
107You can use the Cache-Control: header to change the caches behavior and
108in this example the second request adds the Cache-Control: header with a value
109of 'no-cache' which tells the library that the cached copy
110must not be used when handling this request.
111</p>
112
113<h3>Requirements</h3>
114
115<p>Requires Python 2.7, 3.4, or later. Does not require
116any libraries beyond what is found in the core library.</p>
117
118<h3>Download/Installation</h3>
119
120<p>The latest release of httplib2 is 0.3.0 and
121can be <a href="dist">downloaded from the from
122    the dist directory</a>. See the
123<a href="CHANGELOG">CHANGELOG</a> for what's new in this
124version.</p>
125
126
127<p>The httplib2 module is shipped as a distutils package.  To install
128the library, first unpack the distribution archive, and issue the following
129command:</p>
130
131<pre><code>$ python setup.py install</code></pre>
132
133<p><a href="dist">Download the distribution archives from here</a>. </p>
134
135<p> <a href="test">The resources used in the unit test cases</a>
136  are available also. More documentation on them will be forthcoming.</p>
137
138<p>You can also get the sources directly from the SourceForge hosted
139  subversion repository.</p>
140
141<pre>svn co https://httplib2.svn.sourceforge.net/svnroot/httplib2/trunk httplib2</pre>
142
143
144<h3>Documentation</h3>
145
146<p>In addition to the <a href="ref/">Python library style documentation</a> there
147are also two articles on XML.com, <a href="http://www.xml.com/pub/a/2006/02/01/doing-http-caching-right-introducing-httplib2.html">
148    Doing HTTP Caching Right: Introducing httplib2</a> and
149<a href="http://www.xml.com/pub/a/2006/03/29/httplib2-http-persistence-and-authentication.html">
150httplib2: HTTP Persistence and Authentication </a>.
151
152</p>
153
154<h3>Feedback</h3>
155
156<p>Bugs and enhancement requests are handled through
157<a href="http://sourceforge.net/projects/httplib2/">SourceForge</a>, and anything is up for discussion
158on the <a href="http://sourceforge.net/mail/?group_id=161082">httplib2 mailing list</a>.
159</p>
160
161<h3>To Do</h3>
162
163<p>This module is not perfect and needs the following:</p>
164<ul>
165    <li>Support for Proxies</li>
166    <li>A pluggable store for the cache is in place, with plugins for
167    flat files and memcached.
168    I eventually want to have plugins that allow keeping the cache in Berkeley DB, MySQL, etc.</li>
169    <li>More unit tests</li>
170</ul>
171
172<h3>Project Goal</h3>
173
174<p>To become a worthy addition to the Python core library.</p>
175
176<h3>Additional Information</h3>
177
178<p>
179   <dl>
180       <dt>Author</dt>
181       <dd>Joe Gregorio</dd>
182
183       <dt>License</dt>
184       <dd>MIT</dd>
185
186       <dt>Contributors</dt>
187
188       <dd> Thomas Broyer (t.broyer@ltgt.net) </dd>
189       <dd> James Antill </dd>
190       <dd> Xavier Verges Farrero </dd>
191       <dd> Jonathan Feinberg </dd>
192       <dd> Blair Zajac </dd>
193       <dd> Sam Ruby</dd>
194       <dd> Louis Nyffenegger </dd>
195       <dd> (Your Name Here) </dd>
196   </dl>
197</p>
198
199  <p style="font-size: small">This page last updated on: $LastChangedDate$.</p>
200
201            </div>
202        </div>
203     <!--#include virtual="footer.html" -->
204    </div>
205</body>
206
207</html>
208