Actions

class requests_cache.policy.actions.CacheActions(cache_key=None, error_504=False, expire_after=None, send_request=False, resend_request=False, resend_async=False, skip_read=False, skip_write=False, vary_cache_key=None, directives=None, settings=None, only_if_cached=False, refresh=False, request=None, stale_if_error=None, stale_while_revalidate=None, validation_headers=NOTHING)

Bases: RichMixin

Translates cache settings and headers into specific actions to take for a given cache item.

The resulting actions are then handled in CachedSession.send().

Notes

• See Expiration Precedence for behavior if multiple sources provide an expiration

• See Cache Headers for more details about header behavior

• The following arguments/properties are the outputs of this class:

Parameters:

• cache_key (str) – The cache key created based on the initial request

• error_504 (bool) – Indicates the request cannot be fulfilled based on cache settings

• expire_after (Union[None, int, float, str, datetime, timedelta]) – User or header-provided expiration value

• send_request (bool) – Send a new request

• resend_request (bool) – Send a new request to refresh a stale cache item

• resend_async (bool) – Return a stale cache item, and send a non-blocking request to refresh it

• skip_read (bool) – Skip reading from the cache

• skip_write (bool) – Skip writing to the cache

• vary_cache_key (Optional[str])

• directives (CacheDirectives)

• settings (CacheSettings)

• only_if_cached (bool)

• refresh (bool)

• request (PreparedRequest)

• stale_if_error (Union[bool, None, int, float, str, datetime, timedelta])

• stale_while_revalidate (Union[bool, None, int, float, str, datetime, timedelta])

• validation_headers (Dict[str, str])

cache_key: str

error_504: bool

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

property expires: datetime | None

Convert the user/header-provided expiration value to a datetime. Applies to new cached responses, and previously cached responses that are being revalidated.

classmethod from_request(cache_key, request, settings=None)

Initialize from request info and cache settings.

Note on refreshing: must-revalidate isn’t a standard request header, but is used here to indicate a user-requested refresh. Typically that’s only used in response headers, and max-age=0 would be used by a client to request a refresh. However, this would conflict with the expire_after option provided in CachedSession.request().

Parameters:

• cache_key (str) – The cache key created based on the initial request

• request (PreparedRequest) – The outgoing request

• settings (Optional[CacheSettings]) – Session-level cache settings

is_usable(cached_response, error=False)

Determine whether a given cached response is “fresh enough” to satisfy the request, based on:

• min-fresh

• max-stale

• stale-if-error (if an error has occurred)

• stale-while-revalidate

Parameters:

• cached_response (Optional[CachedResponse])

• error (bool)

resend_async: bool

resend_request: bool

send_request: bool

skip_read: bool

skip_write: bool

update_from_cached_response(cached_response, create_key=None, **key_kwargs)

Determine if we can reuse a cached response, or set headers for a conditional request if possible.

Used after fetching a cached response, but before potentially sending a new request.

Parameters:

• cached_response (Optional[CachedResponse]) – Cached response to examine

• create_key (Optional[Callable[..., str]]) – Cache key function, used for validating Vary headers

• key_kwargs – Additional keyword arguments for create_key.

update_from_response(response)

Update expiration + actions based on headers and other details from a new response.

Used after receiving a new response, but before saving it to the cache.

Parameters:

response (Response)

update_request(request)

Apply validation headers (if any) before sending a request

Parameters:

request (PreparedRequest)

Return type:

PreparedRequest

update_revalidated_response(response, cached_response)

After revalidation, update the cached response’s expiration and headers

Parameters:

• response (Response)

• cached_response (CachedResponse)

Return type:

CachedResponse

vary_cache_key: Optional[str]