Cache Control

Internal utilities for determining cache expiration and other cache actions.

CacheActions

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

coalesce	Get the first non-None value in a list of values
get_cache_directives	Get all Cache-Control directives, and handle multiple headers and comma-separated lists
get_expiration_datetime	Convert an expiration value in any supported format to an absolute datetime
get_url_expiration	Check for a matching per-URL expiration, if any
has_cache_headers	Determine if headers contain supported cache directives
parse_http_date	Attempt to parse an HTTP (RFC 5322-compatible) timestamp
split_kv_directive	Split a cache directive into a (header_value, int) key-value pair, if possible; otherwise just (header_value, True).
to_utc	All internal datetimes are UTC and timezone-naive.
try_int	Convert a string value to an int, if possible, otherwise None
url_match	Determine if a URL matches a pattern

class requests_cache.cache_control.CacheActions(cache_control=False, cache_key=None, expire_after=None, request_headers=NOTHING, skip_read=False, skip_write=False)

Bases: object

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

• Reading from the cache

• Writing to the cache

• Setting cache expiration

• Adding request headers

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

1. Cache-Control request headers (if enabled)

2. Cache-Control response headers (if enabled)

3. Per-request expiration

4. Per-URL expiration

5. Per-session expiration

Parameters

• cache_control (bool) –

• cache_key (Optional[str]) –

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

• request_headers (Dict[str, str]) –

• skip_read (bool) –

• skip_write (bool) –

cache_control

cache_key

expire_after

property expires

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

Return type

Optional[datetime]

classmethod from_headers(cache_key, headers)

Initialize from request headers

Parameters

• cache_key (str) –

• headers (Mapping) –

classmethod from_request(cache_key, request, cache_control=False, **kwargs)

Initialize from request info and cache settings

Parameters

• cache_key (str) –

• request (PreparedRequest) –

• cache_control (bool) –

classmethod from_settings(cache_key, url=None, cache_control=True, request_expire_after=None, session_expire_after=None, urls_expire_after=None, **kwargs)

Initialize from cache settings

Parameters

• cache_key (str) –

• url (Optional[str]) –

• cache_control (bool) –

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

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

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

request_headers

skip_read

skip_write

update_from_cached_response(response)

Used after fetching a cached response, but before potentially sending a new request. Check for relevant cache headers on a cached response, and set corresponding request headers.

Parameters

response (CachedResponse) –

update_from_response(response)

Used after receiving a new response but before saving it to the cache. Update expiration + actions based on response headers, if not previously set.

Parameters

response (Response) –

requests_cache.cache_control.coalesce(*values, default=None)

Get the first non-None value in a list of values

Parameters

values (Any) –

Return type

Any

requests_cache.cache_control.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.cache_control.get_expiration_datetime(expire_after)

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

Parameters

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

Return type

Optional[datetime]

requests_cache.cache_control.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]

requests_cache.cache_control.has_cache_headers(headers)

Determine if headers contain supported cache directives

Parameters

headers (Mapping) –

Return type

bool

requests_cache.cache_control.parse_http_date(value)

Attempt to parse an HTTP (RFC 5322-compatible) timestamp

Parameters

value (str) –

Return type

Optional[datetime]

requests_cache.cache_control.split_kv_directive(header_value)

Split a cache directive into a (header_value, int) key-value pair, if possible; otherwise just (header_value, True).

Parameters

header_value (str) –

Return type

Tuple[str, Union[None, int, bool]]

requests_cache.cache_control.to_utc(dt)

All internal datetimes are UTC and timezone-naive. Convert any user/header-provided datetimes to the same format.

Parameters

dt (datetime) –

requests_cache.cache_control.try_int(value)

Convert a string value to an int, if possible, otherwise None

Parameters

value (Optional[str]) –

Return type

Optional[int]

requests_cache.cache_control.url_match(url, pattern)

Determine if a URL matches a pattern

Parameters

• url (str) – URL to test. Its base URL (without protocol) will be used.

• pattern (str) – Glob pattern to match against. A recursive wildcard will be added if not present

Example

>>> url_match('https://httpbin.org/delay/1', 'httpbin.org/delay')
True
>>> url_match('https://httpbin.org/stream/1', 'httpbin.org/*/1')
True
>>> url_match('https://httpbin.org/stream/2', 'httpbin.org/*/1')
False

Return type

bool