Add HTTPAdapter to API docs.

diff --git a/docs/api.rst b/docs/api.rst
index 8e7eacd..771d7a8 100644 (file)
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -41,6 +41,9 @@ Request Sessions
 .. autoclass:: Session
    :inherited-members:
 
+.. autoclass:: requests.adapters.HTTPAdapter
+   :inherited-members:
+
 
 Exceptions
 ~~~~~~~~~~
@@ -104,6 +107,9 @@ Classes
 .. autoclass:: requests.Session
    :inherited-members:
 
+.. autoclass:: requests.adapters.HTTPAdapter
+   :inherited-members:
+
 
 Migrating to 1.x
 ----------------

diff --git a/requests/adapters.py b/requests/adapters.py
index 5666e66..ac76921 100644 (file)
--- a/requests/adapters.py
+++ b/requests/adapters.py
@@ -43,7 +43,23 @@ class BaseAdapter(object):
 
 
 class HTTPAdapter(BaseAdapter):
-    """Built-In HTTP Adapter for Urllib3."""
+    """The built-in HTTP Adapter for urllib3.
+
+    Provides a general-case interface for Requests sessions to contact HTTP and
+    HTTPS urls by implementing the Transport Adapter interface. This class will
+    usually be created by the :class:`Session <Session>` class under the
+    covers.
+
+    :param pool_connections: The number of urllib3 connection pools to cache.
+    :param pool_maxsize: The maximum number of connections to save in the pool.
+
+    Usage::
+
+      >>> import requests
+      >>> s = requests.Session()
+      >>> a = requests.adapters.HTTPAdapter()
+      >>> s.mount('http://', a)
+    """
     __attrs__ = ['max_retries', 'config', '_pool_connections', '_pool_maxsize']
 
     def __init__(self, pool_connections=DEFAULT_POOLSIZE, pool_maxsize=DEFAULT_POOLSIZE):
@@ -68,6 +84,13 @@ class HTTPAdapter(BaseAdapter):
         self.init_poolmanager(self._pool_connections, self._pool_maxsize)
 
     def init_poolmanager(self, connections, maxsize):
+        """Initializes a urllib3 PoolManager. This method should not be called
+        from user code, and is only exposed for use when subclassing the
+        :class:`HTTPAdapter <requests.adapters.HTTPAdapter>`.
+
+        :param connections: The number of urllib3 connection pools to cache.
+        :param maxsize: The maximum number of connections to save in the pool.
+        """
         # save these values for pickling
         self._pool_connections = connections
         self._pool_maxsize = maxsize
@@ -75,6 +98,15 @@ class HTTPAdapter(BaseAdapter):
         self.poolmanager = PoolManager(num_pools=connections, maxsize=maxsize)
 
     def cert_verify(self, conn, url, verify, cert):
+        """Verify a SSL certificate. This method should not be called from user
+        code, and is only exposed for use when subclassing the
+        :class:`HTTPAdapter <requests.adapters.HTTPAdapter>`.
+
+        :param conn: The urllib3 connection object associated with the cert.
+        :param url: The requested URL.
+        :param verify: Whether we should actually verify the certificate.
+        :param cert: The SSL certificate to verify.
+        """
         if url.startswith('https') and verify:
 
             cert_loc = None
@@ -103,6 +135,14 @@ class HTTPAdapter(BaseAdapter):
                 conn.cert_file = cert
 
     def build_response(self, req, resp):
+        """Builds a :class:`Response <requests.Response>` object from a urllib3
+        response. This should not be called from user code, and is only exposed
+        for use when subclassing the
+        :class:`HTTPAdapter <requests.adapters.HTTPAdapter>`
+
+        :param req: The :class:`PreparedRequest <PreparedRequest>` used to generate the response.
+        :param resp: The urllib3 response object.
+        """
         response = Response()
 
         # Fallback to None if there's no status_code, for whatever reason.
@@ -131,7 +171,13 @@ class HTTPAdapter(BaseAdapter):
         return response
 
     def get_connection(self, url, proxies=None):
-        """Returns a connection for the given URL."""
+        """Returns a urllib3 connection for the given URL. This should not be
+        called from user code, and is only exposed for use when subclassing the
+        :class:`HTTPAdapter <reqeusts.adapters.HTTPAdapter>`.
+
+        :param url: The URL to connect to.
+        :param proxies: (optional) A Requests-style dictionary of proxies used on this request.
+        """
         proxies = proxies or {}
         proxy = proxies.get(urlparse(url).scheme)
 
@@ -144,7 +190,7 @@ class HTTPAdapter(BaseAdapter):
         return conn
 
     def close(self):
-        """Dispose of any internal state.
+        """Disposes of any internal state.
 
         Currently, this just closes the PoolManager, which closes pooled
         connections.
@@ -155,7 +201,15 @@ class HTTPAdapter(BaseAdapter):
         """Obtain the url to use when making the final request.
 
         If the message is being sent through a proxy, the full URL has to be
-        used. Otherwise, we should only use the path portion of the URL."""
+        used. Otherwise, we should only use the path portion of the URL.
+
+        This shoudl not be called from user code, and is only exposed for use
+        when subclassing the
+        :class:`HTTPAdapter <requests.adapters.HTTPAdapter>`.
+
+        :param request: The :class:`PreparedRequest <PreparedRequest>` being sent.
+        :param proxies: A dictionary of schemes to proxy URLs.
+        """
         proxies = proxies or {}
         proxy = proxies.get(urlparse(request.url).scheme)
 
@@ -168,7 +222,15 @@ class HTTPAdapter(BaseAdapter):
 
     def add_headers(self, request, **kwargs):
         """Add any headers needed by the connection. Currently this adds a
-        Proxy-Authorization header."""
+        Proxy-Authorization header.
+
+        This should not be called from user code, and is only exposed for use
+        when subclassing the
+        :class:`HTTPAdapter <requests.adapters.HTTPAdapter>`.
+
+        :param request: The :class:`PreparedRequest <PreparedRequest>` to add headers to.
+        :param kwargs: The keyword arguments from the call to send().
+        """
         proxies = kwargs.get('proxies', {})
 
         if proxies is None:
@@ -186,7 +248,15 @@ class HTTPAdapter(BaseAdapter):
                                                                      password)
 
     def send(self, request, stream=False, timeout=None, verify=True, cert=None, proxies=None):
-        """Sends PreparedRequest object. Returns Response object."""
+        """Sends PreparedRequest object. Returns Response object.
+
+        :param request: The :class:`PreparedRequest <PreparedRequest>` being sent.
+        :param stream: (optional) Whether to stream the request content.
+        :param timeout: (optional) The timeout on the request.
+        :param verify: (optional) Whether to verify SSL certificates.
+        :param vert: (optional) Any user-provided SSL certificate to be trusted.
+        :param proxies: (optional) The proxies dictionary to apply to the request.
+        """
 
         conn = self.get_connection(request.url, proxies)