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 71 h = httplib2.Http(".cache") 72 resp, content = h.request("http://example.org/", "GET") 73 </code></pre> 74 75 <p>The 'content' is the content retrieved from the URL. 76 The content is already decompressed or unzipped if necessary. 77 The 'resp' contains all the response headers. 78 </p> 79 80 <p>To PUT some content to a server that uses SSL 81 and Basic authentication:</p> 82 83 <pre><code>import httplib2 84 h = httplib2.Http(".cache") 85 h.add_credentials('name', 'password') 86 resp, 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 95 h = httplib2.Http(".cache") 96 resp, content = h.request("http://bitworking.org/") 97 ... 98 resp, 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 103 bitworking.org it will be set to be cached for two hours, because 104 that is how I have my server configured. 105 Any subsequent GET to that URI will return the value from the 106 on-disk cache and no request will be made to the server. 107 You can use the Cache-Control: header to change the caches behavior and 108 in this example the second request adds the Cache-Control: header with a value 109 of 'no-cache' which tells the library that the cached copy 110 must 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 116 any 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 121 can 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 124 version.</p> 125 126 127 <p>The httplib2 module is shipped as a distutils package. To install 128 the library, first unpack the distribution archive, and issue the following 129 command:</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 147 are 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"> 150 httplib2: 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 158 on 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 (a] 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
