sg-query-cache 0.1.0__py3-none-any.whl

sg_query_cache/__init__.py

@@ -0,0 +1,39 @@
+"""Cache exact SG query results under explicit identity and freshness contracts.
+
+Wrap a caller-owned SG client with the synchronous or native asynchronous
+adapter using validated settings, an explicit effective identity, and matching
+response context. Caching provides bounded staleness; it does not authenticate
+the supplied identity or make reads causally consistent with SG writes.
+
+Close each owned cache when its work finishes. The async owning factory closes
+its constructed cache; directly injected caches remain caller-owned. Async
+operations and resource cleanup must use one event loop. Optional Valkey
+backends are imported explicitly from `sg_query_cache.valkey` or
+`sg_query_cache.valkey_async`.
+"""
+
+from sg_query_cache._async_backend import AsyncCacheBackend
+from sg_query_cache._async_cache import AsyncQueryCache
+from sg_query_cache._async_client import AsyncCachedShotgun
+from sg_query_cache._async_local import AsyncLocalBackend
+from sg_query_cache._cache import QueryCache
+from sg_query_cache._client import CachedShotgun, ClientContext
+from sg_query_cache._config import CacheSettings
+from sg_query_cache._local import LocalBackend
+from sg_query_cache._metrics import MetricsSink, NullMetrics
+from sg_query_cache._model import Identity
+
+__all__ = [
+    'AsyncCacheBackend',
+    'AsyncCachedShotgun',
+    'AsyncLocalBackend',
+    'AsyncQueryCache',
+    'CacheSettings',
+    'CachedShotgun',
+    'ClientContext',
+    'Identity',
+    'LocalBackend',
+    'MetricsSink',
+    'NullMetrics',
+    'QueryCache',
+]

sg_query_cache/__main__.py

@@ -0,0 +1,8 @@
+"""Run the supported `python -m sg_query_cache` command-line entry point."""
+
+import sys
+
+from sg_query_cache._cli import main
+
+if __name__ == '__main__':
+    sys.exit(main())

sg_query_cache/_async_backend.py

@@ -0,0 +1,101 @@
+"""Define the backend-neutral asynchronous cache storage contract."""
+
+from typing import Protocol
+
+from sg_query_cache._model import (
+    CacheHit,
+    DependencyTag,
+    FillLease,
+    GenerationChange,
+    GenerationVector,
+)
+
+
+class AsyncCacheBackend(Protocol):
+    """Store opaque encoded results through loop-native coroutine methods.
+
+    Each method preserves the corresponding `CacheBackend` arguments, return
+    values, and backend errors while adding coroutine cancellation cooperation.
+    This protocol types the shipped backends; third-party implementations are
+    not yet a supported extension point.
+    """
+
+    async def change(self, changes: tuple[GenerationChange, ...]) -> None:
+        """Replace all applicable generations in caller order.
+
+        Args:
+            changes: Ordered generation replacements to acknowledge together.
+        """
+        ...
+
+    async def close(self) -> None:
+        """Release backend resources; repeated same-loop calls have no effect."""
+        ...
+
+    async def commit(self, lease: FillLease, payload: bytes, remaining_seconds: float) -> bool:
+        """Store encoded bytes only while the exact lease remains current.
+
+        Args:
+            lease: Exact key and token returned by `reserve`.
+            payload: Closed-codec bytes to retain.
+            remaining_seconds: Positive authoritative lifetime remaining.
+
+        Returns:
+            Whether the lease remained current and the result was admitted.
+        """
+        ...
+
+    async def flush_site(self, site_namespace: str, reason: str) -> None:
+        """Replace one site's permanent site generation.
+
+        Args:
+            site_namespace: Stable configured site namespace.
+            reason: Short operator-facing reason code.
+        """
+        ...
+
+    async def lookup(self, key: str) -> CacheHit | None:
+        """Read valid encoded bytes with backend-authoritative remaining age.
+
+        Args:
+            key: Opaque generation-qualified result key.
+
+        Returns:
+            An isolated hit, optionally carrying the backend's fresh decoded
+            value, or `None` for absence, expiry, or corruption.
+        """
+        ...
+
+    async def release(self, lease: FillLease) -> bool:
+        """Remove a fill lease only when its exact token remains current.
+
+        Args:
+            lease: Exact key and token returned by `reserve`.
+
+        Returns:
+            Whether the current lease was removed.
+        """
+        ...
+
+    async def reserve(self, key: str, lease_seconds: float) -> FillLease | None:
+        """Acquire temporary fill ownership for one opaque key.
+
+        Args:
+            key: Opaque generation-qualified result key.
+            lease_seconds: Positive ownership duration.
+
+        Returns:
+            A fresh lease, or `None` while another lease remains current.
+        """
+        ...
+
+    async def resolve(self, tags: tuple[DependencyTag, ...]) -> GenerationVector:
+        """Resolve one complete bounded dependency vector in request order.
+
+        Args:
+            tags: Ordered unique dependency tags.
+
+        Returns:
+            Every requested tag and current token under one incarnation.
+        """
+        ...