Cache Headers#
Most common request and response headers related to caching are supported, including Cache-Control and ETags.
Note
requests-cache is not (yet) intended to be strict implementation of HTTP caching according to RFC 2616, RFC 7234, etc. If there is additional behavior you would like to see, please create an issue to request it.
Conditional Requests#
Conditional requests are automatically sent for any servers that support them. Once a cached response expires, it will only be updated if the remote content has changed.
Here’s an example using the GitHub API to get info about the requests-cache repo:
>>> # Cache a response that will expire immediately
>>> url = 'https://api.github.com/repos/requests-cache/requests-cache'
>>> session = CachedSession(expire_after=0.0001)
>>> session.get(url)
>>> time.sleep(0.0001)
>>> # The cached response will still be used until the remote content actually changes
>>> response = session.get(url)
>>> print(response.from_cache, response.is_expired)
True, True
Cache-Control#
Cache-Control
request headers will always be used if present. This is mainly useful if you are
adding requests-cache to an existing application or library that already uses caching request headers.
Cache-Control
response headers are an opt-in feature. If enabled, these will take priority over
any other expire_after
values. See Expiration Precedence for the full order of precedence.
To enable this behavior, use the cache_control
option:
>>> session = CachedSession(cache_control=True)
Supported Headers#
The following headers are currently supported:
Request headers:
Cache-Control: max-age
: Used as the expiration time in secondsCache-Control: no-cache
: Skip reading from the cacheCache-Control: no-store
: Skip reading from and writing to the cacheIf-None-Match
: Automatically added if anETag
is availableIf-Modified-Since
: Automatically added ifLast-Modified
is available
Response headers:
Cache-Control: max-age
: Used as the expiration time in secondsCache-Control: no-store
Skip writing to the cacheCache-Control: immutable
: Cache the response with no expirationExpires
: Used as an absolute expiration timeETag
: Return expired cache data if the remote content has not changed (304 Not Modified
response)Last-Modified
: Return expired cache data if the remote content has not changed (304 Not Modified
response)