base#

Summary#

`BaseCache`([secret_key, salt, serializer])	A wrapper for lower-level cache storage operations.
`CacheBackend`([cache_name, expire_after, ...])	Base class for cache backends; includes a non-persistent, in-memory cache.
`DictCache`([secret_key, salt, serializer])	Simple in-memory storage that wraps a dict with the `BaseStorage` interface

Module Contents#

class BaseCache(secret_key=None, salt=b'aiohttp-client-cache', serializer=None, **kwargs)#

Bases: object

A wrapper for lower-level cache storage operations. This is separate from CacheBackend to allow a single backend to contain multiple cache objects.

Parameters:

secret_key (Union[Iterable, str, bytes, None]) – Optional secret key used to sign cache items for added security
salt (Union[str, bytes]) – Optional salt used to sign cache items
serializer – Custom serializer that provides loads and dumps methods

_abc_impl = <_abc._abc_data object>#

static _get_serializer(secret_key, salt)#: Get the appropriate serializer to use; either itsdangerous, if a secret key is specified, or plain pickle otherwise. :raises py:exc:ImportError if secret_key is specified but itsdangerous is not installed:

abstract async bulk_delete(keys)#

Delete item(s) from the cache. Does not raise an error if the item is missing.

Parameters:: keys (set) –

abstract async clear()#: Delete all items from the cache

async close()#: Close any active connections, if applicable

abstract async contains(key)#

Check if a key is stored in the cache

Parameters:: key (str) –
Return type:: bool

abstract async delete(key)#

Delete an item from the cache. Does not raise an error if the item is missing.

Parameters:: key (str) –

deserialize(item)#

Deserialize a cached URL or response

Parameters:: item (Union[CachedResponse, bytes, str, None]) –
Return type:: Union[CachedResponse, str, None]

abstract keys()#

Get all keys stored in the cache

Return type:: AsyncIterable[str]

async pop(key, default=None)#

Delete an item from the cache, and return the deleted item

Parameters:: key (str) –
Return type:: Union[CachedResponse, bytes, str, None]

abstract async read(key)#

Read an item from the cache. Returns None if the item is missing.

Parameters:: key (str) –
Return type:: Union[CachedResponse, bytes, str, None]

serialize(item=None)#

Serialize a URL or response into bytes

Parameters:: item (Union[CachedResponse, bytes, str, None]) –
Return type:: Optional[bytes]

abstract async size()#

Get the number of items in the cache

Return type:: int

abstract values()#

Get all values stored in the cache

Return type:: AsyncIterable[Union[CachedResponse, bytes, str, None]]

abstract async write(key, item)#

Write an item to the cache

Parameters:

key (str) –
item (Union[CachedResponse, bytes, str, None]) –

class CacheBackend(cache_name='aiohttp-cache', expire_after=-1, urls_expire_after=None, allowed_codes=(200, ), allowed_methods=('GET', 'HEAD'), include_headers=False, ignored_params=None, autoclose=False, cache_control=False, filter_fn=<function CacheBackend.<lambda>>, **kwargs)#

Bases: object

Base class for cache backends; includes a non-persistent, in-memory cache.

This manages higher-level cache operations, including cache expiration, generating cache keys, and managing redirect history.

Lower-level storage operations are handled by BaseCache. To extend this with your own custom backend, implement one or more subclasses of BaseCache to use as CacheBackend.responses and CacheBackend.response_aliases.

Parameters:

cache_name (str) –
expire_after (Union[None, int, float, str, datetime, timedelta]) –
urls_expire_after (Optional[Dict[str, Union[None, int, float, str, datetime, timedelta]]]) –
allowed_codes (Tuple[int, ...]) –
allowed_methods (Tuple[str, ...]) –
include_headers (bool) –
ignored_params (Optional[Iterable[str]]) –
autoclose (bool) –
cache_control (bool) –
filter_fn (Union[Callable[[Union[ClientResponse, CachedResponse]], bool], Callable[[Union[ClientResponse, CachedResponse]], Awaitable[bool]]]) –
kwargs (Any) –

async _close_if_enabled()#: Close any active connections, if autoclose is enabled

async _get_redirect_response(key)#

Get the response referenced by a redirect key, if available

Parameters:: key (str) –
Return type:: Optional[CachedResponse]

async bulk_delete(keys)#

Parameters:: keys (set) –

async clear()#: Clear cache

async close()#: Close any active connections, if applicable

create_key(method, url, **kwargs)#

Create a unique cache key based on request details

Parameters:

method (str) –
url (Union[str, URL]) –
kwargs (Any) –

async delete(key)#

Delete a response from the cache, along with its history (if applicable)

Parameters:: key (str) –

async delete_expired_responses()#: Deletes all expired responses from the cache. Also deletes any cache items that are filtered out according to filter_fn().

async delete_url(url, method='GET', **kwargs)#

Delete cached response associated with url, along with its history (if applicable)

Parameters:

url (Union[str, URL]) –
method (str) –
kwargs (Any) –

async get_response(key)#

Fetch a cached response based on a cache key

Parameters:: key (str) –
Return type:: Optional[CachedResponse]

async get_urls()#

Get all URLs currently in the cache

Return type:: AsyncIterable[str]

async has_url(url, method='GET', **kwargs)#

Returns True if cache has url, False otherwise

Parameters:

url (Union[str, URL]) –
method (str) –

Return type:

bool

async is_cacheable(response, actions=None)#

Perform all checks needed to determine if the given response should be cached

Parameters:

response (Union[ClientResponse, CachedResponse, None]) –
actions (Optional[CacheActions]) –

Return type:

bool

async request(method, url, expire_after=None, refresh=False, **kwargs)#

Fetch a cached response based on request info

Parameters:

method (str) – HTTP method
url (Union[str, URL]) – Request URL
expire_after (Union[None, int, float, str, datetime, timedelta]) – Expiration time to set only for this request; overrides CachedSession.expire_after, and accepts all the same values.
refresh (bool) – Revalidate with the server before using a cached response, and refresh if needed (e.g., a “soft refresh”, like F5 in a browser)
kwargs – All other request arguments

Return type:

Tuple[Optional[CachedResponse], CacheActions]

async save_response(response, cache_key=None, expires=None)#

Save a response to the cache

Parameters:

response (ClientResponse) – Response to save
cache_key (Optional[str]) – Cache key to use for the response; will be generated if not provided
expires (Optional[datetime]) – Expiration time to set for the response

class DictCache(secret_key=None, salt=b'aiohttp-client-cache', serializer=None, **kwargs)#

Bases: BaseCache, UserDict

Simple in-memory storage that wraps a dict with the BaseStorage interface

Parameters:

secret_key (Union[Iterable, str, bytes, None]) –
salt (Union[str, bytes]) –

_abc_impl = <_abc._abc_data object>#

async bulk_delete(keys)#

Delete item(s) from the cache. Does not raise an error if the item is missing.

Parameters:: keys (set) –

async clear()#: Delete all items from the cache

async contains(key)#

Check if a key is stored in the cache

Parameters:: key (str) –
Return type:: bool

async delete(key)#

Delete an item from the cache. Does not raise an error if the item is missing.

Parameters:: key (str) –

async keys()#

Get all keys stored in the cache

Return type:: AsyncIterable[str]

async read(key)#

An additional step is needed here for response data. The original response object is still in memory, and hasn’t gone through a serialize/deserialize loop. So, the file-like response body has already been read, and needs to be reset.

Parameters:: key (str) –
Return type:: Union[CachedResponse, str, None]

async size()#

Get the number of items in the cache

Return type:: int

async values()#

Get all values stored in the cache

Return type:: AsyncIterable[Union[CachedResponse, bytes, str, None]]

async write(key, item)#

Write an item to the cache

Parameters:

key (str) –
item (Union[CachedResponse, bytes, str, None]) –