spakky-cache 6.3.1__tar.gz

spakky_cache-6.3.1/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.3
+Name: spakky-cache
+Version: 6.3.1
+Summary: Backend-neutral cache contracts and in-memory backend for Spakky Framework
+Author: Spakky
+Author-email: Spakky <sejong418@icloud.com>
+License: MIT
+Requires-Dist: spakky>=6.3.1
+Requires-Dist: typing-extensions>=4.15.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Spakky Cache
+
+Backend-neutral application data cache contracts for [Spakky Framework](https://github.com/E5presso/spakky-framework).
+
+## Installation
+
+```bash
+pip install spakky-cache
+```
+
+## Features
+
+- **Typed cache results**: `CacheHit[T]` and `CacheMiss` represent hit and miss outcomes without backend-specific exceptions.
+- **Sync and async contracts**: `ICache[T]` defines `get`, `set`, `delete`, `clear` and async equivalents.
+- **TTL semantics**: Positive TTL values expire entries deterministically; missing and expired entries are misses.
+- **In-memory backend**: `InMemoryCache[T]` is suitable for local development, tests, and single-process usage.
+- **AOP method caching**: `@cacheable()` and `@cache_evict()` apply cache hit/miss and eviction behavior without manual plumbing.
+- **Application data scope**: This package does not expose or mutate `ApplicationContext` internal caches.
+
+## Quick Start
+
+```python
+from datetime import timedelta
+
+from spakky.cache import CacheHit, InMemoryCache
+
+cache = InMemoryCache[str]()
+cache.set("profile:42", "Ada", ttl=timedelta(minutes=5))
+
+result = cache.get("profile:42")
+if isinstance(result, CacheHit):
+    print(result.value)
+```
+
+## Annotation Usage
+
+Load the `spakky-cache` plugin, then annotate service methods. The plugin registers `InMemoryCache`, `CacheAspect`, and `AsyncCacheAspect` so sync and async methods are handled through Spakky AOP.
+
+```python
+from datetime import timedelta
+
+from spakky.cache import cache_evict, cacheable
+from spakky.core.stereotype.usecase import UseCase
+
+
+@UseCase()
+class ProfileService:
+    def __init__(self) -> None:
+        self.calls = 0
+
+    @cacheable(key="profile:{0}", ttl=timedelta(minutes=5))
+    def load_profile(self, user_id: str) -> str:
+        self.calls += 1
+        return f"profile:{user_id}"
+
+    @cache_evict(key="profile:{0}")
+    def refresh_profile(self, user_id: str) -> None:
+        ...
+```
+
+The default key is derived from the method module, qualified name, positional arguments, and sorted keyword arguments. Explicit `key` values are Python format strings evaluated against method call arguments. Invalid key formatting raises `CacheKeyGenerationError`. Backend failures are not swallowed; cache errors propagate loudly.
+
+`@cache_evict()` deletes the matching entry only after the annotated method succeeds. Failed method calls leave existing entries untouched so a failed refresh does not erase the last known cached value.
+
+## Async Usage
+
+```python
+from spakky.cache import CacheHit, InMemoryCache
+
+cache = InMemoryCache[int]()
+await cache.set_async("answer", 42)
+
+result = await cache.get_async("answer")
+if isinstance(result, CacheHit):
+    assert result.value == 42
+```
+
+## TTL Rules
+
+`ttl=None` stores an entry until explicit deletion or clear. Positive `float`, `int`, or `datetime.timedelta` values expire entries after that duration. Zero or negative TTL values raise `InvalidCacheTTLError`.
+
+The in-memory backend deletes expired entries when they are observed. It is deterministic for one process and does not provide distributed invalidation, stampede protection, or tag-based eviction.
+
+Cache eviction annotations remove a single matching entry only after the annotated method succeeds.
+
+## Scope
+
+`spakky-cache` is an application data cache abstraction. It is separate from `ApplicationContext` internal type, singleton, and context caches. Distributed locks, cache stampede protection, tag invalidation, write-through/write-behind policies, and metrics exporters are outside the current contract.
+
+## License
+
+MIT License

spakky_cache-6.3.1/README.md

@@ -0,0 +1,92 @@
+# Spakky Cache
+
+Backend-neutral application data cache contracts for [Spakky Framework](https://github.com/E5presso/spakky-framework).
+
+## Installation
+
+```bash
+pip install spakky-cache
+```
+
+## Features
+
+- **Typed cache results**: `CacheHit[T]` and `CacheMiss` represent hit and miss outcomes without backend-specific exceptions.
+- **Sync and async contracts**: `ICache[T]` defines `get`, `set`, `delete`, `clear` and async equivalents.
+- **TTL semantics**: Positive TTL values expire entries deterministically; missing and expired entries are misses.
+- **In-memory backend**: `InMemoryCache[T]` is suitable for local development, tests, and single-process usage.
+- **AOP method caching**: `@cacheable()` and `@cache_evict()` apply cache hit/miss and eviction behavior without manual plumbing.
+- **Application data scope**: This package does not expose or mutate `ApplicationContext` internal caches.
+
+## Quick Start
+
+```python
+from datetime import timedelta
+
+from spakky.cache import CacheHit, InMemoryCache
+
+cache = InMemoryCache[str]()
+cache.set("profile:42", "Ada", ttl=timedelta(minutes=5))
+
+result = cache.get("profile:42")
+if isinstance(result, CacheHit):
+    print(result.value)
+```
+
+## Annotation Usage
+
+Load the `spakky-cache` plugin, then annotate service methods. The plugin registers `InMemoryCache`, `CacheAspect`, and `AsyncCacheAspect` so sync and async methods are handled through Spakky AOP.
+
+```python
+from datetime import timedelta
+
+from spakky.cache import cache_evict, cacheable
+from spakky.core.stereotype.usecase import UseCase
+
+
+@UseCase()
+class ProfileService:
+    def __init__(self) -> None:
+        self.calls = 0
+
+    @cacheable(key="profile:{0}", ttl=timedelta(minutes=5))
+    def load_profile(self, user_id: str) -> str:
+        self.calls += 1
+        return f"profile:{user_id}"
+
+    @cache_evict(key="profile:{0}")
+    def refresh_profile(self, user_id: str) -> None:
+        ...
+```
+
+The default key is derived from the method module, qualified name, positional arguments, and sorted keyword arguments. Explicit `key` values are Python format strings evaluated against method call arguments. Invalid key formatting raises `CacheKeyGenerationError`. Backend failures are not swallowed; cache errors propagate loudly.
+
+`@cache_evict()` deletes the matching entry only after the annotated method succeeds. Failed method calls leave existing entries untouched so a failed refresh does not erase the last known cached value.
+
+## Async Usage
+
+```python
+from spakky.cache import CacheHit, InMemoryCache
+
+cache = InMemoryCache[int]()
+await cache.set_async("answer", 42)
+
+result = await cache.get_async("answer")
+if isinstance(result, CacheHit):
+    assert result.value == 42
+```
+
+## TTL Rules
+
+`ttl=None` stores an entry until explicit deletion or clear. Positive `float`, `int`, or `datetime.timedelta` values expire entries after that duration. Zero or negative TTL values raise `InvalidCacheTTLError`.
+
+The in-memory backend deletes expired entries when they are observed. It is deterministic for one process and does not provide distributed invalidation, stampede protection, or tag-based eviction.
+
+Cache eviction annotations remove a single matching entry only after the annotated method succeeds.
+
+## Scope
+
+`spakky-cache` is an application data cache abstraction. It is separate from `ApplicationContext` internal type, singleton, and context caches. Distributed locks, cache stampede protection, tag invalidation, write-through/write-behind policies, and metrics exporters are outside the current contract.
+
+## License
+
+MIT License

spakky_cache-6.3.1/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "spakky-cache"
+version = "6.3.1"
+description = "Backend-neutral cache contracts and in-memory backend for Spakky Framework"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Spakky", email = "sejong418@icloud.com" }]
+dependencies = ["spakky>=6.3.1", "typing-extensions>=4.15.0"]
+
+[project.entry-points."spakky.plugins"]
+spakky-cache = "spakky.cache.main:initialize"
+
+[build-system]
+requires = ["uv_build>=0.10.10,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "src"
+module-name = "spakky.cache"
+
+[tool.pyrefly]
+python-version = "3.11"
+search_path = ["src", ".", "../spakky/src"]
+project_excludes = ["**/__pycache__", "**/*.pyc"]
+
+[tool.ruff]
+builtins = ["_"]
+cache-dir = "~/.cache/ruff"
+
+[tool.pytest.ini_options]
+pythonpath = ["src", "../spakky/src"]
+testpaths = "tests"
+python_files = ["test_*.py"]
+asyncio_mode = "auto"
+addopts = """
+    --cov
+    --cov-report=term
+    --cov-report=xml
+    --no-cov-on-fail
+    --strict-markers
+    --dist=load
+    -p no:warnings
+    -n auto
+    --spec
+"""
+spec_test_format = "{result} {docstring_summary}"
+
+[tool.coverage.run]
+include = ["src/spakky/cache/**/*.py"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+precision = 2
+fail_under = 90
+skip_empty = true
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "@(abc\\.)?abstractmethod",
+    "@(typing\\.)?overload",
+    "\\.\\.\\.",
+    "pass",
+]
+
+[tool.uv.sources]
+spakky = { workspace = true }

spakky_cache-6.3.1/src/spakky/cache/__init__.py

@@ -0,0 +1,36 @@
+"""Backend-neutral application data cache contracts."""
+
+from spakky.core.application.plugin import Plugin
+
+from spakky.cache.annotation import CacheEvict, Cacheable, cache_evict, cacheable
+from spakky.cache.aspects.cache_aspect import AsyncCacheAspect, CacheAspect
+from spakky.cache.backends.memory import InMemoryCache
+from spakky.cache.error import (
+    AbstractSpakkyCacheError,
+    CacheKeyGenerationError,
+    InvalidCacheTTLError,
+)
+from spakky.cache.interfaces.cache import ICache, CacheTTL
+from spakky.cache.result import CacheHit, CacheMiss, CacheResult
+
+PLUGIN_NAME = Plugin(name="spakky-cache")
+"""Plugin identifier for the Spakky Cache package."""
+
+__all__ = [
+    "ICache",
+    "AbstractSpakkyCacheError",
+    "AsyncCacheAspect",
+    "CacheEvict",
+    "CacheHit",
+    "CacheKeyGenerationError",
+    "CacheMiss",
+    "CacheResult",
+    "CacheTTL",
+    "CacheAspect",
+    "Cacheable",
+    "InMemoryCache",
+    "InvalidCacheTTLError",
+    "PLUGIN_NAME",
+    "cache_evict",
+    "cacheable",
+]

spakky_cache-6.3.1/src/spakky/cache/annotation.py

@@ -0,0 +1,54 @@
+"""Cache method annotations."""
+
+from dataclasses import dataclass
+from typing import Callable, ParamSpec, TypeVar
+
+from spakky.core.common.annotation import FunctionAnnotation
+
+from spakky.cache.interfaces.cache import CacheTTL
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+@dataclass
+class Cacheable(FunctionAnnotation):
+    """Annotation for caching method return values."""
+
+    key: str | None = None
+    """Optional format string used as the cache key."""
+
+    ttl: CacheTTL = None
+    """Optional cache entry TTL."""
+
+
+@dataclass
+class CacheEvict(FunctionAnnotation):
+    """Annotation for evicting a cache entry after successful method execution."""
+
+    key: str | None = None
+    """Optional format string used as the cache key."""
+
+
+def cacheable(
+    key: str | None = None,
+    *,
+    ttl: CacheTTL = None,
+) -> 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)(func)
+
+    return decorator
+
+
+def cache_evict(
+    key: str | None = None,
+) -> 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)(func)
+
+    return decorator

spakky_cache-6.3.1/src/spakky/cache/aspects/__init__.py

@@ -0,0 +1,5 @@
+"""Cache AOP aspects."""
+
+from spakky.cache.aspects.cache_aspect import AsyncCacheAspect, CacheAspect
+
+__all__ = ["AsyncCacheAspect", "CacheAspect"]

spakky_cache-6.3.1/src/spakky/cache/aspects/cache_aspect.py

@@ -0,0 +1,114 @@
+"""AOP aspects for cache annotations."""
+
+from inspect import iscoroutinefunction
+
+from spakky.core.aop.aspect import Aspect, AsyncAspect
+from spakky.core.aop.interfaces.aspect import IAspect, IAsyncAspect
+from spakky.core.aop.pointcut import Around
+from spakky.core.common.types import AsyncFunc, Func
+from spakky.core.pod.annotations.order import Order
+
+from spakky.cache.annotation import CacheEvict, Cacheable
+from spakky.cache.error import CacheKeyGenerationError
+from spakky.cache.interfaces.cache import ICache
+from spakky.cache.result import CacheHit
+
+
+def _matches_sync(method: Func) -> bool:
+    return (
+        Cacheable.exists(method) or CacheEvict.exists(method)
+    ) and not iscoroutinefunction(method)
+
+
+def _matches_async(method: Func) -> bool:
+    return (
+        Cacheable.exists(method) or CacheEvict.exists(method)
+    ) and iscoroutinefunction(method)
+
+
+def _key_from_call(
+    joinpoint: Func,
+    configured_key: str | None,
+    args: tuple[object, ...],
+    kwargs: dict[str, object],
+) -> str:
+    try:
+        if configured_key is not None:
+            return configured_key.format(*args, **kwargs)
+        ordered_kwargs = tuple(sorted(kwargs.items(), key=lambda item: item[0]))
+        return (
+            f"{joinpoint.__module__}.{joinpoint.__qualname__}:"
+            f"args={args!r}:kwargs={ordered_kwargs!r}"
+        )
+    except Exception as error:
+        raise CacheKeyGenerationError() from error
+
+
+@Order(0)
+@Aspect()
+class CacheAspect(IAspect):
+    """Aspect that applies cacheable and cache eviction annotations."""
+
+    _cache: ICache[object]
+
+    def __init__(self, cache: ICache[object]) -> None:
+        self._cache = cache
+
+    @Around(_matches_sync)
+    def around(
+        self,
+        joinpoint: Func,
+        *args: object,
+        **kwargs: object,
+    ) -> object:
+        evict = CacheEvict.get_or_none(joinpoint)
+        if evict is not None:
+            result = joinpoint(*args, **kwargs)
+            self._cache.delete(_key_from_call(joinpoint, evict.key, args, kwargs))
+            return result
+
+        cacheable = Cacheable.get(joinpoint)
+        key = _key_from_call(joinpoint, cacheable.key, args, kwargs)
+        cached = self._cache.get(key)
+        if isinstance(cached, CacheHit):
+            return cached.value
+
+        result = joinpoint(*args, **kwargs)
+        self._cache.set(key, result, ttl=cacheable.ttl)
+        return result
+
+
+@Order(0)
+@AsyncAspect()
+class AsyncCacheAspect(IAsyncAspect):
+    """Async aspect that applies cacheable and cache eviction annotations."""
+
+    _cache: ICache[object]
+
+    def __init__(self, cache: ICache[object]) -> None:
+        self._cache = cache
+
+    @Around(_matches_async)
+    async def around_async(
+        self,
+        joinpoint: AsyncFunc,
+        *args: object,
+        **kwargs: object,
+    ) -> object:
+        evict = CacheEvict.get_or_none(joinpoint)
+        if evict is not None:
+            result = await joinpoint(*args, **kwargs)
+            await self._cache.delete_async(
+                _key_from_call(joinpoint, evict.key, args, kwargs)
+            )
+            return result
+
+        cacheable = Cacheable.get(joinpoint)
+        key = _key_from_call(joinpoint, cacheable.key, args, kwargs)
+        cached = await self._cache.get_async(key)
+        if isinstance(cached, CacheHit):
+            return cached.value
+
+        result = await joinpoint(*args, **kwargs)
+        await self._cache.set_async(key, result, ttl=cacheable.ttl)
+        return result

spakky_cache-6.3.1/src/spakky/cache/backends/__init__.py

@@ -0,0 +1,5 @@
+"""Cache backend implementations."""
+
+from spakky.cache.backends.memory import InMemoryCache
+
+__all__ = ["InMemoryCache"]

spakky_cache-6.3.1/src/spakky/cache/backends/memory.py

@@ -0,0 +1,86 @@
+"""In-memory cache backend."""
+
+from collections.abc import Callable
+from datetime import timedelta
+from time import monotonic
+from typing import Generic, TypeVar
+
+from typing_extensions import override
+
+from spakky.cache.error import InvalidCacheTTLError
+from spakky.cache.interfaces.cache import ICache, CacheTTL
+from spakky.cache.result import CacheHit, CacheMiss, CacheResult
+from spakky.core.common.mutability import immutable
+from spakky.core.pod.annotations.pod import Pod
+
+T = TypeVar("T")
+
+
+@immutable
+class _CacheEntry(Generic[T]):
+    value: T
+    expires_at: float | None
+
+
+@Pod()
+class InMemoryCache(ICache[T]):
+    """Deterministic in-memory cache backend for one process."""
+
+    def __init__(self, *, clock: Callable[[], float] = monotonic) -> None:
+        self._clock = clock
+        self._entries: dict[str, _CacheEntry[T]] = {}
+
+    @override
+    def get(self, key: str) -> CacheResult[T]:
+        entry = self._entries.get(key)
+        if entry is None:
+            return CacheMiss()
+        if self._is_expired(entry):
+            self._entries.pop(key)
+            return CacheMiss()
+        return CacheHit(value=entry.value)
+
+    @override
+    def set(self, key: str, value: T, *, ttl: CacheTTL = None) -> None:
+        expires_at = self._compute_expires_at(ttl)
+        self._entries[key] = _CacheEntry(value=value, expires_at=expires_at)
+
+    @override
+    def delete(self, key: str) -> bool:
+        return self._entries.pop(key, None) is not None
+
+    @override
+    def clear(self) -> None:
+        self._entries.clear()
+
+    @override
+    async def get_async(self, key: str) -> CacheResult[T]:
+        return self.get(key)
+
+    @override
+    async def set_async(self, key: str, value: T, *, ttl: CacheTTL = None) -> None:
+        self.set(key, value, ttl=ttl)
+
+    @override
+    async def delete_async(self, key: str) -> bool:
+        return self.delete(key)
+
+    @override
+    async def clear_async(self) -> None:
+        self.clear()
+
+    def _compute_expires_at(self, ttl: CacheTTL) -> float | None:
+        if ttl is None:
+            return None
+        if isinstance(ttl, timedelta):
+            ttl_seconds = ttl.total_seconds()
+        else:
+            ttl_seconds = float(ttl)
+        if ttl_seconds <= 0:
+            raise InvalidCacheTTLError()
+        return self._clock() + ttl_seconds
+
+    def _is_expired(self, entry: _CacheEntry[T]) -> bool:
+        if entry.expires_at is None:
+            return False
+        return self._clock() >= entry.expires_at

spakky_cache-6.3.1/src/spakky/cache/error.py

@@ -0,0 +1,23 @@
+"""Error classes for the spakky-cache package."""
+
+from abc import ABC
+
+from spakky.core.common.error import AbstractSpakkyFrameworkError
+
+
+class AbstractSpakkyCacheError(AbstractSpakkyFrameworkError, ABC):
+    """Base class for cache-related errors."""
+
+    ...
+
+
+class InvalidCacheTTLError(AbstractSpakkyCacheError):
+    """Raised when a cache entry is written with an invalid TTL."""
+
+    message = "Cache TTL must be positive"
+
+
+class CacheKeyGenerationError(AbstractSpakkyCacheError):
+    """Raised when a cache annotation cannot produce a deterministic key."""
+
+    message = "Cache key generation failed"

spakky_cache-6.3.1/src/spakky/cache/interfaces/__init__.py

@@ -0,0 +1,5 @@
+"""Cache interface contracts."""
+
+from spakky.cache.interfaces.cache import ICache
+
+__all__ = ["ICache"]

spakky_cache-6.3.1/src/spakky/cache/interfaces/cache.py

@@ -0,0 +1,56 @@
+"""Backend-neutral cache contract."""
+
+from abc import ABC, abstractmethod
+from datetime import timedelta
+from typing import Generic, TypeAlias, TypeVar
+
+from spakky.cache.result import CacheResult
+
+CacheTTL: TypeAlias = float | int | timedelta | None
+"""Cache entry lifetime. None means no automatic expiry."""
+
+T = TypeVar("T")
+
+
+class ICache(ABC, Generic[T]):
+    """Backend-neutral application data cache contract."""
+
+    @abstractmethod
+    def get(self, key: str) -> CacheResult[T]:
+        """Return a typed hit or miss result for a cache key."""
+        ...
+
+    @abstractmethod
+    def set(self, key: str, value: T, *, ttl: CacheTTL = None) -> None:
+        """Store a cache value with an optional TTL."""
+        ...
+
+    @abstractmethod
+    def delete(self, key: str) -> bool:
+        """Remove one cache key and return whether an entry existed."""
+        ...
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Remove all cache entries from this backend instance."""
+        ...
+
+    @abstractmethod
+    async def get_async(self, key: str) -> CacheResult[T]:
+        """Async variant of get."""
+        ...
+
+    @abstractmethod
+    async def set_async(self, key: str, value: T, *, ttl: CacheTTL = None) -> None:
+        """Async variant of set."""
+        ...
+
+    @abstractmethod
+    async def delete_async(self, key: str) -> bool:
+        """Async variant of delete."""
+        ...
+
+    @abstractmethod
+    async def clear_async(self) -> None:
+        """Async variant of clear."""
+        ...

spakky_cache-6.3.1/src/spakky/cache/main.py

@@ -0,0 +1,17 @@
+"""Plugin initialization entry point."""
+
+from spakky.core.application.application import SpakkyApplication
+
+from spakky.cache.aspects.cache_aspect import AsyncCacheAspect, CacheAspect
+from spakky.cache.backends.memory import InMemoryCache
+
+
+def initialize(app: SpakkyApplication) -> None:
+    """Initialize the spakky-cache plugin.
+
+    Args:
+        app: The SpakkyApplication instance.
+    """
+    app.add(InMemoryCache)
+    app.add(CacheAspect)
+    app.add(AsyncCacheAspect)

spakky_cache-6.3.1/src/spakky/cache/py.typed

@@ -0,0 +1 @@
+

spakky_cache-6.3.1/src/spakky/cache/result.py

@@ -0,0 +1,23 @@
+"""Typed cache result contracts."""
+
+from typing import Generic, TypeAlias, TypeVar
+
+from spakky.core.common.mutability import immutable
+
+T = TypeVar("T")
+
+
+@immutable
+class CacheHit(Generic[T]):
+    """Cache lookup result for an existing entry."""
+
+    value: T
+
+
+@immutable
+class CacheMiss:
+    """Cache lookup result for a missing or expired entry."""
+
+
+CacheResult: TypeAlias = CacheHit[T] | CacheMiss
+"""Cache lookup result type."""