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.

Handling Exceptions From the Underlying HTTP Client Library

Each Consumer instance has an exceptions property that exposes an enum of standard HTTP client exceptions that can be handled:

try:
    repo = github.create_repo(name="myproject", auto_init=True)
except github.exceptions.ConnectionError:
    # Handle client socket error:
    ...

This approach to handling exceptions decouples your code from the backing HTTP client, improving code reuse and testability.

Here are the HTTP client exceptions that are exposed through this property:

• BaseClientException: Base exception for client connection errors.
• ConnectionError: A client socket error occurred.
• ConnectionTimeout: The request timed out while trying to connect to the remote server.
• ServerTimeout: The server did not send any data in the allotted amount of time.
• SSLError: An SSL error occurred.
• InvalidURL: URL used for fetching is malformed.

Of course, you can also explicitly catch a particular client error from the backing client (e.g., requests.FileModeWarning). This may be useful for handling exceptions that are not exposed through the Consumer.exceptions property, for example:

try:
    repo = github.create_repo(name="myproject", auto_init=True)
except aiohttp.ContentTypeError:
    ...

Handling Client Exceptions within an @error_handler

The @error_handler decorator registers a callback to deal with exceptions thrown by the backing HTTP client.

To provide the decorated callback a reference to the Consumer instance at runtime, set the decorator’s optional argument requires_consumer to True. This enables the error handler to leverage the consumer’s exceptions property:

 @error_handler(requires_consumer=True)
 def raise_api_error(consumer, exc_type, exc_val, exc_tb):
     """Wraps client error with custom API error"""
     if isinstance(exc_val, consumer.exceptions.ServerTimeout):
         # Handle the server timeout specifically:
         ...

 class GitHub(Consumer):
     @raise_api_error
     @post("user/repo")
     def create_repo(self, name: Field):
         """Create a new repository."""