Requests Cache

Warnings

• breaking Prior to version 1.0, cache settings could sometimes be modified directly on `CachedSession` or `BaseCache`. As of 1.0, settings can only be accessed and modified via `CachedSession.settings` after initialization.
  Fix: Access and modify cache settings exclusively through `session.settings` attribute, e.g., `session.settings.expire_after = 7200`.
• breaking For users of the DynamoDB backend, the table structure changed in version 1.0. Upgrading to 1.0 requires creating a new DynamoDB table, as existing tables are incompatible.
  Fix: Create a new DynamoDB table when upgrading if you are using the DynamoDB backend. Refer to the DynamoDB backend documentation for details.
• breaking Responses cached with `requests-cache` versions prior to 0.6.0 are invalid due to serialization format changes. These old responses will be treated as expired and automatically re-fetched.
  Fix: No direct fix needed; old entries will be re-fetched. Users can manually clear the cache (`session.cache.clear()`) or convert old cache formats if supported by specific minor versions (check historical changelogs).
• gotcha The global patching method (`requests_cache.install_cache()`) has limitations and can lead to unexpected behavior, especially in multi-threaded/multiprocess applications, when used with other `requests`-patching libraries, or in larger applications where cache behavior might not be obvious across modules. Using `CachedSession` is generally recommended.
  Fix: Prefer `requests_cache.CachedSession` over `requests_cache.install_cache()` for explicit control over caching behavior.
• gotcha The core `requests` library does not natively cache HTTP responses. Users expecting caching behavior without `requests-cache` (or similar) will not get it. When using `requests-cache`, not explicitly calling `clear()` or misconfiguring `expire_after` are common mistakes for managing data freshness.
  Fix: Always use `requests_cache.CachedSession` or `requests_cache.install_cache()` for HTTP response caching. Explicitly manage cache entries using `session.cache.clear()` or `expire_after` settings for desired data freshness.

Install

• pip install requests-cache Install stable version

Imports

• CachedSession

  from requests_cache import CachedSession

  Official documentation recommends importing directly from the top-level `requests_cache` package.
• install_cache

  from requests_cache import install_cache

Quickstart

The most common and recommended way to use `requests-cache` is by creating a `CachedSession` instance, which acts as a direct replacement for `requests.Session`. This example demonstrates making a request, observing it being cached, and then retrieving it from the cache instantly on a subsequent call. It also shows how to clear the cache.

import requests_cache
import requests

# Use CachedSession as a drop-in replacement for requests.Session
session = requests_cache.CachedSession('demo_cache', expire_after=3600)

# Make a request; it will be cached
response1 = session.get('https://httpbin.org/delay/1')
print(f"First request (from cache: {response1.from_cache}): {response1.status_code}")

# Make the same request again; it will be loaded from cache instantly
response2 = session.get('https://httpbin.org/delay/1')
print(f"Second request (from cache: {response2.from_cache}): {response2.status_code}")

# Example for global patching (less recommended for complex apps)
# requests_cache.install_cache('global_cache', expire_after=3600)
# response3 = requests.get('https://httpbin.org/delay/1')
# print(f"Third request (from cache: {getattr(response3, 'from_cache', False)}): {response3.status_code}")

# Clear the cache
session.cache.clear()
print("Cache cleared.")