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 clear()

Delete all items from the cache

abstract async contains(key)

Check if a key is stored in the cache

Return type

bool

Parameters

key (str) –

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

Return type

Union[CachedResponse, str, None]

Parameters

item (Optional[Union[aiohttp_client_cache.response.CachedResponse, bytes, str]]) –

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

Return type

Union[CachedResponse, bytes, str, None]

Parameters

key (str) –

abstract async read(key)

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

Return type

Union[CachedResponse, bytes, str, None]

Parameters

key (str) –

serialize(item=None)

Serialize a URL or response into bytes

Return type

Optional[bytes]

Parameters

item (Optional[Union[aiohttp_client_cache.response.CachedResponse, bytes, str]]) –

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=True, 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
__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=True, 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

async _get_redirect_response(key)

Get the response referenced by a redirect key, if available

Return type

Optional[CachedResponse]

Parameters

key (str) –

async clear()

Clear cache

create_key(*args, **kwargs)

Create a unique cache key based on request details

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)

Delete cached response associated with url, along with its history (if applicable). Works only for GET requests.

Parameters

url (Union[str, yarl.URL]) –

async get_response(key)

Fetch a cached response based on a cache key

Return type

Optional[CachedResponse]

Parameters

key (str) –

get_urls()

Get all URLs currently in the cache

Return type

AsyncIterable[str]

async has_url(url)

Returns True if cache has url, False otherwise. Works only for GET request urls

Return type

bool

Parameters

url (Union[str, yarl.URL]) –

is_cacheable(response)

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

Return type

bool

Parameters

response (Optional[Union[aiohttp.client_reqrep.ClientResponse, aiohttp_client_cache.response.CachedResponse]]) –

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

Fetch a cached response based on request info

Parameters
  • method (Optional[str]) – HTTP method

  • url (Union[str, URL, None]) – 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, actions)

Save a response to the cache

Parameters
  • response (ClientResponse) – Response to save

  • actions (CacheActions) – Specific cache actions to take

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 clear()

Delete all items from the cache

async contains(key)

Check if a key is stored in the cache

Return type

bool

Parameters

key (str) –

async delete(key)

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

Parameters

key (str) –

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.

Return type

Union[CachedResponse, str, None]

Parameters

key (str) –

async size()

Get the number of items in the cache

Return type

int

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