Memory Cache

Lila includes a simple but powerful in-memory caching system to reduce database load and improve response times. It supports TTL (Time To Live), allowing items to expire automatically.

Basic Usage

You can use the Cache class from lila.core.cache to store and retrieve any Python object.

Using Cache in Code 

from lila.core.cache import Cache

# Store a value for 5 minutes (300 seconds)
Cache.set("my_key", {"data": "value"}, ttl=300)

# Retrieve a value
data = Cache.get("my_key")

if data:
    print("Value found in cache")
else:
    print("Value expired or not found")

# Delete a specific key
Cache.delete("my_key")

# Clear everything
Cache.clear()

Asynchronous Caching

Lila features fully non-blocking asynchronous cache methods that should be preferred inside async route handlers:

Using Async Cache in Route Handlers 
from lila.core.cache import Cache

# Store a value asynchronously for 5 minutes
await Cache.set_async("my_key", {"data": "value"}, ttl=300)

# Retrieve a value asynchronously
data = await Cache.get_async("my_key")

# Delete a value asynchronously
await Cache.delete_async("my_key")

# Clear cache database asynchronously
await Cache.clear_async()

Cache Drivers & Configuration (v2.0)

Lila v2.0 introduces a pluggable cache driver architecture. By default, it uses a high-performance In-Memory LRU + TTL cache, but you can effortlessly switch to Redis without code changes: 

from lila.core.cache import Cache

# 1. Configured via .env:
# CACHE_DRIVER="memory"  (Default, zero infrastructure)
# CACHE_DRIVER="file"    (persistent JSON fallback in CACHE_DIR)
# CACHE_DRIVER="redis"   (requires pip install "lila-framework[redis]")

# 2. Or configured programmatically with options:
Cache.configure(driver="memory", options={"max_items": 10000, "default_ttl": 300})

# If Redis is not installed or unreachable, Lila logs one notice and keeps
# working on the in-memory cache (there is no "fallback" option to enable):
Cache.configure(driver="redis", options={"host": "127.0.0.1", "port": 6379})

# Force a fresh configuration (re-reads CACHE_DRIVER from .env):
Cache.configure()

Clearing the Cache

clear() / clear_async() preserve server-side session entries by default; pass include_sessions=True to wipe everything (this logs users out). 

from lila.core.cache import Cache

# Remove cached values but keep sessions (used by the admin panel)
await Cache.clear_async(include_sessions=False)

# Remove everything, including server-side session payloads
Cache.clear(include_sessions=True)

Atomic Counter (Rate Limiting)

Lila provides atomic counter incrementing for high-throughput rate limiting: 

# Increment key with TTL expiration window
current_count = await Cache.incr_async("rate_limit:ip:127.0.0.1", ttl=60)
if current_count > 100:
    return JSONResponse({"error": "rate_limit_exceeded"}, status_code=429)

Cache Telemetry Stats

Retrieve real-time metrics for monitoring and the Admin 2.0 dashboard: 

stats = Cache.stats()
# Returns: {"driver": "memory", "active_backend": "memory", "memory_items": 42, "redis_available": True}

Route Caching Decorator

Cache entire responses directly from the route decorator: 

@router.get("/products", cache=120) # Caches response for 120 seconds
async def list_products(request: Request):
    return await Product.get_all_async()