Hide navigation sidebar
Hide table of contents sidebar
Support urllib3 on GitHub Sponsors
Back to top
Toggle table of contents sidebar

# 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 as `request()`.

    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 of `str`/`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 a `Retry` 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. When `False`, 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 response `r` to return the connection back into the pool. If None, it takes the value of `response_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 of `assert_fingerprint`, `assert_hostname` and `host` in this order to verify connections. If `assert_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 if `ssl` is available and are fed into `urllib3.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` and `HTTPSConnectionPool`.

  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