Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / httplib2 / 258eefbf401dea86fd62d6bd5ab6cb1238eedc00 / . / doc / html / libhttplib2.html
blob: e477cad5b4dfdb7092a9f77f9613292c58a03acc [file] [log] [blame]
joe.gregorio258eefb2008-09-06 01:30:25 +0000[diff] [blame^]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml">
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5 <title>httplib2 A comprehensive HTTP client library. &mdash; httplib2 v0.4 documentation</title>
6 <link rel="stylesheet" href="_static/default.css" type="text/css" />
7 <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
8 <script type="text/javascript">
9 var DOCUMENTATION_OPTIONS = {
10 URL_ROOT: '',
11 VERSION: '0.4',
12 COLLAPSE_MODINDEX: false,
13 FILE_SUFFIX: ''
14 };
15 </script>
16 <script type="text/javascript" src="_static/jquery.js"></script>
17 <script type="text/javascript" src="_static/interface.js"></script>
18 <script type="text/javascript" src="_static/doctools.js"></script>
19 <link rel="contents" title="Global table of contents" href="contents.html" />
20 <link rel="index" title="Global index" href="genindex.html" />
21 <link rel="search" title="Search" href="search.html" />
22 <link rel="top" title="httplib2 v0.4 documentation" href="index.html" />
23 <link rel="prev" title="The httplib2 Library" href="index.html" />
24 </head>
25 <body>
26 <div class="related">
27 <h3>Navigation</h3>
28 <ul>
29 <li class="right" style="margin-right: 10px">
30 <a href="genindex.html" title="General Index"
31 accesskey="I">index</a></li>
32 <li class="right" >
33 <a href="modindex.html" title="Global Module Index"
34 accesskey="M">modules</a> |</li>
35 <li class="right" >
36 <a href="index.html" title="The httplib2 Library"
37 accesskey="P">previous</a> |</li>
38 <li><a href="index.html">httplib2 v0.4 documentation</a> &raquo;</li>
39 </ul>
40 </div>
41 <div class="document">
42 <div class="documentwrapper">
43 <div class="bodywrapper">
44 <div class="body">
45
46
47 <div class="section" id="module-httplib2">
48<h1 id="module-httplib2"><tt class="xref docutils literal"><span class="pre">httplib2</span></tt> A comprehensive HTTP client library.<a class="headerlink" href="#module-httplib2" title="Permalink to this headline"></a></h1>
49<p>The <tt class="xref docutils literal"><span class="pre">httplib2</span></tt> module is a comprehensive HTTP client library with the
50following features:</p>
51<dl class="describe">
52<dt>
53<tt class="descname">HTTP and HTTPS</tt></dt>
54<dd>HTTPS support is only available if the socket module was compiled with SSL
55support.</dd></dl>
56
57<dl class="describe">
58<dt>
59<tt class="descname">Keep-Alive</tt></dt>
60<dd>Supports HTTP 1.1 Keep-Alive, keeping the socket open and performing multiple
61requests over the same connection if possible.</dd></dl>
62
63<dl class="describe">
64<dt>
65<tt class="descname">Authentication</tt></dt>
66<dd><p>The following three types of HTTP Authentication are supported. These can be
67used over both HTTP and HTTPS.</p>
68<blockquote>
69<ul class="simple">
70<li>Digest</li>
71<li>Basic</li>
72<li>WSSE</li>
73</ul>
74</blockquote>
75</dd></dl>
76
77<dl class="describe">
78<dt>
79<tt class="descname">Caching</tt></dt>
80<dd>The module can optionally operate with a private cache that understands the
81Cache-Control: header and uses both the ETag and Last-Modified cache validators.</dd></dl>
82
83<dl class="describe">
84<dt>
85<tt class="descname">All Methods</tt></dt>
86<dd>The module can handle any HTTP request method, not just GET and POST.</dd></dl>
87
88<dl class="describe">
89<dt>
90<tt class="descname">Redirects</tt></dt>
91<dd>Automatically follows 3XX redirects on GETs.</dd></dl>
92
93<dl class="describe">
94<dt>
95<tt class="descname">Compression</tt></dt>
96<dd>Handles both <tt class="docutils literal"><span class="pre">deflate</span></tt> and <tt class="docutils literal"><span class="pre">gzip</span></tt> types of compression.</dd></dl>
97
98<dl class="describe">
99<dt>
100<tt class="descname">Lost update support</tt></dt>
101<dd>Automatically adds back ETags into PUT requests to resources we have already
102cached. This implements Section 3.2 of Detecting the Lost Update Problem Using
103Unreserved Checkout</dd></dl>
104
105<p>The <tt class="xref docutils literal"><span class="pre">httplib2</span></tt> module defines the following variables:</p>
106<dl class="data">
107<dt id="httplib2.debuglevel">
108<!--[httplib2.debuglevel]--><tt class="descclassname">httplib2.</tt><tt class="descname">debuglevel</tt><a class="headerlink" href="#httplib2.debuglevel" title="Permalink to this definition"></a></dt>
109<dd>The amount of debugging information to print. The default is 0.</dd></dl>
110
111<p>The <tt class="xref docutils literal"><span class="pre">httplib2</span></tt> module may raise the following Exceptions. Note that there
112is an option that turns exceptions into normal responses with an HTTP status
113code indicating an error occured. See
114<a title="httplib2.Http.force_exception_to_status_code" class="reference internal" href="#httplib2.Http.force_exception_to_status_code"><tt class="xref docutils literal"><span class="pre">Http.force_exception_to_status_code</span></tt></a></p>
115<dl class="exception">
116<dt id="httplib2.HttpLib2Error">
117<!--[httplib2.HttpLib2Error]-->exception <tt class="descclassname">httplib2.</tt><tt class="descname">HttpLib2Error</tt><a class="headerlink" href="#httplib2.HttpLib2Error" title="Permalink to this definition"></a></dt>
118<dd>The Base Exception for all exceptions raised by httplib2.</dd></dl>
119
120<dl class="exception">
121<dt id="httplib2.RedirectMissingLocation">
122<!--[httplib2.RedirectMissingLocation]-->exception <tt class="descclassname">httplib2.</tt><tt class="descname">RedirectMissingLocation</tt><a class="headerlink" href="#httplib2.RedirectMissingLocation" title="Permalink to this definition"></a></dt>
123<dd>A 3xx redirect response code was provided but no Location: header was provided
124to point to the new location.</dd></dl>
125
126<dl class="exception">
127<dt id="httplib2.RedirectLimit">
128<!--[httplib2.RedirectLimit]-->exception <tt class="descclassname">httplib2.</tt><tt class="descname">RedirectLimit</tt><a class="headerlink" href="#httplib2.RedirectLimit" title="Permalink to this definition"></a></dt>
129<dd>The maximum number of redirections was reached without coming to a final URI.</dd></dl>
130
131<dl class="exception">
132<dt id="httplib2.ServerNotFoundError">
133<!--[httplib2.ServerNotFoundError]-->exception <tt class="descclassname">httplib2.</tt><tt class="descname">ServerNotFoundError</tt><a class="headerlink" href="#httplib2.ServerNotFoundError" title="Permalink to this definition"></a></dt>
134<dd>Unable to resolve the host name given.</dd></dl>
135
136<dl class="exception">
137<dt id="httplib2.RelativeURIError">
138<!--[httplib2.RelativeURIError]-->exception <tt class="descclassname">httplib2.</tt><tt class="descname">RelativeURIError</tt><a class="headerlink" href="#httplib2.RelativeURIError" title="Permalink to this definition"></a></dt>
139<dd>A relative, as opposed to an absolute URI, was passed into request().</dd></dl>
140
141<dl class="exception">
142<dt id="httplib2.FailedToDecompressContent">
143<!--[httplib2.FailedToDecompressContent]-->exception <tt class="descclassname">httplib2.</tt><tt class="descname">FailedToDecompressContent</tt><a class="headerlink" href="#httplib2.FailedToDecompressContent" title="Permalink to this definition"></a></dt>
144<dd>The headers claimed that the content of the response was compressed but the
145decompression algorithm applied to the content failed.</dd></dl>
146
147<dl class="exception">
148<dt id="httplib2.UnimplementedDigestAuthOptionError">
149<!--[httplib2.UnimplementedDigestAuthOptionError]-->exception <tt class="descclassname">httplib2.</tt><tt class="descname">UnimplementedDigestAuthOptionError</tt><a class="headerlink" href="#httplib2.UnimplementedDigestAuthOptionError" title="Permalink to this definition"></a></dt>
150<dd>The server requested a type of Digest authentication that we are unfamiliar
151with.</dd></dl>
152
153<dl class="exception">
154<dt id="httplib2.UnimplementedHmacDigestAuthOptionError">
155<!--[httplib2.UnimplementedHmacDigestAuthOptionError]-->exception <tt class="descclassname">httplib2.</tt><tt class="descname">UnimplementedHmacDigestAuthOptionError</tt><a class="headerlink" href="#httplib2.UnimplementedHmacDigestAuthOptionError" title="Permalink to this definition"></a></dt>
156<dd>The server requested a type of HMACDigest authentication that we are unfamiliar
157with.</dd></dl>
158
159<dl class="class">
160<dt id="httplib2.Http">
161<!--[httplib2.Http]-->class <tt class="descclassname">httplib2.</tt><tt class="descname">Http</tt><big>(</big><span class="optional">[</span><em>cache=None</em><span class="optional">]</span><span class="optional">[</span>, <em>timeout=None</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#httplib2.Http" title="Permalink to this definition"></a></dt>
162<dd>The class that represents a client HTTP interface. The <em>cache</em> parameter is
163either the name of a directory to be used as a flat file cache, or it must an
164object that implements the required caching interface. The <em>timeout</em> parameter
165is the socket level timeout.</dd></dl>
166
167<dl class="class">
168<dt id="httplib2.Response">
169<!--[httplib2.Response]-->class <tt class="descclassname">httplib2.</tt><tt class="descname">Response</tt><big>(</big><em>info</em><big>)</big><a class="headerlink" href="#httplib2.Response" title="Permalink to this definition"></a></dt>
170<dd>Response is a subclass of <tt class="xref docutils literal"><span class="pre">dict</span></tt> and instances of this class are
171returned from calls to Http.request. The <em>info</em> parameter is either an
172<tt class="xref docutils literal"><span class="pre">rfc822.Message</span></tt> or an <tt class="xref docutils literal"><span class="pre">httplib.HTTPResponse</span></tt> object.</dd></dl>
173
174<dl class="class">
175<dt id="httplib2.FileCache">
176<!--[httplib2.FileCache]-->class <tt class="descclassname">httplib2.</tt><tt class="descname">FileCache</tt><big>(</big><em>dir_name</em><span class="optional">[</span>, <em>safe=safename</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#httplib2.FileCache" title="Permalink to this definition"></a></dt>
177<dd>FileCache implements a Cache as a directory of files. The <em>dir_name</em> parameter
178is the name of the directory to use. If the directory does not exist then
179FileCache attempts to create the directory. The optional <em>safe</em> parameter is a
180funtion which generates the cache filename for each URI. A FileCache object is
181constructed and used for caching when you pass a directory name into the
182constructor of <a title="httplib2.Http" class="reference internal" href="#httplib2.Http"><tt class="xref docutils literal"><span class="pre">Http</span></tt></a>.</dd></dl>
183
184<p>Http objects have the following methods:</p>
185<div class="section" id="id1">
186<span id="http-objects"></span><h2 id="id1"><span id="http-objects"></span>Http Objects<a class="headerlink" href="#id1" title="Permalink to this headline"></a></h2>
187<dl class="method">
188<dt id="httplib2.Http.request">
189<!--[httplib2.Http.request]--><tt class="descclassname">Http.</tt><tt class="descname">request</tt><big>(</big><em>uri</em><span class="optional">[</span>, <em>method=&quot;GET&quot;</em>, <em>body=None</em>, <em>headers=None</em>, <em>redirections=DEFAULT_MAX_REDIRECTS</em>, <em>connection_type=None</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#httplib2.Http.request" title="Permalink to this definition"></a></dt>
190<dd><p>Performs a single HTTP request. The <em>uri</em> is the URI of the HTTP resource and
191can begin with either <tt class="docutils literal"><span class="pre">http</span></tt> or <tt class="docutils literal"><span class="pre">https</span></tt>. The value of <em>uri</em> must be an
192absolute URI.</p>
193<p>The <em>method</em> is the HTTP method to perform, such as <tt class="docutils literal"><span class="pre">GET</span></tt>, <tt class="docutils literal"><span class="pre">POST</span></tt>,
194<tt class="docutils literal"><span class="pre">DELETE</span></tt>, etc. There is no restriction on the methods allowed.</p>
195<p>The <em>body</em> is the entity body to be sent with the request. It is a string
196object.</p>
197<p>Any extra headers that are to be sent with the request should be provided in the
198<em>headers</em> dictionary.</p>
199<p>The maximum number of redirect to follow before raising an exception is
200<em>redirections</em>. The default is 5.</p>
201<p>The <em>connection_type</em> is the type of connection object to use. The supplied
202class should implement the interface of httplib.HTTPConnection.</p>
203<p>The return value is a tuple of (response, content), the first being and instance
204of the <a title="httplib2.Response" class="reference internal" href="#httplib2.Response"><tt class="xref docutils literal"><span class="pre">Response</span></tt></a> class, the second being a string that contains the
205response entity body.</p>
206</dd></dl>
207
208<dl class="method">
209<dt id="httplib2.Http.add_credentials">
210<!--[httplib2.Http.add_credentials]--><tt class="descclassname">Http.</tt><tt class="descname">add_credentials</tt><big>(</big><em>name</em>, <em>password</em><span class="optional">[</span>, <em>domain=None</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#httplib2.Http.add_credentials" title="Permalink to this definition"></a></dt>
211<dd>Adds a name and password that will be used when a request requires
212authentication. Supplying the optional <em>domain</em> name will restrict these
213credentials to only be sent to the specified domain. If <em>domain</em> is not
214specified then the given credentials will be used to try to satisfy every HTTP
215401 challenge.</dd></dl>
216
217<dl class="method">
218<dt id="httplib2.Http.add_certificate">
219<!--[httplib2.Http.add_certificate]--><tt class="descclassname">Http.</tt><tt class="descname">add_certificate</tt><big>(</big><em>key</em>, <em>cert</em>, <em>domain</em><big>)</big><a class="headerlink" href="#httplib2.Http.add_certificate" title="Permalink to this definition"></a></dt>
220<dd>Add a <em>key</em> and <em>cert</em> that will be used for an SSL connection to the specified
221domain. <em>keyfile</em> is the name of a PEM formatted file that contains your
222private key. <em>certfile</em> is a PEM formatted certificate chain file.</dd></dl>
223
224<dl class="method">
225<dt id="httplib2.Http.clear_credentials">
226<!--[httplib2.Http.clear_credentials]--><tt class="descclassname">Http.</tt><tt class="descname">clear_credentials</tt><big>(</big><big>)</big><a class="headerlink" href="#httplib2.Http.clear_credentials" title="Permalink to this definition"></a></dt>
227<dd>Remove all the names and passwords used for authentication.</dd></dl>
228
229<dl class="attribute">
230<dt id="httplib2.Http.follow_redirects">
231<!--[httplib2.Http.follow_redirects]--><tt class="descclassname">Http.</tt><tt class="descname">follow_redirects</tt><a class="headerlink" href="#httplib2.Http.follow_redirects" title="Permalink to this definition"></a></dt>
232<dd>If <tt class="xref docutils literal"><span class="pre">True</span></tt>, which is the default, safe redirects are followed, where safe means
233that the client is only doing a <tt class="docutils literal"><span class="pre">GET</span></tt> or <tt class="docutils literal"><span class="pre">HEAD</span></tt> on the URI to which it is
234being redirected. If <tt class="xref docutils literal"><span class="pre">False</span></tt> then no redirects are followed. Note that a False
235&#8216;follow_redirects&#8217; takes precedence over a True &#8216;follow_all_redirects&#8217;. Another
236way of saying that is for &#8216;follow_all_redirects&#8217; to have any affect,
237&#8216;follow_redirects&#8217; must be True.</dd></dl>
238
239<dl class="attribute">
240<dt id="httplib2.Http.follow_all_redirects">
241<!--[httplib2.Http.follow_all_redirects]--><tt class="descclassname">Http.</tt><tt class="descname">follow_all_redirects</tt><a class="headerlink" href="#httplib2.Http.follow_all_redirects" title="Permalink to this definition"></a></dt>
242<dd>If <tt class="xref docutils literal"><span class="pre">False</span></tt>, which is the default, only safe redirects are followed, where safe
243means that the client is only doing a <tt class="docutils literal"><span class="pre">GET</span></tt> or <tt class="docutils literal"><span class="pre">HEAD</span></tt> on the URI to which it
244is being redirected. If <tt class="xref docutils literal"><span class="pre">True</span></tt> then all redirects are followed. Note that a
245False &#8216;follow_redirects&#8217; takes precedence over a True &#8216;follow_all_redirects&#8217;.
246Another way of saying that is for &#8216;follow_all_redirects&#8217; to have any affect,
247&#8216;follow_redirects&#8217; must be True.</dd></dl>
248
249<dl class="attribute">
250<dt id="httplib2.Http.force_exception_to_status_code">
251<!--[httplib2.Http.force_exception_to_status_code]--><tt class="descclassname">Http.</tt><tt class="descname">force_exception_to_status_code</tt><a class="headerlink" href="#httplib2.Http.force_exception_to_status_code" title="Permalink to this definition"></a></dt>
252<dd><p>If <tt class="xref docutils literal"><span class="pre">True</span></tt>, which is the default, then no <tt class="xref docutils literal"><span class="pre">httplib2</span></tt> exceptions will be
253thrown. Instead, those error conditions will be turned into <a title="httplib2.Response" class="reference internal" href="#httplib2.Response"><tt class="xref docutils literal"><span class="pre">Response</span></tt></a>
254objects that will be returned normally.</p>
255<p>If <tt class="xref docutils literal"><span class="pre">False</span></tt>, then exceptions will be thrown.</p>
256</dd></dl>
257
258<dl class="attribute">
259<dt id="httplib2.Http.ignore_etag">
260<!--[httplib2.Http.ignore_etag]--><tt class="descclassname">Http.</tt><tt class="descname">ignore_etag</tt><a class="headerlink" href="#httplib2.Http.ignore_etag" title="Permalink to this definition"></a></dt>
261<dd>Defaults to <tt class="xref docutils literal"><span class="pre">False</span></tt>. If <tt class="xref docutils literal"><span class="pre">True</span></tt>, then any etags present in the cached
262response are ignored when processing the current request, i.e. httplib2 does
263<strong>not</strong> use &#8216;if-match&#8217; for PUT or &#8216;if-none-match&#8217; when GET or HEAD requests are
264made. This is mainly to deal with broken servers which supply an etag, but
265change it capriciously.</dd></dl>
266
267<p>If you wish to supply your own caching implementation then you will need to pass
268in an object that supports the following methods. Note that the <tt class="xref docutils literal"><span class="pre">memcache</span></tt>
269module supports this interface natively.</p>
270</div>
271<div class="section" id="id2">
272<span id="cache-objects"></span><h2 id="id2"><span id="cache-objects"></span>Cache Objects<a class="headerlink" href="#id2" title="Permalink to this headline"></a></h2>
273<dl class="method">
274<dt id="httplib2.Cache.get">
275<!--[httplib2.Cache.get]--><tt class="descclassname">Cache.</tt><tt class="descname">get</tt><big>(</big><em>key</em><big>)</big><a class="headerlink" href="#httplib2.Cache.get" title="Permalink to this definition"></a></dt>
276<dd>Takes a string <em>key</em> and returns the value as a string.</dd></dl>
277
278<dl class="method">
279<dt id="httplib2.Cache.set">
280<!--[httplib2.Cache.set]--><tt class="descclassname">Cache.</tt><tt class="descname">set</tt><big>(</big><em>key</em>, <em>value</em><big>)</big><a class="headerlink" href="#httplib2.Cache.set" title="Permalink to this definition"></a></dt>
281<dd>Takes a string <em>key</em> and <em>value</em> and stores it in the cache.</dd></dl>
282
283<dl class="method">
284<dt id="httplib2.Cache.delete">
285<!--[httplib2.Cache.delete]--><tt class="descclassname">Cache.</tt><tt class="descname">delete</tt><big>(</big><em>key</em><big>)</big><a class="headerlink" href="#httplib2.Cache.delete" title="Permalink to this definition"></a></dt>
286<dd>Deletes the cached value stored at <em>key</em>. The value of <em>key</em> is a string.</dd></dl>
287
288<p>Response objects are derived from <tt class="xref docutils literal"><span class="pre">dict</span></tt> and map header names (lower case
289with the trailing colon removed) to header values. In addition to the dict
290methods a Response object also has:</p>
291</div>
292<div class="section" id="id3">
293<span id="response-objects"></span><h2 id="id3"><span id="response-objects"></span>Response Objects<a class="headerlink" href="#id3" title="Permalink to this headline"></a></h2>
294<dl class="attribute">
295<dt id="httplib2.Response.fromcache">
296<!--[httplib2.Response.fromcache]--><tt class="descclassname">Response.</tt><tt class="descname">fromcache</tt><a class="headerlink" href="#httplib2.Response.fromcache" title="Permalink to this definition"></a></dt>
297<dd>If <tt class="docutils literal"><span class="pre">true</span></tt> the the response was returned from the cache.</dd></dl>
298
299<dl class="attribute">
300<dt id="httplib2.Response.version">
301<!--[httplib2.Response.version]--><tt class="descclassname">Response.</tt><tt class="descname">version</tt><a class="headerlink" href="#httplib2.Response.version" title="Permalink to this definition"></a></dt>
302<dd>The version of HTTP that the server supports. A value of 11 means &#8216;1.1&#8217;.</dd></dl>
303
304<dl class="attribute">
305<dt id="httplib2.Response.status">
306<!--[httplib2.Response.status]--><tt class="descclassname">Response.</tt><tt class="descname">status</tt><a class="headerlink" href="#httplib2.Response.status" title="Permalink to this definition"></a></dt>
307<dd>The numerical HTTP status code returned in the response.</dd></dl>
308
309<dl class="attribute">
310<dt id="httplib2.Response.reason">
311<!--[httplib2.Response.reason]--><tt class="descclassname">Response.</tt><tt class="descname">reason</tt><a class="headerlink" href="#httplib2.Response.reason" title="Permalink to this definition"></a></dt>
312<dd>The human readable component of the HTTP response status code.</dd></dl>
313
314<dl class="attribute">
315<dt id="httplib2.Response.previous">
316<!--[httplib2.Response.previous]--><tt class="descclassname">Response.</tt><tt class="descname">previous</tt><a class="headerlink" href="#httplib2.Response.previous" title="Permalink to this definition"></a></dt>
317<dd>If redirects are followed then the <a title="httplib2.Response" class="reference internal" href="#httplib2.Response"><tt class="xref docutils literal"><span class="pre">Response</span></tt></a> object returned is just for
318the very last HTTP request and <em>previous</em> points to the previous
319<a title="httplib2.Response" class="reference internal" href="#httplib2.Response"><tt class="xref docutils literal"><span class="pre">Response</span></tt></a> object. In this manner they form a chain going back through
320the responses to the very first response. Will be <tt class="xref docutils literal"><span class="pre">None</span></tt> if there are no
321previous respones.</dd></dl>
322
323<p>The Response object also populates the header <tt class="docutils literal"><span class="pre">content-location</span></tt>, that
324contains the URI that was ultimately requested. This is useful if redirects were
325encountered, you can determine the ultimate URI that the request was sent to.
326All Response objects contain this key value, including <tt class="docutils literal"><span class="pre">previous</span></tt> responses so
327you can determine the entire chain of redirects. If
328<a title="httplib2.Http.force_exception_to_status_code" class="reference internal" href="#httplib2.Http.force_exception_to_status_code"><tt class="xref docutils literal"><span class="pre">Http.force_exception_to_status_code</span></tt></a> is <tt class="xref docutils literal"><span class="pre">True</span></tt> and the number of
329redirects has exceeded the number of allowed number of redirects then the
330<a title="httplib2.Response" class="reference internal" href="#httplib2.Response"><tt class="xref docutils literal"><span class="pre">Response</span></tt></a> object will report the error in the status code, but the
331complete chain of previous responses will still be in tact.</p>
332<p>To do a simple <tt class="docutils literal"><span class="pre">GET</span></tt> request just supply the absolute URI of the resource:</p>
333</div>
334<div class="section" id="examples">
335<span id="httplib2-example"></span><h2 id="examples"><span id="httplib2-example"></span>Examples<a class="headerlink" href="#examples" title="Permalink to this headline"></a></h2>
336<div class="highlight"><pre><span class="kn">import</span> <span class="nn">httplib2</span>
337<span class="n">h</span> <span class="o">=</span> <span class="n">httplib2</span><span class="o">.</span><span class="n">Http</span><span class="p">()</span>
338<span class="n">resp</span><span class="p">,</span> <span class="n">content</span> <span class="o">=</span> <span class="n">h</span><span class="o">.</span><span class="n">request</span><span class="p">(</span><span class="s">&quot;http://bitworking.org/&quot;</span><span class="p">)</span>
339<span class="k">assert</span> <span class="n">resp</span><span class="o">.</span><span class="n">status</span> <span class="o">==</span> <span class="mf">200</span>
340<span class="k">assert</span> <span class="n">resp</span><span class="p">[</span><span class="s">&#39;content-type&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s">&#39;text/html&#39;</span>
341</pre></div>
342<p>Here is more complex example that does a PUT of some text to a resource that
343requires authentication. The Http instance also uses a file cache in the
344directory <tt class="docutils literal"><span class="pre">.cache</span></tt>.</p>
345<div class="highlight"><pre><span class="kn">import</span> <span class="nn">httplib2</span>
346<span class="n">h</span> <span class="o">=</span> <span class="n">httplib2</span><span class="o">.</span><span class="n">Http</span><span class="p">(</span><span class="s">&quot;.cache&quot;</span><span class="p">)</span>
347<span class="n">h</span><span class="o">.</span><span class="n">add_credentials</span><span class="p">(</span><span class="s">&#39;name&#39;</span><span class="p">,</span> <span class="s">&#39;password&#39;</span><span class="p">)</span>
348<span class="n">resp</span><span class="p">,</span> <span class="n">content</span> <span class="o">=</span> <span class="n">h</span><span class="o">.</span><span class="n">request</span><span class="p">(</span><span class="s">&quot;https://example.org/chap/2&quot;</span><span class="p">,</span>
349 <span class="s">&quot;PUT&quot;</span><span class="p">,</span> <span class="n">body</span><span class="o">=</span><span class="s">&quot;This is text&quot;</span><span class="p">,</span>
350 <span class="n">headers</span><span class="o">=</span><span class="p">{</span><span class="s">&#39;content-type&#39;</span><span class="p">:</span><span class="s">&#39;text/plain&#39;</span><span class="p">}</span> <span class="p">)</span>
351</pre></div>
352<p>Here is an example that connects to a server that supports the Atom Publishing
353Protocol.</p>
354<div class="highlight"><pre><span class="kn">import</span> <span class="nn">httplib2</span>
355<span class="n">h</span> <span class="o">=</span> <span class="n">httplib2</span><span class="o">.</span><span class="n">Http</span><span class="p">()</span>
356<span class="n">h</span><span class="o">.</span><span class="n">add_credentials</span><span class="p">(</span><span class="n">myname</span><span class="p">,</span> <span class="n">mypasswd</span><span class="p">)</span>
357<span class="n">h</span><span class="o">.</span><span class="n">follow_all_redirects</span> <span class="o">=</span> <span class="bp">True</span>
358<span class="n">headers</span> <span class="o">=</span> <span class="p">{</span><span class="s">&#39;Content-Type&#39;</span><span class="p">:</span> <span class="s">&#39;application/atom+xml&#39;</span><span class="p">}</span>
359<span class="n">body</span> <span class="o">=</span> <span class="s">&quot;&quot;&quot;&lt;?xml version=&quot;1.0&quot; ?&gt;</span>
360<span class="s"> &lt;entry xmlns=&quot;http://www.w3.org/2005/Atom&quot;&gt;</span>
361<span class="s"> &lt;title&gt;Atom-Powered Robots Run Amok&lt;/title&gt;</span>
362<span class="s"> &lt;id&gt;urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a&lt;/id&gt;</span>
363<span class="s"> &lt;updated&gt;2003-12-13T18:30:02Z&lt;/updated&gt;</span>
364<span class="s"> &lt;author&gt;&lt;name&gt;John Doe&lt;/name&gt;&lt;/author&gt;</span>
365<span class="s"> &lt;content&gt;Some text.&lt;/content&gt;</span>
366<span class="s">&lt;/entry&gt;</span>
367<span class="s">&quot;&quot;&quot;</span>
368<span class="n">uri</span> <span class="o">=</span> <span class="s">&quot;http://www.example.com/collection/&quot;</span>
369<span class="n">resp</span><span class="p">,</span> <span class="n">content</span> <span class="o">=</span> <span class="n">h</span><span class="o">.</span><span class="n">request</span><span class="p">(</span><span class="n">uri</span><span class="p">,</span> <span class="s">&quot;POST&quot;</span><span class="p">,</span> <span class="n">body</span><span class="o">=</span><span class="n">body</span><span class="p">,</span> <span class="n">headers</span><span class="o">=</span><span class="n">headers</span><span class="p">)</span>
370</pre></div>
371<p>Here is an example of providing data to an HTML form processor. In this case we
372presume this is a POST form. We need to take our data and format it as
373&#8220;application/x-www-form-urlencoded&#8221; data and use that as a body for a POST
374request.</p>
375<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">httplib2</span>
376<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">urllib</span>
377<span class="gp">&gt;&gt;&gt; </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s">&#39;name&#39;</span><span class="p">:</span> <span class="s">&#39;fred&#39;</span><span class="p">,</span> <span class="s">&#39;address&#39;</span><span class="p">:</span> <span class="s">&#39;123 shady lane&#39;</span><span class="p">}</span>
378<span class="gp">&gt;&gt;&gt; </span><span class="n">body</span> <span class="o">=</span> <span class="n">urllib</span><span class="o">.</span><span class="n">urlencode</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
379<span class="gp">&gt;&gt;&gt; </span><span class="n">body</span>
380<span class="go">&#39;name=fred&amp;address=123+shady+lane&#39;</span>
381<span class="gp">&gt;&gt;&gt; </span><span class="n">h</span> <span class="o">=</span> <span class="n">httplib2</span><span class="o">.</span><span class="n">Http</span><span class="p">()</span>
382<span class="gp">&gt;&gt;&gt; </span><span class="n">resp</span><span class="p">,</span> <span class="n">content</span> <span class="o">=</span> <span class="n">h</span><span class="o">.</span><span class="n">request</span><span class="p">(</span><span class="s">&quot;http://example.com&quot;</span><span class="p">,</span> <span class="n">method</span><span class="o">=</span><span class="s">&quot;POST&quot;</span><span class="p">,</span> <span class="n">body</span><span class="o">=</span><span class="n">body</span><span class="p">)</span>
383</pre></div>
384</div>
385</div>
386
387
388 </div>
389 </div>
390 </div>
391 <div class="sphinxsidebar">
392 <div class="sphinxsidebarwrapper">
393 <h3>Table Of Contents</h3>
394 <ul>
395<li><a class="reference external" href=""><tt class="docutils literal"><span class="pre">httplib2</span></tt> A comprehensive HTTP client library.</a><ul>
396<li><a class="reference external" href="#id1">Http Objects</a></li>
397<li><a class="reference external" href="#id2">Cache Objects</a></li>
398<li><a class="reference external" href="#id3">Response Objects</a></li>
399<li><a class="reference external" href="#examples">Examples</a></li>
400</ul>
401</li>
402</ul>
403
404 <h4>Previous topic</h4>
405 <p class="topless"><a href="index.html" title="previous chapter">The httplib2 Library</a></p>
406 <h3>This Page</h3>
407 <ul class="this-page-menu">
408 <li><a href="_sources/libhttplib2.txt">Show Source</a></li>
409 </ul>
410 <h3>Quick search</h3>
411 <form class="search" action="search.html" method="get">
412 <input type="text" name="q" size="18" /> <input type="submit" value="Go" />
413 <input type="hidden" name="check_keywords" value="yes" />
414 <input type="hidden" name="area" value="default" />
415 </form>
416 </div>
417 </div>
418 <div class="clearer"></div>
419 </div>
420 <div class="related">
421 <h3>Navigation</h3>
422 <ul>
423 <li class="right" style="margin-right: 10px">
424 <a href="genindex.html" title="General Index"
425 accesskey="I">index</a></li>
426 <li class="right" >
427 <a href="modindex.html" title="Global Module Index"
428 accesskey="M">modules</a> |</li>
429 <li class="right" >
430 <a href="index.html" title="The httplib2 Library"
431 accesskey="P">previous</a> |</li>
432 <li><a href="index.html">httplib2 v0.4 documentation</a> &raquo;</li>
433 </ul>
434 </div>
435 <div class="footer">
436 &copy; Copyright 2008, Joe Gregorio.
437 Last updated on Sep 05, 2008.
438 Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
439 </div>
440 </body>
441</html>