diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/user_guide/expiration.md | 23 | ||||
-rw-r--r-- | docs/user_guide/headers.md | 8 |
2 files changed, 30 insertions, 1 deletions
diff --git a/docs/user_guide/expiration.md b/docs/user_guide/expiration.md index ab79b24..b0628fb 100644 --- a/docs/user_guide/expiration.md +++ b/docs/user_guide/expiration.md @@ -120,6 +120,29 @@ In addition to HTTP error codes, `stale_if_error` also applies to python excepti [Errors and Exceptions](https://2.python-requests.org/en/master/user/quickstart/#errors-and-exceptions) for more details on request errors in general. +(stale-while-revalidate)= +## Asynchronous Revalidation +You can use the `stale_while_revalidate` option to improve performance when refreshing responses. +This will cause an expired cached response to be returned initially, while a non-blocking request is +sent to refresh the response for the next time it's requested. + +```{note} +While the corresponding response header `Cache-Control: stale-while-revalidate` only applies to +{ref}`conditional-requests`, requests-cache extends this behavior to other refresh requests as well +(even if a validator is not available). +``` + +You may either set this to `True` to do this regardless of the cached response's age: +```python +session = CachedSession(stale_while_revalidate=True) +``` + +Or specify a maximum staleness value you are willing to accept: +```python +# Use a cached response while revalidating, if it expired 5 minutes ago or less +session = CachedSession(stale_while_revalidate=timedelta(minutes=5)) +``` + ## Removing Expired Responses ### Manual Removal diff --git a/docs/user_guide/headers.md b/docs/user_guide/headers.md index 0ce1ee4..3b3e8e9 100644 --- a/docs/user_guide/headers.md +++ b/docs/user_guide/headers.md @@ -26,6 +26,10 @@ requests-cache repo: True ``` +```{note} +Also see {ref}`stale-while-revalidate` for a variation of this behavior. +``` + ## 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 sends requests with cache @@ -62,11 +66,13 @@ The following headers are currently supported: - `If-Modified-Since`: Automatically added for revalidation, if `Last-Modified` is available **Response headers:** +- `Cache-Control: immutable`: Cache the response with no expiration - `Cache-Control: max-age`: Used as the expiration time in seconds - `Cache-Control: must-revalidate`: When used in combination with `max-age=0`, revalidate immediately. - `Cache-Control: no-cache`: Revalidate with the server before using a cached response - `Cache-Control: no-store` Skip writing to the cache -- `Cache-Control: immutable`: Cache the response with no expiration +- `Cache-Control: stale-if-error`: Same behavior as request header +- `Cache-Control: stale-while-revalidate`: If expired by less than this many seconds, return the stale response immediately and send an asynchronous revalidation request - `Expires`: Used as an absolute expiration datetime - `ETag`: Validator used for conditional requests - `Last-Modified`: Validator used for conditional requests |