cache_control

Summary

CacheActions([cache_control, expire_after, ...])

A dataclass that contains info on specific actions to take for a given cache item.

coalesce(*values[, default])	Get the first non-None value in a list of values
compose_refresh_headers(request_headers, ...)	Returns headers containing directives for conditional requests if the cached headers support it
convert_to_utc_naive(dt)	All internal datetimes are UTC and timezone-naive.
get_cache_directives(headers)	Get all Cache-Control directives, and handle multiple headers and comma-separated lists
get_expiration_datetime(expire_after)	Convert an expiration value in any supported format to an absolute datetime
get_url_expiration(url[, urls_expire_after])	Check for a matching per-URL expiration, if any
has_cache_headers(headers)	Determine if headers contain cache directives that we currently support
parse_http_date(value)	Attempt to parse an HTTP (RFC 5322-compatible) timestamp
split_kv_directive(header_value)	Split a cache directive into a (header_value, int) key-value pair, if possible; otherwise just (header_value, True).
try_int(value)
url_match(url, pattern)	Determine if a URL matches a pattern

Module Contents

Utilities for determining cache expiration and other cache actions

class CacheActions(cache_control=False, expire_after=None, key=None, revalidate=False, skip_read=False, skip_write=False)

Bases: object

A dataclass that contains info on specific actions to take for a given cache item. This is determined by a combination of CacheBackend settings and request + response headers. If multiple sources are provided, 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) –

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

• key (str) –

• revalidate (bool) –

• skip_read (bool) –

• skip_write (bool) –

cache_control: bool

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

property expires: datetime | None

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

classmethod from_headers(key, headers)

Initialize from request headers

Parameters:

• key (str) –

• headers (Mapping) –

classmethod from_request(key, cache_control=False, cache_disabled=False, refresh=False, headers=None, **kwargs)

Initialize from request info and CacheBackend settings

Parameters:

• key (str) –

• cache_control (bool) –

• cache_disabled (bool) –

• refresh (bool) –

• headers (Optional[Mapping]) –

classmethod from_settings(key, url, cache_control=False, refresh=False, request_expire_after=None, session_expire_after=None, urls_expire_after=None, **kwargs)

Initialize from CacheBackend settings

Parameters:

• key (str) –

• url (Union[str, URL]) –

• cache_control (bool) –

• refresh (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]]]) –

key: str

revalidate: bool

skip_read: bool

skip_write: bool

update_from_response(response)

Update expiration + actions based on response headers, if not previously set by request

Parameters:

response (ClientResponse) –

_(value)

Parameters:

value (str) –

coalesce(*values, default=None)

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

Parameters:

values (Any) –

Return type:

Any

compose_refresh_headers(request_headers, cached_headers)

Returns headers containing directives for conditional requests if the cached headers support it

Parameters:

• request_headers (Optional[Mapping]) –

• cached_headers (Mapping) –

Return type:

tuple[bool, Mapping]

convert_to_utc_naive(dt)

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

Parameters:

dt (datetime) –

get_cache_directives(headers)

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

Parameters:

headers (Mapping) –

Return type:

dict

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]

get_url_expiration(url, urls_expire_after=None)

Check for a matching per-URL expiration, if any

Parameters:

• url (Union[str, URL]) –

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

Return type:

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

has_cache_headers(headers)

Determine if headers contain cache directives that we currently support

Parameters:

headers (Mapping) –

Return type:

bool

parse_http_date(value)

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

Parameters:

value (str) –

Return type:

Optional[datetime]

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

try_int(value)

url_match(url, pattern)

Determine if a URL matches a pattern

Parameters:

• url (Union[str, URL]) – 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

Return type:

bool

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