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

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

async _get_redirect_response(key)

Get the response referenced by a redirect key, if available

Return type

Optional[CachedResponse]

Parameters

key (str) –

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

Return type

Optional[CachedResponse]

Parameters

key (str) –

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

Return type

bool

Parameters
is_cacheable(response, actions=None)

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

Return type

bool

Parameters
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, actions)

Save a response to the cache

Parameters
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

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) –

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.

Return type

Union[CachedResponse, str, None]

Parameters

key (str) –

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