cache_control

Summary

CacheActions([key, expire_after, skip_read, …])

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(key=None, expire_after=None, skip_read=False, skip_write=False, revalidate=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
Return type

None

expire_after
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, request_expire_after=None, session_expire_after=None, urls_expire_after=None, **kwargs)

Initialize from CacheBackend settings

Parameters
key
revalidate
skip_read
skip_write
update_from_response(response)

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

Parameters

response (aiohttp.client_reqrep.ClientResponse) –

coalesce(*values, default=None)

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

Return type

Any

Parameters

values (Any) –

get_cache_directives(headers)

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

Return type

Dict

Parameters

headers (Mapping) –

get_expiration_datetime(expire_after)

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

Return type

Optional[datetime]

Parameters

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

get_url_expiration(url, urls_expire_after=None)

Check for a matching per-URL expiration, if any

Return type

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

Parameters
has_cache_headers(headers)

Determine if headers contain cache directives that we currently support

Return type

bool

Parameters

headers (Mapping) –

parse_http_date(value)

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

Return type

Optional[datetime]

Parameters

value (str) –

split_kv_directive(header_value)

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

Return type

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

Parameters

header_value (str) –

to_utc(dt)

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

Parameters

dt (datetime.datetime) –

try_int(value)

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

Return type

Optional[int]

Parameters

value (Optional[str]) –

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