Default to doing DNS resolution through a proxy server if present.

- Resolve an issue where proxy information by default was not resolving DNS
  through a proxy server (unlike the `socks` library), so users getting
  proxy information from an environment variable (HTTP_PROXY/HTTPS_PROXY)
  with no external DNS could not connect to hosts with DNS names.

- Resolve a potential issue where if the proxy server was a different
  address family to the destination host and there was functional DNS, may
  not work.  For example, using a IPv4-only proxy server to connect to an
  IPv6-only host via an IPv4-only internal network.

- Improved documentation of the ProxyInfo class.

1 files changed, 20 insertions, 4 deletions

diff --git a/python3/httplib2/__init__.py b/python3/httplib2/__init__.py
index e01ddd7..43f7419 100644
--- a/python3/httplib2/__init__.py
+++ b/python3/httplib2/__init__.py
@@ -714,11 +714,27 @@ class KeyCerts(Credentials):
 
 class ProxyInfo(object):
   """Collect information required to use a proxy."""
-  def __init__(self, proxy_type, proxy_host, proxy_port, proxy_rdns=None, proxy_user=None, proxy_pass=None):
-      """The parameter proxy_type must be set to one of socks.PROXY_TYPE_XXX
-      constants. For example:
+  def __init__(self, proxy_type, proxy_host, proxy_port, proxy_rdns=True, proxy_user=None, proxy_pass=None):
+      """
+        Args:
+          proxy_type: The type of proxy server.  This must be set to one of
+          socks.PROXY_TYPE_XXX constants.  For example:
+
+            p = ProxyInfo(proxy_type=socks.PROXY_TYPE_HTTP,
+              proxy_host='localhost', proxy_port=8000)
+
+          proxy_host: The hostname or IP address of the proxy server.
+
+          proxy_port: The port that the proxy server is running on.
+
+          proxy_rdns: If True (default), DNS queries will not be performed
+          locally, and instead, handed to the proxy to resolve.  This is useful
+          if the network does not allow resolution of non-local names.  In
+          httplib2 0.9 and earlier, this defaulted to False.
+
+          proxy_user: The username used to authenticate with the proxy server.
 
-p = ProxyInfo(proxy_type=socks.PROXY_TYPE_HTTP, proxy_host='localhost', proxy_port=8000)
+          proxy_pass: The password used to authenticate with the proxy server.
       """
       self.proxy_type, self.proxy_host, self.proxy_port, self.proxy_rdns, self.proxy_user, self.proxy_pass = proxy_type, proxy_host, proxy_port, proxy_rdns, proxy_user, proxy_pass