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
`utcnow`()	Get the current time in UTC, as a timezone-naive datetime

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:

Cache-Control request headers (if enabled)
Cache-Control response headers (if enabled)
Per-request expiration
Per-URL expiration
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 (Mapping | None)

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 (dict[str, Union[None, int, float, str, datetime, timedelta]] | None)

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

compose_refresh_headers(request_headers, cached_headers)¶

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

Parameters:

request_headers (Mapping | None)
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:: datetime | None

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 (dict[str, Union[None, int, float, str, datetime, timedelta]] | None)

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:: datetime | None

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

utcnow()¶

Get the current time in UTC, as a timezone-naive datetime

Return type:: datetime