Utility Modules

Cache Keys

requests_cache.cache_keys.create_key(request, ignored_params=None, include_get_headers=False, **kwargs)[source]

Create a normalized cache key from a request object

Return type

str

requests_cache.cache_keys.decode(value, encoding='utf-8')[source]

Decode a value from bytes, if hasn’t already been. Note: PreparedRequest.body is always encoded in utf-8.

Return type

str

requests_cache.cache_keys.encode(value, encoding='utf-8')[source]

Encode a value to bytes, if it hasn’t already been

Return type

bytes

requests_cache.cache_keys.normalize_dict(items, normalize_data=True)[source]

Sort items in a dict

Parameters
Return type

Union[Mapping, str, bytes, None]

requests_cache.cache_keys.remove_ignored_headers(headers, ignored_parameters)[source]

Remove any ignored request headers

Return type

CaseInsensitiveDict

requests_cache.cache_keys.remove_ignored_url_params(url, ignored_parameters)[source]

Remove any ignored request parameters from the URL

Return type

str

Cache-Control

Utilities for determining cache expiration and other cache actions

class requests_cache.cache_control.CacheActions(cache_key, request, cache_control=False, **kwargs)[source]

A dataclass that contains info on specific actions to take for a given cache item. This is determined by a combination of cache 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

property expires: Optional[datetime.datetime]

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

Return type

Optional[datetime]

update_from_response(response)[source]

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

requests_cache.cache_control.coalesce(*values, default=None)[source]

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

Return type

Any

requests_cache.cache_control.get_cache_directives(headers)[source]

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

Return type

Dict

requests_cache.cache_control.get_expiration_datetime(expire_after)[source]

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

Return type

Optional[datetime]

requests_cache.cache_control.get_url_expiration(url, urls_expire_after=None)[source]

Check for a matching per-URL expiration, if any

Return type

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

requests_cache.cache_control.has_cache_headers(headers)[source]

Determine if headers contain cache directives that we currently support

Return type

bool

requests_cache.cache_control.parse_http_date(value)[source]

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

Return type

Optional[datetime]

requests_cache.cache_control.split_kv_directive(header_value)[source]

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

requests_cache.cache_control.to_utc(dt)[source]

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

requests_cache.cache_control.try_int(value)[source]

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

Return type

Optional[int]

requests_cache.cache_control.url_match(url, pattern)[source]

Determine if a URL matches a pattern

Parameters

  • url (str) – 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

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