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