콘텐츠로 이동

spakky-cache

애플리케이션 데이터 캐시 계약과 AOP 어노테이션입니다.

어노테이션

Cache method annotations.

Cacheable(key=None, ttl=None, tags=()) dataclass

Bases: FunctionAnnotation

Annotation for caching method return values.

key = None class-attribute instance-attribute

Optional format string used as the cache key.

ttl = None class-attribute instance-attribute

Optional cache entry TTL.

tags = () class-attribute instance-attribute

Optional tags associated with the stored cache entry.

CacheEvict(key=None, tags=()) dataclass

Bases: FunctionAnnotation

Annotation for evicting a cache entry after successful method execution.

key = None class-attribute instance-attribute

Optional format string used as the cache key.

tags = () class-attribute instance-attribute

Optional cache tags to evict after successful method execution.

cacheable(key=None, *, ttl=None, tags=())

Decorate a method so its return value is cached by AOP.

Source code in core/spakky-cache/src/spakky/cache/annotation.py 
36
37
38
39
40
41
42
43
44
45
46
47
def cacheable[**P, R](
    key: str | None = None,
    *,
    ttl: CacheTTL = None,
    tags: tuple[str, ...] = (),
) -> Callable[[Callable[P, R]], Callable[P, R]]:
    """Decorate a method so its return value is cached by AOP."""

    def decorator(func: Callable[P, R]) -> Callable[P, R]:
        return Cacheable(key=key, ttl=ttl, tags=tags)(func)

    return decorator

cache_evict(key=None, *, tags=())

Decorate a method so its cache entry is evicted after success.

Source code in core/spakky-cache/src/spakky/cache/annotation.py 
50
51
52
53
54
55
56
57
58
59
60
def cache_evict[**P, R](
    key: str | None = None,
    *,
    tags: tuple[str, ...] = (),
) -> Callable[[Callable[P, R]], Callable[P, R]]:
    """Decorate a method so its cache entry is evicted after success."""

    def decorator(func: Callable[P, R]) -> Callable[P, R]:
        return CacheEvict(key=key, tags=tags)(func)

    return decorator

AOP Aspect

AOP aspects for cache annotations.

CacheAspect(cache)

Bases: IAspect

Aspect that applies cacheable and cache eviction annotations.

Source code in core/spakky-cache/src/spakky/cache/aspects/cache_aspect.py 
54
55
def __init__(self, cache: ICache[object]) -> None:
    self._cache = cache

AsyncCacheAspect(cache)

Bases: IAsyncAspect

Async aspect that applies cacheable and cache eviction annotations.

Source code in core/spakky-cache/src/spakky/cache/aspects/cache_aspect.py 
114
115
def __init__(self, cache: ICache[object]) -> None:
    self._cache = cache

결과 계약

Typed cache result contracts.

CacheResult = CacheHit[T] | CacheMiss

Cache lookup result type.

CacheHit

Cache lookup result for an existing entry.

CacheMiss

Cache lookup result for a missing or expired entry.

CacheMetricsSnapshot

Point-in-time cache backend metrics.

캐시 인터페이스

Backend-neutral cache contract.

CacheTTL = float | int | timedelta | None

Cache entry lifetime. None means no automatic expiry.

ICache

Bases: ABC

Backend-neutral application data cache contract.

get(key) abstractmethod

Return a typed hit or miss result for a cache key.

Source code in core/spakky-cache/src/spakky/cache/interfaces/cache.py 
16
17
18
19
@abstractmethod
def get(self, key: str) -> CacheResult[T]:
    """Return a typed hit or miss result for a cache key."""
    ...

set(key, value, *, ttl=None) abstractmethod

Store a cache value with an optional TTL.

Source code in core/spakky-cache/src/spakky/cache/interfaces/cache.py 
21
22
23
24
@abstractmethod
def set(self, key: str, value: T, *, ttl: CacheTTL = None) -> None:
    """Store a cache value with an optional TTL."""
    ...

delete(key) abstractmethod

Remove one cache key and return whether an entry existed.

Source code in core/spakky-cache/src/spakky/cache/interfaces/cache.py 
26
27
28
29
@abstractmethod
def delete(self, key: str) -> bool:
    """Remove one cache key and return whether an entry existed."""
    ...

clear() abstractmethod

Remove all cache entries from this backend instance.

Source code in core/spakky-cache/src/spakky/cache/interfaces/cache.py 
31
32
33
34
@abstractmethod
def clear(self) -> None:
    """Remove all cache entries from this backend instance."""
    ...

get_async(key) abstractmethod async

Async variant of get.

Source code in core/spakky-cache/src/spakky/cache/interfaces/cache.py 
36
37
38
39
@abstractmethod
async def get_async(self, key: str) -> CacheResult[T]:
    """Async variant of get."""
    ...

set_async(key, value, *, ttl=None) abstractmethod async

Async variant of set.

Source code in core/spakky-cache/src/spakky/cache/interfaces/cache.py 
41
42
43
44
@abstractmethod
async def set_async(self, key: str, value: T, *, ttl: CacheTTL = None) -> None:
    """Async variant of set."""
    ...

delete_async(key) abstractmethod async

Async variant of delete.

Source code in core/spakky-cache/src/spakky/cache/interfaces/cache.py 
46
47
48
49
@abstractmethod
async def delete_async(self, key: str) -> bool:
    """Async variant of delete."""
    ...

clear_async() abstractmethod async

Async variant of clear.

Source code in core/spakky-cache/src/spakky/cache/interfaces/cache.py 
51
52
53
54
@abstractmethod
async def clear_async(self) -> None:
    """Async variant of clear."""
    ...

ITaggedCache

Bases: ICache[T], ABC

Cache backend that can index and evict entries by tag.

set_with_tags(key, value, *, tags, ttl=None) abstractmethod

Store a value and associate it with cache tags.

Source code in core/spakky-cache/src/spakky/cache/interfaces/cache.py 
60
61
62
63
64
65
66
67
68
69
70
@abstractmethod
def set_with_tags(
    self,
    key: str,
    value: T,
    *,
    tags: tuple[str, ...],
    ttl: CacheTTL = None,
) -> None:
    """Store a value and associate it with cache tags."""
    ...

evict_tags(*tags) abstractmethod

Remove entries associated with one or more tags.

Source code in core/spakky-cache/src/spakky/cache/interfaces/cache.py 
72
73
74
75
@abstractmethod
def evict_tags(self, *tags: str) -> int:
    """Remove entries associated with one or more tags."""
    ...

set_with_tags_async(key, value, *, tags, ttl=None) abstractmethod async

Async variant of set_with_tags.

Source code in core/spakky-cache/src/spakky/cache/interfaces/cache.py 
77
78
79
80
81
82
83
84
85
86
87
@abstractmethod
async def set_with_tags_async(
    self,
    key: str,
    value: T,
    *,
    tags: tuple[str, ...],
    ttl: CacheTTL = None,
) -> None:
    """Async variant of set_with_tags."""
    ...

evict_tags_async(*tags) abstractmethod async

Async variant of evict_tags.

Source code in core/spakky-cache/src/spakky/cache/interfaces/cache.py 
89
90
91
92
@abstractmethod
async def evict_tags_async(self, *tags: str) -> int:
    """Async variant of evict_tags."""
    ...

IStampedeProtectedCache

Bases: ICache[T], ABC

Cache backend that serializes concurrent miss population.

get_or_set(key, factory, *, ttl=None, tags=()) abstractmethod

Return cached value or populate it once through a backend lock.

Source code in core/spakky-cache/src/spakky/cache/interfaces/cache.py 
 98
 99
100
101
102
103
104
105
106
107
108
@abstractmethod
def get_or_set(
    self,
    key: str,
    factory: Callable[[], T],
    *,
    ttl: CacheTTL = None,
    tags: tuple[str, ...] = (),
) -> T:
    """Return cached value or populate it once through a backend lock."""
    ...

get_or_set_async(key, factory, *, ttl=None, tags=()) abstractmethod async

Async variant of get_or_set.

Source code in core/spakky-cache/src/spakky/cache/interfaces/cache.py 
110
111
112
113
114
115
116
117
118
119
120
@abstractmethod
async def get_or_set_async(
    self,
    key: str,
    factory: Callable[[], Awaitable[T]],
    *,
    ttl: CacheTTL = None,
    tags: tuple[str, ...] = (),
) -> T:
    """Async variant of get_or_set."""
    ...

ICacheMetrics

Bases: ICache[T], ABC

Cache backend that exposes deterministic metrics counters.

metrics() abstractmethod

Return a point-in-time metrics snapshot.

Source code in core/spakky-cache/src/spakky/cache/interfaces/cache.py 
126
127
128
129
@abstractmethod
def metrics(self) -> CacheMetricsSnapshot:
    """Return a point-in-time metrics snapshot."""
    ...

IWritePolicyCache

Bases: ICache[T], ABC

Cache backend that coordinates cache writes with an origin writer.

write_through(key, value, writer, *, ttl=None, tags=()) abstractmethod

Write to the origin first, then update the cache.

Source code in core/spakky-cache/src/spakky/cache/interfaces/cache.py 
135
136
137
138
139
140
141
142
143
144
145
146
@abstractmethod
def write_through(
    self,
    key: str,
    value: T,
    writer: Callable[[T], None],
    *,
    ttl: CacheTTL = None,
    tags: tuple[str, ...] = (),
) -> None:
    """Write to the origin first, then update the cache."""
    ...

write_behind(key, value, writer, *, ttl=None, tags=()) abstractmethod

Update the cache first, then invoke the origin writer.

Source code in core/spakky-cache/src/spakky/cache/interfaces/cache.py 
148
149
150
151
152
153
154
155
156
157
158
159
@abstractmethod
def write_behind(
    self,
    key: str,
    value: T,
    writer: Callable[[T], None],
    *,
    ttl: CacheTTL = None,
    tags: tuple[str, ...] = (),
) -> None:
    """Update the cache first, then invoke the origin writer."""
    ...

write_through_async(key, value, writer, *, ttl=None, tags=()) abstractmethod async

Async variant of write_through.

Source code in core/spakky-cache/src/spakky/cache/interfaces/cache.py 
161
162
163
164
165
166
167
168
169
170
171
172
@abstractmethod
async def write_through_async(
    self,
    key: str,
    value: T,
    writer: Callable[[T], Awaitable[None]],
    *,
    ttl: CacheTTL = None,
    tags: tuple[str, ...] = (),
) -> None:
    """Async variant of write_through."""
    ...

write_behind_async(key, value, writer, *, ttl=None, tags=()) abstractmethod async

Async variant of write_behind.

Source code in core/spakky-cache/src/spakky/cache/interfaces/cache.py 
174
175
176
177
178
179
180
181
182
183
184
185
@abstractmethod
async def write_behind_async(
    self,
    key: str,
    value: T,
    writer: Callable[[T], Awaitable[None]],
    *,
    ttl: CacheTTL = None,
    tags: tuple[str, ...] = (),
) -> None:
    """Async variant of write_behind."""
    ...

플러그인 진입점

Plugin initialization entry point.

initialize(app)

Initialize the spakky-cache plugin.

Parameters:

Name Type Description Default
app SpakkyApplication

The SpakkyApplication instance.

 required
Source code in core/spakky-cache/src/spakky/cache/main.py 
 8
 9
10
11
12
13
14
15
def initialize(app: SpakkyApplication) -> None:
    """Initialize the spakky-cache plugin.

    Args:
        app: The SpakkyApplication instance.
    """
    app.add(CacheAspect)
    app.add(AsyncCacheAspect)

에러

Error classes for the spakky-cache package.

AbstractSpakkyCacheError

Bases: AbstractSpakkyFrameworkError, ABC

Base class for cache-related errors.

InvalidCacheTTLError

Bases: AbstractSpakkyCacheError

Raised when a cache entry is written with an invalid TTL.

CacheKeyGenerationError

Bases: AbstractSpakkyCacheError

Raised when a cache annotation cannot produce a deterministic key.

CacheBackendCapabilityError

Bases: AbstractSpakkyCacheError

Raised when a cache annotation requires a backend capability.