phzyx-cache 0.1.0__py3-none-any.whl

phzyx/cache/__init__.py

@@ -0,0 +1,13 @@
+"""Phzyx versioned resource cache."""
+
+from phzyx.cache.backends import MemoryCache, RedisCache
+from phzyx.cache.resource import ResourceCache
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MemoryCache",
+    "RedisCache",
+    "ResourceCache",
+    "__version__",
+]

phzyx/cache/backends.py

@@ -0,0 +1,76 @@
+"""Cache backends — memory and optional Redis."""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class CacheBackend(Protocol):
+    def get(self, key: str) -> str | None: ...
+
+    def set(self, key: str, value: str, *, ttl: int | None = None) -> None: ...
+
+    def delete(self, key: str) -> None: ...
+
+
+@dataclass
+class MemoryCache:
+    """Process-local cache with optional TTL."""
+
+    _data: dict[str, tuple[str, float | None]] = field(default_factory=dict)
+
+    def get(self, key: str) -> str | None:
+        item = self._data.get(key)
+        if item is None:
+            return None
+        value, expires = item
+        if expires is not None and time.time() > expires:
+            self._data.pop(key, None)
+            return None
+        return value
+
+    def set(self, key: str, value: str, *, ttl: int | None = None) -> None:
+        exp = time.time() + ttl if ttl else None
+        self._data[key] = (value, exp)
+
+    def delete(self, key: str) -> None:
+        self._data.pop(key, None)
+
+
+class RedisCache:
+    """Redis string cache (optional redis package)."""
+
+    def __init__(self, client: Any | None = None, *, url: str = "redis://localhost:6379/0") -> None:
+        if client is not None:
+            self._client = client
+        else:
+            try:
+                import redis  # type: ignore[import-not-found]
+            except ImportError as exc:  # pragma: no cover
+                raise ImportError("uv add 'phzyx-cache[redis]'") from exc
+            self._client = redis.Redis.from_url(url, decode_responses=True)
+
+    def get(self, key: str) -> str | None:
+        val = self._client.get(key)
+        return None if val is None else str(val)
+
+    def set(self, key: str, value: str, *, ttl: int | None = None) -> None:
+        if ttl:
+            self._client.setex(key, ttl, value)
+        else:
+            self._client.set(key, value)
+
+    def delete(self, key: str) -> None:
+        self._client.delete(key)
+
+
+def dumps(obj: Any) -> str:
+    return json.dumps(obj, default=str, separators=(",", ":"))
+
+
+def loads(raw: str) -> Any:
+    return json.loads(raw)

phzyx/cache/resource.py

@@ -0,0 +1,53 @@
+"""Per-resource versioned list cache."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from phzyx.cache.backends import CacheBackend, dumps, loads
+
+
+class ResourceCache:
+    """Cache lists under ``phzyx:res:{name}:v{version}:list:{suffix}``.
+
+    ``invalidate(resource)`` bumps the version so all prior list keys miss.
+    """
+
+    def __init__(
+        self, backend: CacheBackend, *, prefix: str = "phzyx", ttl: int | None = 60
+    ) -> None:
+        self.backend = backend
+        self.prefix = prefix
+        self.ttl = ttl
+
+    def _ver_key(self, resource: str) -> str:
+        return f"{self.prefix}:res:{resource}:version"
+
+    def version(self, resource: str) -> int:
+        raw = self.backend.get(self._ver_key(resource))
+        return int(raw or "1")
+
+    def invalidate(self, resource: str) -> int:
+        """Bump resource version; returns new version."""
+        v = self.version(resource) + 1
+        self.backend.set(self._ver_key(resource), str(v))
+        return v
+
+    def _list_key(self, resource: str, suffix: str) -> str:
+        return f"{self.prefix}:res:{resource}:v{self.version(resource)}:list:{suffix}"
+
+    def get_list(self, resource: str, suffix: str = "default") -> list[dict[str, Any]] | None:
+        raw = self.backend.get(self._list_key(resource, suffix))
+        if raw is None:
+            return None
+        data = loads(raw)
+        return data if isinstance(data, list) else None
+
+    def set_list(
+        self,
+        resource: str,
+        rows: list[dict[str, Any]],
+        *,
+        suffix: str = "default",
+    ) -> None:
+        self.backend.set(self._list_key(resource, suffix), dumps(rows), ttl=self.ttl)

phzyx_cache-0.1.0.dist-info/METADATA

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: phzyx-cache
+Version: 0.1.0
+Summary: Phzyx versioned resource cache (memory / Redis)
+Author: Athul Nandaswaroop
+License-Expression: MIT
+Requires-Python: >=3.11
+Provides-Extra: redis
+Requires-Dist: redis>=5; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# phzyx-cache
+
+**Public battery.** `uv add 'phzyx-cache'` or `uv add 'phzyx-forge[cache]'`.
+
+
+Per-resource **version keys** for list caching. Writes bump the version so stale lists miss.
+
+```python
+from phzyx.cache import MemoryCache, ResourceCache
+
+cache = ResourceCache(MemoryCache())
+cache.set_list("users", "v1", [{"id": 1}])  # version auto-managed
+cache.invalidate("users")  # on write
+```
+
+Redis:
+
+```bash
+uv add 'phzyx-cache[redis]'
+```
+
+**Limits:** only Phzyx write path invalidates; external DB writers can serve stale lists until TTL/version bump. Not a query cache for arbitrary SQL.

phzyx_cache-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+phzyx/cache/__init__.py,sha256=OoE_98mKZUZ6DuNHz9EpLlinqqkH9uzZm7g6K5yoXPY,258
+phzyx/cache/backends.py,sha256=IJilcU0wwzOm0jEV8owAcmF0chNuF1Yrf0MEpJ7Hs18,2222
+phzyx/cache/resource.py,sha256=U0Hr1c-de6iwb59UaVVDKpX2FcYhm01jF_YrbLqa12I,1675
+phzyx_cache-0.1.0.dist-info/METADATA,sha256=u__oq8A5j5V38yQH-WU5-LhLTBBxuMdA1CfE9I1d-G8,888
+phzyx_cache-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+phzyx_cache-0.1.0.dist-info/RECORD,,

phzyx_cache-0.1.0.dist-info/WHEEL

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