Request

All operations relating to handling of requests to an HTTP service.

This is the core module for handling requests and their responses including using authorisation and caching as necessary.

Classes:

RequestHandler(connector[, authoriser, ...])

Generic HTTP request handler.

class aiorequestful.request.RequestHandler(connector, authoriser=None, payload_handler=None, response_handlers=None, wait_timer=None, retry_timer=None)

Bases: Generic

Generic HTTP request handler. Handles error responses, retries on failed requests, authorisation, caching etc.

Parameters:

• connector (Callable[[], aiohttp.ClientSession]) – When called, returns a new session to use when making requests.

• authoriser (A | None (default: None)) – The authoriser to use when authorising requests to the HTTP service.

• payload_handler (PayloadHandler (default: None)) – Handles payload data conversion to return response payload in expected format.

• response_handlers (Sequence[StatusHandler] (default: None)) – Handlers to handle responses for specific status codes. Should many of the given handlers be responsible for handling the same status code, the first handler in the sequence will be used for that status code.

• wait_timer (Timer (default: None)) – The time to wait after every request, regardless of whether it was successful. It is best practice to configure this such that a maximum time can be achieved within a reasonable time to ensure times between requests do not get too large. Useful to help manage calls to services that have strict restraints around rate limiting.

• retry_timer (Timer (default: None)) – The timer that controls how long to wait in between each successive failed request. It is best practice to configure this such that a maximum time can be achieved within a reasonable time to cause a timeout and raise an exception.

Attributes:

closed	Is the stored client session closed.
session	The ClientSession object if it exists and is open.
retry_timer	The timer that controls how long to wait in between each successive failed request.
logger	The logging.Logger for this object
authoriser	The Authoriser object
payload_handler	Handles payload data conversion to return response payload in expected format
response_handlers	Handles a response according to its status, payload, headers, etc.
wait_timer	The time to wait after every request, regardless of whether it was successful

Methods:

create([authoriser, cache, payload_handler, ...])	Create a new RequestHandler with an appropriate session connector given the input kwargs
authorise()	Authenticate and authorise, testing/refreshing/re-authorising as needed.
close()	Close the current session.
log(method, url[, message, level])	Format and log a request or request adjacent message to the given level.
request(**kwargs)	Generic method for handling HTTP requests handling errors, authorisation, backoff, caching etc.
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 closed

Is the stored client session closed.

property session: ClientSession

The ClientSession object if it exists and is open.

property retry_timer: Timer | None

The timer that controls how long to wait in between each successive failed request. Always returns a reset timer with initial settings.

classmethod create(authoriser=None, cache=None, payload_handler=None, response_handlers=None, wait_timer=None, retry_timer=None, **session_kwargs)

Create a new RequestHandler with an appropriate session connector given the input kwargs

Return type:

RequestHandler[A, P]

logger: Logger

The logging.Logger for this object

authoriser

The Authoriser object

property payload_handler: PayloadHandler

Handles payload data conversion to return response payload in expected format

property response_handlers: dict[int, StatusHandler]

Handles a response according to its status, payload, headers, etc.

wait_timer

The time to wait after every request, regardless of whether it was successful

async authorise()

Authenticate and authorise, testing/refreshing/re-authorising as needed. Updates the session with new credentials.

Returns:

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

Raises:

AuthoriserError – If the token cannot be validated.

async close()

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

Return type:

None

log(method, url, message=None, level=10, **kwargs)

Format and log a request or request adjacent message to the given level.

Return type:

None

async request(**kwargs)

Generic method for handling HTTP requests handling errors, authorisation, backoff, caching etc. as configured.

See aiohttp reference for more info on available kwargs: https://docs.aiohttp.org/en/stable/client_reference.html#aiohttp.ClientSession.request

Returns:

P – The JSON formatted response or, if JSON formatting not possible, the text response.

Raises:

• RequestError – For any request which fails.

• ResponseError – For any request which returns an invalid response.

• StatusHandlerError – For any request which returns a response with a status that could not be handled.

async get(url, **kwargs)

Sends a GET request.

Return type:

P

async post(url, **kwargs)

Sends a POST request.

Return type:

P

async put(url, **kwargs)

Sends a PUT request.

Return type:

P

async delete(url, **kwargs)

Sends a DELETE request.

Return type:

P

async options(url, **kwargs)

Sends an OPTIONS request.

Return type:

P

async head(url, **kwargs)

Sends a HEAD request.

Return type:

P

async patch(url, **kwargs)

Sends a PATCH request.

Return type:

P