Actions

Internal utilities for determining cache expiration and other cache actions.

class requests_cache.policy.actions.CacheActions(cache_control=False, cache_key=None, expire_after=None, request_directives=NOTHING, skip_read=False, skip_write=False, validation_headers=NOTHING)

Bases: object

A class that translates cache settings and headers into specific actions to take for a given cache item. Actions include:

• Read from the cache

• Write to the cache

• Set cache expiration

• Add headers for conditional requests

If multiple sources provide an expiration time, they will be used in the following order of precedence:

1. Cache-Control request headers

2. Cache-Control response headers (if enabled)

3. Per-request expiration

4. Per-URL expiration

5. Per-session expiration

See Cache Headers for more details about behavior.

Parameters

• cache_control (bool) –

• cache_key (Optional[str]) –

• expire_after (Union[None, int, float, str, datetime, timedelta]) –

• request_directives (Dict[str, str]) –

• skip_read (bool) –

• skip_write (bool) –

• validation_headers (Dict[str, str]) –

cache_control

cache_key

expire_after

property expires

Convert the user/header-provided expiration value to a datetime

Return type

Optional[datetime]

classmethod from_request(cache_key, request, cache_control=False, session_expire_after=None, urls_expire_after=None, request_expire_after=None, **kwargs)

Initialize from request info and cache settings

Parameters

• cache_key (str) –

• request (PreparedRequest) –

• cache_control (bool) –

• session_expire_after (Union[None, int, float, str, datetime, timedelta]) –

• urls_expire_after (Optional[Dict[str, Union[None, int, float, str, datetime, timedelta]]]) –

• request_expire_after (Union[None, int, float, str, datetime, timedelta]) –

request_directives

skip_read

skip_write

update_from_cached_response(response)

Check for relevant cache headers from a cached response, and set headers for a conditional request, if possible.

Used after fetching a cached response, but before potentially sending a new request (if expired).

Parameters

response (CachedResponse) –

update_from_response(response)

Update expiration + actions based on headers from a new response.

Used after receiving a new response but before saving it to the cache.

Parameters

response (Response) –

validation_headers

requests_cache.policy.actions.get_cache_directives(headers)

Get all Cache-Control directives, and handle multiple headers and comma-separated lists

Parameters

headers (Mapping) –

Return type

Dict

requests_cache.policy.actions.get_expiration_datetime(expire_after, ignore_invalid_httpdate=False)

Convert an expiration value in any supported format to an absolute datetime

Parameters

• expire_after (Union[None, int, float, str, datetime, timedelta]) –

• ignore_invalid_httpdate (bool) –

Return type

Optional[datetime]

requests_cache.policy.actions.get_expiration_seconds(expire_after)

Convert an expiration value in any supported format to an expiration time in seconds

Parameters

expire_after (Union[None, int, float, str, datetime, timedelta]) –

Return type

int

requests_cache.policy.actions.get_url_expiration(url, urls_expire_after=None)

Check for a matching per-URL expiration, if any

Parameters

• url (Optional[str]) –

• urls_expire_after (Optional[Dict[str, Union[None, int, float, str, datetime, timedelta]]]) –

Return type

Union[None, int, float, str, datetime, timedelta]