advalcache 0.1.0__py3-none-any.whl

advalcache/__init__.py

@@ -0,0 +1,320 @@
+"""advalcache/__init__.py — Public API surface.
+
+    from advalcache import Cache
+    cache = Cache(capacity_mb=512)
+
+    @cache.cached(regen_ms=800, regen_usd=0.015, change_interval_s=60)
+    def get_stock_price(ticker: str) -> dict:
+        return api.fetch(ticker)
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any, Callable, Optional, Tuple
+
+from advalcache.config import CacheConfig
+from advalcache.stats import CacheStats
+from advalcache._engine import AdValEngine, AsyncAdValEngine, CacheEntry
+from advalcache.decorators import make_cached_decorator
+
+__version__ = "0.1.0"
+__all__ = [
+    "Cache",
+    "AsyncCache",
+    "CacheConfig",
+    "CacheStats",
+    "CacheEntry",
+    "__version__",
+]
+
+
+class Cache:
+    """AdVal in-memory cache — synchronous.
+
+    The simplest usage::
+
+        from advalcache import Cache
+
+        cache = Cache(capacity_mb=256)
+
+        @cache.cached(regen_ms=800, regen_usd=0.015, change_interval_s=60)
+        def fetch_quote(ticker: str) -> dict:
+            return live_api.get(ticker)
+
+    For full configuration, pass a ``CacheConfig``::
+
+        cache = Cache(config=CacheConfig(capacity_mb=512, obs_port=9999))
+
+    Can also be used as a context manager for automatic shutdown::
+
+        with Cache(capacity_mb=64) as cache:
+            ...
+    """
+
+    def __init__(
+        self,
+        capacity_mb: float = 256.0,
+        *,
+        config: Optional[CacheConfig] = None,
+    ) -> None:
+        if config is None:
+            config = CacheConfig(capacity_mb=capacity_mb)
+        self._config = config
+        self._engine = AdValEngine(**config.engine_kwargs())
+        self.cached = make_cached_decorator(
+            self._engine, key_prefix=config.key_prefix, is_async=False
+        )
+        self._obs_server: Any = None
+        if config.obs_port is not None:
+            self._start_obs_server(config.obs_port)
+
+    # ------------------------------------------------------------------
+    # Manual get / put / invalidate
+    # ------------------------------------------------------------------
+
+    def get(
+        self,
+        key: str,
+        refresh_callback: Optional[Callable[[], Tuple[Any, float, int]]] = None,
+    ) -> Optional[Tuple[Any, bool, float, float]]:
+        """Look up a key.
+
+        Returns ``(value, is_fresh, freshness, score)`` on a hit,
+        or ``None`` on a miss.
+
+        Args:
+            key: The cache key.
+            refresh_callback: Optional callable that returns ``(data, latency_ms,
+                size_bytes)``. If the entry is stale but high-value, AdVal calls
+                this in a background thread to re-sync the entry.
+        """
+        return self._engine.get(key, refresh_callback)
+
+    def put(
+        self,
+        key: str,
+        value: Any,
+        *,
+        regen_ms: float = 100.0,
+        regen_usd: float = 0.0,
+        change_interval_s: float = 0.0,
+        cls: str = "generic",
+        size_bytes: Optional[int] = None,
+    ) -> bool:
+        """Admit or update an entry.
+
+        Returns True if the entry was admitted, False if declined by
+        admission control (e.g. too volatile and too cheap).
+
+        Args:
+            key: Cache key.
+            value: The value to cache.
+            regen_ms: Regeneration latency in milliseconds.
+            regen_usd: Regeneration cost in USD.
+            change_interval_s: How often this object changes (seconds). 0 = immutable.
+            cls: Object class label for telemetry (informational only).
+            size_bytes: Override the estimated memory footprint. If None, estimated
+                via ``sys.getsizeof(value)``.
+        """
+        return self._engine.put(
+            key=key, data=value, cls=cls,
+            size_bytes=size_bytes,
+            regen_ms=regen_ms, regen_usd=regen_usd,
+            change_interval_s=change_interval_s,
+        )
+
+    def invalidate(self, key: str) -> bool:
+        """Remove a key from the cache. Returns True if it was resident."""
+        return self._engine.invalidate(key)
+
+    def invalidate_prefix(self, prefix: str) -> int:
+        """Remove all keys that start with ``prefix``. Returns count removed."""
+        return self._engine.invalidate_prefix(prefix)
+
+    def clear(self) -> None:
+        """Flush all entries and reset all metrics."""
+        self._engine.clear()
+
+    # ------------------------------------------------------------------
+    # Telemetry helpers
+    # ------------------------------------------------------------------
+
+    def record_ram_latency(self, ms: float) -> None:
+        """Record a measured RAM retrieval latency for stats reporting."""
+        self._engine.record_ram_latency(ms)
+
+    def record_origin_latency(self, ms: float) -> None:
+        """Record a measured origin (DB / API) latency for stats reporting."""
+        self._engine.record_origin_latency(ms)
+
+    # ------------------------------------------------------------------
+    # Stats
+    # ------------------------------------------------------------------
+
+    def get_stats(self) -> CacheStats:
+        """Return a frozen snapshot of current telemetry."""
+        return CacheStats.from_snapshot(self._engine.snapshot())
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def count(self) -> int:
+        """Number of entries currently in the cache."""
+        return self._engine.count
+
+    @property
+    def resident_mb(self) -> float:
+        """Current resident memory footprint in MB."""
+        return self._engine.resident_mb
+
+    @property
+    def capacity_mb(self) -> float:
+        """Configured maximum capacity in MB."""
+        return self._engine.capacity_mb
+
+    @property
+    def config(self) -> CacheConfig:
+        return self._config
+
+    # ------------------------------------------------------------------
+    # Context manager
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> "Cache":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.shutdown()
+
+    def shutdown(self, wait: bool = True) -> None:
+        """Gracefully stop background refresh threads."""
+        self._engine.shutdown(wait)
+        if self._obs_server is not None:
+            try:
+                self._obs_server.shutdown()
+            except Exception:
+                pass
+
+    # ------------------------------------------------------------------
+    # Built-in observability server (optional)
+    # ------------------------------------------------------------------
+
+    def _start_obs_server(self, port: int) -> None:
+        """Start the built-in FastAPI observability server on a background thread."""
+        try:
+            from advalcache.server import ObsServer
+            self._obs_server = ObsServer(self._engine, port=port)
+            t = threading.Thread(target=self._obs_server.run, daemon=True)
+            t.start()
+        except ImportError:
+            import warnings
+            warnings.warn(
+                "advalcache: obs_port requires 'advalcache[fastapi]' extra. "
+                "Install with: pip install advalcache[fastapi]",
+                stacklevel=3,
+            )
+
+    def __repr__(self) -> str:
+        return (
+            f"Cache(capacity_mb={self.capacity_mb}, "
+            f"resident={self.resident_mb:.2f}MB, "
+            f"count={self.count})"
+        )
+
+
+class AsyncCache:
+    """AdVal in-memory cache — async version.
+
+    Drop-in replacement for ``Cache`` when your functions are ``async def``.
+    Uses ``asyncio.Lock`` internally — safe in any event loop without blocking.
+
+    Usage::
+
+        from advalcache import AsyncCache
+
+        cache = AsyncCache(capacity_mb=256)
+
+        @cache.cached(regen_ms=800, regen_usd=0.015, change_interval_s=60)
+        async def fetch_quote(ticker: str) -> dict:
+            return await live_api.get_async(ticker)
+    """
+
+    def __init__(
+        self,
+        capacity_mb: float = 256.0,
+        *,
+        config: Optional[CacheConfig] = None,
+    ) -> None:
+        if config is None:
+            config = CacheConfig(capacity_mb=capacity_mb)
+        self._config = config
+        self._engine = AsyncAdValEngine(**config.engine_kwargs())
+        self.cached = make_cached_decorator(
+            self._engine, key_prefix=config.key_prefix, is_async=True
+        )
+
+    async def get(
+        self,
+        key: str,
+        refresh_callback: Optional[Callable] = None,
+    ) -> Optional[Tuple[Any, bool, float, float]]:
+        return await self._engine.get(key, refresh_callback)
+
+    async def put(
+        self,
+        key: str,
+        value: Any,
+        *,
+        regen_ms: float = 100.0,
+        regen_usd: float = 0.0,
+        change_interval_s: float = 0.0,
+        cls: str = "generic",
+        size_bytes: Optional[int] = None,
+    ) -> bool:
+        return await self._engine.put(
+            key=key, data=value, cls=cls,
+            size_bytes=size_bytes,
+            regen_ms=regen_ms, regen_usd=regen_usd,
+            change_interval_s=change_interval_s,
+        )
+
+    async def invalidate(self, key: str) -> bool:
+        return await self._engine.invalidate(key)
+
+    async def invalidate_prefix(self, prefix: str) -> int:
+        return await self._engine.invalidate_prefix(prefix)
+
+    async def clear(self) -> None:
+        await self._engine.clear()
+
+    def get_stats(self) -> CacheStats:
+        return CacheStats.from_snapshot(self._engine.snapshot())
+
+    @property
+    def count(self) -> int:
+        return self._engine.count
+
+    @property
+    def resident_mb(self) -> float:
+        return self._engine.resident_mb
+
+    @property
+    def capacity_mb(self) -> float:
+        return self._engine.capacity_mb
+
+    async def __aenter__(self) -> "AsyncCache":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        self._engine.shutdown(wait=False)
+
+    def __repr__(self) -> str:
+        return (
+            f"AsyncCache(capacity_mb={self.capacity_mb}, "
+            f"resident={self.resident_mb:.2f}MB, "
+            f"count={self.count})"
+        )

advalcache/__main__.py

@@ -0,0 +1,58 @@
+"""advalcache/__main__.py — CLI entry point.
+
+    python -m advalcache --help
+    advalcache serve --port 9999 --capacity-mb 256
+    advalcache version
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="advalcache",
+        description="AdVal Cache SDK — CLI tools",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    # version
+    sub.add_parser("version", help="Print the advalcache version and exit.")
+
+    # serve
+    serve_p = sub.add_parser("serve", help="Start a standalone AdVal observability server.")
+    serve_p.add_argument("--port", type=int, default=9999, help="HTTP port (default: 9999)")
+    serve_p.add_argument("--capacity-mb", type=float, default=256.0,
+                         help="Cache capacity in MB (default: 256)")
+
+    args = parser.parse_args()
+
+    if args.command == "version":
+        from advalcache import __version__
+        print(f"advalcache {__version__}")
+
+    elif args.command == "serve":
+        print(f"Starting AdVal observability server on http://127.0.0.1:{args.port}")
+        print(f"Cache capacity: {args.capacity_mb} MB")
+        print("Press Ctrl+C to stop.")
+        try:
+            from advalcache import Cache
+            from advalcache.server import ObsServer
+            cache = Cache(capacity_mb=args.capacity_mb)
+            server = ObsServer(cache._engine, port=args.port)
+            server.run()
+        except ImportError:
+            print("ERROR: 'advalcache serve' requires the fastapi extra.")
+            print("Install with: pip install advalcache[fastapi]")
+            sys.exit(1)
+        except KeyboardInterrupt:
+            print("\nShutdown.")
+
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()