Senders

Manipulate the way clients send requests.

SyncSender	Send requests synchronously.
AsyncSender	Send requests asynchronously.
RetryingSender	Retry requests if unsuccessful.
CachingSender	Cache successful GET requests.

See also Other classes.

Senders provide a hook between defining a request and sending it to the Web API. The sender of a Client also determines whether synchronous or asynchronous calls are used to send requests and process responses.

Sender instances are passed to a client at initialisation.

import tekore as tk

tk.Credentials(*conf, sender=tk.SyncSender())
tk.Spotify(sender=tk.RetryingSender())

Senders wrap around the httpx library and accept additional keyword arguments to httpx.Client().

proxies = {
    'http': 'http://10.10.10.10:8000',
    'https': 'http://10.10.10.10:8000',
}
tk.SyncSender(proxies=proxies)

Instances of httpx.Client or httpx.AsyncClient can also be passed in for a finer control over sender behaviour.

from httpx import Client

client = Client(proxies=proxies)
tk.SyncSender(client)

Concrete senders

Final senders in a possible chain that concretely make the request to Spotify.

class tekore.SyncSender(client=None)

Bases: Sender

Send requests synchronously.

Warning

The underlying client is not closed automatically. Use sender.client.close() to close it, particularly if multiple senders are instantiated.

Parameters:

client (Client | None) – httpx.Client to use when sending requests

close()

Close the underlying synchronous client.

Return type:

None

property is_async: bool

Sender asynchronicity, always False.

send(request)

Send request with httpx.Client.

Parameters:

request (Request)

Return type:

Response

class tekore.AsyncSender(client=None)

Bases: Sender

Send requests asynchronously.

Warning

The underlying client is not closed automatically. Use await sender.client.aclose() to close it, particularly if multiple senders are instantiated.

Parameters:

client (AsyncClient | None) – httpx.AsyncClient to use when sending requests

async close()

Close the underlying asynchronous client.

Return type:

None

property is_async: bool

Sender asynchronicity, always True.

async send(request)

Send request with httpx.AsyncClient.

Parameters:

request (Request)

Return type:

Response

Extending senders

Senders that extend the functionality of other senders.

class tekore.RetryingSender(retries=0, sender=None)

Bases: ExtendingSender

Retry requests if unsuccessful.

On server errors the set amount of retries are used to resend requests. On TooManyRequests the Retry-After header is checked and used to wait before requesting again.

Note

Even when the number of retries is set to zero, retries based on rate limiting are still performed.

Parameters:

• retries (int) – maximum number of retries on server errors before giving up

• sender (Sender | None) – request sender, SyncSender if not specified

Examples

Use for only rate limiting by leaving the retry count to zero.

tk.RetryingSender()

Pass the maximum number of retries to retry failed requests.

tk.RetryingSender(retries=3)

send(request)

Delegate request to underlying sender and retry if failed.

Parameters:

request (Request)

Return type:

Response | Coroutine[None, None, Response]

class tekore.CachingSender(max_size=None, sender=None)

Bases: ExtendingSender

Cache successful GET requests.

The Web API provides response headers for caching. Resources are cached based on Cache-Control, ETag and Vary headers. Thus CachingSender can be used with user tokens too. Resources marked as private, errors and Vary: * are not cached.

When using asynchronous senders, the cache is protected with asyncio.Lock to prevent concurrent access. The lock is instantiated on the first asynchronous call, so using only one asyncio.run() (per sender) is advised.

Note that if the cache has no maximum size it can grow without limit. Use CachingSender.clear() to empty the cache.

Parameters:

• max_size (int | None) – maximum cache size (amount of responses), if specified the least recently used response is discarded when the cache would overflow

• sender (Sender | None) – request sender, SyncSender if not specified

clear()

Clear sender cache.

Return type:

None

property max_size: int | None

Maximum amount of requests stored in the cache.

Returns:

maximum cache size

Return type:

int | None

send(request)

Maybe load request from cache, or delegate to underlying sender.

Parameters:

request (Request)

Return type:

Response | Coroutine[None, None, Response]

Other classes

Bases for subclassing or other endeavours.

Sender	Sender interface for requests.
ExtendingSender	Base class for senders that extend other senders.
SenderConflictWarning	Sender arguments to a client are in conflict.
Client	Base class for clients.
Request	Wrapper for parameters of a HTTP request.
Response	Wrapper for result of a HTTP request.

class tekore.Sender

Bases: ABC

Sender interface for requests.

abstractmethod close()

Close underlying client.

Return type:

None | Coroutine[None, None, None]

abstract property is_async: bool

Sender asynchronicity mode.

abstractmethod send(request)

Send a request.

Parameters:

request (Request) – request to send

Returns:

resulting response

Return type:

Response

class tekore.ExtendingSender(sender)

Bases: Sender

Base class for senders that extend other senders.

Parameters:

sender (Sender | None) – request sender, SyncSender if not specified

close()

Close the underlying sender.

To close synchronous senders, call close(). To close asynchronous senders, await close().

Return type:

None | Coroutine[None, None, None]

property is_async: bool

Sender asynchronicity, delegated to the underlying sender.

class tekore.SenderConflictWarning

Bases: RuntimeWarning

Sender arguments to a client are in conflict.

class tekore.Client(sender, asynchronous=None)

Bases: ExtendingSender

Base class for clients.

Parameters:

• sender (Sender | None) – request sender - If not specified, a SyncSender is used

• asynchronous (bool | None) – synchronicity requirement - If specified, overrides passed sender if they are in conflict and instantiates a sender of the requested type

send(request)

Send request with underlying sender.

Parameters:

request (Request)

Return type:

Response | Coroutine[None, None, Response]

class tekore.Request(method, url, params=None, headers=None, data=None, json=None, content=None)

Wrapper for parameters of a HTTP request.

Parameters:

• method (str)

• url (str)

• params (dict | None)

• headers (dict | None)

• data (dict | None)

• json (dict | None)

• content (str | None)

class tekore.Response(url, headers, status_code, content)

Wrapper for result of a HTTP request.

Parameters:

• url (str)

• headers (dict)

• status_code (int)

• content (dict | None)