Clients

To use a common English metaphor: Uplink stands on the shoulders of giants.

Uplink doesn’t implement any code to handle HTTP protocol stuff directly; for that, the library delegates to an actual HTTP client, such as Requests or Aiohttp. Whatever backing client you choose, when a request method on a Consumer subclass is invoked, Uplink ultimately interacts with the backing library’s interface, at minimum to submit requests and read responses.

This section covers the interaction between Uplink and the backing HTTP client library of your choosing, including how to specify your selection.

Swapping Out the Default HTTP Session

By default, Uplink sends requests using the Requests library. You can configure the backing HTTP client object using the client parameter of the Consumer constructor:

github = GitHub(BASE_URL, client=...)

For example, you can use the client parameter to pass in your own Requests session object:

session = requests.Session()
session.verify = False
github = GitHub(BASE_URL, client=session)

Further, this also applies for session objects from other HTTP client libraries that Uplink supports, such as aiohttp (i.e., a custom ClientSession works here, as well).

Following the above example, the client parameter also accepts an instance of any requests.Session subclass. This makes it easy to leverage functionality from third-party Requests extensions, such as requests-oauthlib, with minimal integration overhead:

from requests_oauthlib import OAuth2Session

session = OAuth2Session(...)
api = MyApi(BASE_URL, client=session)

Synchronous vs. Asynchronous

Notably, Requests blocks while waiting for a response from the server. For non-blocking requests, Uplink comes with built-in (but optional) support for aiohttp and twisted.

For instance, you can provide the AiohttpClient when constructing a Consumer instance:

from uplink import AiohttpClient

github = GitHub(BASE_URL, client=AiohttpClient())

Checkout this example on GitHub for more.