Filesystem

../_images/files-generic.png

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