Filesystem#

This backend stores responses in files on the local filesystem (one file per response).

File Formats#

By default, responses are saved as pickle files, since this format is generally the fastest. If you want to save responses in a human-readable format, you can use one of the other available Serializers. For example, to save responses as JSON files:

>>> session = CachedSession('~/http_cache', backend='filesystem', serializer='json')
>>> session.get('https://httpbin.org/get')
>>> print(list(session.cache.paths()))
['/home/user/http_cache/4dc151d95200ec.json']

Or as YAML (requires pyyaml):

>>> session = CachedSession('~/http_cache', backend='filesystem', serializer='yaml')
>>> session.get('https://httpbin.org/get')
>>> print(list(session.cache.paths()))
['/home/user/http_cache/4dc151d95200ec.yaml']

Cache Files#

See Cache Files for general info on specifying cache paths
The path for a given response will be in the format <cache_name>/<cache_key>
Redirects are stored in a separate SQLite database, located at <cache_name>/redirects.sqlite
Use FileCache.paths() to get a list of all cached response paths

API Reference#

`FileCache`	Filesystem backend.
`FileDict`	A dictionary-like interface to files on the local filesystem

class requests_cache.backends.filesystem.FileCache(cache_name='http_cache', use_temp=False, **kwargs)[source]#

Bases: requests_cache.backends.base.BaseCache

Filesystem backend.

Parameters

cache_name (Union[Path, str]) – Base directory for cache files
use_cache_dir – Store datebase in a user cache directory (e.g., ~/.cache/)
use_temp (bool) – Store cache files in a temp directory (e.g., /tmp/http_cache/). Note: if cache_name is an absolute path, this option will be ignored.
extension – Extension for cache files. If not specified, the serializer default extension will be used.

bulk_delete(keys)#

Remove multiple responses and their associated redirects from the cache

Parameters: keys (Iterable[str]) –

property cache_dir#

Base directory for cache files

Return type: Path

clear()[source]#: Clear the cache

create_key(request=None, **kwargs)#

Create a normalized cache key from a request object

Parameters: request (Union[Request, PreparedRequest, CachedRequest, None]) –
Return type: str

delete(key)#

Delete a response or redirect from the cache, as well any associated redirect history

Parameters: key (str) –

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

Delete a cached response for the specified request

Parameters

url (str) –
method (str) –

delete_urls(urls, method='GET', **kwargs)#

Delete all cached responses for the specified requests

Parameters

urls (Iterable[str]) –
method (str) –

get_response(key, default=None)#

Retrieve a response from the cache, if it exists

Parameters

key (str) – Cache key for the response
default – Value to return if key is not in the cache

Return type

Optional[CachedResponse]

has_key(key)#

Returns True if key is in the cache

Parameters: key (str) –
Return type: bool

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

Returns True if the specified request is cached

Parameters

url (str) –
method (str) –

Return type

bool

keys(check_expiry=False)#

Get all cache keys for redirects and valid responses combined

Return type: Iterator[str]

paths()[source]#

Get absolute file paths to all cached responses

Return type: Iterator[Path]

remove_expired_responses(*args, **kwargs)[source]#

Remove expired and invalid responses from the cache, optionally with revalidation

Parameters: expire_after – A new expiration time used to revalidate the cache

response_count(check_expiry=False)#

Get the number of responses in the cache, excluding invalid (unusable) responses. Can also optionally exclude expired responses.

Return type: int

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

Save a response to the cache

Parameters

cache_key (Optional[str]) – Cache key for this response; will otherwise be generated based on request
response (Union[Response, CachedResponse]) – Response to save
expires (Optional[datetime]) – Absolute expiration time for this response

update(other)#

Update this cache with the contents of another cache

Parameters: other (BaseCache) –

property urls#

Get all URLs currently in the cache (excluding redirects)

Return type: Iterator[str]

values(check_expiry=False)#

Get all valid response objects from the cache

Return type: Iterator[CachedResponse]

class requests_cache.backends.filesystem.FileDict(cache_name, use_temp=False, use_cache_dir=False, extension=None, **kwargs)[source]#

Bases: requests_cache.backends.base.BaseStorage

A dictionary-like interface to files on the local filesystem

Parameters

cache_name (Union[Path, str]) –
use_temp (bool) –
use_cache_dir (bool) –
extension (Optional[str]) –

bulk_delete(keys)#

Delete multiple keys from the cache, without raising errors for missing keys. This is a naive implementation that subclasses should override with a more efficient backend-specific implementation, if possible.

Parameters: keys (Iterable[str]) –

clear() → None. Remove all items from D.[source]#

get(k[, d]) → D[k] if k in D, else d. d defaults to None.#

items() → a set-like object providing a view on D's items#

keys() → a set-like object providing a view on D's keys[source]#

paths()[source]#

Get absolute file paths to all cached responses

Return type: Iterator[Path]

pop(k[, d]) → v, remove specified key and return the corresponding value.#: If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair#: as a 2-tuple; but raise KeyError if D is empty.

property serializer#

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D#

update([E, ]**F) → None. Update D from mapping/iterable E and F.#: If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values#