Make per-request expiration thread-safe by passing via request headers instead of session attribute, and use Cache-Control request headers by default

2 files changed, 7 insertions, 4 deletions

diff --git a/docs/user_guide/expiration.md b/docs/user_guide/expiration.md
index 6ef3dbf..37bc010 100644
--- a/docs/user_guide/expiration.md
+++ b/docs/user_guide/expiration.md
@@ -16,8 +16,8 @@ reponses:
 Expiration can be set on a per-session, per-URL, or per-request basis, in addition to cache
 headers (see sections below for usage details). When there are multiple values provided for a given
 request, the following order of precedence is used:
-1. Cache-Control request headers (if enabled)
-2. Cache-Control response headers (if enabled)
+1. Cache-Control response headers (if enabled)
+2. Cache-Control request headers
 3. Per-request expiration (`expire_after` argument for {py:meth}`.CachedSession.request`)
 4. Per-URL expiration (`urls_expire_after` argument for {py:class}`.CachedSession`)
 5. Per-session expiration (`expire_after` argument for {py:class}`.CacheBackend`)
diff --git a/docs/user_guide/headers.md b/docs/user_guide/headers.md
index 7aade73..a1c7e2f 100644
--- a/docs/user_guide/headers.md
+++ b/docs/user_guide/headers.md
@@ -32,8 +32,11 @@ True, True
 ```
 
 ## Cache-Control
-If enabled, `Cache-Control` directives will take priority over any other `expire_after` value.
-See {ref}`precedence` for the full order of precedence.
+`Cache-Control` request headers will be used if present. This is mainly useful for patching an
+existing library that sets request headers.
+
+`Cache-Control` response headers are an opt-in feature. If enabled, these will take priority over
+any other `expire_after` values. See {ref}`precedence` for the full order of precedence.
 
 To enable this behavior, use the `cache_control` option:
 ```python