phzyx-cache 0.1.0__tar.gz

phzyx_cache-0.1.0/.gitignore

@@ -0,0 +1,87 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+.eggs/
+dist/
+!packages/admin/web/dist/
+!packages/admin/web/dist/**
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+examples/**/.venv/
+
+# uv / packaging
+# uv.lock is committed for reproducible workspace installs
+
+# Testing / coverage
+.pytest_cache/
+.hypothesis/
+.coverage
+.coverage.*
+coverage.xml
+coverage.json
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+dmypy.json
+.pytype/
+.pyre/
+
+# Type checkers / IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env / secrets
+.env
+.env.*
+!.env.example
+
+# Node (AdminBoard SPA + sites)
+node_modules/
+.pnpm-store/
+packages/admin/web/node_modules/
+# Built SPA is committed for offline wheel/demo convenience (M4);
+# rebuild via packages/admin/web `npm run build` when sources change.
+# packages/admin/web/dist/
+
+# Local tooling
+.justfile.local
+packages/admin/web/node_modules/
+dist-release/
+
+# Local demo SQLite
+examples/**/*.db
+examples/**/media/
+
+
+# Admin web tooling
+packages/admin/web/test-results/
+packages/admin/web/playwright-report/
+packages/admin/web/blob-report/
+
+# Private: research, design plans, AI agent helpers (local only — do not push)
+# Files remain on disk; they are untracked for remotes.
+research/
+AGENTS.md
+AGENT_TO_AGENT.md
+docs/agent-rules.md
+.cursor/
+.claude/
+.grok/
+

phzyx_cache-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,22 @@
+# 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/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "phzyx-cache"
+version = "0.1.0"
+description = "Phzyx versioned resource cache (memory / Redis)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Athul Nandaswaroop" }]
+dependencies = []
+
+[project.optional-dependencies]
+redis = ["redis>=5"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/phzyx"]

phzyx_cache-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/test_resource_cache.py

@@ -0,0 +1,28 @@
+"""Resource version cache tests (S6.2)."""
+
+from __future__ import annotations
+
+import pytest
+from phzyx.cache import MemoryCache, ResourceCache
+
+
+@pytest.mark.unit
+def test_list_cache_invalidate_on_version_bump() -> None:
+    cache = ResourceCache(MemoryCache(), ttl=None)
+    cache.set_list("users", [{"id": 1}])
+    assert cache.get_list("users") == [{"id": 1}]
+    cache.invalidate("users")
+    assert cache.get_list("users") is None
+    cache.set_list("users", [{"id": 2}])
+    assert cache.get_list("users") == [{"id": 2}]
+
+
+@pytest.mark.unit
+def test_memory_ttl_expiry() -> None:
+    import time
+
+    mem = MemoryCache()
+    mem.set("k", "v", ttl=1)
+    assert mem.get("k") == "v"
+    time.sleep(1.05)
+    assert mem.get("k") is None