Skip to content

Cache Configuration API

Pydantic models defining configuration for cache backends and the cache manager.

Manager Configuration

CacheManagerConfig

CacheManagerConfig

Bases: BaseModel

Global cache manager configuration.

Source code in src/jinpy_utils/cache/config.py 
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
class CacheManagerConfig(BaseModel):
    """Global cache manager configuration."""

    backends: list[MemoryCacheConfig | RedisCacheConfig | FileCacheConfig] = Field(
        default_factory=list
    )
    enable_singleton: bool = Field(default=True)
    async_queue_size: int = Field(default=10_000, gt=0)
    default_backend: str | None = Field(
        default=None, description="Default backend name to use"
    )

    model_config = ConfigDict(use_enum_values=True, extra="ignore")

    @field_validator("backends")
    @classmethod
    def validate_backends(cls, v: list[Any]) -> list[Any]:
        names = [b.name for b in v if hasattr(b, "name")]
        if len(names) != len(set(names)):
            raise ValueError("Backend names must be unique")
        return v

Backend Configurations

BaseCacheBackendConfig

BaseCacheBackendConfig

Bases: BaseModel

Base configuration for all cache backends.

Source code in src/jinpy_utils/cache/config.py 
11
12
13
14
15
16
17
18
19
20
21
22
class BaseCacheBackendConfig(BaseModel):
    """Base configuration for all cache backends."""

    backend_type: CacheBackendType
    name: str = Field(..., description="Unique backend name")
    enabled: bool = True
    default_ttl: float | None = Field(
        default=None, ge=0, description="Default TTL in seconds"
    )
    serializer: Literal["json", "pickle", "str", "bytes"] = "json"

    model_config = ConfigDict(extra="allow", use_enum_values=True)

MemoryCacheConfig

MemoryCacheConfig

Bases: BaseCacheBackendConfig

Configuration for in-memory cache.

Source code in src/jinpy_utils/cache/config.py 
25
26
27
28
29
30
31
32
33
34
class MemoryCacheConfig(BaseCacheBackendConfig):
    """Configuration for in-memory cache."""

    backend_type: CacheBackendType = CacheBackendType.MEMORY
    max_entries: int | None = Field(
        default=None,
        ge=1,
        description="Optional max entries for eviction (FIFO)",
    )
    thread_safe: bool = True

RedisCacheConfig

RedisCacheConfig

Bases: BaseCacheBackendConfig

Configuration for Redis cache (async).

Source code in src/jinpy_utils/cache/config.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
class RedisCacheConfig(BaseCacheBackendConfig):
    """Configuration for Redis cache (async)."""

    backend_type: CacheBackendType = CacheBackendType.REDIS
    url: str = Field(
        ...,
        description="Redis URL, e.g., redis://localhost:6379/0",
    )
    decode_responses: bool = False
    pool_size: int = Field(default=10, ge=1, le=100)
    connect_timeout: float = Field(default=5.0, gt=0)
    command_timeout: float = Field(default=2.0, gt=0)
    ssl: bool = False

    @field_validator("url")
    @classmethod
    def validate_url(cls, v: str) -> str:
        if not v.startswith(("redis://", "rediss://")):
            raise ValueError("Redis URL must start with redis:// or rediss://")
        return v

FileCacheConfig

FileCacheConfig

Bases: BaseCacheBackendConfig

Configuration for file-based cache.

Source code in src/jinpy_utils/cache/config.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
class FileCacheConfig(BaseCacheBackendConfig):
    """Configuration for file-based cache."""

    backend_type: CacheBackendType = CacheBackendType.FILE
    directory: Path = Field(
        default=Path(".cache"),
        description="Directory for stored cache entries",
    )
    file_extension: str = Field(default=".bin")
    max_entries: int | None = Field(default=None, ge=1)

    @field_validator("directory")
    @classmethod
    def ensure_dir(cls, v: Path) -> Path:
        v.mkdir(parents=True, exist_ok=True)
        return v

Examples

Minimal in-memory config

from jinpy_utils.cache import CacheManager, CacheManagerConfig, MemoryCacheConfig

cfg = CacheManagerConfig(
    default_backend="mem",
    backends=[MemoryCacheConfig(name="mem", default_ttl=30)]
)
CacheManager(cfg)

File backend config

from pathlib import Path
from jinpy_utils.cache import CacheManager, CacheManagerConfig, FileCacheConfig

cfg = CacheManagerConfig(
    default_backend="disk",
    backends=[FileCacheConfig(name="disk", directory=Path(".cache"), file_extension=".bin")]
)
CacheManager(cfg)

Redis backend config

from jinpy_utils.cache import CacheManager, CacheManagerConfig, RedisCacheConfig

cfg = CacheManagerConfig(
    default_backend="redis",
    backends=[RedisCacheConfig(name="redis", url="redis://localhost:6379/0", decode_responses=False)]
)
CacheManager(cfg)