lexigram-cache

Multi-backend caching system for Lexigram Framework — Redis, Memcached, and in-memory caching.

Overview

Multi-backend async caching for the Lexigram Framework. Supports Redis, in-memory, and Memcached backends with stampede protection, circuit breaker, Result-aware caching, and domain model round-trip serialization.

Configure backends via CacheModule.configure() and inject CacheBackendProtocol into any service. The @cacheable decorator provides cache-aside logic with automatic key generation and Result support.

Full documentation: docs.lexigram.dev

Install

uv add lexigram-cache
# Optional extras
uv add "lexigram-cache[redis,memcached,semantic]"

Quick Start

from lexigram import Application
from lexigram.di.module import Module, module
from lexigram.cache import CacheModule, CacheConfig
from lexigram.cache.config import CacheBackendConfig
from lexigram.cache.types import BackendType
from lexigram.contracts.infra.cache import CacheBackendProtocol

@module(imports=[
    CacheModule.configure(
        CacheConfig(
            backends=[
                CacheBackendConfig(
                    name="default",
                    type=BackendType.REDIS,
                    default=True,
                    redis_url="redis://localhost:6379/0",
                )
            ]
        )
    )
])
class AppModule(Module):
    pass

async def main():
    async with Application.boot(modules=[AppModule]) as app:
        cache = await app.container.resolve(CacheBackendProtocol)
        await cache.set("greeting", "hello", ttl=60)
        value = await cache.get("greeting")
        print(value.unwrap())  # "hello"

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Configuration

Zero-config usage: Call CacheModule.configure() with no arguments; backends are then loaded from the cache: section of application.yaml. Use CacheModule.stub() (in-memory) in tests.

Option 1 — YAML file

# application.yaml
cache:
  enabled: true
  backends:
    - name: redis
      type: redis
      default: true
      redis_url: "redis://localhost:6379/0"
      default_ttl: 300
  service:
    enable_protection: true

Option 2 — Profiles + Environment Variables (recommended)

export LEX_CACHE__ENABLED=true
export LEX_CACHE__BACKENDS__0__TYPE=redis
export LEX_CACHE__BACKENDS__0__REDIS_URL=redis://localhost:6379/0

Option 3 — Python

from lexigram.cache import CacheModule, CacheConfig
from lexigram.cache.config import CacheBackendConfig
from lexigram.cache.types import BackendType

CacheModule.configure(
    CacheConfig(
        backends=[
            CacheBackendConfig(
                name="redis",
                type=BackendType.REDIS,
                default=True,
                redis_url="redis://localhost:6379/0",
            )
        ]
    )
)

Config reference

Module Factory Methods

Key Features

• Multi-backend — Redis, in-memory, and Memcached with a unified protocol
• Stampede protection — Distributed lock on cold reads prevents thundering herd
• Circuit breaker — Opens on repeated backend failures, falls through to origin
• @cacheable decorator — Cache-aside with automatic key generation and Result support
• Domain model serialization — Type-tagged JSON envelope preserves type identity round-trip
• Production security — Blocks insecure Redis passwords when LEX_ENV=production

Testing

from lexigram.cache import CacheService

async with Application.boot(modules=[CacheModule.stub()]) as app:
    cache = await app.container.resolve(CacheService)
    await cache.set("key", "value", ttl=60)
    assert await cache.get("key") == "value"

Key Source Files