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
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).
to_utc(dt)	"All internal datetimes are UTC and timezone-naive.
try_int(value)	Convert a string value to an int, if possible, otherwise None
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 (Optional[str]) –

• revalidate (bool) –

• skip_read (bool) –

• skip_write (bool) –

Return type

None

cache_control: bool

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

property expires: Optional[datetime.datetime]

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

Return type

Optional[datetime]

classmethod from_headers(key, headers)

Initialize from request headers

Parameters

• key (str) –

• headers (Mapping) –

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

Initialize from request info and CacheBackend settings

Parameters

• key (str) –

• cache_control (bool) –

• headers (Optional[Mapping]) –

classmethod from_settings(key, url, cache_control=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) –

• 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) –

coalesce(*values, default=None)

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

Parameters

values (Any) –

Return type

Any

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

to_utc(dt)

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

Parameters

dt (datetime) –

try_int(value)

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

Parameters

value (Optional[str]) –

Return type

Optional[int]

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

Return type

bool

Parameters

• url (Union[str, yarl.URL]) –

• pattern (str) –