cache-sync 0.3.1__tar.gz

cache_sync-0.3.1/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.3
+Name: cache-sync
+Version: 0.3.1
+Summary: Async hybrid Python cache with in-memory L1, distributed L2 providers, pluggable invalidation, stampede protection, and typed decorators.
+Keywords: async,cache,redis,invalidation,stampede-protection
+Author: Peter Cinibulk
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: redis>=5.0.0 ; extra == 'all'
+Requires-Dist: aio-pika>=9.0.0 ; extra == 'all'
+Requires-Dist: aiokafka>=0.10.0 ; extra == 'all'
+Requires-Dist: asyncpg>=0.29.0 ; extra == 'all'
+Requires-Dist: pydantic>=1.10.0 ; extra == 'all'
+Requires-Dist: aiokafka>=0.10.0 ; extra == 'kafka'
+Requires-Dist: asyncpg>=0.29.0 ; extra == 'postgres'
+Requires-Dist: pydantic>=1.10.0 ; extra == 'pydantic'
+Requires-Dist: aio-pika>=9.0.0 ; extra == 'rabbitmq'
+Requires-Dist: redis>=5.0.0 ; extra == 'redis'
+Requires-Python: >=3.12
+Project-URL: Changelog, https://github.com/petercinibulk/cache-sync/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://petercinibulk.github.io/cache-sync/
+Project-URL: Issues, https://github.com/petercinibulk/cache-sync/issues
+Project-URL: Repository, https://github.com/petercinibulk/cache-sync
+Provides-Extra: all
+Provides-Extra: kafka
+Provides-Extra: postgres
+Provides-Extra: pydantic
+Provides-Extra: rabbitmq
+Provides-Extra: redis
+Description-Content-Type: text/markdown
+
+# cache-sync
+
+Async hybrid Python cache with in-memory L1 caching, optional Redis L2 caching, pluggable invalidation, stampede protection, fail-safe stale values, and typed decorators.
+
+## Features
+
+- Async-first API for Python 3.12 and newer.
+- Fast in-process L1 cache with optional Redis-backed L2 storage.
+- Pluggable invalidation buses for Redis Streams, RabbitMQ, Kafka, and PostgreSQL.
+- Request stampede protection with per-key refresh coordination.
+- Fail-safe stale reads for short backend outages.
+- Typed decorators that preserve the wrapped function signature.
+- Serializer choices for JSON, pickle, and Pydantic models.
+
+## Documentation
+
+The end-user documentation is published at <https://petercinibulk.github.io/cache-sync/> and is built from [`docs/`](docs/index.md) with Zensical.
+
+## Install
+
+```bash
+uv add cache-sync
+```
+
+Install optional providers only when your application uses them:
+
+```bash
+uv add "cache-sync[redis]"
+uv add "cache-sync[rabbitmq]"
+uv add "cache-sync[kafka]"
+uv add "cache-sync[postgres]"
+uv add "cache-sync[all]"
+```
+
+| Extra | Installs | Use when |
+| --- | --- | --- |
+| `redis` | `redis` | You need Redis L2 storage or Redis Streams invalidation. |
+| `rabbitmq` | `aio-pika` | You use RabbitMQ as the invalidation bus. |
+| `kafka` | `aiokafka` | You use Kafka as the invalidation bus. |
+| `postgres` | `asyncpg` | You use PostgreSQL `LISTEN`/`NOTIFY` for invalidation. |
+| `pydantic` | `pydantic` | You want Pydantic model serialization helpers. |
+| `all` | all provider dependencies | You want every optional provider available. |
+
+## Quick Start
+
+```python
+from cache_sync import CacheOptions, CacheSync
+
+cache = CacheSync(
+    options=CacheOptions(
+        ttl_seconds=60,
+        fail_safe_seconds=300,
+        hard_timeout_seconds=5,
+        jitter_seconds=5,
+    ),
+)
+
+await cache.start()
+
+
+@cache.cached(lambda user_id: f"user:{user_id}")
+async def get_user(user_id: str) -> dict[str, str]:
+    return {"id": user_id, "name": "Peter"}
+
+
+user = await get_user("123")
+await get_user.remove_cached("123")
+await cache.stop()
+```
+
+## Redis L2 Example
+
+```python
+from redis.asyncio import Redis
+
+from cache_sync import CacheOptions, CacheSync, RedisDistributedCache
+
+redis = Redis.from_url("redis://localhost:6379/0")
+
+cache = CacheSync(
+    distributed_cache=RedisDistributedCache(redis),
+    options=CacheOptions(ttl_seconds=60, fail_safe_seconds=300),
+)
+
+await cache.start()
+
+
+@cache.cached(lambda product_id: f"product:{product_id}")
+async def get_product(product_id: str) -> dict[str, str]:
+    return {"id": product_id}
+```
+
+For a complete walkthrough with shared values and cross-instance invalidation, see the [get started tutorial](https://petercinibulk.github.io/cache-sync/tutorials/get-started/).
+
+## Project
+
+- License: MIT
+- Source: <https://github.com/petercinibulk/cache-sync>
+- Issues: <https://github.com/petercinibulk/cache-sync/issues>

cache_sync-0.3.1/README.md

@@ -0,0 +1,99 @@
+# cache-sync
+
+Async hybrid Python cache with in-memory L1 caching, optional Redis L2 caching, pluggable invalidation, stampede protection, fail-safe stale values, and typed decorators.
+
+## Features
+
+- Async-first API for Python 3.12 and newer.
+- Fast in-process L1 cache with optional Redis-backed L2 storage.
+- Pluggable invalidation buses for Redis Streams, RabbitMQ, Kafka, and PostgreSQL.
+- Request stampede protection with per-key refresh coordination.
+- Fail-safe stale reads for short backend outages.
+- Typed decorators that preserve the wrapped function signature.
+- Serializer choices for JSON, pickle, and Pydantic models.
+
+## Documentation
+
+The end-user documentation is published at <https://petercinibulk.github.io/cache-sync/> and is built from [`docs/`](docs/index.md) with Zensical.
+
+## Install
+
+```bash
+uv add cache-sync
+```
+
+Install optional providers only when your application uses them:
+
+```bash
+uv add "cache-sync[redis]"
+uv add "cache-sync[rabbitmq]"
+uv add "cache-sync[kafka]"
+uv add "cache-sync[postgres]"
+uv add "cache-sync[all]"
+```
+
+| Extra | Installs | Use when |
+| --- | --- | --- |
+| `redis` | `redis` | You need Redis L2 storage or Redis Streams invalidation. |
+| `rabbitmq` | `aio-pika` | You use RabbitMQ as the invalidation bus. |
+| `kafka` | `aiokafka` | You use Kafka as the invalidation bus. |
+| `postgres` | `asyncpg` | You use PostgreSQL `LISTEN`/`NOTIFY` for invalidation. |
+| `pydantic` | `pydantic` | You want Pydantic model serialization helpers. |
+| `all` | all provider dependencies | You want every optional provider available. |
+
+## Quick Start
+
+```python
+from cache_sync import CacheOptions, CacheSync
+
+cache = CacheSync(
+    options=CacheOptions(
+        ttl_seconds=60,
+        fail_safe_seconds=300,
+        hard_timeout_seconds=5,
+        jitter_seconds=5,
+    ),
+)
+
+await cache.start()
+
+
+@cache.cached(lambda user_id: f"user:{user_id}")
+async def get_user(user_id: str) -> dict[str, str]:
+    return {"id": user_id, "name": "Peter"}
+
+
+user = await get_user("123")
+await get_user.remove_cached("123")
+await cache.stop()
+```
+
+## Redis L2 Example
+
+```python
+from redis.asyncio import Redis
+
+from cache_sync import CacheOptions, CacheSync, RedisDistributedCache
+
+redis = Redis.from_url("redis://localhost:6379/0")
+
+cache = CacheSync(
+    distributed_cache=RedisDistributedCache(redis),
+    options=CacheOptions(ttl_seconds=60, fail_safe_seconds=300),
+)
+
+await cache.start()
+
+
+@cache.cached(lambda product_id: f"product:{product_id}")
+async def get_product(product_id: str) -> dict[str, str]:
+    return {"id": product_id}
+```
+
+For a complete walkthrough with shared values and cross-instance invalidation, see the [get started tutorial](https://petercinibulk.github.io/cache-sync/tutorials/get-started/).
+
+## Project
+
+- License: MIT
+- Source: <https://github.com/petercinibulk/cache-sync>
+- Issues: <https://github.com/petercinibulk/cache-sync/issues>

cache_sync-0.3.1/pyproject.toml

@@ -0,0 +1,107 @@
+[project]
+name = "cache-sync"
+version = "0.3.1"
+description = "Async hybrid Python cache with in-memory L1, distributed L2 providers, pluggable invalidation, stampede protection, and typed decorators."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Peter Cinibulk" }]
+
+# Published dependencies.
+dependencies = []
+keywords = ["async", "cache", "redis", "invalidation", "stampede-protection"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: AsyncIO",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Changelog = "https://github.com/petercinibulk/cache-sync/blob/main/CHANGELOG.md"
+Documentation = "https://petercinibulk.github.io/cache-sync/"
+Issues = "https://github.com/petercinibulk/cache-sync/issues"
+Repository = "https://github.com/petercinibulk/cache-sync"
+
+# Published optional dependencies, or "extras".
+[project.optional-dependencies]
+kafka = ["aiokafka>=0.10.0"]
+postgres = ["asyncpg>=0.29.0"]
+pydantic = ["pydantic>=1.10.0"]
+rabbitmq = ["aio-pika>=9.0.0"]
+redis = ["redis>=5.0.0"]
+all = [
+  "redis>=5.0.0",
+  "aio-pika>=9.0.0",
+  "aiokafka>=0.10.0",
+  "asyncpg>=0.29.0",
+  "pydantic>=1.10.0",
+]
+
+# Local dependencies for development.
+[dependency-groups]
+redis = ["redis>=5.0.0"]
+rabbitmq = ["aio-pika>=9.0.0"]
+kafka = ["aiokafka>=0.10.0"]
+postgres = ["asyncpg>=0.29.0"]
+pydantic = ["pydantic>=1.10.0"]
+docs = ["zensical>=0.0.45"]
+all = [
+  { include-group = "redis" },
+  { include-group = "rabbitmq" },
+  { include-group = "kafka" },
+  { include-group = "postgres" },
+  { include-group = "pydantic" },
+]
+dev = [
+  { include-group = "all" },
+  { include-group = "docs" },
+  "pytest>=8.0.0",
+  "pytest-asyncio>=0.23.0",
+  "pytest-cov>=7.1.0",
+  "ruff>=0.5.0",
+  "ty>=0.0.1a8",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.21,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv]
+package = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["A", "ASYNC", "B", "C4", "E", "F", "I", "N", "PERF", "RUF", "SIM", "UP", "W"]
+ignore = ["B904", "UP046", "UP047"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.pytest.ini_options]
+addopts = [
+  "--cov=cache_sync",
+  "--cov-report=term-missing",
+]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ty.environment]
+python-version = "3.12"
+python-platform = "all"
+root = ["./src"]
+
+[tool.ty.src]
+include = ["src", "tests"]

cache_sync-0.3.1/src/cache_sync/__init__.py

@@ -0,0 +1,80 @@
+"""Public API for cache-sync."""
+
+from typing import TYPE_CHECKING, Any
+
+from cache_sync.core import CacheOptions, CacheSync
+from cache_sync.decorators import CachedFunction
+from cache_sync.distributed_cache import DistributedCache
+from cache_sync.invalidation import (
+    InvalidationBus,
+    InvalidationHandler,
+    InvalidationMessage,
+    InvalidationTransport,
+    TransportInvalidationBus,
+)
+from cache_sync.serializers import (
+    JsonSerializer,
+    PickleSerializer,
+    PydanticSerializer,
+    Serializer,
+)
+
+if TYPE_CHECKING:
+    from cache_sync.providers.kafka import KafkaInvalidationBus
+    from cache_sync.providers.postgres import PostgresNotifyInvalidationBus
+    from cache_sync.providers.rabbitmq import RabbitMQInvalidationBus
+    from cache_sync.providers.redis import (
+        RedisDistributedCache,
+        RedisStreamsInvalidationBus,
+    )
+
+__all__ = [
+    "CacheOptions",
+    "CacheSync",
+    "CachedFunction",
+    "DistributedCache",
+    "InvalidationBus",
+    "InvalidationHandler",
+    "InvalidationMessage",
+    "InvalidationTransport",
+    "JsonSerializer",
+    "KafkaInvalidationBus",
+    "PickleSerializer",
+    "PostgresNotifyInvalidationBus",
+    "PydanticSerializer",
+    "RabbitMQInvalidationBus",
+    "RedisDistributedCache",
+    "RedisStreamsInvalidationBus",
+    "Serializer",
+    "TransportInvalidationBus",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "RedisDistributedCache":
+        from cache_sync.providers.redis import RedisDistributedCache
+
+        return RedisDistributedCache
+
+    if name == "RedisStreamsInvalidationBus":
+        from cache_sync.providers.redis import RedisStreamsInvalidationBus
+
+        return RedisStreamsInvalidationBus
+
+    if name == "RabbitMQInvalidationBus":
+        from cache_sync.providers.rabbitmq import RabbitMQInvalidationBus
+
+        return RabbitMQInvalidationBus
+
+    if name == "KafkaInvalidationBus":
+        from cache_sync.providers.kafka import KafkaInvalidationBus
+
+        return KafkaInvalidationBus
+
+    if name == "PostgresNotifyInvalidationBus":
+        from cache_sync.providers.postgres import PostgresNotifyInvalidationBus
+
+        return PostgresNotifyInvalidationBus
+
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)

cache_sync-0.3.1/src/cache_sync/core.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, ParamSpec, TypeVar, cast
+
+from cache_sync.distributed_cache import DistributedCache
+from cache_sync.invalidation import InvalidationBus
+
+T = TypeVar("T")
+P = ParamSpec("P")
+_CACHE_OPTION_DEFAULTS = {
+    "ttl_seconds": 60.0,
+    "fail_safe_seconds": 300.0,
+    "hard_timeout_seconds": 5.0,
+    "jitter_seconds": 0.0,
+}
+
+
+class _Unset:
+    __slots__ = ()
+
+
+_UNSET = _Unset()
+
+if TYPE_CHECKING:
+    from cache_sync.decorators import CachedFunction
+
+
+@dataclass(frozen=True, slots=True, init=False)
+class CacheOptions:
+    """Runtime policy for cache freshness, factory timeouts, and TTL jitter."""
+
+    ttl_seconds: float = 60
+    fail_safe_seconds: float = 300
+    hard_timeout_seconds: float = 5
+    jitter_seconds: float = 0
+    _supplied: frozenset[str] = field(
+        default_factory=frozenset,
+        repr=False,
+        compare=False,
+    )
+
+    def __init__(
+        self,
+        ttl_seconds: float | _Unset = _UNSET,
+        fail_safe_seconds: float | _Unset = _UNSET,
+        hard_timeout_seconds: float | _Unset = _UNSET,
+        jitter_seconds: float | _Unset = _UNSET,
+    ) -> None:
+        values = {
+            "ttl_seconds": ttl_seconds,
+            "fail_safe_seconds": fail_safe_seconds,
+            "hard_timeout_seconds": hard_timeout_seconds,
+            "jitter_seconds": jitter_seconds,
+        }
+        supplied = frozenset(name for name, value in values.items() if value is not _UNSET)
+
+        for name, default in _CACHE_OPTION_DEFAULTS.items():
+            value = values[name]
+            object.__setattr__(self, name, default if value is _UNSET else value)
+
+        object.__setattr__(self, "_supplied", supplied)
+
+    def merge_over(self, defaults: CacheOptions) -> CacheOptions:
+        """Return this option object's supplied fields over cache defaults."""
+
+        values = {
+            name: getattr(self if name in self._supplied else defaults, name)
+            for name in _CACHE_OPTION_DEFAULTS
+        }
+        return CacheOptions(**values)
+
+
+@dataclass(slots=True)
+class CacheEntry:
+    """In-memory cache entry with freshness and fail-safe deadlines."""
+
+    value: object
+    expires_at: float
+    fail_safe_until: float
+
+    @property
+    def is_fresh(self) -> bool:
+        return time.monotonic() < self.expires_at
+
+    @property
+    def is_fail_safe_available(self) -> bool:
+        return time.monotonic() < self.fail_safe_until
+
+
+class CacheSync:
+    """Async two-level cache with optional distributed storage and invalidation."""
+
+    def __init__(
+        self,
+        *,
+        distributed_cache: DistributedCache | None = None,
+        invalidation_bus: InvalidationBus | None = None,
+        options: CacheOptions | None = None,
+    ) -> None:
+        """Create a cache using optional L2 storage and invalidation providers."""
+
+        self._memory: dict[str, CacheEntry] = {}
+        self._locks: dict[str, asyncio.Lock] = {}
+        self._distributed_cache = distributed_cache
+        self._invalidation_bus = invalidation_bus
+        self._options = options or CacheOptions()
+
+    async def start(self) -> None:
+        """Start the configured invalidation bus, if any."""
+
+        if self._invalidation_bus is None:
+            return
+
+        await self._invalidation_bus.start(
+            remove_local=self.remove_local,
+            clear_local=self.clear_memory,
+        )
+
+    async def stop(self) -> None:
+        """Stop the configured invalidation bus, if any."""
+
+        if self._invalidation_bus is not None:
+            await self._invalidation_bus.stop()
+
+    def cached(
+        self,
+        key: str | Callable[..., str] | None = None,
+        *,
+        options: CacheOptions | None = None,
+    ) -> Callable[[Callable[P, Awaitable[T]]], CachedFunction[P, T]]:
+        """Decorate an async function using this cache instance."""
+
+        from cache_sync.decorators import CachedFunction
+
+        def decorator(func: Callable[P, Awaitable[T]]) -> CachedFunction[P, T]:
+            return CachedFunction(self, func, key, options)
+
+        return decorator
+
+    async def get_or_set(
+        self,
+        key: str,
+        factory: Callable[[], Awaitable[T]],
+        *,
+        options: CacheOptions | None = None,
+    ) -> T:
+        """Return a cached value or compute, store, and return a new value."""
+
+        opts = self._effective_options(options)
+        entry = self._memory.get(key)
+
+        if entry and entry.is_fresh:
+            return cast(T, entry.value)
+
+        lock = self._locks.setdefault(key, asyncio.Lock())
+
+        async with lock:
+            entry = self._memory.get(key)
+            if entry and entry.is_fresh:
+                return cast(T, entry.value)
+
+            if self._distributed_cache is not None:
+                cached_value = await self._distributed_cache.get(key)
+                if cached_value is not None:
+                    self._set_memory(key, cached_value, opts)
+                    return cast(T, cached_value)
+
+            stale = entry if entry and entry.is_fail_safe_available else None
+
+            try:
+                value = await asyncio.wait_for(
+                    factory(),
+                    timeout=opts.hard_timeout_seconds,
+                )
+                await self.set(key, value, options=opts, publish_invalidation=False)
+                return value
+            except Exception:
+                if stale is not None:
+                    return cast(T, stale.value)
+                raise
+
+    async def set(
+        self,
+        key: str,
+        value: object,
+        *,
+        options: CacheOptions | None = None,
+        publish_invalidation: bool = True,
+    ) -> None:
+        """Store a value in local memory and optional distributed storage."""
+
+        opts = self._effective_options(options)
+        self._set_memory(key, value, opts)
+
+        if self._distributed_cache is not None:
+            await self._distributed_cache.set(
+                key,
+                value,
+                ttl_seconds=self._ttl_with_jitter(opts),
+            )
+
+        if publish_invalidation and self._invalidation_bus is not None:
+            await self._invalidation_bus.invalidate(key)
+
+    async def remove(self, key: str) -> None:
+        """Remove a key locally, from distributed storage, and from peer nodes."""
+
+        self.remove_local(key)
+
+        if self._distributed_cache is not None:
+            await self._distributed_cache.delete(key)
+
+        if self._invalidation_bus is not None:
+            await self._invalidation_bus.invalidate(key)
+
+    async def clear(self) -> None:
+        """Clear all local entries and publish a clear message to peer nodes."""
+
+        self.clear_memory()
+
+        if self._invalidation_bus is not None:
+            await self._invalidation_bus.clear()
+
+    def remove_local(self, key: str) -> None:
+        """Remove a key from only this process's in-memory cache."""
+
+        self._memory.pop(key, None)
+
+    def clear_memory(self) -> None:
+        """Clear only this process's in-memory cache."""
+
+        self._memory.clear()
+
+    def _effective_options(self, options: CacheOptions | None) -> CacheOptions:
+        if options is None:
+            return self._options
+        return options.merge_over(self._options)
+
+    def _set_memory(self, key: str, value: object, opts: CacheOptions) -> None:
+        ttl = self._ttl_with_jitter(opts)
+        now = time.monotonic()
+        self._memory[key] = CacheEntry(
+            value=value,
+            expires_at=now + ttl,
+            fail_safe_until=now + ttl + opts.fail_safe_seconds,
+        )
+
+    def _ttl_with_jitter(self, opts: CacheOptions) -> float:
+        if opts.jitter_seconds <= 0:
+            return opts.ttl_seconds
+        return opts.ttl_seconds + random.uniform(0, opts.jitter_seconds)