Documented changes in fixing bug 1597381 Map exceptions to status codes
diff --git a/httplib2/__init__.py b/httplib2/__init__.py
index 6e5973b..f1c27f7 100644
--- a/httplib2/__init__.py
+++ b/httplib2/__init__.py
@@ -791,6 +791,12 @@
return (response, content)
+
+# Need to catch and rebrand some exceptions
+# Then need to optionally turn all exceptions into status codes
+# including all socket.* and httplib.* exceptions.
+
+
def request(self, uri, method="GET", body=None, headers=None, redirections=DEFAULT_MAX_REDIRECTS):
""" Performs a single HTTP request.
The 'uri' is the URI of the HTTP resource and can begin
diff --git a/libhttplib2.tex b/libhttplib2.tex
index 2500336..f8b50d7 100644
--- a/libhttplib2.tex
+++ b/libhttplib2.tex
@@ -101,7 +101,10 @@
% the source code should be documented using this environment, but
% constructor parameters must be omitted.
-The \module{httplib2} module may raise the following Exceptions:
+The \module{httplib2} module may raise the following Exceptions. Note that
+there is an option that turns exceptions into
+normal responses with an HTTP status code indicating
+an error occured. See \member{Http.force_exception_to_status_code}
\begin{excdesc}{HttpLib2Error}
The Base Exception for all exceptions raised by httplib2.
@@ -112,18 +115,24 @@
was provided to point to the new location.
\end{excdesc}
-
\begin{excdesc}{RedirectLimit}
The maximum number of redirections was reached without coming to a final URI.
\end{excdesc}
+\begin{excdesc}{ServerNotFoundError}
+Unable to resolve the host name given.
+\end{excdesc}
+
+\begin{excdesc}{RelativeURIError}
+A relative, as opposed to an absolute URI, was passed into request().
+\end{excdesc}
+
\begin{excdesc}{FailedToDecompressContent}
The headers claimed that the content of the response was compressed but the
decompression algorithm applied to the content failed.
\end{excdesc}
-
\begin{excdesc}{UnimplementedDigestAuthOptionError}
The server requested a type of Digest authentication that we
are unfamiliar with.
@@ -220,6 +229,14 @@
URI to which it is being redirected. If \code{True} then all redirects are followed.
\end{memberdesc}
+\begin{memberdesc}[Http]{force_exception_to_status_code}
+If \code{True}, which is the default, then no \module{httplib2} exceptions will be thrown. Instead,
+those error conditions will be turned into \class{Response} objects
+that will be returned normally.
+
+If \code{False}, then exceptions will be thrown.
+\end{memberdesc}
+
\begin{memberdesc}[Http]{ignore_etag}
Defaults to \code{False}. If True, then any etags present in the cached response
are ignored when processing the current request, i.e. httplib2 does *not* use
@@ -294,7 +311,12 @@
redirects were encountered, you can determine the ultimate URI that
the request was sent to. All Response objects contain this key value,
including \code{previous} responses so you can determine the entire
-chain of redirects.
+chain of redirects. If \member{Http.force_exception_to_status_code} is \code{True}
+and the number of redirects has exceeded the number of allowed number
+of redirects then the \class{Response} object will report the error
+in the status code, but the complete chain of previous responses will
+still be in tact.
+
% ==== 4. ====
% Now is probably a good time for a complete example. (Alternatively,
@@ -351,4 +373,19 @@
\end{verbatim}
% Note that there is no trailing ">>> " prompt shown.
+Here is an example of providing data to an HTML form processor.
+In this case we presume this is a POST form. We need to take our
+data and format it as "application/x-www-form-urlencoded" data and use that as a
+body for a POST request.
+\begin{verbatim}
+>>> import httplib2
+>>> import urllib
+>>> data = {'name': 'fred', 'address': '123 shady lane'}
+>>> body = urllib.urlencode(data)
+>>> body
+'name=fred&address=123+shady+lane'
+>>> h = httplib2.Http()
+>>> resp, content = h.request("http://example.com", method="POST", body=body)
+\end{verbatim}
+% Note that there is no trailing ">>> " prompt shown.
diff --git a/ref.tex b/ref.tex
index dfee4bd..8093e3b 100644
--- a/ref.tex
+++ b/ref.tex
@@ -19,9 +19,9 @@
Email: \email{joe@bitworking.org}
}
-\date{July 2, 2006} % update before release!
+\date{Mar 8, 2007} % update before release!
-\release{0.2} % release version; this is used to define the
+\release{0.3} % release version; this is used to define the
% \version macro
\makeindex % tell \index to actually write the .idx file
diff --git a/ref/about.html b/ref/about.html
index 457db27..dee4004 100644
--- a/ref/about.html
+++ b/ref/about.html
@@ -47,7 +47,7 @@
About this document ...</A>
</H1>
<strong>The httplib2 Library</strong>,
-July 2, 2006, Release 0.2
+Mar 8, 2007, Release 0.3
<p> This document was generated using the <a
href="http://saftsack.fs.uni-bayreuth.de/~latex2ht/">
<strong>LaTeX</strong>2<tt>HTML</tt></a> translator.
@@ -103,7 +103,7 @@
</div>
</div>
<hr />
-<span class="release-info">Release 0.2, documentation updated on July 2, 2006.</span>
+<span class="release-info">Release 0.3, documentation updated on Mar 8, 2007.</span>
</DIV>
<!--End of Navigation Panel-->
diff --git a/ref/cache-objects.html b/ref/cache-objects.html
index 1ce96ea..6863974 100644
--- a/ref/cache-objects.html
+++ b/ref/cache-objects.html
@@ -62,7 +62,7 @@
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
- <td><nobr><b><tt id='l2h-17' xml:id='l2h-17' class="method">get</tt></b>(</nobr></td>
+ <td><nobr><b><tt id='l2h-20' xml:id='l2h-20' class="method">get</tt></b>(</nobr></td>
<td><var>key</var>)</td></tr></table></dt>
<dd>
Takes a string <var>key</var> and returns the value as a string.
@@ -70,7 +70,7 @@
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
- <td><nobr><b><tt id='l2h-18' xml:id='l2h-18' class="method">set</tt></b>(</nobr></td>
+ <td><nobr><b><tt id='l2h-21' xml:id='l2h-21' class="method">set</tt></b>(</nobr></td>
<td><var>key, value</var>)</td></tr></table></dt>
<dd>
Takes a string <var>key</var> and <var>value</var> and stores it in the cache.
@@ -78,7 +78,7 @@
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
- <td><nobr><b><tt id='l2h-19' xml:id='l2h-19' class="method">delete</tt></b>(</nobr></td>
+ <td><nobr><b><tt id='l2h-22' xml:id='l2h-22' class="method">delete</tt></b>(</nobr></td>
<td><var>key</var>)</td></tr></table></dt>
<dd>
Deletes the cached value stored at <var>key</var>. The value
@@ -120,7 +120,7 @@
</div>
</div>
<hr />
-<span class="release-info">Release 0.2, documentation updated on July 2, 2006.</span>
+<span class="release-info">Release 0.3, documentation updated on Mar 8, 2007.</span>
</DIV>
<!--End of Navigation Panel-->
diff --git a/ref/contents.html b/ref/contents.html
index 64b357e..e4fc819 100644
--- a/ref/contents.html
+++ b/ref/contents.html
@@ -96,7 +96,7 @@
</div>
</div>
<hr />
-<span class="release-info">Release 0.2, documentation updated on July 2, 2006.</span>
+<span class="release-info">Release 0.3, documentation updated on Mar 8, 2007.</span>
</DIV>
<!--End of Navigation Panel-->
diff --git a/ref/http-objects.html b/ref/http-objects.html
index 5032c54..2596974 100644
--- a/ref/http-objects.html
+++ b/ref/http-objects.html
@@ -59,7 +59,7 @@
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
- <td><nobr><b><tt id='l2h-12' xml:id='l2h-12' class="method">request</tt></b>(</nobr></td>
+ <td><nobr><b><tt id='l2h-14' xml:id='l2h-14' class="method">request</tt></b>(</nobr></td>
<td><var>uri, </var><big>[</big><var>method="GET", body=None, headers=None, redirections=DEFAULT_MAX_REDIRECTS</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Performs a single HTTP request.
@@ -87,7 +87,7 @@
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
- <td><nobr><b><tt id='l2h-13' xml:id='l2h-13' class="method">add_credentials</tt></b>(</nobr></td>
+ <td><nobr><b><tt id='l2h-15' xml:id='l2h-15' class="method">add_credentials</tt></b>(</nobr></td>
<td><var>name, password</var>)</td></tr></table></dt>
<dd>
Adds a name and password that will be used when a request
@@ -96,14 +96,14 @@
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
- <td><nobr><b><tt id='l2h-14' xml:id='l2h-14' class="method">clear_credentials</tt></b>(</nobr></td>
+ <td><nobr><b><tt id='l2h-16' xml:id='l2h-16' class="method">clear_credentials</tt></b>(</nobr></td>
<td><var></var>)</td></tr></table></dt>
<dd>
Remove all the names and passwords used for authentication.
</dl>
<P>
-<dl><dt><b><tt id='l2h-15' xml:id='l2h-15' class="member">follow_all_redirects</tt></b></dt>
+<dl><dt><b><tt id='l2h-17' xml:id='l2h-17' class="member">follow_all_redirects</tt></b></dt>
<dd>
If <code>False</code>, which is the default, only safe redirects are followed, where
safe means that the client is only doing a <code>GET</code> or <code>HEAD</code> on the
@@ -111,7 +111,18 @@
</dl>
<P>
-<dl><dt><b><tt id='l2h-16' xml:id='l2h-16' class="member">ignore_etag</tt></b></dt>
+<dl><dt><b><tt id='l2h-18' xml:id='l2h-18' class="member">force_exception_to_status_code</tt></b></dt>
+<dd>
+If <code>True</code>, which is the default, then no <tt class="module">httplib2</tt> exceptions will be thrown. Instead,
+those error conditions will be turned into <tt class="class">Response</tt> objects
+that will be returned normally.
+
+<P>
+If <code>False</code>, then exceptions will be thrown.
+</dl>
+
+<P>
+<dl><dt><b><tt id='l2h-19' xml:id='l2h-19' class="member">ignore_etag</tt></b></dt>
<dd>
Defaults to <code>False</code>. If True, then any etags present in the cached response
are ignored when processing the current request, i.e. httplib2 does *not* use
@@ -154,7 +165,7 @@
</div>
</div>
<hr />
-<span class="release-info">Release 0.2, documentation updated on July 2, 2006.</span>
+<span class="release-info">Release 0.3, documentation updated on Mar 8, 2007.</span>
</DIV>
<!--End of Navigation Panel-->
diff --git a/ref/httplib2-example.html b/ref/httplib2-example.html
index 6e6e5c0..1b245a1 100644
--- a/ref/httplib2-example.html
+++ b/ref/httplib2-example.html
@@ -106,6 +106,22 @@
</pre></div>
<P>
+Here is an example of providing data to an HTML form processor.
+In this case we presume this is a POST form. We need to take our
+data and format it as "application/x-www-form-urlencoded" data and use that as a
+body for a POST request.
+
+<P>
+<div class="verbatim"><pre>
+>>> import httplib2
+>>> import urllib
+>>> data = {'name': 'fred', 'address': '123 shady lane'}
+>>> body = urllib.urlencode(data)
+>>> body
+'name=fred&address=123+shady+lane'
+>>> h = httplib2.Http()
+>>> resp, content = h.request("http://example.com", method="POST", body=body)
+</pre></div>
<P>
<IMG
@@ -150,7 +166,7 @@
</div>
</div>
<hr />
-<span class="release-info">Release 0.2, documentation updated on July 2, 2006.</span>
+<span class="release-info">Release 0.3, documentation updated on Mar 8, 2007.</span>
</DIV>
<!--End of Navigation Panel-->
diff --git a/ref/index.html b/ref/index.html
index e1dd92b..eab247b 100644
--- a/ref/index.html
+++ b/ref/index.html
@@ -48,8 +48,8 @@
<p>
Email: <span class="email">joe@bitworking.org</span>
</p>
-<p><strong>Release 0.2</strong><br />
-<strong>July 2, 2006</strong></p>
+<p><strong>Release 0.3</strong><br />
+<strong>Mar 8, 2007</strong></p>
<p></p>
</div>
</div>
@@ -120,7 +120,7 @@
</div>
</div>
<hr />
-<span class="release-info">Release 0.2, documentation updated on July 2, 2006.</span>
+<span class="release-info">Release 0.3, documentation updated on Mar 8, 2007.</span>
</DIV>
<!--End of Navigation Panel-->
diff --git a/ref/module-httplib2.html b/ref/module-httplib2.html
index 5ead329..137482c 100644
--- a/ref/module-httplib2.html
+++ b/ref/module-httplib2.html
@@ -109,7 +109,10 @@
</dd></dl>
<P>
-The <tt class="module">httplib2</tt> module may raise the following Exceptions:
+The <tt class="module">httplib2</tt> module may raise the following Exceptions. Note that
+there is an option that turns exceptions into
+normal responses with an HTTP status code indicating
+an error occured. See <tt class="member">Http.force_exception_to_status_code</tt>
<P>
<dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-3' xml:id='l2h-3' class="exception">HttpLib2Error</tt></b></dt>
@@ -131,21 +134,33 @@
</dd></dl>
<P>
-<dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-6' xml:id='l2h-6' class="exception">FailedToDecompressContent</tt></b></dt>
+<dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-6' xml:id='l2h-6' class="exception">ServerNotFoundError</tt></b></dt>
+<dd>
+Unable to resolve the host name given.
+</dd></dl>
+
+<P>
+<dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-7' xml:id='l2h-7' class="exception">RelativeURIError</tt></b></dt>
+<dd>
+A relative, as opposed to an absolute URI, was passed into request().
+</dd></dl>
+
+<P>
+<dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-8' xml:id='l2h-8' class="exception">FailedToDecompressContent</tt></b></dt>
<dd>
The headers claimed that the content of the response was compressed but the
decompression algorithm applied to the content failed.
</dd></dl>
<P>
-<dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-7' xml:id='l2h-7' class="exception">UnimplementedDigestAuthOptionError</tt></b></dt>
+<dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-9' xml:id='l2h-9' class="exception">UnimplementedDigestAuthOptionError</tt></b></dt>
<dd>
The server requested a type of Digest authentication that we
are unfamiliar with.
</dd></dl>
<P>
-<dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-8' xml:id='l2h-8' class="exception">UnimplementedHmacDigestAuthOptionError</tt></b></dt>
+<dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-10' xml:id='l2h-10' class="exception">UnimplementedHmacDigestAuthOptionError</tt></b></dt>
<dd>
The server requested a type of HMACDigest authentication that we
are unfamiliar with.
@@ -153,7 +168,7 @@
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
- <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-9' xml:id='l2h-9' class="class">Http</tt></b>(</nobr></td>
+ <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-11' xml:id='l2h-11' class="class">Http</tt></b>(</nobr></td>
<td><var></var><big>[</big><var>cache=None</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
The class that represents a client HTTP interface.
@@ -164,7 +179,7 @@
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
- <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-10' xml:id='l2h-10' class="class">Response</tt></b>(</nobr></td>
+ <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-12' xml:id='l2h-12' class="class">Response</tt></b>(</nobr></td>
<td><var>info</var>)</td></tr></table></dt>
<dd>
Response is a subclass of <tt class="class">dict</tt> and instances of this
@@ -175,7 +190,7 @@
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
- <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-11' xml:id='l2h-11' class="class">FileCache</tt></b>(</nobr></td>
+ <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-13' xml:id='l2h-13' class="class">FileCache</tt></b>(</nobr></td>
<td><var>dir_name, </var><big>[</big><var>safe=safename</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
FileCache implements a Cache as a directory of files.
@@ -237,7 +252,7 @@
</div>
</div>
<hr />
-<span class="release-info">Release 0.2, documentation updated on July 2, 2006.</span>
+<span class="release-info">Release 0.3, documentation updated on Mar 8, 2007.</span>
</DIV>
<!--End of Navigation Panel-->
diff --git a/ref/node2.html b/ref/node2.html
index 462ced8..2f910b1 100644
--- a/ref/node2.html
+++ b/ref/node2.html
@@ -106,7 +106,7 @@
</div>
</div>
<hr />
-<span class="release-info">Release 0.2, documentation updated on July 2, 2006.</span>
+<span class="release-info">Release 0.3, documentation updated on Mar 8, 2007.</span>
</DIV>
<!--End of Navigation Panel-->
diff --git a/ref/ref.html b/ref/ref.html
index e1dd92b..eab247b 100644
--- a/ref/ref.html
+++ b/ref/ref.html
@@ -48,8 +48,8 @@
<p>
Email: <span class="email">joe@bitworking.org</span>
</p>
-<p><strong>Release 0.2</strong><br />
-<strong>July 2, 2006</strong></p>
+<p><strong>Release 0.3</strong><br />
+<strong>Mar 8, 2007</strong></p>
<p></p>
</div>
</div>
@@ -120,7 +120,7 @@
</div>
</div>
<hr />
-<span class="release-info">Release 0.2, documentation updated on July 2, 2006.</span>
+<span class="release-info">Release 0.3, documentation updated on Mar 8, 2007.</span>
</DIV>
<!--End of Navigation Panel-->
diff --git a/ref/response-objects.html b/ref/response-objects.html
index 28e585b..0b78a16 100644
--- a/ref/response-objects.html
+++ b/ref/response-objects.html
@@ -61,32 +61,32 @@
a Response object also has:
<P>
-<dl><dt><b><tt id='l2h-20' xml:id='l2h-20' class="member">fromcache</tt></b></dt>
+<dl><dt><b><tt id='l2h-23' xml:id='l2h-23' class="member">fromcache</tt></b></dt>
<dd>
If <code>true</code> the the response was returned from the cache.
</dl>
<P>
-<dl><dt><b><tt id='l2h-21' xml:id='l2h-21' class="member">version</tt></b></dt>
+<dl><dt><b><tt id='l2h-24' xml:id='l2h-24' class="member">version</tt></b></dt>
<dd>
The version of HTTP that the server supports. A value
of 11 means '1.1'.
</dl>
<P>
-<dl><dt><b><tt id='l2h-22' xml:id='l2h-22' class="member">status</tt></b></dt>
+<dl><dt><b><tt id='l2h-25' xml:id='l2h-25' class="member">status</tt></b></dt>
<dd>
The numerical HTTP status code returned in the response.
</dl>
<P>
-<dl><dt><b><tt id='l2h-23' xml:id='l2h-23' class="member">reason</tt></b></dt>
+<dl><dt><b><tt id='l2h-26' xml:id='l2h-26' class="member">reason</tt></b></dt>
<dd>
The human readable component of the HTTP response status code.
</dl>
<P>
-<dl><dt><b><tt id='l2h-24' xml:id='l2h-24' class="member">previous</tt></b></dt>
+<dl><dt><b><tt id='l2h-27' xml:id='l2h-27' class="member">previous</tt></b></dt>
<dd>
If redirects are followed then the <tt class="class">Response</tt> object returned
is just for the very last HTTP request and <var>previous</var> points to
@@ -101,7 +101,11 @@
redirects were encountered, you can determine the ultimate URI that
the request was sent to. All Response objects contain this key value,
including <code>previous</code> responses so you can determine the entire
-chain of redirects.
+chain of redirects. If <tt class="member">Http.force_exception_to_status_code</tt> is <code>True</code>
+and the number of redirects has exceeded the number of allowed number
+of redirects then the <tt class="class">Response</tt> object will report the error
+in the status code, but the complete chain of previous responses will
+still be in tact.
<P>
@@ -138,7 +142,7 @@
</div>
</div>
<hr />
-<span class="release-info">Release 0.2, documentation updated on July 2, 2006.</span>
+<span class="release-info">Release 0.3, documentation updated on Mar 8, 2007.</span>
</DIV>
<!--End of Navigation Panel-->