or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

backends.mdexpiration.mdindex.mdmodels.mdpatching.mdserialization.mdsessions.md
tile.json

tessl/pypi-requests-cache

A persistent cache for python requests

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/requests-cache@1.2.x

To install, run

npx @tessl/cli install tessl/pypi-requests-cache@1.2.0

index.mddocs/

Requests-Cache

A persistent cache for Python requests that enables transparent HTTP response caching with multiple storage backends, flexible expiration policies, and seamless integration with existing requests-based code.

Package Information

  • Package Name: requests-cache
  • Language: Python
  • Installation: pip install requests-cache

Core Imports

import requests_cache

For drop-in session replacement:

from requests_cache import CachedSession

For global monkey-patching:

from requests_cache import install_cache, uninstall_cache

Basic Usage

import requests_cache

# Option 1: Use CachedSession as drop-in replacement for requests.Session
session = requests_cache.CachedSession('demo_cache')
response = session.get('https://httpbin.org/get')
print(f"From cache: {response.from_cache}")

# Option 2: Global monkey-patch for all requests functions
requests_cache.install_cache('demo_cache')
import requests
response = requests.get('https://httpbin.org/get')
print(f"From cache: {response.from_cache}")

# Configure expiration and backends
session = requests_cache.CachedSession(
    cache_name='my_cache',
    backend='sqlite',
    expire_after=300,  # 5 minutes
    allowable_codes=[200, 404],
    allowable_methods=['GET', 'POST']
)

Architecture

Requests-cache implements a layered architecture:

  • Session Layer: CachedSession and CacheMixin provide the main user interface, extending requests.Session with caching capabilities
  • Backend Layer: Multiple storage backends (SQLite, Redis, MongoDB, DynamoDB, Filesystem, Memory) handle response persistence
  • Policy Layer: Cache settings, expiration patterns, and HTTP header processing determine caching behavior
  • Serialization Layer: Multiple serializers (pickle, JSON, YAML, BSON) handle response data conversion
  • Key Generation: Normalizes requests into cache keys for consistent matching and retrieval

This design enables transparent drop-in replacement for existing requests code while providing extensive customization for advanced use cases.

Capabilities

Session-Based Caching

The primary interface for caching with full control over cache settings, expiration policies, and backends. Provides a drop-in replacement for requests.Session with transparent caching capabilities.

class CachedSession:
    def __init__(
        self,
        cache_name: str = 'http_cache',
        backend: Optional[BackendSpecifier] = None,
        serializer: Optional[SerializerType] = None,
        expire_after: ExpirationTime = -1,
        **kwargs
    ): ...

class CacheMixin:
    @classmethod
    def wrap(cls, original_session: Session, **kwargs) -> 'CacheMixin': ...
    def cache_disabled(self): ...

Session-Based Caching

Global Monkey-Patching

Functions to globally patch the requests library, enabling caching for all requests functions without code changes. Includes context managers for temporary caching control.

def install_cache(
    cache_name: str = 'http_cache',
    backend: Optional[BackendSpecifier] = None,
    **kwargs
): ...

def uninstall_cache(): ...

def enabled(*args, **kwargs): ...

def disabled(): ...

def get_cache() -> Optional[BaseCache]: ...

def is_installed() -> bool: ...

def clear(): ...

def delete(*args, **kwargs): ...

Global Monkey-Patching

Cache Backends

Multiple storage backends for different use cases, from simple in-memory caching to distributed storage solutions. Each backend provides consistent interfaces while optimizing for specific storage characteristics.

class SQLiteCache: ...
class RedisCache: ... 
class MongoCache: ...
class GridFSCache: ...
class FileCache: ...
class DynamoDbCache: ...

def init_backend(
    cache_name: str,
    backend: Optional[BackendSpecifier] = None,
    **kwargs
) -> BaseCache: ...

Cache Backends

Cache Policy and Expiration

Flexible expiration policies supporting HTTP Cache-Control headers, URL-specific patterns, and custom logic. Includes support for conditional requests, stale-if-error patterns, and cache validation.

class CacheSettings: ...
class CacheActions: ...
class CacheDirectives: ...

def get_expiration_datetime(expire_after: ExpirationTime) -> Optional[datetime]: ...
def get_url_expiration(url: str, urls_expire_after: ExpirationPatterns) -> ExpirationTime: ...

ExpirationTime = Union[None, int, float, str, datetime, timedelta]
ExpirationPatterns = Dict[ExpirationPattern, ExpirationTime]

Cache Policy and Expiration

Response and Request Models

Cached response and request objects that maintain compatibility with the requests library while adding cache-specific metadata and functionality.

class CachedResponse:
    @property
    def from_cache(self) -> bool: ...
    @property 
    def is_expired(self) -> bool: ...
    def is_older_than(self, time: ExpirationTime) -> bool: ...

class CachedRequest: ...
class OriginalResponse: ...

AnyResponse = Union[OriginalResponse, CachedResponse]

Response and Request Models

Serialization

Multiple serialization options for storing response data, including secure pickle variants, JSON with binary support, YAML, and BSON formats optimized for different storage backends.

class SerializerPipeline: ...
class Stage: ...

def init_serializer(
    serializer: Optional[SerializerType],
    decode_content: bool
) -> Optional[SerializerPipeline]: ...

# Available serializers
pickle_serializer: SerializerPipeline
json_serializer: SerializerPipeline
yaml_serializer: SerializerPipeline
bson_serializer: SerializerPipeline

Serialization

Types

# Backend types
BackendSpecifier = Union[str, BaseCache]
StrOrPath = Union[Path, str]

# Expiration types  
ExpirationTime = Union[None, int, float, str, datetime, timedelta]
ExpirationPattern = Union[str, Pattern]
ExpirationPatterns = Dict[ExpirationPattern, ExpirationTime]

# Callback types
FilterCallback = Callable[[Response], bool]
KeyCallback = Callable[..., str]

# Serializer types
SerializerType = Union[str, SerializerPipeline, Stage]

# Response types
AnyResponse = Union[OriginalResponse, CachedResponse]
AnyRequest = Union[Request, PreparedRequest, CachedRequest]
AnyPreparedRequest = Union[PreparedRequest, CachedRequest]

# Special expiration constants
DO_NOT_CACHE: int
EXPIRE_IMMEDIATELY: int  # 0
NEVER_EXPIRE: int  # -1