add documentation for timeouts

The httplib2 client docs don't say what units the timeout is in nor explain 
what happens if you leave it at the default. From looking at the code, I think 
the following patch would fix it:

HACL Zooko-Ofsimplegeos-MacBook-Pro:~/playground/httplib2/httplib2$ hg diff
diff -r ab1e9b202938 python2/httplib2/__init__.py
--- a/python2/httplib2/__init__.py      Thu Jul 22 00:31:16 2010 -0500
+++ b/python2/httplib2/__init__.py      Wed Sep 01 12:21:54 2010 -0600
@@ -708,7 +708,14 @@

 class HTTPConnectionWithTimeout(httplib.HTTPConnection):
-    """HTTPConnection subclass that supports timeouts"""
+    """
+    HTTPConnection subclass that supports timeouts
+
+    All timeouts are in seconds. If None is passed for timeout then
+    Python's default timeout for sockets will be used. See for example
+    the docs of socket.setdefaulttimeout():
+    http://docs.python.org/library/socket.html#socket.setdefaulttimeout
+    """

     def __init__(self, host, port=None, strict=None, timeout=None, proxy_info=None):
         httplib.HTTPConnection.__init__(self, host, port, strict)
@@ -749,8 +756,14 @@
             raise socket.error, msg

 class HTTPSConnectionWithTimeout(httplib.HTTPSConnection):
-    "This class allows communication via SSL."
+    """
+    This class allows communication via SSL.

+    All timeouts are in seconds. If None is passed for timeout then
+    Python's default timeout for sockets will be used. See for example
+    the docs of socket.setdefaulttimeout():
+    http://docs.python.org/library/socket.html#socket.setdefaulttimeout
+    """
     def __init__(self, host, port=None, key_file=None, cert_file=None,
                  strict=None, timeout=None, proxy_info=None):
         httplib.HTTPSConnection.__init__(self, host, port=port, key_file=key_file,
@@ -789,11 +802,18 @@
 and more.
     """
     def __init__(self, cache=None, timeout=None, proxy_info=None):
-        """The value of proxy_info is a ProxyInfo instance.
+        """
+        The value of proxy_info is a ProxyInfo instance.

-If 'cache' is a string then it is used as a directory name
-for a disk cache. Otherwise it must be an object that supports
-the same interface as FileCache."""
+        If 'cache' is a string then it is used as a directory name for
+        a disk cache. Otherwise it must be an object that supports the
+        same interface as FileCache.
+
+        All timeouts are in seconds. If None is passed for timeout
+        then Python's default timeout for sockets will be used. See
+        for example the docs of socket.setdefaulttimeout():
+        http://docs.python.org/library/socket.html#socket.setdefaulttimeout
+        """
         self.proxy_info = proxy_info
         # Map domain name to an httplib connection
         self.connections = {}
Original issue reported on code.google.com by zoo...@gmail.com on 1 Sep 2010 at 6:22
yaocaigen / httplib2

add documentation for timeouts #110
