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 (Iterable | str | bytes | None) – Optional secret key used to sign cache items for added security

  • salt (str | bytes) – Optional salt used to sign cache items

  • serializer – Custom serializer that provides loads and dumps methods

abstractmethod async bulk_delete(keys)

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

Parameters:

keys (set)

abstractmethod async clear()

Delete all items from the cache

async close()

Close any active connections, if applicable

abstractmethod async contains(key)

Check if a key is stored in the cache

Parameters:

key (str)

Return type:

bool

abstractmethod 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:

CachedResponse | str | None

abstractmethod 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]

abstractmethod 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:

bytes | None

abstractmethod async size()

Get the number of items in the cache

Return type:

int

abstractmethod values()

Get all values stored in the cache

Return type:

AsyncIterable[Union[CachedResponse, bytes, str, None]]

abstractmethod async write(key, item)

Write an item to the cache

Parameters:
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:
async bulk_delete(keys)
Parameters:

keys (set)

async clear()

Clear cache

async close()

Close any active connections, if applicable

create_cache_actions(key, url, expire_after=None, refresh=False, **kwargs)

Create cache actions based on request info

Parameters:

  • key (str) – key from create_key function

  • 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:

CacheActions

create_key(method, url, **kwargs)

Create a unique cache key based on request details

Parameters:
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:
property disabled
async get_response(key)

Fetch a cached response based on a cache key

Parameters:

key (str)

Return type:

CachedResponse | None

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:
Return type:

bool

async is_cacheable(response, actions=None)

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

Parameters:
Return type:

bool

async request(actions)

Fetch a cached response based on cache actions

Parameters:

actions (CacheActions) – CacheActions from create_cache_actions function

Return type:

CachedResponse | None

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

Save a response to the cache

Parameters:

  • response (ClientResponse) – Response to save

  • cache_key (str | None) – Cache key to use for the response; will be generated if not provided

  • expires (datetime | None) – 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:
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:

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: