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
_abc_impl = <_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

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
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, 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.

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

  • cache_name (str) – Cache prefix or namespace, depending on backend

  • expire_after (Union[None, int, float, str, datetime, timedelta]) – Time after which a cache entry will be expired; see Cache Expiration for possible formats

  • urls_expire_after (Optional[Dict[str, Union[None, int, float, str, datetime, timedelta]]]) – Expiration times to apply for different URL patterns

  • allowed_codes (tuple) – Only cache responses with these status codes

  • allowed_methods (tuple) – Only cache requests with these HTTP methods

  • include_headers (bool) – Cache requests with different headers separately

  • ignored_params (Optional[Iterable]) – Request parameters to be excluded from the cache key

  • cache_control (bool) – Use Cache-Control response headers

  • filter_fn (Callable) – function that takes a aiohttp.ClientResponse object and returns a boolean indicating whether or not that response should be cached. Will be applied to both new and previously cached responses

  • secret_key (Union[Iterable, str, bytes]) – 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

Parameters
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
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
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
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(method, url, expire_after=None, **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.

  • 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: aiohttp_client_cache.backends.base.BaseCache, collections.UserDict

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

Parameters
_abc_impl = <_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)#

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

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