What’s the meaning of pool_connections in requests.adapters.HTTPAdapter?

When initializing a requests’ Session, two HTTPAdapter will be created and mount to http and https.

This is how HTTPAdapter is defined:

class requests.adapters.HTTPAdapter(pool_connections=10, pool_maxsize=10,
                                    max_retries=0, pool_block=False)

While I understand the meaning of pool_maxsize(which is the number of session a pool can save), I don’t understand what pool_connections means or what it does. Doc says:

Parameters: 
pool_connections – The number of urllib3 connection pools to cache.

But what does it mean “to cache”? And what’s the point using multiple connection pools?

Answer

Requests uses urllib3 to manage its connections and other features.

Re-using connections is an important factor in keeping recurring HTTP requests performant. The urllib3 README explains:

Why do I want to reuse connections?

Performance. When you normally do a urllib call, a separate socket connection is created with each request. By reusing existing sockets (supported since HTTP 1.1), the requests will take up less resources on the server’s end, and also provide a faster response time at the client’s end. […]

To answer your question, “pool_maxsize” is the number of connections to keep around per host (this is useful for multi-threaded applications), whereas “pool_connections” is the number of host-pools to keep around. For example, if you’re connecting to 100 different hosts, and pool_connections=10, then only the latest 10 hosts’ connections will be re-used.