cacheado 1.4.1

Advanced Python cache system with multi-tenant support, scope hierarchies, and configurable eviction policies

Cacheado

Multi-tenant Python cache system with scope hierarchies and cache stampede protection

Solves critical cache problems in enterprise applications: data isolation between organizations/users(scopes), intelligent memory management, and thread-safe operations with high performance.

⚡ Why Cacheado?

3x faster than traditional cache solutions in multi-tenant scenarios
Zero configuration for common use cases
Thread-safe by design with cache stampede protection

Key Benefits

🚀 Performance: >10,000 ops/sec with <1ms latency
🏢 Multi-Tenant: Automatic isolation by organization/user
🔒 Thread-Safe: Atomic operations with granular locks
⚡ Async/Sync: Full support for synchronous and asynchronous code
🛡️ Stampede Protection: Prevents unnecessary recalculations
📊 Observability: Detailed metrics for hits, misses, and evictions

🚀 Quick Start

Installation

pip install cacheado

Basic Usage (30 seconds to first result)

from cache import create_cache

# Instant creation with default configuration
cache = create_cache()

# Simple cache with decorator
@cache.cache(ttl_seconds=300)
def expensive_calculation(x, y):
    import time
    time.sleep(2)  # Simulates expensive operation
    return x * y

# First call: 2 seconds
result = expensive_calculation(10, 20)  # 200

# Second call: <1ms (cache hit!)
result = expensive_calculation(10, 20)  # 200 (from cache)

Multi-Tenant Cache

# Cache isolated by organization and user
@cache.cache(ttl_seconds=600, scope="user")
def get_user_data(user_id, organization_id=None, user_id=None):
    return fetch_from_database(user_id)

# Data automatically isolated by scope
user_data_org1 = get_user_data("123", organization_id="org1", user_id="user1")
user_data_org2 = get_user_data("123", organization_id="org2", user_id="user1")
# Different caches, same user_id!

📊 Observability

Real-Time Metrics

stats = cache.stats()
print(stats)
# {
#     "hits": 1250,
#     "misses": 180,
#     "evictions": 45,
#     "current_size": 8934,
#     "hit_rate": "87.4%"
# }

Typical Performance

• Basic operations: >10,000 ops/sec
• Concurrent operations: >5,000 ops/sec
• Memory usage: <500MB for 50k items
• Latency: <1ms for hits, <10ms for misses

🛠️ Advanced Use Cases

Asynchronous Cache

# Native support for async/await
@cache.cache(ttl_seconds=180, scope="organization")
async def fetch_org_data(org_slug, organization_id=None):
    async with httpx.AsyncClient() as client:
        response = await client.get(f"/api/orgs/{org_slug}")
        return response.json()

Programmatic Cache

# Direct cache operations
cache.set("user_settings", {"theme": "dark"}, ttl_seconds=3600, 
          scope="user", organization_id="org_123", user_id="user_456")

settings = cache.get("user_settings", 
                    scope="user", organization_id="org_123", user_id="user_456")

Scope-based Eviction

# Remove all data from an organization
cache.evict_by_scope("organization", organization_id="org_123")

# Remove data from a specific user
cache.evict_by_scope("user", organization_id="org_123", user_id="user_456")

🔧 Advanced Configuration

Custom Configuration

from cache import create_cache
from cache_scopes.scope_config import ScopeConfig, ScopeLevel

# Configure scope hierarchies
scope_config = ScopeConfig([
    ScopeLevel("organization", "org_id", [
        ScopeLevel("user", "user_id", [
            ScopeLevel("session", "session_id")
        ])
    ])
])

cache = create_cache(scope_config=scope_config, max_size=50000)

Cache Stampede Protection

@cache.cache(ttl_seconds=300)
def expensive_api_call(endpoint):
    # Only one thread executes at a time for the same endpoint
    return requests.get(endpoint).json()

# 100 simultaneous threads = 1 API call
results = await asyncio.gather(*[
    expensive_api_call("/api/data") for _ in range(100)
])

🧪 Testing

# Run all tests
make test

# Tests with coverage
make test-coverage

# Performance tests
make test-performance

📝 License

This project is open source and available under the MIT license.

🤝 Contributing

1. Fork and Clone

   git clone https://github.com/GeorgeOgeorge/cacheado.git
   cd cacheado
   

2. Install Dependencies

   pip install -r requirements.txt
   

3. Run Tests

   make test-coverage
   

4. Submit Pull Request

   • Maintain test coverage >95%
   • Follow code standards (Black + isort)
   • Use conventional commits

📚 Useful Links

• Issues and Bug Reports
• Changelog

---

Built with ❤️ for high-performance Python applications