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[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

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(expire_after=None)¶

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

Parameters: expire_after (Union[None, int, float, str, datetime, timedelta]) – 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
expire_after – Time in seconds until this cache item should expire
expires (Optional[datetime]) –

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.

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¶