Connection Pools#
- class urllib3.HTTPConnectionPool(host, port=None, strict=False, timeout=<object object>, maxsize=1, block=False, headers=None, retries=None, _proxy=None, _proxy_headers=None, _proxy_config=None, **conn_kw)#
Bases:
ConnectionPool
,RequestMethods
Thread-safe connection pool for one host.
- Parameters
host – Host used for this HTTP Connection (e.g. “localhost”), passed into
http.client.HTTPConnection
.port – Port used for this HTTP Connection (None is equivalent to 80), passed into
http.client.HTTPConnection
.strict –
Causes BadStatusLine to be raised if the status line can’t be parsed as a valid HTTP/1.0 or 1.1 status line, passed into
http.client.HTTPConnection
.Note
Only works in Python 2. This parameter is ignored in Python 3.
timeout – Socket timeout in seconds for each individual connection. This can be a float or integer, which sets the timeout for the HTTP request, or an instance of
urllib3.util.Timeout
which gives you more fine-grained control over request timeouts. After the constructor has been parsed, this is always a urllib3.util.Timeout object.maxsize – Number of connections to save that can be reused. More than 1 is useful in multithreaded situations. If
block
is set to False, more connections will be created but they will not be saved once they’ve been used.block – If set to True, no more than
maxsize
connections will be used at a time. When no free connections are available, the call will block until a connection has been released. This is a useful side effect for particular multithreaded situations where one does not want to use more than maxsize connections per host to prevent flooding.headers – Headers to include with all requests, unless other headers are given explicitly.
retries – Retry configuration to use by default with requests in this pool.
_proxy – Parsed proxy URL, should not be used directly, instead, see
urllib3.ProxyManager
_proxy_headers – A dictionary with proxy headers, should not be used directly, instead, see
urllib3.ProxyManager
**conn_kw – Additional parameters are used to create fresh
urllib3.connection.HTTPConnection
,urllib3.connection.HTTPSConnection
instances.
- ConnectionCls#
alias of
HTTPConnection
- ResponseCls#
alias of
HTTPResponse
- close()#
Close all pooled connections and disable the pool.
- is_same_host(url)#
Check if the given
url
is a member of the same host as this connection pool.
- scheme = 'http'#
- urlopen(method, url, body=None, headers=None, retries=None, redirect=True, assert_same_host=True, timeout=<object object>, pool_timeout=None, release_conn=None, chunked=False, body_pos=None, **response_kw)#
Get a connection from the pool and perform an HTTP request. This is the lowest level call for making a request, so you’ll need to specify all the raw details.
Note
More commonly, it’s appropriate to use a convenience method provided by
RequestMethods
, such asrequest()
.Note
release_conn will only behave as expected if preload_content=False because we want to make preload_content=False the default behaviour someday soon without breaking backwards compatibility.
- Parameters
method – HTTP request method (such as GET, POST, PUT, etc.)
url – The URL to perform the request on.
body – Data to send in the request body, either
str
,bytes
, an iterable ofstr
/bytes
, or a file-like object.headers – Dictionary of custom headers to send, such as User-Agent, If-None-Match, etc. If None, pool headers are used. If provided, these headers completely replace any pool-specific headers.
retries (
Retry
, False, or an int.) –Configure the number of retries to allow before raising a
MaxRetryError
exception.Pass
None
to retry until you receive a response. Pass aRetry
object for fine-grained control over different types of retries. Pass an integer number to retry connection errors that many times, but no other types of errors. Pass zero to never retry.If
False
, then retries are disabled and any exception is raised immediately. Also, instead of raising a MaxRetryError on redirects, the redirect response will be returned.redirect – If True, automatically handle redirects (status codes 301, 302, 303, 307, 308). Each redirect counts as a retry. Disabling retries will disable redirect, too.
assert_same_host – If
True
, will make sure that the host of the pool requests is consistent else will raise HostChangedError. WhenFalse
, you can use the pool on an HTTP proxy and request foreign hosts.timeout – If specified, overrides the default timeout for this one request. It may be a float (in seconds) or an instance of
urllib3.util.Timeout
.pool_timeout – If set and the pool is set to block=True, then this method will block for
pool_timeout
seconds and raise EmptyPoolError if no connection is available within the time period.release_conn – If False, then the urlopen call will not release the connection back into the pool once a response is received (but will release if you read the entire contents of the response such as when preload_content=True). This is useful if you’re not preloading the response’s content immediately. You will need to call
r.release_conn()
on the responser
to return the connection back into the pool. If None, it takes the value ofresponse_kw.get('preload_content', True)
.chunked – If True, urllib3 will send the body using chunked transfer encoding. Otherwise, urllib3 will send the body using the standard content-length form. Defaults to False.
body_pos (int) – Position to seek to in file-like body in the event of a retry or redirect. Typically this won’t need to be set because urllib3 will auto-populate the value when needed.
**response_kw – Additional parameters are passed to
urllib3.response.HTTPResponse.from_httplib()
- class urllib3.HTTPSConnectionPool(host, port=None, strict=False, timeout=<object object>, maxsize=1, block=False, headers=None, retries=None, _proxy=None, _proxy_headers=None, key_file=None, cert_file=None, cert_reqs=None, key_password=None, ca_certs=None, ssl_version=None, assert_hostname=None, assert_fingerprint=None, ca_cert_dir=None, **conn_kw)#
Bases:
HTTPConnectionPool
Same as
HTTPConnectionPool
, but HTTPS.HTTPSConnection
uses one ofassert_fingerprint
,assert_hostname
andhost
in this order to verify connections. Ifassert_hostname
is False, no verification is done.The
key_file
,cert_file
,cert_reqs
,ca_certs
,ca_cert_dir
,ssl_version
,key_password
are only used ifssl
is available and are fed intourllib3.util.ssl_wrap_socket()
to upgrade the connection socket into an SSL socket.- ConnectionCls#
alias of
HTTPSConnection
- scheme = 'https'#
- class urllib3.connectionpool.ConnectionPool(host, port=None)#
Bases:
object
Base class for all connection pools, such as
HTTPConnectionPool
andHTTPSConnectionPool
.Note
ConnectionPool.urlopen() does not normalize or percent-encode target URIs which is useful if your target server doesn’t support percent-encoded target URIs.
- QueueCls#
alias of
LifoQueue
- close()#
Close all pooled connections and disable the pool.
- scheme = None#