Base

Base interface for implementations of all cache backends.

Classes:

`ResponseRepositorySettings`(name[, ...])	Settings for a response type from a given endpoint to be used to configure a repository in the cache backend.
`ResponseRepository`(settings[, expire])	Represents a repository in the backend cache, providing a dict-like interface for interacting with this repository.
`ResponseCache`(cache_name[, ...])	Represents a backend cache of many repositories, providing a dict-like interface for interacting with them.

class aiorequestful.cache.backend.base.ResponseRepositorySettings(name, payload_handler=<aiorequestful.response.payload.StringPayloadHandler object>)

Bases: Generic

Settings for a response type from a given endpoint to be used to configure a repository in the cache backend.

Attributes:

`name`	That name of the repository in the backend
`payload_handler`(response)	Handles payload data conversion to/from expected format for de/serialization.
`fields`	The names of the fields relating to the keys extracted by `get_key()` in the order in which they appear from the results of this method.

Methods:

`get_key`(**kwargs)	Extracts the name to assign to a cache entry in the repository from the given request kwargs.
`get_name`(payload)	Extracts the name to assign to a cache entry in the repository from a given `response`.

name: str: That name of the repository in the backend

payload_handler(response: str | bytes | bytearray | aiohttp.client_reqrep.ClientResponse | T) → collections.abc.Awaitable: PayloadHandler[TypeVar(V)] = <aiorequestful.response.payload.StringPayloadHandler object>: Handles payload data conversion to/from expected format for de/serialization.

abstract property fields: tuple[str, ...]: The names of the fields relating to the keys extracted by get_key() in the order in which they appear from the results of this method.

abstractmethod get_key(**kwargs)

Extracts the name to assign to a cache entry in the repository from the given request kwargs.

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

Return type:: tuple

abstractmethod static get_name(payload)

Extracts the name to assign to a cache entry in the repository from a given response.

Return type:: str | None

class aiorequestful.cache.backend.base.ResponseRepository(settings, expire=datetime.timedelta(days=7))

Bases: AsyncIterable[tuple[K, V]], Generic

Represents a repository in the backend cache, providing a dict-like interface for interacting with this repository.

A repository is a data store within the backend e.g. a table in a database.

Parameters:

settings (ResponseRepositorySettings[TypeVar(V, bound= Any)]) – The settings to use to identify and interact with the repository in the backend.
expire (timedelta | relativedelta (default: datetime.timedelta(days=7))) – The expiry time to apply to cached responses after which responses are invalidated.

Attributes:

`expire`	The datetime representing the maximum allowed expiry time from now.
`logger`	The `logging.Logger` for this object
`settings`	The settings to use to identify and interact with the repository in the backend.
`connection`	The current connection to the backend.

Methods:

`create`(args, *kwargs)	Set up the backend repository in the backend database if it doesn't already exist and return the initialised object that represents it.
`commit`()	Commit the changes to the repository
`close`()	Close the connection to the repository.
`count`([include_expired])	Get the number of responses in this repository.
`contains`(request)	Check whether the repository contains a given `request`
`clear`([expired_only])	Clear the repository of all entries.
`serialize`(value)	Serialize a given `value` to a type that can be persisted to the repository.
`deserialize`(value)	Deserialize a value from the repository to the expected response value type.
`get_key_from_request`(request)	Extract the key to use when persisting responses for a given `request`
`get_response`(request)	Get the response relating to the given `request` from this repository if it exists.
`get_responses`(requests)	Get the responses relating to the given `requests` from this repository if they exist.
`save_response`(response)	Save the given `response` to this repository if a key can be extracted from it.
`save_responses`(responses)	Save the given `responses` to this repository if a key can be extracted from them.
`delete_response`(request)	Delete the given `request` from this repository if it exists.
`delete_responses`(requests)	Delete the given `requests` from this repository if they exist.

property expire: datetime: The datetime representing the maximum allowed expiry time from now.

abstractmethod classmethod create(*args, **kwargs)

Set up the backend repository in the backend database if it doesn’t already exist and return the initialised object that represents it.

Return type:: Self

logger: Logger: The logging.Logger for this object

settings: The settings to use to identify and interact with the repository in the backend.

connection: The current connection to the backend.

abstractmethod async commit()

Commit the changes to the repository

Return type:: None

abstractmethod async close()

Close the connection to the repository.

Return type:: None

abstractmethod async count(include_expired=True)

Get the number of responses in this repository.

Parameters:: include_expired (bool (default: True)) – Whether to include expired responses in the final count.
Returns:: int – The number of responses in this repository.

abstractmethod async contains(request)

Check whether the repository contains a given request

Return type:: bool

abstractmethod async clear(expired_only=False)

Clear the repository of all entries.

Parameters:: expired_only (bool (default: False)) – Whether to only remove responses that have expired.
Returns:: int – The number of responses cleared from the repository.

async serialize(value)

Serialize a given value to a type that can be persisted to the repository.

Returns:: Optional[TypeVar(V, bound= Any)] – Serialized object if serializing is possible, None otherwise.

async deserialize(value)

Deserialize a value from the repository to the expected response value type.

Returns:: Any – Deserialized object if deserializing is possible, None otherwise.

abstractmethod get_key_from_request(request)

Extract the key to use when persisting responses for a given request

Return type:: TypeVar(K, bound= tuple)

abstractmethod async get_response(request)

Get the response relating to the given request from this repository if it exists.

Returns:: Optional[TypeVar(V, bound= Any)] – The result if found.

async get_responses(requests)

Get the responses relating to the given requests from this repository if they exist.

Returns:: list[TypeVar(V, bound= Any)] – Results unordered.

async save_response(response)

Save the given response to this repository if a key can be extracted from it. Safely fail if not

Return type:: None

async save_responses(responses)

Save the given responses to this repository if a key can be extracted from them. Safely fail on those that can’t.

Return type:: None

abstractmethod async delete_response(request)

Delete the given request from this repository if it exists.

Returns:: bool – True if deleted in the repository and False if request was not found in the repository.

async delete_responses(requests)

Delete the given requests from this repository if they exist.

Returns:: int – The number of the given requests deleted in the repository.

class aiorequestful.cache.backend.base.ResponseCache(cache_name, repository_getter=None, expire=datetime.timedelta(days=7))

Bases: MutableMapping[str, R], Generic

Represents a backend cache of many repositories, providing a dict-like interface for interacting with them.

Parameters:

cache_name (str) – The name to give to this cache.
repository_getter (Callable[[Self, str | URL], Optional[TypeVar(R, bound= ResponseRepository)]] (default: None)) – A function that can be used to identify the repository in this cache that matches a given URL.
expire (timedelta | relativedelta (default: datetime.timedelta(days=7))) – The expiry time to apply to cached responses after which responses are invalidated.

Attributes:

`type`
`cache_name`	The name to give to this cache.
`repository_getter`	A function that can be used to identify the repository in this cache that matches a given URL.
`expire`	The expiry time to apply to cached responses after which responses are invalidated.

Methods:

`connect`(value, **kwargs)	Connect to the backend from a given generic `value`.
`commit`()	Commit the changes to the cache
`close`()	Close the connection to the repository.
`create_repository`(settings)	Create and return a `SQLiteResponseStorage` and store this object in this cache.
`get_repository_from_url`(url)	Returns the repository to use from the stored repositories in this cache for the given `url`.
`get_repository_from_requests`(requests)	Returns the repository to use from the stored repositories in this cache for the given `requests`.
`get_response`(request)	Get the response relating to the given `request` from the appropriate repository if it exists.
`get_responses`(requests)	Get the responses relating to the given `requests` from the appropriate repository if they exist.
`save_response`(response)	Save the given `response` to the appropriate repository if a key can be extracted from it.
`save_responses`(responses)	Save the given `responses` to the appropriate repository if a key can be extracted from them.
`delete_response`(request)	Delete the given `request` from the appropriate repository if it exists.
`delete_responses`(requests)	Delete the given `requests` from the appropriate repository.

type = None

abstractmethod async classmethod connect(value, **kwargs)

Connect to the backend from a given generic value.

Return type:: Self

cache_name: The name to give to this cache.

repository_getter: A function that can be used to identify the repository in this cache that matches a given URL.

expire: The expiry time to apply to cached responses after which responses are invalidated.

abstractmethod async commit()

Commit the changes to the cache

Return type:: None

abstractmethod async close(): Close the connection to the repository.

abstractmethod create_repository(settings)

Create and return a SQLiteResponseStorage and store this object in this cache.

Creates a repository with the given settings in the cache if it doesn’t exist.

Return type:: ResponseRepository

get_repository_from_url(url)

Returns the repository to use from the stored repositories in this cache for the given url.

Return type:: Optional[TypeVar(R, bound= ResponseRepository)]

get_repository_from_requests(requests)

Returns the repository to use from the stored repositories in this cache for the given requests.

Return type:: Optional[TypeVar(R, bound= ResponseRepository)]

async get_response(request)

Get the response relating to the given request from the appropriate repository if it exists.

Returns:: Any – The result if found.

async get_responses(requests)

Get the responses relating to the given requests from the appropriate repository if they exist.

Returns:: list – Results unordered.

async save_response(response)

Save the given response to the appropriate repository if a key can be extracted from it.

Return type:: None

async save_responses(responses)

Save the given responses to the appropriate repository if a key can be extracted from them. Safely fail on those that can’t.

Return type:: None

async delete_response(request)

Delete the given request from the appropriate repository if it exists.

Returns:: bool – True if deleted in the repository and False if request was not found in the repository.

async delete_responses(requests)

Delete the given requests from the appropriate repository.

Returns:: int – The number of the given requests deleted in the repository.