Add support for Cache-Control: only-if-cached and corresponding options for request() and send()

2 files changed, 57 insertions, 0 deletions

diff --git a/docs/user_guide/expiration.md b/docs/user_guide/expiration.md
index ef0e6b3..5c81ef0 100644
--- a/docs/user_guide/expiration.md
+++ b/docs/user_guide/expiration.md
@@ -117,3 +117,57 @@ You can also apply a new `expire_after` value to previously cached responses:
 ```python
 >>> session.remove_expired_responses(expire_after=timedelta(days=30))
 ```
+
+## Request Options
+In addition to the base arguments for {py:func}`requests.request`, requests-cache adds some extra
+cache-related arguments. These apply to {py:meth}`.CachedSession.request`,
+{py:meth}`.CachedSession.send`, and all HTTP method-specific functions (`get()`, `post()`, etc.).
+
+### Per-Request Expiration
+The `expire_after` argument can be used to override the session's expiration for a single request.
+```python
+>>> session = CachedSession(expire_after=300)
+>>> # This request will be cached for 60 seconds, not 300
+>>> session.get('http://httpbin.org/get', expire_after=60)
+```
+
+### Manual Refresh
+If you want to manually refresh a response before it expires, you can use the `refresh` argument.
+This will always send a new request, and ignore and overwrite any previously cached response. The
+response will be saved with a new expiration time, according to the normal expiration rules described above.
+```python
+>>> response = session.get('http://httpbin.org/get')
+>>> response = session.get('http://httpbin.org/get', refresh=True)
+>>> assert response.from_cache is False
+```
+
+A related argument is `revalidate`, which is basically a "soft refresh." It will send a quick
+{ref}`conditional request <conditional-requests>` to the server, and use the cached response if the
+remote content has not changed. If the cached response does not contain validation headers, this
+option will have no effect.
+
+### Cache-Only Requests
+If you want to only use cached responses without making any real requests, you can use the
+`only_if_cached` option. This essentially uses your cache in "offline mode". If a response isn't
+cached or is expired, you will get a `504 Not Cached` response instead.
+```python
+>>> session = CachedSession()
+>>> session.cache.clear()
+>>> response = session.get('http://httpbin.org/get', only_if_cached=True)
+>>> print(response.status_code)
+504
+>>> response.raise_for_status()
+HTTPError: 504 Server Error: Not Cached for url: http://httpbin.org/get
+```
+
+You can also combine this with `stale_if_error` to return cached responses even if they are expired.
+```python
+>>> session = CachedSession(expire_after=1, stale_if_error=True)
+>>> session.get('http://httpbin.org/get')
+>>> time.sleep(1)
+
+>>> # The response will be cached but expired by this point
+>>> response = session.get('http://httpbin.org/get', only_if_cached=True)
+>>> print(response.status_code)
+200
+```
diff --git a/docs/user_guide/headers.md b/docs/user_guide/headers.md
index ecc95c1..1dccde6 100644
--- a/docs/user_guide/headers.md
+++ b/docs/user_guide/headers.md
@@ -11,6 +11,7 @@ requests-cache is not (yet) intended to be strict implementation of HTTP caching
 would like to see, please create an issue to request it.
 ```
 
+(conditional-requests)=
 ## Conditional Requests
 [Conditional requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests) are
 automatically sent for any servers that support them. Once a cached response expires, it will only
@@ -49,6 +50,8 @@ The following headers are currently supported:
 - `Cache-Control: max-age`: Used as the expiration time in seconds
 - `Cache-Control: no-cache`: Revalidate with the server before using a cached response
 - `Cache-Control: no-store`: Skip reading from and writing to the cache
+- `Cache-Control: only-if-cached`: Only return results from the cache. If not cached, return a 504
+  response instead of sending a new request. Note that this may return a stale response.
 - `If-None-Match`: Automatically added for revalidation, if an `ETag` is available
 - `If-Modified-Since`: Automatically added for revalidation, if `Last-Modified` is available