Request

All operations relating to handling of requests to an API.

Classes:

RequestHandler(authoriser[, cache])

Generic API request handler using cached responses for GET requests only.

class musify.api.request.RequestHandler(authoriser, cache=None)

Bases: object

Generic API request handler using cached responses for GET requests only. Caches GET responses for a maximum of 4 weeks by default. Handles error responses and backoff on failed requests. See APIAuthoriser for more info on which params to pass to authorise requests.

Parameters:

• authoriser (APIAuthoriser) – The authoriser to use when authorising requests to the API.

• cache (ResponseCache | None (default: None)) – When given, set up a CachedSession and attempt to use the cache for certain request types before calling the API.

Attributes:

backoff_final	The maximum wait time to retry a request in seconds until giving up when applying backoff to failed requests
timeout	When the response gives a time to wait until (i.e. retry-after), the program will exit if this time is above this timeout (in seconds).
logger	The MusifyLogger for this object
authoriser	The APIAuthoriser object
cache	The cache to use when attempting to return a cached response.
session	The Session object
backoff_start	The initial backoff time for failed requests
backoff_factor	The factor by which to increase backoff time for failed requests i.e. backoff_start ** backoff_factor.
backoff_count	The maximum number of request attempts to make before giving up and raising an exception

Methods:

authorise([force_load, force_new])	Method for API authorisation which tests/refreshes/reauthorises as needed.
close()	Close the current session.
request(method, url, *args, **kwargs)	Generic method for handling API requests with back-off on failed requests.
get(url, **kwargs)	Sends a GET request.
post(url, **kwargs)	Sends a POST request.
put(url, **kwargs)	Sends a PUT request.
delete(url, **kwargs)	Sends a DELETE request.
options(url, **kwargs)	Sends an OPTIONS request.
head(url, **kwargs)	Sends a HEAD request.
patch(url, **kwargs)	Sends a PATCH request.

property backoff_final: int

The maximum wait time to retry a request in seconds until giving up when applying backoff to failed requests

property timeout: int

When the response gives a time to wait until (i.e. retry-after), the program will exit if this time is above this timeout (in seconds)

logger: MusifyLogger

The MusifyLogger for this object

authoriser

The APIAuthoriser object

cache

The cache to use when attempting to return a cached response.

session

The Session object

backoff_start

The initial backoff time for failed requests

backoff_factor

The factor by which to increase backoff time for failed requests i.e. backoff_start ** backoff_factor

backoff_count

The maximum number of request attempts to make before giving up and raising an exception

authorise(force_load=False, force_new=False)

Method for API authorisation which tests/refreshes/reauthorises as needed.

Parameters:

• force_load (bool (default: False)) – Reloads the token even if it’s already been loaded into the object. Ignored when force_new is True.

• force_new (bool (default: False)) – Ignore saved/loaded token and generate new token.

Returns:

dict[str, str] – Headers for request authorisation.

Raises:

APIError – If the token cannot be validated.

close()

Close the current session. No more requests will be possible once this has been called.

Return type:

None

request(method, url, *args, **kwargs)

Generic method for handling API requests with back-off on failed requests. See request() for more arguments.

Parameters:

• method (str) – method for the new Request object: GET, OPTIONS, HEAD, POST, PUT, PATCH, or DELETE.

• url (str) – URL for the new Request object.

Returns:

dict[str, Any] – The JSON formatted response or, if JSON formatting not possible, the text response.

Raises:

APIError – On any logic breaking error/response.

get(url, **kwargs)

Sends a GET request.

Return type:

dict[str, Any]

post(url, **kwargs)

Sends a POST request.

Return type:

dict[str, Any]

put(url, **kwargs)

Sends a PUT request.

Return type:

dict[str, Any]

delete(url, **kwargs)

Sends a DELETE request.

Return type:

dict[str, Any]

options(url, **kwargs)

Sends an OPTIONS request.

Return type:

dict[str, Any]

head(url, **kwargs)

Sends a HEAD request.

Return type:

dict[str, Any]

patch(url, **kwargs)

Sends a PATCH request.

Return type:

dict[str, Any]