Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / httplib2 / 1ad5dd57f7a5dcfef699a3a199652066de9d9032 / . / index.html
blob: 3a100a03ffcc62d7d14a4b7da1e92ba647c5e02a [file] [log] [blame]
jcgregorio2d66d4f2006-02-07 05:34:14 +0000[diff] [blame]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
jcgregorio4ce467a2006-03-22 14:48:43 +0000[diff] [blame]12 <div>
jcgregorio2d66d4f2006-02-07 05:34:14 +0000[diff] [blame]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 three 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 </ul>
37 </dd>
38
39 <dt>Caching</dt>
40 <dd>The module can optionally operate with a private
41 cache that understands the Cache-Control: header and
42 uses both the ETag and Last-Modified cache validators.
43 </dd>
44
45 <dt>All Methods</dt>
46 <dd>The module can handle any HTTP request method, not just GET and POST.</dd>
47
48 <dt>Redirects</dt>
49 <dd>Automatically follows 3XX redirects on GETs.</dd>
50
51 <dt>Compression</dt>
jcgregorioa0713ab2006-07-01 05:21:34 +0000[diff] [blame]52 <dd>Handles both 'deflate' and 'gzip' types of compression.</dd>
jcgregorio2d66d4f2006-02-07 05:34:14 +0000[diff] [blame]53
54 <dt>Lost update support</dt>
55 <dd>Automatically adds back ETags into PUT requests to resources
56 we have already cached. This implements Section 3.2 of
57 <a href="http://www.w3.org/1999/04/Editing/#Table">Detecting the Lost Update Problem Using Unreserved Checkout</a></dd>
58
59 <dt>Unit Tested</dt>
60 <dd>A large and growing set of unit tests.</dd>
61
62 </dl>
63
jcgregorio4ce467a2006-03-22 14:48:43 +0000[diff] [blame]64<h3>Usage</h3>
jcgregorio2d66d4f2006-02-07 05:34:14 +0000[diff] [blame]65
66<p>A simple retrieval:</p>
67
jcgregoriob7753b32006-02-15 19:04:08 +0000[diff] [blame]68<pre><code>import httplib2
69h = httplib2.Http(".cache")
70resp, content = h.request("http://example.org/", "GET")
jcgregorio2d66d4f2006-02-07 05:34:14 +0000[diff] [blame]71</code></pre>
72
73<p>The 'content' is the content retrieved from the URL.
74The content is already decompressed or unzipped if necessary.
jcgregoriob7753b32006-02-15 19:04:08 +0000[diff] [blame]75The 'resp' contains all the response headers.
jcgregorio2d66d4f2006-02-07 05:34:14 +0000[diff] [blame]76</p>
77
78<p>To PUT some content to a server that uses SSL
79and Basic authentication:</p>
80
jcgregoriob7753b32006-02-15 19:04:08 +0000[diff] [blame]81<pre><code>import httplib2
82h = httplib2.Http(".cache")
jcgregorioe34942d2006-05-08 01:06:37 +0000[diff] [blame]83h.add_credentials('name', 'password')
jcgregoriob7753b32006-02-15 19:04:08 +0000[diff] [blame]84resp, content = h.request("https://example.org/chap/2",
85 "PUT", body="This is text",
86 headers={'content-type':'text/plain'} )
jcgregorio2d66d4f2006-02-07 05:34:14 +0000[diff] [blame]87</code></pre>
88
89<p>Use the Cache-Control: header to control
90 how the caching operates.</p>
91
jcgregoriob7753b32006-02-15 19:04:08 +0000[diff] [blame]92<pre><code>import httplib2
93h = httplib2.Http(".cache")
94resp, content = h.request("http://bitworking.org/")
95 ...
96resp, content = h.request("http://bitworking.org/",
97 headers={'cache-control':'no-cache'})
jcgregorio2d66d4f2006-02-07 05:34:14 +0000[diff] [blame]98</code></pre>
99
100<p>The first request will be cached and since this is a request to
101bitworking.org it will be set to be cached for two hours, because
102that is how I have my server configured.
103Any subsequent GET to that URI will return the value from the
104on-disk cache and no request will be made to the server.
105You can use the Cache-Control: header to change the caches behavior and
106in this example the second request adds the Cache-Control: header with a value
107of 'no-cache' which tells the library that the cached copy
108must not be used when handling this request.
109</p>
110
jcgregorio4ce467a2006-03-22 14:48:43 +0000[diff] [blame]111<h3>Requirements</h3>
jcgregorio2d66d4f2006-02-07 05:34:14 +0000[diff] [blame]112
jcgregorio1eed40f2006-02-15 18:56:46 +0000[diff] [blame]113<p>Requires Python 2.3 or later. Does not require
jcgregorio2d66d4f2006-02-07 05:34:14 +0000[diff] [blame]114any libraries beyond what is found in the core library.</p>
115
jcgregorio4ce467a2006-03-22 14:48:43 +0000[diff] [blame]116<h3>Download/Installation</h3>
jcgregorio1eed40f2006-02-15 18:56:46 +0000[diff] [blame]117
jcgregorio1ad5dd52006-07-01 19:36:36 +0000[diff] [blame^]118<p>The latest release of httplib2 is 0.2.0 and
119can be <a href="dist">downloaded from the from
120 the dist directory</a>. See the
121<a href="CHANGELOG">CHANGELOG</a> for what's new in this
122version.</p>
123
124
jcgregorio1eed40f2006-02-15 18:56:46 +0000[diff] [blame]125<p>The httplib2 module is shipped as a distutils package. To install
126the library, first unpack the distribution archive, and issue the following
127command:</p>
128
129<pre><code>$ python setup.py install</code></pre>
130
131<p><a href="dist">Download the distribution archives from here</a>. </p>
132
133<p> <a href="test">The resources used in the unit test cases</a>
134 are available also. More documentation on them will be forthcoming.</p>
135
jcgregorioec114932006-03-03 16:23:26 +0000[diff] [blame]136<p>You can also get the sources directly from the SourceForge hosted
137 subversion repository.</p>
138
jcgregorio4ce467a2006-03-22 14:48:43 +0000[diff] [blame]139<pre>svn co https://svn.sourceforge.net/svnroot/httplib2/trunk httplib2</pre>
140
141
142<h3>Feedback</h3>
143
144<p>Bugs and enhancement requests are handled through
145<a href="http://sourceforge.net/projects/httplib2/">SourceForge</a>, and anything is up for discussion
146on the <a href="http://sourceforge.net/mail/?group_id=161082">httplib2 mailing list</a>.
147</p>
148
149<h3>To Do</h3>
jcgregorio2d66d4f2006-02-07 05:34:14 +0000[diff] [blame]150
151<p>This module is not perfect and needs the following:</p>
152<ul>
153 <li>Support for Proxies</li>
jcgregorio1ad5dd52006-07-01 19:36:36 +0000[diff] [blame^]154 <li><del>A pluggable store for the cache.</del> Right now the store is just flat files in a directory.
155 I would like to have plugins that allow keeping the cache in Berkeley DB, <del>memcached</del>, Squid, MySQL, etc.</li>
jcgregorio2d66d4f2006-02-07 05:34:14 +0000[diff] [blame]156 <li>More unit tests</li>
157</ul>
158
jcgregorio4ce467a2006-03-22 14:48:43 +0000[diff] [blame]159<h3>Project Goal</h3>
jcgregorio2d66d4f2006-02-07 05:34:14 +0000[diff] [blame]160
161<p>To become a worthy addition to the Pyhton core library.</p>
162
jcgregorio4ce467a2006-03-22 14:48:43 +0000[diff] [blame]163<h3>Additional Information</h3>
jcgregorio2d66d4f2006-02-07 05:34:14 +0000[diff] [blame]164
165<p>
166 <dl>
167 <dt>Author</dt>
168 <dd>Joe Gregorio</dd>
169
170 <dt>License</dt>
171 <dd>MIT</dd>
172
173 <dt>Contributors</dt>
jcgregorio22a9e162006-03-22 14:45:46 +0000[diff] [blame]174
jcgregorio92088922006-07-01 05:53:21 +0000[diff] [blame]175 <dd> Thomas Broyer (t.broyer@ltgt.net) </dd>
176 <dd> James Antill </dd>
177 <dd> Xavier Verges Farrero </dd>
178 <dd> Jonathan Feinberg </dd>
179 <dd> Blair Zajac </dd>
180 <dd> (Your Name Here) </dd>
jcgregorio22a9e162006-03-22 14:45:46 +0000[diff] [blame]181 </dl>
jcgregorio2d66d4f2006-02-07 05:34:14 +0000[diff] [blame]182</p>
183
jcgregorio1eed40f2006-02-15 18:56:46 +0000[diff] [blame]184 <p style="font-size: small">This page last updated on: $LastChangedDate$.</p>
jcgregorio2d66d4f2006-02-07 05:34:14 +0000[diff] [blame]185
186 </div>
187 </div>
188 <!--#include virtual="footer.html" -->
189 </div>
190</body>
191
192</html>