tiercache 0.1.0__py3-none-any.whl

smartcache/__init__.py

@@ -0,0 +1,41 @@
+"""
+SmartCache — RAM-first three-tier cache with swappable backends.
+
+Quick start:
+
+    from smartcache import CacheManager
+
+    # From config file
+    cache = CacheManager.from_config("smartcache.yaml")
+
+    # Or in code
+    from smartcache import CacheManager
+    from smartcache.backends.ram import RamBackend
+    from smartcache.backends.dry.local import LocalBackend
+    from smartcache.tracking.sqlite import SQLiteTracking
+
+    cache = CacheManager(
+        hot=RamBackend(ttl_seconds=14400, max_size_bytes=2 * 1024**3),
+        cold=RamBackend(ttl_seconds=86400, max_size_bytes=10 * 1024**3),
+        dry=LocalBackend(base_path="/var/cache/smartcache", max_size_bytes=100 * 1024**3),
+        tracking=SQLiteTracking(path="/var/cache/smartcache/index.db"),
+    )
+
+    value = await cache.get("my-key")
+    await cache.set("my-key", data)
+    await cache.set("my-key", data, ttl_hours=2)
+    await cache.set("my-key", data, tags={"type": "thumbnail"})
+"""
+
+from .manager import CacheManager, TTLResolver
+from .backends.base import AbstractBackend
+from .tracking.base import AbstractTracking
+
+__all__ = [
+    "CacheManager",
+    "TTLResolver",
+    "AbstractBackend",
+    "AbstractTracking",
+]
+
+__version__ = "0.1.0"

smartcache/backends/base.py

@@ -0,0 +1,29 @@
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+
+class AbstractBackend(ABC):
+
+    @abstractmethod
+    async def get(self, key: str) -> Optional[Any]:
+        """Return value for key, or None if missing / expired."""
+
+    @abstractmethod
+    async def set(self, key: str, value: Any, ttl_seconds: Optional[int] = None) -> None:
+        """Store value. ttl_seconds=None means no expiry."""
+
+    @abstractmethod
+    async def delete(self, key: str) -> None:
+        """Remove a key. No-op if not found."""
+
+    @abstractmethod
+    async def flush(self) -> None:
+        """Clear all entries."""
+
+    @abstractmethod
+    async def size_bytes(self) -> int:
+        """Current memory/storage usage in bytes."""
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Release any connections or resources."""

smartcache/backends/dry/local.py

@@ -0,0 +1,109 @@
+import hashlib
+import json
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+import aiofiles
+import aiofiles.os
+
+from ...serializer import dumps, loads
+from ..base import AbstractBackend
+
+
+class LocalBackend(AbstractBackend):
+    """
+    Local filesystem dry cache. Values are stored as pickled binary files
+    with a JSON sidecar for metadata (TTL, key, created_at).
+
+    Files are sharded into subdirectories by the first 4 hex chars of the
+    key hash to avoid large flat directories.
+
+    Requires: aiofiles (included in base install)
+    """
+
+    def __init__(self, base_path: str, max_size_bytes: int) -> None:
+        self._base = Path(base_path)
+        self._max_size = max_size_bytes
+        self._base.mkdir(parents=True, exist_ok=True)
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    async def get(self, key: str) -> Optional[Any]:
+        data_path, meta_path = self._paths(key)
+        if not data_path.exists():
+            return None
+        meta = self._read_meta(meta_path)
+        if meta is None:
+            return None
+        if self._expired(meta):
+            await self._remove_files(data_path, meta_path)
+            return None
+        async with aiofiles.open(data_path, "rb") as f:
+            return loads(await f.read())
+
+    async def set(self, key: str, value: Any, ttl_seconds: Optional[int] = None) -> None:
+        data_path, meta_path = self._paths(key)
+        data_path.parent.mkdir(parents=True, exist_ok=True)
+        raw = dumps(value)
+        async with aiofiles.open(data_path, "wb") as f:
+            await f.write(raw)
+        meta = {
+            "key": key,
+            "created_at": time.time(),
+            "ttl_seconds": ttl_seconds,
+            "size": len(raw),
+        }
+        async with aiofiles.open(meta_path, "w") as f:
+            await f.write(json.dumps(meta))
+
+    async def delete(self, key: str) -> None:
+        data_path, meta_path = self._paths(key)
+        await self._remove_files(data_path, meta_path)
+
+    async def flush(self) -> None:
+        import shutil
+        shutil.rmtree(self._base, ignore_errors=True)
+        self._base.mkdir(parents=True, exist_ok=True)
+
+    async def size_bytes(self) -> int:
+        total = 0
+        for p in self._base.rglob("*.bin"):
+            total += p.stat().st_size
+        return total
+
+    async def close(self) -> None:
+        pass
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _paths(self, key: str) -> tuple[Path, Path]:
+        h = hashlib.sha256(key.encode()).hexdigest()
+        shard = self._base / h[:2] / h[2:4]
+        return shard / f"{h}.bin", shard / f"{h}.meta.json"
+
+    @staticmethod
+    def _read_meta(path: Path) -> Optional[dict]:
+        try:
+            return json.loads(path.read_text())
+        except (FileNotFoundError, json.JSONDecodeError):
+            return None
+
+    @staticmethod
+    def _expired(meta: dict) -> bool:
+        ttl = meta.get("ttl_seconds")
+        if not ttl:
+            return False
+        return time.time() > meta["created_at"] + ttl
+
+    @staticmethod
+    async def _remove_files(*paths: Path) -> None:
+        for p in paths:
+            try:
+                await aiofiles.os.remove(p)
+            except FileNotFoundError:
+                pass

smartcache/backends/dry/mongodb.py

@@ -0,0 +1,103 @@
+import time
+from typing import Any, Optional
+
+from ...serializer import dumps, loads
+from ..base import AbstractBackend
+
+
+class MongoDBBackend(AbstractBackend):
+    """
+    MongoDB GridFS dry cache using motor (async driver).
+    Large values are stored via GridFS; metadata (TTL, key) lives in the
+    files collection. A TTL index on `metadata.expires_at` lets MongoDB
+    handle expiry automatically — no cron job needed.
+
+    Requires: pip install smartcache[mongodb]
+    """
+
+    def __init__(self, uri: str, database: str) -> None:
+        try:
+            import motor.motor_asyncio as motor
+        except ImportError:
+            raise ImportError(
+                "MongoDB backend requires motor. "
+                "Install it with: pip install smartcache[mongodb]"
+            )
+        self._motor = motor
+        self._uri = uri
+        self._database = database
+        self._client: Optional[Any] = None
+        self._fs: Optional[Any] = None
+
+    async def _get_fs(self) -> Any:
+        if self._fs is None:
+            import motor.motor_asyncio as motor
+            from motor.motor_asyncio import AsyncIOMotorGridFSBucket
+            self._client = motor.AsyncIOMotorClient(self._uri)
+            db = self._client[self._database]
+            self._fs = AsyncIOMotorGridFSBucket(db, bucket_name="smartcache")
+            # Ensure TTL index on expires_at metadata field
+            await db["smartcache.files"].create_index(
+                "metadata.expires_at",
+                expireAfterSeconds=0,
+                sparse=True,
+            )
+        return self._fs
+
+    async def get(self, key: str) -> Optional[Any]:
+        fs = await self._get_fs()
+        cursor = fs.find({"metadata.cache_key": key})
+        docs = await cursor.to_list(length=1)
+        if not docs:
+            return None
+        doc = docs[0]
+        expires_at = doc.get("metadata", {}).get("expires_at")
+        if expires_at and time.time() > expires_at:
+            await fs.delete(doc["_id"])
+            return None
+        stream = await fs.open_download_stream(doc["_id"])
+        raw = await stream.read()
+        return loads(raw)
+
+    async def set(self, key: str, value: Any, ttl_seconds: Optional[int] = None) -> None:
+        fs = await self._get_fs()
+        # Delete existing entry for this key first
+        await self.delete(key)
+        raw = dumps(value)
+        metadata: dict[str, Any] = {"cache_key": key, "created_at": time.time()}
+        if ttl_seconds:
+            metadata["expires_at"] = time.time() + ttl_seconds
+        await fs.upload_from_stream(
+            key,
+            raw,
+            metadata=metadata,
+        )
+
+    async def delete(self, key: str) -> None:
+        fs = await self._get_fs()
+        cursor = fs.find({"metadata.cache_key": key})
+        docs = await cursor.to_list(length=None)
+        for doc in docs:
+            await fs.delete(doc["_id"])
+
+    async def flush(self) -> None:
+        fs = await self._get_fs()
+        cursor = fs.find({})
+        docs = await cursor.to_list(length=None)
+        for doc in docs:
+            await fs.delete(doc["_id"])
+
+    async def size_bytes(self) -> int:
+        if self._client is None:
+            return 0
+        db = self._client[self._database]
+        result = await db["smartcache.files"].aggregate([
+            {"$group": {"_id": None, "total": {"$sum": "$length"}}}
+        ]).to_list(length=1)
+        return result[0]["total"] if result else 0
+
+    async def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+            self._fs = None

smartcache/backends/dry/s3.py

@@ -0,0 +1,119 @@
+import time
+from typing import Any, Optional
+
+from ...serializer import dumps, loads
+from ..base import AbstractBackend
+
+_META_TTL_KEY    = "x-smartcache-ttl"
+_META_CREATED_KEY = "x-smartcache-created"
+
+
+class S3Backend(AbstractBackend):
+    """
+    S3-compatible dry cache using aioboto3.
+    TTL is stored as object metadata and checked on get.
+
+    Compatible with: AWS S3, MinIO, Cloudflare R2, and any S3-compatible service.
+
+    Requires: pip install smartcache[s3]
+    """
+
+    def __init__(
+        self,
+        bucket: str,
+        endpoint_url: Optional[str] = None,
+        access_key: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        prefix: str = "smartcache/",
+    ) -> None:
+        try:
+            import aioboto3
+        except ImportError:
+            raise ImportError(
+                "S3 backend requires aioboto3. "
+                "Install it with: pip install smartcache[s3]"
+            )
+        self._aioboto3 = aioboto3
+        self._bucket = bucket
+        self._endpoint_url = endpoint_url
+        self._access_key = access_key
+        self._secret_key = secret_key
+        self._prefix = prefix
+        self._session: Optional[Any] = None
+
+    def _object_key(self, key: str) -> str:
+        return f"{self._prefix}{key}"
+
+    def _session_kwargs(self) -> dict:
+        kwargs: dict = {}
+        if self._access_key:
+            kwargs["aws_access_key_id"] = self._access_key
+        if self._secret_key:
+            kwargs["aws_secret_access_key"] = self._secret_key
+        return kwargs
+
+    async def get(self, key: str) -> Optional[Any]:
+        session = self._aioboto3.Session(**self._session_kwargs())
+        async with session.client("s3", endpoint_url=self._endpoint_url) as s3:
+            try:
+                response = await s3.get_object(
+                    Bucket=self._bucket, Key=self._object_key(key)
+                )
+            except s3.exceptions.NoSuchKey:
+                return None
+            except Exception:
+                return None
+
+            meta = response.get("Metadata", {})
+            ttl = meta.get(_META_TTL_KEY)
+            created = meta.get(_META_CREATED_KEY)
+            if ttl and created:
+                if time.time() > float(created) + int(ttl):
+                    await self.delete(key)
+                    return None
+
+            body = await response["Body"].read()
+            return loads(body)
+
+    async def set(self, key: str, value: Any, ttl_seconds: Optional[int] = None) -> None:
+        session = self._aioboto3.Session(**self._session_kwargs())
+        raw = dumps(value)
+        meta: dict[str, str] = {_META_CREATED_KEY: str(time.time())}
+        if ttl_seconds:
+            meta[_META_TTL_KEY] = str(ttl_seconds)
+        async with session.client("s3", endpoint_url=self._endpoint_url) as s3:
+            await s3.put_object(
+                Bucket=self._bucket,
+                Key=self._object_key(key),
+                Body=raw,
+                Metadata=meta,
+            )
+
+    async def delete(self, key: str) -> None:
+        session = self._aioboto3.Session(**self._session_kwargs())
+        async with session.client("s3", endpoint_url=self._endpoint_url) as s3:
+            await s3.delete_object(Bucket=self._bucket, Key=self._object_key(key))
+
+    async def flush(self) -> None:
+        session = self._aioboto3.Session(**self._session_kwargs())
+        async with session.client("s3", endpoint_url=self._endpoint_url) as s3:
+            paginator = s3.get_paginator("list_objects_v2")
+            async for page in paginator.paginate(Bucket=self._bucket, Prefix=self._prefix):
+                objects = [{"Key": o["Key"]} for o in page.get("Contents", [])]
+                if objects:
+                    await s3.delete_objects(
+                        Bucket=self._bucket, Delete={"Objects": objects}
+                    )
+
+    async def size_bytes(self) -> int:
+        total = 0
+        session = self._aioboto3.Session(**self._session_kwargs())
+        async with session.client("s3", endpoint_url=self._endpoint_url) as s3:
+            paginator = s3.get_paginator("list_objects_v2")
+            async for page in paginator.paginate(Bucket=self._bucket, Prefix=self._prefix):
+                for obj in page.get("Contents", []):
+                    total += obj.get("Size", 0)
+        return total
+
+    async def close(self) -> None:
+        pass

smartcache/backends/memcached.py

@@ -0,0 +1,115 @@
+from typing import Any, Optional
+
+from ..serializer import dumps, loads
+from .base import AbstractBackend
+
+# Memcached default max item size is 1MB.
+# We chunk at 900KB to stay safely under the limit regardless of server config.
+_CHUNK_SIZE = 900 * 1024  # 900 KB
+_META_SUFFIX = b"__chunks__"
+
+
+class MemcachedBackend(AbstractBackend):
+    """
+    Memcached-backed RAM cache using aiomcache.
+    Values are pickled before storage.
+    Large values are automatically split into 900KB chunks and reassembled
+    on get — no server-side config needed regardless of item size.
+    TTL is enforced natively by Memcached.
+    Suitable for multi-process or multi-server deployments.
+
+    Requires: pip install smartcache[memcached]
+    """
+
+    def __init__(self, host: str, port: int, ttl_seconds: int, max_size_bytes: int) -> None:
+        try:
+            import aiomcache
+        except ImportError:
+            raise ImportError(
+                "Memcached backend requires aiomcache. "
+                "Install it with: pip install smartcache[memcached]"
+            )
+        self._aiomcache = aiomcache
+        self._host = host
+        self._port = port
+        self._ttl = ttl_seconds
+        self._max_size = max_size_bytes
+        self._client: Optional[Any] = None
+
+    async def _get_client(self) -> Any:
+        if self._client is None:
+            self._client = self._aiomcache.Client(self._host, self._port)
+        return self._client
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    async def get(self, key: str) -> Optional[Any]:
+        client = await self._get_client()
+        bkey = key.encode()
+
+        # Check if this key was stored in chunks
+        meta_raw = await client.get(bkey + _META_SUFFIX)
+        if meta_raw is not None:
+            n_chunks = int(meta_raw)
+            chunks = []
+            for i in range(n_chunks):
+                chunk = await client.get(f"{key}__chunk_{i}".encode())
+                if chunk is None:
+                    return None  # partial expiry — treat as miss
+                chunks.append(chunk)
+            return loads(b"".join(chunks))
+
+        # Single item
+        raw = await client.get(bkey)
+        if raw is None:
+            return None
+        return loads(raw)
+
+    async def set(self, key: str, value: Any, ttl_seconds: Optional[int] = None) -> None:
+        ttl = ttl_seconds if ttl_seconds is not None else self._ttl
+        exptime = ttl or 0
+        client = await self._get_client()
+        raw = dumps(value)
+
+        if len(raw) <= _CHUNK_SIZE:
+            await client.set(key.encode(), raw, exptime=exptime)
+            return
+
+        # Split into chunks
+        chunks = [raw[i: i + _CHUNK_SIZE] for i in range(0, len(raw), _CHUNK_SIZE)]
+        for i, chunk in enumerate(chunks):
+            await client.set(f"{key}__chunk_{i}".encode(), chunk, exptime=exptime)
+        # Store chunk count as metadata key
+        await client.set(
+            key.encode() + _META_SUFFIX,
+            str(len(chunks)).encode(),
+            exptime=exptime,
+        )
+
+    async def delete(self, key: str) -> None:
+        client = await self._get_client()
+        bkey = key.encode()
+
+        meta_raw = await client.get(bkey + _META_SUFFIX)
+        if meta_raw is not None:
+            n_chunks = int(meta_raw)
+            for i in range(n_chunks):
+                await client.delete(f"{key}__chunk_{i}".encode())
+            await client.delete(bkey + _META_SUFFIX)
+        else:
+            await client.delete(bkey)
+
+    async def flush(self) -> None:
+        client = await self._get_client()
+        await client.flush_all()
+
+    async def size_bytes(self) -> int:
+        # Memcached does not expose per-key sizes
+        return 0
+
+    async def close(self) -> None:
+        if self._client is not None:
+            await self._client.close()
+            self._client = None

smartcache/backends/ram.py

@@ -0,0 +1,101 @@
+import asyncio
+import sys
+import time
+from collections import OrderedDict
+from typing import Any, Awaitable, Callable, Optional
+
+from .base import AbstractBackend
+
+EvictCallback = Callable[[str, Any], Awaitable[None]]
+
+
+class RamBackend(AbstractBackend):
+    """
+    In-process RAM cache using an OrderedDict for O(1) LRU eviction.
+    TTL is checked lazily on get. Size is estimated from value length (bytes)
+    or sys.getsizeof for other types.
+
+    on_evict: optional async callback(key, value) fired when an entry is
+    dropped due to LRU pressure or TTL expiry. Used by CacheManager to
+    demote evicted entries to dry cache (failsafe).
+    """
+
+    def __init__(
+        self,
+        ttl_seconds: int,
+        max_size_bytes: int,
+        on_evict: Optional[EvictCallback] = None,
+    ) -> None:
+        self._ttl = ttl_seconds
+        self._max_size = max_size_bytes
+        self._on_evict = on_evict
+        # key -> (value, expiry_monotonic)  expiry=0 means no expiry
+        self._store: OrderedDict[str, tuple[Any, float]] = OrderedDict()
+        self._current_size = 0
+        self._lock = asyncio.Lock()
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    async def get(self, key: str) -> Optional[Any]:
+        async with self._lock:
+            entry = self._store.get(key)
+            if entry is None:
+                return None
+            value, expiry = entry
+            if self._expired(expiry):
+                self._remove(key, evict=False)  # expired — don't demote to dry
+                return None
+            self._store.move_to_end(key)
+            return value
+
+    async def set(self, key: str, value: Any, ttl_seconds: Optional[int] = None) -> None:
+        ttl = ttl_seconds if ttl_seconds is not None else self._ttl
+        expiry = time.monotonic() + ttl if ttl else 0.0
+        size = self._measure(value)
+        async with self._lock:
+            if key in self._store:
+                old_value, _ = self._store[key]
+                self._current_size -= self._measure(old_value)
+            while self._current_size + size > self._max_size and self._store:
+                self._remove(next(iter(self._store)), evict=True)  # LRU — demote to dry
+            self._store[key] = (value, expiry)
+            self._store.move_to_end(key)
+            self._current_size += size
+
+    async def delete(self, key: str) -> None:
+        async with self._lock:
+            if key in self._store:
+                self._remove(key, evict=False)  # explicit delete — don't demote to dry
+
+    async def flush(self) -> None:
+        async with self._lock:
+            self._store.clear()
+            self._current_size = 0
+
+    async def size_bytes(self) -> int:
+        return self._current_size
+
+    async def close(self) -> None:
+        pass
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _remove(self, key: str, evict: bool = False) -> None:
+        value, _ = self._store.pop(key)
+        self._current_size -= self._measure(value)
+        if evict and self._on_evict is not None:
+            asyncio.create_task(self._on_evict(key, value))
+
+    @staticmethod
+    def _expired(expiry: float) -> bool:
+        return expiry != 0.0 and time.monotonic() > expiry
+
+    @staticmethod
+    def _measure(value: Any) -> int:
+        if isinstance(value, (bytes, bytearray, memoryview)):
+            return len(value)
+        return sys.getsizeof(value)