Documented changes in fixing bug 1597381 Map exceptions to status codes

10 files changed, 82 insertions, 36 deletions

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 @@ July 2, 2006, Release 0.2
 </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 @@ supports this interface natively.
 
 <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 @@ Takes a string <var>key</var> and returns the value as a string.
 
 <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 @@ Takes a string <var>key</var> and <var>value</var> and stores it in the cache.
 
 <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 @@ of <var>key</var> is a string.
 </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 @@ Contents</A>
 </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 @@ Http objects have the following methods:
 
 <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 @@ The return value is a tuple of (response, content), the first being and instance
 
 <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 @@ requires authentication.
 
 <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 @@ URI to which it is being redirected. If <code>True</code> then all redirects are
 </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 @@ is mainly to deal with broken servers which supply an etag, but change it capric
 </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 @@ resp, content = h.request(uri, "POST", body=body, headers=headers)
 </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 @@ resp, content = h.request(uri, "POST", body=body, headers=headers)
 </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 @@ A comprehensive HTTP client library.</a>
 </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 @@ The amount of debugging information to print. The default is 0.
 </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 @@ The maximum number of redirections was reached without coming to a final URI.
 </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 @@ are unfamiliar with.
 
 <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 @@ implements the required caching interface.
 
 <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 @@ an <tt class="class">rfc822.Message</tt> or an <tt class="class">httplib.HTTPRes
 
 <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 @@ into the constructor of <tt class="class">Http</tt>.
 </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 @@ A comprehensive HTTP client library.</a>
 </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 @@ A comprehensive HTTP client library.</a>
 </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 @@ to header values. In addition to the dict methods
 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 @@ contains the URI that was ultimately requested. This is useful if
 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 @@ chain of redirects.
 </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-->