Skip to main content

🌐 cachka

Enterprise-grade hybrid cache for Python Flexible multi-layer caching with memory (L1), SQLite disk (L2), and Redis (L3) support. Works seamlessly in async, sync, and threaded environments.

PyPI - Version PyPI - Python Version License


✨ Features

  • Flexible multi-layer architecture: Compose cache layers (memory, SQLite, Redis) in any order
  • Async & sync support: Use the same decorator everywhere, native sync/async implementations
  • TTL with smart LRU eviction (no memory leaks)
  • Observability: Prometheus metrics, OpenTelemetry tracing
  • Security: AES-GCM encryption for SQLite storage
  • Resilience: Circuit breaker, graceful degradation
  • Zero dependencies for core functionality (SQLite included)
  • Type-safe: Full type hints and dataclass configs
  • Redis support: Optional Redis backend for distributed caching
  • Rate limiter: Redis sliding-window limiter for external APIs (optional)

🚀 Quick Start

1. Install

# Core (required) - includes memory and SQLite
pip install cachka

# With Prometheus metrics
pip install "cachka[prometheus]"

# With Redis support
pip install "cachka[redis]"

# Full enterprise features
pip install "cachka[full]"

2. Initialize Cache

from cachka import cache_registry, CacheConfig
from cachka.sqlitecache import SQLiteCacheConfig
from cachka.ttllrucache import MemoryCacheConfig

# Basic initialization (memory + SQLite with defaults)
config = CacheConfig(
    cache_layers=[
        "memory",  # Default memory cache
        ("sqlite", SQLiteCacheConfig(db_path="cache.db"))  # SQLite with custom path
    ]
)
cache_registry.initialize(config)

# Advanced: Custom memory cache + SQLite
config = CacheConfig(
    cache_layers=[
        ("memory", MemoryCacheConfig(maxsize=2048, ttl=600)),
        ("sqlite", SQLiteCacheConfig(
            db_path="cache.db",
            enable_encryption=True,
            encryption_key="your-base64-encoded-32-byte-key"
        ))
    ],
    enable_metrics=True
)
cache_registry.initialize(config)

# With Redis (requires: pip install cachka[redis])
from cachka.rediscache import RedisCacheConfig

config = CacheConfig(
    cache_layers=[
        "memory",  # Fast L1
        ("sqlite", SQLiteCacheConfig(db_path="cache.db")),  # L2
        ("redis", RedisCacheConfig(host="localhost", port=6379))  # L3
    ]
)
cache_registry.initialize(config)

📖 Usage Examples

Basic Async Function Caching

import asyncio
from cachka import cached, cache_registry, CacheConfig
from cachka.sqlitecache import SQLiteCacheConfig

# Initialize cache
config = CacheConfig(
    cache_layers=[
        "memory",
        ("sqlite", SQLiteCacheConfig(db_path="cache.db"))
    ]
)
cache_registry.initialize(config)

@cached(ttl=300)  # Cache for 5 minutes
async def fetch_user_data(user_id: int):
    # Simulate API call
    await asyncio.sleep(0.1)
    return {"id": user_id, "name": f"User {user_id}"}

async def main():
    # First call - fetches data
    user1 = await fetch_user_data(1)
    print(user1)  # {"id": 1, "name": "User 1"}

    # Second call - returns cached data (no API call)
    user1_cached = await fetch_user_data(1)
    print(user1_cached)  # {"id": 1, "name": "User 1"} (from cache)

    # Cleanup
    await cache_registry.shutdown()

asyncio.run(main())

Sync Function Caching

from cachka import cached, cache_registry, CacheConfig
from cachka.sqlitecache import SQLiteCacheConfig

config = CacheConfig(
    cache_layers=[
        "memory",
        ("sqlite", SQLiteCacheConfig(db_path="cache.db"))
    ]
)
cache_registry.initialize(config)

@cached(ttl=60)
def expensive_computation(n: int) -> int:
    """Fibonacci calculation - cached after first call"""
    if n < 2:
        return n
    return expensive_computation(n - 1) + expensive_computation(n - 2)

# First call - computes
result1 = expensive_computation(30)  # Takes time

# Second call - returns cached result instantly
result2 = expensive_computation(30)  # Instant!

Class Methods with simplified_self_serialization

from cachka import cached, cache_registry, CacheConfig
from cachka.sqlitecache import SQLiteCacheConfig

config = CacheConfig(
    cache_layers=[
        "memory",
        ("sqlite", SQLiteCacheConfig(db_path="cache.db"))
    ]
)
cache_registry.initialize(config)

class UserService:
    @cached(ttl=300, simplified_self_serialization=True)
    async def get_user(self, user_id: int):
        # Cache key will be based on user_id only, not self instance
        # Uses class name instead of self for cache key generation
        return await self._fetch_from_db(user_id)

    async def _fetch_from_db(self, user_id: int):
        # Database query simulation
        return {"id": user_id, "name": f"User {user_id}"}

service = UserService()
user = await service.get_user(123)  # Cached by user_id and class name only

Multi-Layer Cache Configuration

from cachka import cache_registry, CacheConfig
from cachka.ttllrucache import MemoryCacheConfig
from cachka.sqlitecache import SQLiteCacheConfig
from cachka.rediscache import RedisCacheConfig
import base64
import secrets

# Generate encryption key (32 bytes, base64-encoded)
encryption_key = base64.b64encode(secrets.token_bytes(32)).decode()

config = CacheConfig(
    cache_layers=[
        # L1: Fast in-memory cache
        ("memory", MemoryCacheConfig(
            maxsize=4096,
            ttl=1800,  # 30 minutes
            shards=8
        )),
        # L2: Persistent SQLite cache
        ("sqlite", SQLiteCacheConfig(
            db_path="secure_cache.db",
            enable_encryption=True,
            encryption_key=encryption_key
        )),
        # L3: Distributed Redis cache (optional)
        ("redis", RedisCacheConfig(
            host="localhost",
            port=6379,
            db=0,
            key_prefix="myapp:"
        ))
    ],
    vacuum_interval=3600,  # Cleanup every hour
    cleanup_on_start=True,  # Clean expired on startup
    enable_metrics=True,   # Prometheus metrics
    circuit_breaker_threshold=50,  # Open circuit after 50 failures
    circuit_breaker_window=60      # Recovery window: 60 seconds
)

cache_registry.initialize(config)

Redis Cache (Optional)

from cachka import cache_registry, CacheConfig
from cachka.rediscache import RedisCacheConfig

# Install: pip install cachka[redis]

config = CacheConfig(
    cache_layers=[
        "memory",  # Fast local cache
        ("redis", RedisCacheConfig(
            host="localhost",
            port=6379,
            db=0,
            password=None,  # Optional
            key_prefix="myapp:",  # Namespace for keys
            max_connections=50
        ))
    ]
)
cache_registry.initialize(config)

# Use as normal - Redis handles TTL automatically
@cached(ttl=300)
async def get_data(key: str):
    return {"data": f"value for {key}"}

Rate Limiter (Optional Redis)

Distributed or in-process sliding-window rate limiter. Independent from cache_layers — choose backend explicitly.

# Install redis backend: pip install cachka[redis]

from cachka import (
    cache_registry,
    CacheConfig,
    rate_limited,
    RateLimiterConfig,
    RateLimitExceeded,
)
from cachka.rediscache import RedisCacheConfig

# 1) Cache for @cached (can stay memory-only)
cache_registry.initialize(
    CacheConfig(cache_layers=["memory"], vacuum_interval=None, cleanup_on_start=False)
)

# 2) Rate limiter — call once at startup (own backend + redis when needed)
cache = cache_registry.get()
cache.init_rate_limiter(
    {
        "external_api": RateLimiterConfig(
            max_requests=60,
            window_seconds=60,
            max_wait_sec=30.0,
        ),
    },
    backend="redis",  # or "memory" for single-process / tests
    redis=RedisCacheConfig(host="localhost", port=6379),
)

@rate_limited(tag="external_api")
async def fetch_external(query: str):
    ...
  • Call init_rate_limiter once per process. Re-init overwrites profiles and does not close the previous Redis client; clean up with cache_registry.shutdown() / graceful_shutdown().
  • backend="redis" — shared quota across workers (needs redis=RedisCacheConfig(...))
  • backend="memory" — in-process only (no Redis)
  • Redis key shape: rate_limit:<tag>:<identifier> (e.g. rate_limit:external_api:default)
  • Optional identifier on @rate_limited splits buckets inside one tag

On Redis connection errors the Redis limiter fails open. If the quota is exhausted / wait times out, @rate_limited raises RateLimitExceeded.

Low-level RateLimiter / MemoryRateLimiter classes are still available.

Graceful Shutdown

import asyncio
from cachka import cache_registry

async def main():
    # Your application code
    pass

# Cleanup on application exit
async def cleanup():
    await cache_registry.shutdown()

# In FastAPI, for example:
# @app.on_event("shutdown")
# async def shutdown_event():
#     await cache_registry.shutdown()

Accessing Metrics (Prometheus)

from cachka import cache_registry

# After enabling metrics in config
cache = cache_registry.get()
metrics_text = cache.get_metrics_text()
print(metrics_text)
# Output: Prometheus metrics in text format

Health Check

from cachka import cache_registry

cache = cache_registry.get()
health = await cache.health_check()
print(health)
# {
#     "status": "healthy",
#     "circuit_breaker": "CLOSED",
#     "cache_layers_count": 2
# }

🏗️ Architecture

Cache Layers

cachka supports flexible multi-layer caching:

  1. Memory (L1): Fast in-memory LRU cache with TTL

    • Configurable via MemoryCacheConfig
    • Sharded for better concurrency
    • Automatic eviction when full
  2. SQLite (L2): Persistent disk-based cache

    • Configurable via SQLiteCacheConfig
    • Optional AES-GCM encryption
    • Automatic cleanup of expired entries
  3. Redis (L3): Distributed cache (optional)

    • Configurable via RedisCacheConfig
    • Requires: pip install cachka[redis]
    • Automatic TTL handling
    • Connection pooling

Cache Flow

When you call cache.get(key):

  1. Checks L1 (memory) → if found, return
  2. Checks L2 (SQLite) → if found, promote to L1 and return
  3. Checks L3 (Redis) → if found, promote to L2 and L1, return
  4. If not found in any layer → return None

When you call cache.set(key, value, ttl):

  1. Writes to all configured layers (write-through)
  2. Each layer respects its own TTL configuration

⚙️ Configuration

CacheConfig

Main configuration class:

@dataclass
class CacheConfig:
    cache_layers: list[Union[str, tuple[str, Any]]]  # Required: list of cache layers
    vacuum_interval: Optional[int] = None  # SQLite vacuum interval (seconds)
    cleanup_on_start: bool = False  # Clean expired entries on startup
    enable_metrics: bool = False  # Enable Prometheus metrics
    name: str = "default_cache"  # Cache name for metrics
    circuit_breaker_threshold: int = 50  # Failures before opening circuit
    circuit_breaker_window: int = 60  # Recovery window (seconds)

MemoryCacheConfig

@dataclass
class MemoryCacheConfig:
    maxsize: int = 1024  # Maximum cache size
    ttl: int = 300  # Time to live (seconds)
    shards: int = 8  # Number of shards for concurrency
    enable_metrics: bool = False  # Enable metrics for this layer
    name: str = "memory_cache"  # Layer name

SQLiteCacheConfig

@dataclass
class SQLiteCacheConfig:
    db_path: str = "cache.db"  # Database file path
    enable_encryption: bool = False  # Enable AES-GCM encryption
    encryption_key: Optional[str] = None  # Base64-encoded 32-byte key
    max_key_length: int = 512  # Maximum key length

RedisCacheConfig

@dataclass
class RedisCacheConfig:
    host: str = "localhost"  # Redis host
    port: int = 6379  # Redis port
    db: int = 0  # Redis database number
    password: Optional[str] = None  # Redis password
    socket_timeout: Optional[float] = None  # Socket timeout
    socket_connect_timeout: Optional[float] = None  # Connection timeout
    max_connections: int = 50  # Connection pool size
    key_prefix: str = "cachka:"  # Prefix for all keys

🔧 Advanced Usage

Custom Cache Layer Order

You can configure cache layers in any order:

# Memory only
config = CacheConfig(cache_layers=["memory"])

# SQLite only
config = CacheConfig(cache_layers=[("sqlite", SQLiteCacheConfig())])

# Redis only (requires redis)
config = CacheConfig(cache_layers=[("redis", RedisCacheConfig())])

# Custom order: Redis -> Memory -> SQLite
config = CacheConfig(
    cache_layers=[
        ("redis", RedisCacheConfig()),
        "memory",
        ("sqlite", SQLiteCacheConfig())
    ]
)

Direct Cache Access

from cachka import cache_registry

cache = cache_registry.get()

# Async operations
await cache.set("key", "value", ttl=60)
value = await cache.get("key")
await cache.delete("key")

# Sync operations
cache.set_sync("key", "value", ttl=60)
value = cache.get_sync("key")
cache.delete_sync("key")

📦 Installation Options

# Core (memory + SQLite)
pip install cachka

# With Prometheus metrics
pip install "cachka[prometheus]"

# With OpenTelemetry tracing
pip install "cachka[tracing]"

# With encryption support
pip install "cachka[encryption]"

# With Redis support
pip install "cachka[redis]"

# All features
pip install "cachka[full]"

🧪 Testing

# Install dev dependencies
pip install "cachka[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=cachka --cov-report=html

📝 License

MIT License - see LICENSE file for details.


🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.


📚 API Reference

Decorator

  • @cached(ttl=300, simplified_self_serialization=False) - Cache decorator

Configuration

  • CacheConfig - Main cache configuration
  • MemoryCacheConfig - Memory cache configuration
  • SQLiteCacheConfig - SQLite cache configuration
  • RedisCacheConfig - Redis cache configuration (optional)

Registry

  • cache_registry.initialize(config) - Initialize cache
  • cache_registry.get() - Get cache instance
  • cache_registry.shutdown() - Shutdown cache
  • cache_registry.reset() - Reset registry

Rate Limiter (optional)

  • cache.init_rate_limiter(profiles, backend="redis"|"memory", redis=...) — register profiles (once per process)
  • Re-init is overwritten in place; previous Redis client is not closed — use graceful_shutdown()
  • backend="redis" requires redis=RedisCacheConfig(...) and cachka[redis]
  • backend="memory" — in-process limiter (no Redis)
  • cache.get_rate_limiter(tag) / @rate_limited(tag="...")
  • RateLimiter / MemoryRateLimiter / RateLimiterConfig / RateLimitExceeded
  • Redis key: rate_limit:<tag>:<identifier>

Cache Interface

  • cache.get(key) - Get value (async)
  • cache.get_sync(key) - Get value (sync)
  • cache.set(key, value, ttl) - Set value (async)
  • cache.set_sync(key, value, ttl) - Set value (sync)
  • cache.delete(key) - Delete key (async)
  • cache.delete_sync(key) - Delete key (sync)
  • cache.cleanup_expired() - Clean expired entries (async)
  • cache.cleanup_expired_sync() - Clean expired entries (sync)
  • cache.health_check() - Health check (async)
  • cache.get_metrics_text() - Get Prometheus metrics

Metadata

Release files for cachka 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cachka 0.3.0
File Size Uploaded Provenance Actions
cachka-0.3.0.tar.gz 44.2 kB Without provenance Details for cachka-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cachka 0.3.0
File Interpreter ABI Platform Actions
cachka-0.3.0-py3-none-any.whl Python 3 none any Details for cachka-0.3.0-py3-none-any.whl

Total release size: 73.3 kB

Release files / cachka-0.3.0.tar.gz

Download URL cachka-0.3.0.tar.gz
Size 44.2 kB
Tags Source
SHA-256 checksum
How to use checksums
051472d70063ed0fb438787567902732b3bc156cd31572f8a1cf93d664a399a0
BLAKE2b-256 checksum
How to use checksums
df39fb18c9e3bd40d5113a290b15e1fcbf48a454e7dbc36d62c40717e47becd4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.31 {"installer":{"name":"uv","version":"0.11.31","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / cachka-0.3.0-py3-none-any.whl

Download URL cachka-0.3.0-py3-none-any.whl
Size 29.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5be358533d188261aa919f1334e0a8fa4809be3ccd4fed2481c3fb7a9aa6a5a1
BLAKE2b-256 checksum
How to use checksums
6f004cbf68468bef0d0644ceefc36cd9ef77c6261eba519d9a8dc560f2c3b3ab
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.31 {"installer":{"name":"uv","version":"0.11.31","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for cachka 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page