ab-cache 0.1.1__py3-none-any.whl

ab_cache-0.1.1.dist-info/METADATA

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: ab-cache
+Version: 0.1.1
+Author-email: Matthew Coulter <53892067+mattcoulter7@users.noreply.github.com>
+License-File: LICENSE
+Requires-Python: <4,>=3.12
+Requires-Dist: ab-dependency
+Requires-Dist: diskcache<6,>=5.6.3
+Requires-Dist: orjson<4,>=3.11.2
+Requires-Dist: pydantic<3,>=2.11.7
+Requires-Dist: slugify<0.0.2,>=0.0.1
+Requires-Dist: sqlmodel<0.0.25,>=0.0.24
+Requires-Dist: uuid7<0.2,>=0.1.0
+Provides-Extra: all
+Requires-Dist: redis<7,>=6.4.0; extra == 'all'
+Provides-Extra: redis-async
+Requires-Dist: redis<7,>=6.4.0; extra == 'redis-async'
+Provides-Extra: redis-sync
+Requires-Dist: redis<7,>=6.4.0; extra == 'redis-sync'
+Description-Content-Type: text/markdown
+
+# Open Banking, Opened | Database
+
+Database Package for Open Banking, Opened API packages.

ab_cache-0.1.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+ab_core/cache/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ab_core/cache/codec.py,sha256=F5NcEK0iuI4s1Tld-sgbPNZJHSX8LNhL5iI9xBEEeXo,503
+ab_core/cache/exceptions.py,sha256=y58IFOUCrs3PcoS2UTen-wiIieVmIeUPjaRDNjSgvVU,323
+ab_core/cache/namespace.py,sha256=QDbyOz8gtOfiGTS5RMNHVYFR8eF1tp2bZWtXGPqsUfM,628
+ab_core/cache/session_context.py,sha256=RllVnajJ1IURpdbcfCSd17EV1GYdwzd-Nz531VnhYZI,1859
+ab_core/cache/caches/__init__.py,sha256=Bok3B34ievCDZrI1siSbume2m4Mxioe32M0UR8hIy4o,305
+ab_core/cache/caches/base.py,sha256=kcxXTLaDU-GdxtAna2X-e7GiBlzi6qh6QqUAE43kd-4,3285
+ab_core/cache/caches/disk.py,sha256=Gh3hjrBTONbAHvpR88QndzVZ5tcFLebdrJJu2_cYIv0,15097
+ab_core/cache/caches/inmemory.py,sha256=F7QltcRl86BI-wKyTgXOwrmxjLuLfof83iRldFL_pPE,12331
+ab_core/cache/caches/redis.py,sha256=FN5YZb597Pzo4KxncODsqVvpWFa_ZAhItx4GRgwe_HE,11914
+ab_core/cache/caches/template.py,sha256=3vuhEoQZQW4b1_LO4XMMF3nCtDV7j1px6lQS0FKmwOk,4890
+ab_core/cache/schema/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ab_core/cache/schema/cache_type.py,sha256=VdQDSUaJ9X0Uclg78GH_UYNN__-brUdR7rM7faCcKZw,143
+ab_cache-0.1.1.dist-info/METADATA,sha256=0XVeSUZzBLmLazVoULt6jN6TFjTVFR_rPOjaOg8oSN4,785
+ab_cache-0.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ab_cache-0.1.1.dist-info/licenses/LICENSE,sha256=REBFOD_HdKi9ZZ38nP3A_NjpLFaijF1A6_PDiMglbLk,1072
+ab_cache-0.1.1.dist-info/RECORD,,

ab_cache-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ab_cache-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matthew Coulter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ab_core/cache/caches/__init__.py

@@ -0,0 +1,10 @@
+from typing import Annotated, Union
+
+from pydantic import Discriminator
+
+from .disk import DiskCache
+from .inmemory import InMemoryCache
+from .redis import RedisCache
+from .template import TemplateCache
+
+Cache = Annotated[Union[RedisCache, TemplateCache, InMemoryCache, DiskCache], Discriminator("type")]

ab_core/cache/caches/base.py

@@ -0,0 +1,134 @@
+from abc import ABC, abstractmethod
+from typing import (
+    Any,
+    AsyncContextManager,
+    ContextManager,
+    Generic,
+    Optional,
+    Self,
+    TypeVar,
+)
+
+from pydantic import BaseModel, Field
+
+from ab_core.cache.namespace import CacheNamespace
+
+
+class CacheSession(BaseModel, ABC):
+    namespace: CacheNamespace = Field(
+        default_factory=CacheNamespace,
+    )
+
+    @abstractmethod
+    def get(self, key: str): ...
+
+    @abstractmethod
+    def set(self, key: str, value, expiry: Optional[int] = None) -> bool: ...
+
+    @abstractmethod
+    def set_if_not_exists(self, key: str, value, expiry: Optional[int] = None) -> bool: ...
+
+    @abstractmethod
+    def delete(self, key: str) -> int: ...
+
+    @abstractmethod
+    def increment(
+        self,
+        key: str,
+        *,
+        increment_by: int = 1,
+        initial_value: Optional[int] = None,
+        expiry: Optional[int] = None,
+    ) -> int: ...
+
+    @abstractmethod
+    def get_keys(self, pattern: str = "*"): ...
+
+    @abstractmethod
+    def delete_keys(self, pattern: str = "*") -> int: ...
+
+    @abstractmethod
+    def get_ttl(self, key: str) -> int: ...
+
+    @abstractmethod
+    def expire(self, key: str, ttl: int) -> bool: ...
+
+    @abstractmethod
+    def close(self) -> None: ...
+
+    def __enter__(self: Self) -> Self:
+        return self
+
+    def __exit__(self, type_: Any, value: Any, traceback: Any) -> None:
+        self.close()
+
+
+class CacheAsyncSession(BaseModel, ABC):
+    namespace: CacheNamespace = Field(
+        default_factory=CacheNamespace,
+    )
+
+    @abstractmethod
+    async def get(self, key: str): ...
+
+    @abstractmethod
+    async def set(self, key: str, value, expiry: Optional[int] = None) -> bool: ...
+
+    @abstractmethod
+    async def set_if_not_exists(self, key: str, value, expiry: Optional[int] = None) -> bool: ...
+
+    @abstractmethod
+    async def delete(self, key: str) -> int: ...
+
+    @abstractmethod
+    async def increment(
+        self,
+        key: str,
+        *,
+        increment_by: int = 1,
+        initial_value: Optional[int] = None,
+        expiry: Optional[int] = None,
+    ) -> int: ...
+
+    @abstractmethod
+    async def get_keys(self, pattern: str = "*"): ...
+
+    @abstractmethod
+    async def delete_keys(self, pattern: str = "*") -> int: ...
+
+    @abstractmethod
+    async def get_ttl(self, key: str) -> int: ...
+
+    @abstractmethod
+    async def expire(self, key: str, ttl: int) -> bool: ...
+
+    @abstractmethod
+    async def close(self) -> None: ...
+
+    async def __aenter__(self: Self) -> Self:
+        return self
+
+    async def __aexit__(self, type_: Any, value: Any, traceback: Any) -> None:
+        await self.close()
+
+
+SYNC_SESSION = TypeVar("SYNC_SESSION", bound=CacheSession)
+ASYNC_SESSION = TypeVar("ASYNC_SESSION", bound=CacheAsyncSession)
+
+
+class CacheBase(BaseModel, Generic[SYNC_SESSION, ASYNC_SESSION], ABC):
+    namespace: CacheNamespace = Field(default_factory=CacheNamespace)
+
+    @abstractmethod
+    def sync_session(
+        self,
+        *,
+        current_session: Optional[SYNC_SESSION] = None,
+    ) -> ContextManager[SYNC_SESSION]: ...
+
+    @abstractmethod
+    async def async_session(
+        self,
+        *,
+        current_session: Optional[ASYNC_SESSION] = None,
+    ) -> AsyncContextManager[ASYNC_SESSION]: ...

ab_core/cache/caches/disk.py

@@ -0,0 +1,407 @@
+import asyncio
+import fnmatch
+import time
+from contextlib import asynccontextmanager, contextmanager
+from pathlib import Path
+from typing import AsyncIterator, Iterator, Literal, Optional, override
+
+import diskcache  # pip install diskcache
+from pydantic import ConfigDict, Field
+
+from ab_core.cache.codec import DecodedT, safe_decode, safe_encode
+from ab_core.cache.exceptions import GenericCacheReadError, GenericCacheWriteError
+
+from ..schema.cache_type import CacheType
+from .base import CacheAsyncSession, CacheBase, CacheSession
+
+# ────────────────────────────────────────────────────────────────────────────────
+# Sync Session
+# ────────────────────────────────────────────────────────────────────────────────
+
+
+class DiskCacheSyncSession(CacheSession):
+    """
+    Synchronous disk-backed session using `diskcache.Cache | diskcache.FanoutCache`.
+
+    - Keys are namespaced.
+    - Values are stored as EncodedT (bytes-like) via `safe_encode`.
+    - Expiration is handled by DiskCache per-item `expire` seconds.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    cache: diskcache.Cache | diskcache.FanoutCache = Field(..., exclude=True)
+
+    def _get_with_expire_time(self, k: str):
+        # Returns `None` if missing, else a tuple (value, expire_time)
+        _missing = object()
+        res = self.cache.get(k, default=_missing, expire_time=True)
+        return None if res is _missing else res  # type: ignore[return-value]
+
+    @override
+    def get(self, key: str) -> DecodedT:
+        k = self.namespace.apply(key)
+        try:
+            res = self._get_with_expire_time(k)
+            if res is None:
+                raise KeyError(f"No data found for key `{k}`")
+            value, expire_time = res
+            # If value is present but already expired by race, DiskCache returns default.
+            return safe_decode(value)
+        except KeyError:
+            raise
+        except Exception as e:
+            raise GenericCacheReadError(e) from e
+
+    @override
+    def set(self, key: str, value, expiry: Optional[int] = None) -> bool:
+        k = self.namespace.apply(key)
+        try:
+            return bool(self.cache.set(k, safe_encode(value), expire=expiry))
+        except Exception as e:
+            raise GenericCacheWriteError(e) from e
+
+    @override
+    def set_if_not_exists(self, key: str, value, expiry: Optional[int] = None) -> bool:
+        k = self.namespace.apply(key)
+        try:
+            # `add` stores only if missing
+            return bool(self.cache.add(k, safe_encode(value), expire=expiry))
+        except Exception as e:
+            raise GenericCacheWriteError(e) from e
+
+    @override
+    def delete(self, key: str) -> int:
+        k = self.namespace.apply(key)
+        try:
+            return 1 if self.cache.delete(k) else 0
+        except Exception as e:
+            raise GenericCacheWriteError(e) from e
+
+    @override
+    def increment(
+        self,
+        key: str,
+        *,
+        increment_by: int = 1,
+        initial_value: Optional[int] = None,
+        expiry: Optional[int] = None,
+    ) -> int:
+        k = self.namespace.apply(key)
+        try:
+            # mirror in-memory semantics (store integer as utf-8 bytes)
+            with self.cache.transact():
+                res = self._get_with_expire_time(k)
+                if res is None:
+                    new_val = int(initial_value or 0)
+                    self.cache.set(k, str(new_val).encode("utf-8"), expire=expiry)
+                    return new_val
+                value, _ = res
+                try:
+                    current = int(safe_decode(value))
+                except Exception as conv:
+                    raise GenericCacheWriteError(f"Value for key `{k}` is not an integer") from conv
+                new_val = current + int(increment_by)
+                # do NOT change expiry for existing key (parity with Redis impl)
+                self.cache.set(k, str(new_val).encode("utf-8"))
+                return new_val
+        except GenericCacheWriteError:
+            raise
+        except Exception as e:
+            raise GenericCacheWriteError(e) from e
+
+    @override
+    def get_keys(self, pattern: str = "*") -> list[str]:
+        pat = self.namespace.apply(pattern)
+        try:
+            out: list[str] = []
+            # iterkeys() may include expired; verify liveness via get(...)
+            for k in self.cache.iterkeys():
+                if not isinstance(k, str):
+                    continue
+                if not fnmatch.fnmatch(k, pat):
+                    continue
+                res = self._get_with_expire_time(k)
+                if res is None:
+                    continue  # missing/expired
+                out.append(self.namespace.strip(k))
+            return out
+        except Exception as e:
+            raise GenericCacheReadError(e) from e
+
+    @override
+    def delete_keys(self, pattern: str = "*") -> int:
+        pat = self.namespace.apply(pattern)
+        try:
+            deleted = 0
+            for k in list(self.cache.iterkeys()):
+                if isinstance(k, str) and fnmatch.fnmatch(k, pat):
+                    if self.cache.delete(k):
+                        deleted += 1
+            return deleted
+        except Exception as e:
+            raise GenericCacheWriteError(e) from e
+
+    @override
+    def get_ttl(self, key: str) -> int:
+        k = self.namespace.apply(key)
+        try:
+            res = self._get_with_expire_time(k)
+            if res is None:
+                raise KeyError(f"No data found for key `{k}`")
+            _, exp = res
+            if exp is None:
+                return -1  # no expiration
+            ttl = int(exp - time.time())
+            if ttl < 0:
+                # already expired in-between; treat as missing now
+                self.cache.delete(k)
+                raise KeyError(f"No data found for key `{k}`")
+            return ttl
+        except KeyError:
+            raise
+        except Exception as e:
+            raise GenericCacheReadError(e) from e
+
+    @override
+    def expire(self, key: str, ttl: int) -> bool:
+        k = self.namespace.apply(key)
+        try:
+            return bool(self.cache.touch(k, expire=int(ttl)))
+        except Exception as e:
+            raise GenericCacheWriteError(e) from e
+
+    @override
+    def close(self) -> None:
+        try:
+            self.cache.close()
+        except Exception:
+            pass
+
+
+# ────────────────────────────────────────────────────────────────────────────────
+# Async Session (wrap sync DiskCache with to_thread)
+# ────────────────────────────────────────────────────────────────────────────────
+
+
+class DiskCacheAsyncSession(CacheAsyncSession):
+    """
+    Async facade for `diskcache.Cache | diskcache.FanoutCache` wrapped with `asyncio.to_thread`.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    cache: diskcache.Cache | diskcache.FanoutCache = Field(..., exclude=True)
+
+    def _ns(self, key: str) -> str:
+        return self.namespace.apply(key)
+
+    @override
+    async def get(self, key: str) -> DecodedT:
+        k = self._ns(key)
+
+        def _work():
+            _missing = object()
+            res = self.cache.get(k, default=_missing, expire_time=True)
+            if res is _missing:
+                raise KeyError(f"No data found for key `{k}`")
+            value, _ = res
+            return safe_decode(value)
+
+        try:
+            return await asyncio.to_thread(_work)
+        except KeyError:
+            raise
+        except Exception as e:
+            raise GenericCacheReadError(e) from e
+
+    @override
+    async def set(self, key: str, value, expiry: Optional[int] = None) -> bool:
+        k = self._ns(key)
+        try:
+            return await asyncio.to_thread(self.cache.set, k, safe_encode(value), expiry)
+        except Exception as e:
+            raise GenericCacheWriteError(e) from e
+
+    @override
+    async def set_if_not_exists(self, key: str, value, expiry: Optional[int] = None) -> bool:
+        k = self._ns(key)
+        try:
+            return await asyncio.to_thread(self.cache.add, k, safe_encode(value), expiry)
+        except Exception as e:
+            raise GenericCacheWriteError(e) from e
+
+    @override
+    async def delete(self, key: str) -> int:
+        k = self._ns(key)
+        try:
+            ok = await asyncio.to_thread(self.cache.delete, k)
+            return 1 if ok else 0
+        except Exception as e:
+            raise GenericCacheWriteError(e) from e
+
+    @override
+    async def increment(
+        self,
+        key: str,
+        *,
+        increment_by: int = 1,
+        initial_value: Optional[int] = None,
+        expiry: Optional[int] = None,
+    ) -> int:
+        k = self._ns(key)
+
+        def _work() -> int:
+            with self.cache.transact():
+                _missing = object()
+                res = self.cache.get(k, default=_missing, expire_time=True)
+                if res is _missing:
+                    new_val = int(initial_value or 0)
+                    self.cache.set(k, str(new_val).encode("utf-8"), expire=expiry)
+                    return new_val
+                value, _ = res
+                try:
+                    current = int(safe_decode(value))
+                except Exception as conv:
+                    raise GenericCacheWriteError(f"Value for key `{k}` is not an integer") from conv
+                new_val = current + int(increment_by)
+                self.cache.set(k, str(new_val).encode("utf-8"))
+                return new_val
+
+        try:
+            return await asyncio.to_thread(_work)
+        except GenericCacheWriteError:
+            raise
+        except Exception as e:
+            raise GenericCacheWriteError(e) from e
+
+    @override
+    async def get_keys(self, pattern: str = "*") -> list[str]:
+        pat = self.namespace.apply(pattern)
+
+        def _work() -> list[str]:
+            out: list[str] = []
+            for k in self.cache.iterkeys():
+                if not isinstance(k, str):
+                    continue
+                if not fnmatch.fnmatch(k, pat):
+                    continue
+                _missing = object()
+                res = self.cache.get(k, default=_missing, expire_time=True)
+                if res is _missing:
+                    continue
+                out.append(self.namespace.strip(k))
+            return out
+
+        try:
+            return await asyncio.to_thread(_work)
+        except Exception as e:
+            raise GenericCacheReadError(e) from e
+
+    @override
+    async def delete_keys(self, pattern: str = "*") -> int:
+        pat = self.namespace.apply(pattern)
+
+        def _work() -> int:
+            deleted = 0
+            for k in list(self.cache.iterkeys()):
+                if isinstance(k, str) and fnmatch.fnmatch(k, pat):
+                    if self.cache.delete(k):
+                        deleted += 1
+            return deleted
+
+        try:
+            return await asyncio.to_thread(_work)
+        except Exception as e:
+            raise GenericCacheWriteError(e) from e
+
+    @override
+    async def get_ttl(self, key: str) -> int:
+        k = self._ns(key)
+
+        def _work() -> int:
+            _missing = object()
+            res = self.cache.get(k, default=_missing, expire_time=True)
+            if res is _missing:
+                raise KeyError(f"No data found for key `{k}`")
+            _, exp = res
+            if exp is None:
+                return -1
+            ttl = int(exp - time.time())
+            if ttl < 0:
+                self.cache.delete(k)
+                raise KeyError(f"No data found for key `{k}`")
+            return ttl
+
+        try:
+            return await asyncio.to_thread(_work)
+        except KeyError:
+            raise
+        except Exception as e:
+            raise GenericCacheReadError(e) from e
+
+    @override
+    async def expire(self, key: str, ttl: int) -> bool:
+        k = self._ns(key)
+        try:
+            return await asyncio.to_thread(self.cache.touch, k, int(ttl))
+        except Exception as e:
+            raise GenericCacheWriteError(e) from e
+
+    @override
+    async def close(self) -> None:
+        try:
+            await asyncio.to_thread(self.cache.close)
+        except Exception:
+            pass
+
+
+# ────────────────────────────────────────────────────────────────────────────────
+# Cache factory
+# ────────────────────────────────────────────────────────────────────────────────
+
+
+class DiskCache(CacheBase[DiskCacheSyncSession, DiskCacheAsyncSession]):
+    # Adjust enum name if your CacheType differs, e.g. DISKCACHE or DISK_CACHE
+    type: Literal[CacheType.DISK] = CacheType.DISK
+
+    # Where to persist on disk (e.g. a container volume path)
+    directory: Path = Field(..., description="Directory for diskcache storage")
+    timeout: int = Field(default=60, description="Timeout for path cache")
+
+    # Fanout options
+    fanout: bool = Field(False, description="Use diskcache.FanoutCache instead of Cache")
+    shards: int = Field(8, description="Number of shards when using FanoutCache")
+
+    def _new_cache(self) -> diskcache.Cache | diskcache.FanoutCache:
+        if self.fanout:
+            return diskcache.FanoutCache(self.directory, timeout=self.timeout, shards=self.shards)
+        return diskcache.Cache(self.directory, timeout=self.timeout)
+
+    @override
+    @contextmanager
+    def sync_session(
+        self,
+        *,
+        current_session: Optional[DiskCacheSyncSession] = None,
+    ) -> Iterator[DiskCacheSyncSession]:
+        if current_session:
+            yield current_session
+        else:
+            with DiskCacheSyncSession(namespace=self.namespace, cache=self._new_cache()) as session:
+                yield session
+
+    @override
+    @asynccontextmanager
+    async def async_session(
+        self,
+        *,
+        current_session: Optional[DiskCacheAsyncSession] = None,
+    ) -> AsyncIterator[DiskCacheAsyncSession]:
+        if current_session:
+            yield current_session
+        else:
+            async with DiskCacheAsyncSession(
+                namespace=self.namespace, cache=self._new_cache()
+            ) as session:
+                yield session