diff options
Diffstat (limited to 'requests/adapters.py')
| -rw-r--r-- | requests/adapters.py | 109 |
1 files changed, 95 insertions, 14 deletions
diff --git a/requests/adapters.py b/requests/adapters.py index 5666e66..98b7317 100644 --- a/requests/adapters.py +++ b/requests/adapters.py @@ -25,6 +25,7 @@ from .cookies import extract_cookies_to_jar from .exceptions import ConnectionError, Timeout, SSLError from .auth import _basic_auth_str +DEFAULT_POOLBLOCK = False DEFAULT_POOLSIZE = 10 DEFAULT_RETRIES = 0 @@ -43,19 +44,41 @@ class BaseAdapter(object): class HTTPAdapter(BaseAdapter): - """Built-In HTTP Adapter for Urllib3.""" - __attrs__ = ['max_retries', 'config', '_pool_connections', '_pool_maxsize'] - - def __init__(self, pool_connections=DEFAULT_POOLSIZE, pool_maxsize=DEFAULT_POOLSIZE): - self.max_retries = DEFAULT_RETRIES + """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. + :param max_retries: The maximum number of retries each connection should attempt. + :param pool_block: Whether the connection pool should block for connections. + + Usage:: + + >>> import requests + >>> s = requests.Session() + >>> a = requests.adapters.HTTPAdapter() + >>> s.mount('http://', a) + """ + __attrs__ = ['max_retries', 'config', '_pool_connections', '_pool_maxsize', + '_pool_block'] + + def __init__(self, pool_connections=DEFAULT_POOLSIZE, + pool_maxsize=DEFAULT_POOLSIZE, max_retries=DEFAULT_RETRIES, + pool_block=DEFAULT_POOLBLOCK): + self.max_retries = max_retries self.config = {} super(HTTPAdapter, self).__init__() self._pool_connections = pool_connections self._pool_maxsize = pool_maxsize + self._pool_block = pool_block - self.init_poolmanager(pool_connections, pool_maxsize) + self.init_poolmanager(pool_connections, pool_maxsize, block=pool_block) def __getstate__(self): return dict((attr, getattr(self, attr, None)) for attr in @@ -65,16 +88,36 @@ class HTTPAdapter(BaseAdapter): for attr, value in state.items(): setattr(self, attr, value) - self.init_poolmanager(self._pool_connections, self._pool_maxsize) + self.init_poolmanager(self._pool_connections, self._pool_maxsize, + block=self._pool_block) + + def init_poolmanager(self, connections, maxsize, block=DEFAULT_POOLBLOCK): + """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>`. - def init_poolmanager(self, connections, maxsize): + :param connections: The number of urllib3 connection pools to cache. + :param maxsize: The maximum number of connections to save in the pool. + :param block: Block when no free connections are available. + """ # save these values for pickling self._pool_connections = connections self._pool_maxsize = maxsize + self._pool_block = block - self.poolmanager = PoolManager(num_pools=connections, maxsize=maxsize) + self.poolmanager = PoolManager(num_pools=connections, maxsize=maxsize, + block=block) 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 +146,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 +182,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 +201,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 +212,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 +233,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 +259,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) |