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>
+&gt;&gt;&gt; import httplib2
+&gt;&gt;&gt; import urllib
+&gt;&gt;&gt; data = {'name': 'fred', 'address': '123 shady lane'}
+&gt;&gt;&gt; body = urllib.urlencode(data)
+&gt;&gt;&gt; body
+'name=fred&amp;address=123+shady+lane'
+&gt;&gt;&gt; h = httplib2.Http()
+&gt;&gt;&gt; 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>&nbsp;<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>&nbsp;<tt id='l2h-6' xml:id='l2h-6' class="exception">FailedToDecompressContent</tt></b></dt>
+<dl><dt><b><span class="typelabel">exception</span>&nbsp;<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>&nbsp;<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>&nbsp;<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>&nbsp;<tt id='l2h-7' xml:id='l2h-7' class="exception">UnimplementedDigestAuthOptionError</tt></b></dt>
+<dl><dt><b><span class="typelabel">exception</span>&nbsp;<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>&nbsp;<tt id='l2h-8' xml:id='l2h-8' class="exception">UnimplementedHmacDigestAuthOptionError</tt></b></dt>
+<dl><dt><b><span class="typelabel">exception</span>&nbsp;<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>&nbsp;<tt id='l2h-9' xml:id='l2h-9' class="class">Http</tt></b>(</nobr></td>
+  <td><nobr><b><span class="typelabel">class</span>&nbsp;<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>&nbsp;<tt id='l2h-10' xml:id='l2h-10' class="class">Response</tt></b>(</nobr></td>
+  <td><nobr><b><span class="typelabel">class</span>&nbsp;<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>&nbsp;<tt id='l2h-11' xml:id='l2h-11' class="class">FileCache</tt></b>(</nobr></td>
+  <td><nobr><b><span class="typelabel">class</span>&nbsp;<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-->