From: Cory Benfield Date: Tue, 9 Apr 2013 18:54:47 +0000 (+0100) Subject: Add HTTPAdapter to API docs. X-Git-Tag: v1.2.1~20^2~1 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=c73f65335268da9b7ee9a793d8923ab8ce710457;p=services%2Fpython-requests.git Add HTTPAdapter to API docs. --- diff --git a/docs/api.rst b/docs/api.rst index 8e7eacd..771d7a8 100644 --- 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 --- 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 ` 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 `. + + :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 `. + + :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 ` object from a urllib3 + response. This should not be called from user code, and is only exposed + for use when subclassing the + :class:`HTTPAdapter ` + + :param req: The :class:`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 `. + + :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 `. + + :param request: The :class:`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 `. + + :param request: The :class:`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 ` 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)