Metadata-Version: 2.4
Name: cacheado
Version: 1.4.1
Summary: Advanced Python cache system with multi-tenant support, scope hierarchies, and configurable eviction policies
Author-email: George Mendonca Silva de Morais <george1bsilva@outlook.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/GeorgeOgeorge/cacheado
Project-URL: Repository, https://github.com/GeorgeOgeorge/cacheado
Project-URL: Documentation, https://github.com/GeorgeOgeorge/cacheado#readme
Project-URL: Bug Tracker, https://github.com/GeorgeOgeorge/cacheado/issues
Keywords: cache,multi-tenant,hierarchical,eviction,thread-safe
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Cacheado

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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

```bash
pip install cacheado
```

### Basic Usage (30 seconds to first result)

```python
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

```python
# 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

```python
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

```python
# 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

```python
# 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

```python
# 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

```python
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

```python
@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

```bash
# 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**
   ```bash
   git clone https://github.com/GeorgeOgeorge/cacheado.git
   cd cacheado
   ```

2. **Install Dependencies**
   ```bash
   pip install -r requirements.txt
   ```

3. **Run Tests**
   ```bash
   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](https://github.com/GeorgeOgeorge/cacheado/issues)
- [Changelog](https://github.com/GeorgeOgeorge/cacheado/releases)

---

**Built with ❤️ for high-performance Python applications**
