As someone who has written a few API client libraries and works on Requests a bit, I realize I have some overlapping knowledge that I need to share. There are some patterns I've found from building my own API client libraries and helping developers of other client libraries. I hesitate to call these "Best Practices" because I'm sure there are better ways of providing this functionality based on how you're designing your library, but the underlying idea of allowing users more choice and freedom should hopefully shine through regardless.

Before we get to that, though, let's start with some basics.

Requests Connection Pooling - Cruise Control for Better Performance One of the things that Requests does for its users is provide connection pooling. It only does this when the user uses a Session object though. So, all API client libraries really need to use Session objects under the hood and share a Session object as much as possible. Take, for example, github3.py. Users create a GitHub object and can retrieve other objects with that - Users, Repositories, Issues, Pull Requests, etc. Any object that was created by that same GitHub instance (or an instance of an object it created) will share the same Session and thus the same connection pool. That means they all share the same credentials and the same configuration. Now, if someone creates a different GitHub object, that will receive a new Session (unless the user passes in a specific one that it wants to share with a different instance) so that the Sessions aren't really shared between everything, just objects created from the same ancestor (for lack of a better term).

Requests Adapters - Fine Tuning Your HTTP Experience In the past, I have written about retries in which we create a new HTTPAdapter to configure how Requests performs retries in a granular way. Adapters, however, are fantastic tools that allow users to configure much more than just retries. For example, if you want to change the connection pool limit you can simply specify: import requests my_session = requests . Session () my_adapter = requests . adapters . HTTPAdapter ( pool_maxsize = 20 ) my_session . mount ( 'https://' , my_adapter ) In fact, there are several options that most people do not usually need but which users can specify: max_retries - This can be an integer or a Retry object as documented in my other blog post

- This can be an integer or a object as documented in my other blog post pool_connections - The number of connection pools to create

- The number of connection pools to create pool_maxsize - The maximum number of connections to keep in a connection pool

- The maximum number of connections to keep in a connection pool pool_block - Whether or not the connection pool should block waiting for a fresh connection. This defaults to False which means that we will always create a new connection rather than wait for a previous request to finish and return the connection to the pool. By overriding some of these defaults, you can make your HTTP experience with Requests custom.