Blame - index.html - platform/external/python/httplib2

2006-02-07 05:34:14 +0000

[diff] [blame]

1

<html>

2

<head>

3

4

<title>Joe Gregorio | BitWorking | Projects | httplib2.py</title>

</head>

jcgregorio

2006-03-22 14:48:43 +0000

[diff] [blame]

12

<div>

jcgregorio

2006-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.

</dd>

<dt>Keep-Alive</dt>

<dd>Supports HTTP 1.1 Keep-Alive, keeping the socket

25

open and performing multiple requests over the same connection

if possible.

</dd>

<dt>Authentication</dt>

jcgregorio

48bb357

2006-08-28 17:31:06 +0000

[diff] [blame]

30

<dd>The following types of HTTP Authentication are supported.

jcgregorio

2006-02-07 05:34:14 +0000

[diff] [blame]

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

jcgregorio

48bb357

2006-08-28 17:31:06 +0000

[diff] [blame]

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>

jcgregorio

2006-02-07 05:34:14 +0000

[diff] [blame]

</ul>

</dd>

<dt>Caching</dt>

<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.

</dd>

<dt>All Methods</dt>

<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>

jcgregorio

a0713ab

2006-07-01 05:21:34 +0000

[diff] [blame]

54

<dd>Handles both 'deflate' and 'gzip' types of compression.</dd>

jcgregorio

2006-02-07 05:34:14 +0000

[diff] [blame]

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>

</dl>

jcgregorio

2006-03-22 14:48:43 +0000

[diff] [blame]

66

<h3>Usage</h3>

jcgregorio

2006-02-07 05:34:14 +0000

[diff] [blame]

67

68

<p>A simple retrieval:</p>

69

jcgregorio

2006-02-15 19:04:08 +0000

[diff] [blame]

70

<pre><code>import httplib2

71

h = httplib2.Http(".cache")

72

resp, content = h.request("http://example.org/", "GET")

jcgregorio

2006-02-07 05:34:14 +0000

[diff] [blame]

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.

jcgregorio

2006-02-15 19:04:08 +0000

[diff] [blame]

77

The 'resp' contains all the response headers.

jcgregorio

2006-02-07 05:34:14 +0000

[diff] [blame]

78

</p>

79

80

<p>To PUT some content to a server that uses SSL

81

and Basic authentication:</p>

82

jcgregorio

2006-02-15 19:04:08 +0000

[diff] [blame]

83

<pre><code>import httplib2

84

h = httplib2.Http(".cache")

jcgregorio

e34942d

2006-05-08 01:06:37 +0000

[diff] [blame]

85

h.add_credentials('name', 'password')

jcgregorio

2006-02-15 19:04:08 +0000

[diff] [blame]

86

resp, content = h.request("https://example.org/chap/2",

87

"PUT", body="This is text",

88

headers={'content-type':'text/plain'} )

jcgregorio

2006-02-07 05:34:14 +0000

[diff] [blame]

89

</code></pre>

90

91

<p>Use the Cache-Control: header to control

92

how the caching operates.</p>

93

jcgregorio

2006-02-15 19:04:08 +0000

[diff] [blame]

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'})

jcgregorio

2006-02-07 05:34:14 +0000

[diff] [blame]

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

jcgregorio

2006-03-22 14:48:43 +0000

[diff] [blame]

113

<h3>Requirements</h3>

jcgregorio

2006-02-07 05:34:14 +0000

[diff] [blame]

114

jcgregorio

1eed40f

2006-02-15 18:56:46 +0000

[diff] [blame]

115

<p>Requires Python 2.3 or later. Does not require

jcgregorio

2006-02-07 05:34:14 +0000

[diff] [blame]

116

any libraries beyond what is found in the core library.</p>

117

jcgregorio

2006-03-22 14:48:43 +0000

[diff] [blame]

118

<h3>Download/Installation</h3>

jcgregorio

1eed40f

2006-02-15 18:56:46 +0000

[diff] [blame]

119

jcgregorio

1ad5dd5

2006-07-01 19:36:36 +0000

[diff] [blame]

120

<p>The latest release of httplib2 is 0.2.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

version.</p>

jcgregorio

2006-02-15 18:56:46 +0000

[diff] [blame]

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

jcgregorio

ec11493

2006-03-03 16:23:26 +0000

[diff] [blame]

138

<p>You can also get the sources directly from the SourceForge hosted

139

subversion repository.</p>

140

jcgregorio

864fa04

2007-02-14 03:37:33 +0000

[diff] [blame]

141

<pre>svn co https://httplib2.svn.sourceforge.net/svnroot/httplib2/trunk httplib2</pre>

142

jcgregorio

2006-03-22 14:48:43 +0000

[diff] [blame]

143

jcgregorio

f9c2835

2006-07-03 18:17:02 +0000

[diff] [blame]

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

150

httplib2: HTTP Persistence and Authentication </a>.

151

152

</p>

jcgregorio

2006-03-22 14:48:43 +0000

[diff] [blame]

<h3>Feedback</h3>

<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>.

</p>

jcgregorio

2006-02-07 05:34:14 +0000

[diff] [blame]

162

163

<p>This module is not perfect and needs the following:</p>

164

<ul>

165

<li>Support for Proxies</li>

jcgregorio

a39ff0a

2007-02-14 03:41:53 +0000

[diff] [blame]

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>

jcgregorio

2006-02-07 05:34:14 +0000

[diff] [blame]

169

<li>More unit tests</li>

170

</ul>

171

jcgregorio

2006-03-22 14:48:43 +0000

[diff] [blame]

172

<h3>Project Goal</h3>

jcgregorio

2006-02-07 05:34:14 +0000

[diff] [blame]

173

jcgregorio

92ff808

2006-07-31 13:43:28 +0000

[diff] [blame]

174

<p>To become a worthy addition to the Python core library.</p>

jcgregorio

2006-02-07 05:34:14 +0000

[diff] [blame]

175

jcgregorio

2006-03-22 14:48:43 +0000

[diff] [blame]

176

<h3>Additional Information</h3>

jcgregorio

2006-02-07 05:34:14 +0000

[diff] [blame]

<p>

<dl>

<dt>Author</dt>

<dd>Joe Gregorio</dd>

<dt>License</dt>

<dt>Contributors</dt>

jcgregorio

22a9e16

2006-03-22 14:45:46 +0000

[diff] [blame]

187

jcgregorio

9208892

2006-07-01 05:53:21 +0000

[diff] [blame]

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

jcgregorio

22a9e16

2006-03-22 14:45:46 +0000

[diff] [blame]

194

</dl>

jcgregorio

2006-02-07 05:34:14 +0000

[diff] [blame]

195

</p>

196

jcgregorio

1eed40f

2006-02-15 18:56:46 +0000

[diff] [blame]

197

<p style="font-size: small">This page last updated on: $LastChangedDate$.</p>

jcgregorio