The Base Consumer Class

Consumer

uplink.Consumer

Consumer(base_url='', client=None, converters=(), auth=None, hooks=(), **kwargs)

Bases: Consumer, _Consumer

Base consumer class with which to define custom consumers.

Example usage:

from uplink import Consumer, get

class GitHub(Consumer):

    @get("/users/{user}")
    def get_user(self, user):
        pass

client = GitHub("https://api.github.com/")
client.get_user("prkumar").json()  # {'login': 'prkumar', ... }

PARAMETER	DESCRIPTION
base_url	The base URL for any request sent from this consumer instance. TYPE: str DEFAULT: ''
client	A supported HTTP client instance (e.g., a requests.Session) or an adapter (e.g., uplink.RequestsClient). TYPE: optional DEFAULT: None
converters	One or more objects that encapsulate custom (de)serialization strategies for request properties and/or the response body. (E.g., uplink.converters.MarshmallowConverter) TYPE: ConverterFactory DEFAULT: ()
auth	The authentication object for this consumer instance. TYPE: tuple or callable DEFAULT: None
hooks	One or more hooks to modify behavior of request execution and response handling (see uplink.response_handler or uplink.error_handler). TYPE: TransactionHook DEFAULT: ()

Source code in uplink/builder.py

def __init__(
    self, base_url="", client=None, converters=(), auth=None, hooks=(), **kwargs
):
    builder = Builder()
    builder.base_url = base_url
    builder.converters = kwargs.pop("converter", converters)
    hooks = kwargs.pop("hook", hooks)
    if isinstance(hooks, hooks_.TransactionHook):
        hooks = (hooks,)
    builder.add_hook(*hooks)
    builder.auth = auth
    builder.client = client
    self.__session = session.Session(builder)
    self.__client = builder.client

exceptions property

exceptions

An enum of standard HTTP client exceptions that can be handled.

This property enables the handling of specific exceptions from the backing HTTP client.

Example

try:
    github.get_user(user_id)
except github.exceptions.ServerTimeout:
    # Handle the timeout of the request
    ...

session property

session

The Session object for this consumer instance.

Exposes the configuration of this Consumer instance and allows the persistence of certain properties across all requests sent from that instance.

Example usage:

import uplink

class MyConsumer(uplink.Consumer):
    def __init__(self, language):
        # Set this header for all requests of the instance.
        self.session.headers["Accept-Language"] = language
        ...

RETURNS	DESCRIPTION
	Session

Session

uplink.session.Session

Session(builder)

The session of a Consumer instance.

Exposes the configuration of a Consumer instance and allows the persistence of certain properties across all requests sent from that instance.

Source code in uplink/session.py

def __init__(self, builder):
    self.__builder = builder
    self.__params = None
    self.__headers = None
    self.__context = None

auth property writable

auth

The authentication object for this consumer instance.

base_url property

base_url

The base URL for any requests sent from this consumer instance.

context property

context

A dictionary of name-value pairs that are made available to request middleware.

headers property

headers

A dictionary of headers to be sent on each request from this consumer instance.

params property

params

A dictionary of querystring data to attach to each request from this consumer instance.

inject

inject(hook, *more_hooks)

Add hooks (e.g., functions decorated with either uplink.response_handler or uplink.error_handler) to the session.

Source code in uplink/session.py

def inject(self, hook, *more_hooks):
    """
    Add hooks (e.g., functions decorated with either
    [`uplink.response_handler`][uplink.response_handler] or
    [`uplink.error_handler`][uplink.error_handler]) to the session.
    """
    self.__builder.add_hook(hook, *more_hooks)