hydict 0.5.0__tar.gz

hydict-0.5.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.3
+Name: hydict
+Version: 0.5.0
+Summary: hydict — a dict-compatible hierarchical cache for Python with local L1 memory and Redis/Valkey L2 storage.
+Author: Veeresh Hanni
+Author-email: Veeresh Hanni <veereshhanni347@gmail.com>
+Requires-Dist: redis>=5.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# hydict
+
+`hydict` is a dict-compatible hierarchical cache for Python. It uses local
+in-memory storage as L1 and can use Redis or Valkey as L2.
+
+## Version 0.5.0
+
+Version 0.5.0 is the V5 release. It includes the synchronous cache API,
+invalidation, metrics, and per-key stampede protection. V5 release verification
+recorded 82 passing tests.
+
+## Features
+
+- Fast, local L1 in-memory cache
+- Optional Redis/Valkey L2 cache
+- L1 promotion after an L2 cache hit
+- TTL support, including TTL preservation during L2-to-L1 promotion
+- LRU eviction with an optional `max_entries` limit
+- Redis connection pooling
+- Thread-safe L1 operations
+- Cache invalidation
+- Cache statistics
+- `get_or_set()` with per-key locking to reduce cache stampedes
+
+## Quick start
+
+```python
+from hydict import HDict
+
+cache = HDict(max_entries=100)
+
+cache["name"] = "Veeresh"
+assert cache["name"] == "Veeresh"
+```
+
+Use `set()` when a value needs a TTL:
+
+```python
+cache.set("session:1", {"user_id": 1}, ttl=60)
+```
+
+## Redis or Valkey backend
+
+Pass `RedisConfig` to enable L2 storage. A compatible Redis or Valkey server
+must be available at the configured address.
+
+```python
+from hydict import HDict, RedisConfig
+
+cache = HDict(
+    RedisConfig(
+        host="localhost",
+        port=6379,
+        max_connections=10,
+    )
+)
+
+cache.set("user:1", {"name": "Veeresh"}, ttl=300)
+```
+
+Reads check L1 first. On an L1 miss, `HDict` checks L2 and promotes an L2 hit
+into L1.
+
+## Loading missing values
+
+`get_or_set()` returns an existing value when present. For a missing key, it
+calls the loader, stores the returned value, and returns it. Concurrent callers
+for the same key share a per-key lock, so only one loader call populates that
+key at a time.
+
+```python
+user = cache.get_or_set(
+    "user:1",
+    lambda: load_user_from_database(),
+    ttl=60,
+)
+```
+
+## Invalidation and metrics
+
+```python
+cache.invalidate("user:1")
+
+print(cache.stats())
+# {
+#     "l1_hits": 0,
+#     "l2_hits": 0,
+#     "total_hits": 0,
+#     "misses": 0,
+#     "loader_calls": 0,
+# }
+```
+
+`invalidate()` removes the key from L1 and, when configured, L2.
+
+## Development
+
+Run the test suite:
+
+```powershell
+python -m pip install -e .
+pytest -q
+```
+
+Redis integration tests are opt-in. Set `HYDICT_REDIS_INTEGRATION=1` before
+running the integration test suite with a Redis server available.
+
+## Continuous integration and releases
+
+GitHub Actions runs unit tests for pull requests and runs the complete
+`pytest -q` suite against Redis 7 with `HYDICT_REDIS_INTEGRATION=1` for release
+validation. Publishing runs only for version tags such as `v0.5.0`, and only
+after both test jobs succeed. After a successful PyPI upload, the workflow also
+creates a GitHub Release with generated notes and the wheel/source archive
+attached.
+
+To enable publishing, create the `PYPI_TOKEN` repository secret with a PyPI API
+token. The workflow passes it to Twine without placing the token in the
+repository or workflow logs.
+
+## Roadmap
+
+The next planned release is `0.6.0` (V6), which will introduce an asynchronous
+API for `asyncio` applications. Async support is not part of version 0.5.0.
+
+See [docs/architecture.md](docs/architecture.md) for cache behavior and design
+notes, the [developer guide](docs/developer-guide.md) for API and implementation
+details, and [CHANGELOG.md](CHANGELOG.md) for release history.

hydict-0.5.0/README.md

@@ -0,0 +1,128 @@
+# hydict
+
+`hydict` is a dict-compatible hierarchical cache for Python. It uses local
+in-memory storage as L1 and can use Redis or Valkey as L2.
+
+## Version 0.5.0
+
+Version 0.5.0 is the V5 release. It includes the synchronous cache API,
+invalidation, metrics, and per-key stampede protection. V5 release verification
+recorded 82 passing tests.
+
+## Features
+
+- Fast, local L1 in-memory cache
+- Optional Redis/Valkey L2 cache
+- L1 promotion after an L2 cache hit
+- TTL support, including TTL preservation during L2-to-L1 promotion
+- LRU eviction with an optional `max_entries` limit
+- Redis connection pooling
+- Thread-safe L1 operations
+- Cache invalidation
+- Cache statistics
+- `get_or_set()` with per-key locking to reduce cache stampedes
+
+## Quick start
+
+```python
+from hydict import HDict
+
+cache = HDict(max_entries=100)
+
+cache["name"] = "Veeresh"
+assert cache["name"] == "Veeresh"
+```
+
+Use `set()` when a value needs a TTL:
+
+```python
+cache.set("session:1", {"user_id": 1}, ttl=60)
+```
+
+## Redis or Valkey backend
+
+Pass `RedisConfig` to enable L2 storage. A compatible Redis or Valkey server
+must be available at the configured address.
+
+```python
+from hydict import HDict, RedisConfig
+
+cache = HDict(
+    RedisConfig(
+        host="localhost",
+        port=6379,
+        max_connections=10,
+    )
+)
+
+cache.set("user:1", {"name": "Veeresh"}, ttl=300)
+```
+
+Reads check L1 first. On an L1 miss, `HDict` checks L2 and promotes an L2 hit
+into L1.
+
+## Loading missing values
+
+`get_or_set()` returns an existing value when present. For a missing key, it
+calls the loader, stores the returned value, and returns it. Concurrent callers
+for the same key share a per-key lock, so only one loader call populates that
+key at a time.
+
+```python
+user = cache.get_or_set(
+    "user:1",
+    lambda: load_user_from_database(),
+    ttl=60,
+)
+```
+
+## Invalidation and metrics
+
+```python
+cache.invalidate("user:1")
+
+print(cache.stats())
+# {
+#     "l1_hits": 0,
+#     "l2_hits": 0,
+#     "total_hits": 0,
+#     "misses": 0,
+#     "loader_calls": 0,
+# }
+```
+
+`invalidate()` removes the key from L1 and, when configured, L2.
+
+## Development
+
+Run the test suite:
+
+```powershell
+python -m pip install -e .
+pytest -q
+```
+
+Redis integration tests are opt-in. Set `HYDICT_REDIS_INTEGRATION=1` before
+running the integration test suite with a Redis server available.
+
+## Continuous integration and releases
+
+GitHub Actions runs unit tests for pull requests and runs the complete
+`pytest -q` suite against Redis 7 with `HYDICT_REDIS_INTEGRATION=1` for release
+validation. Publishing runs only for version tags such as `v0.5.0`, and only
+after both test jobs succeed. After a successful PyPI upload, the workflow also
+creates a GitHub Release with generated notes and the wheel/source archive
+attached.
+
+To enable publishing, create the `PYPI_TOKEN` repository secret with a PyPI API
+token. The workflow passes it to Twine without placing the token in the
+repository or workflow logs.
+
+## Roadmap
+
+The next planned release is `0.6.0` (V6), which will introduce an asynchronous
+API for `asyncio` applications. Async support is not part of version 0.5.0.
+
+See [docs/architecture.md](docs/architecture.md) for cache behavior and design
+notes, the [developer guide](docs/developer-guide.md) for API and implementation
+details, and [CHANGELOG.md](CHANGELOG.md) for release history.

hydict-0.5.0/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "hydict"
+version = "0.5.0"
+description = "hydict — a dict-compatible hierarchical cache for Python with local L1 memory and Redis/Valkey L2 storage."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["redis>=5.0"]
+
+[[project.authors]]
+name = "Veeresh Hanni"
+email = "veereshhanni347@gmail.com"
+
+[build-system]
+requires = ["uv_build>=0.12.20,<0.13.0"]
+build-backend = "uv_build"

hydict-0.5.0/pyproject.toml.orig

@@ -0,0 +1,16 @@
+[project]
+name = "hydict"
+version = "0.5.0"
+description = "hydict — a dict-compatible hierarchical cache for Python with local L1 memory and Redis/Valkey L2 storage."
+readme = "README.md"
+authors = [
+    { name = "Veeresh Hanni", email = "veereshhanni347@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "redis>=5.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.20,<0.13.0"]
+build-backend = "uv_build"

hydict-0.5.0/src/hydict/__init__.py

@@ -0,0 +1,17 @@
+from .core import HDict
+from .config import RedisConfig
+from .exceptions import (
+    HydictError,
+    BackendError,
+    BackendConnectionError,
+    BackendOperationError,
+)
+
+__all__ = [
+    "HDict",
+    "RedisConfig",
+    "HydictError",
+    "BackendError",
+    "BackendConnectionError",
+    "BackendOperationError",
+]

hydict-0.5.0/src/hydict/backends/__init__.py

@@ -0,0 +1,9 @@
+from .base import Backend
+from .memory import MemoryBackend
+from .remote import RemoteBackend
+
+__all__ = [
+    "Backend",
+    "MemoryBackend",
+    "RemoteBackend",
+]

hydict-0.5.0/src/hydict/backends/base.py

@@ -0,0 +1,32 @@
+from abc import ABC, abstractmethod
+
+
+class Backend(ABC):
+
+    @abstractmethod
+    def set(self, key, value, ttl=None):
+        pass
+
+    @abstractmethod
+    def get(self, key):
+        pass
+
+    @abstractmethod
+    def get_with_ttl(self, key):
+        pass
+
+    @abstractmethod
+    def delete(self, key):
+        pass
+
+    @abstractmethod
+    def exists(self, key):
+        pass
+
+    @abstractmethod
+    def clear(self):
+        pass
+
+    @abstractmethod
+    def __len__(self):
+        pass

hydict-0.5.0/src/hydict/backends/memory.py

@@ -0,0 +1,102 @@
+from collections import OrderedDict
+import threading
+import time
+
+from .base import Backend
+
+class MemoryBackend(Backend):
+
+    def __init__(self, max_entries=None):
+        self._data = OrderedDict()
+        self._expiry = {}
+        self.max_entries = max_entries
+        self._lock = threading.RLock()
+
+    def set(self, key, value, ttl=None):
+        with self._lock:
+            self._data[key] = value
+            self._data.move_to_end(key)
+
+            if ttl is None:
+                self._expiry.pop(key, None)
+            else:
+                self._expiry[key] = time.monotonic() + ttl
+
+            self._evict_if_needed()
+
+    def get(self, key):
+        with self._lock:
+            self._remove_if_expired(key)
+
+            value = self._data[key]
+
+            self._data.move_to_end(key)
+
+            return value
+
+    def get_with_ttl(self, key):
+        with self._lock:
+            self._remove_if_expired(key)
+
+            if key not in self._data:
+                raise KeyError(key)
+
+            expiry = self._expiry.get(key)
+
+            if expiry is None:
+                ttl = -1
+            else:
+                remaining = expiry - time.monotonic()
+
+                if remaining <= 0:
+                    self._remove_if_expired(key)
+                    raise KeyError(key)
+
+                ttl = max(0, int(remaining))
+
+            self._data.move_to_end(key)
+
+            return self._data[key], ttl
+
+    def delete(self, key):
+        with self._lock:
+            self._remove_if_expired(key)
+
+            del self._data[key]
+            self._expiry.pop(key, None)
+
+    def exists(self, key):
+        with self._lock:
+            self._remove_if_expired(key)
+            return key in self._data
+
+    def clear(self):
+        with self._lock:
+            self._data.clear()
+            self._expiry.clear()
+
+    def __len__(self):
+        with self._lock:
+            self._remove_expired()
+            return len(self._data)
+
+    def _evict_if_needed(self):
+        if self.max_entries is None:
+            return
+
+        while len(self._data) > self.max_entries:
+            oldest_key, _ = self._data.popitem(last=False)
+            self._expiry.pop(oldest_key, None)
+
+    def _remove_if_expired(self, key):
+        expiry = self._expiry.get(key)
+
+        if expiry is not None and time.monotonic() >= expiry:
+            self._data.pop(key, None)
+            self._expiry.pop(key, None)
+
+    def _remove_expired(self):
+        for key in list(self._expiry):
+            self._remove_if_expired(key)
+
+    

hydict-0.5.0/src/hydict/backends/remote.py

@@ -0,0 +1,153 @@
+import redis
+
+from redis.exceptions import ConnectionError as RedisConnectionError
+from redis.exceptions import RedisError
+
+from ..config.redis import RedisConfig
+from .base import Backend
+
+from ..exceptions import (
+    BackendConnectionError,
+    BackendOperationError,
+)
+
+from ..serialization import Serializer
+
+class RemoteBackend(Backend):
+    
+    def __init__(self, config: RedisConfig):
+        if config.pool_timeout is None:
+            pool = redis.ConnectionPool(
+                host=config.host,
+                port=config.port,
+                db=config.db,
+                password=config.password,
+                decode_responses=config.decode_responses,
+                max_connections=config.max_connections,
+            )
+        else:
+            pool = redis.BlockingConnectionPool(
+                host=config.host,
+                port=config.port,
+                db=config.db,
+                password=config.password,
+                decode_responses=config.decode_responses,
+                max_connections=config.max_connections,
+                timeout=config.pool_timeout,
+            )
+
+        self.client = redis.Redis(connection_pool=pool)
+        self.serializer = Serializer()
+
+    def set(self, key, value, ttl=None):
+        try:
+            value = self.serializer.serialize(value)
+
+            if ttl is None:
+                self.client.set(key, value)
+            else:
+                self.client.set(key, value, ex=ttl)
+
+        except RedisConnectionError as exc:
+            raise BackendConnectionError(
+                "Remote backend connection failed"
+            ) from exc
+
+        except RedisError as exc:
+            raise BackendOperationError(
+                f"Failed to set key: {key}"
+            ) from exc
+
+    def get(self, key):
+        try:
+            value = self.client.get(key)
+
+        except RedisConnectionError as exc:
+            raise BackendConnectionError(
+                "Remote backend connection failed"
+            ) from exc
+
+        except RedisError as exc:
+            raise BackendOperationError(
+                f"Failed to get key: {key}"
+            ) from exc
+
+        if value is None:
+            raise KeyError(key)
+
+        return self.serializer.deserialize(value)
+
+    def delete(self, key):
+        try:
+            self.client.delete(key)
+
+        except RedisConnectionError as exc:
+            raise BackendConnectionError(
+                "Remote backend connection failed"
+            ) from exc
+
+        except RedisError as exc:
+            raise BackendOperationError(
+                f"Failed to delete key: {key}"
+            ) from exc
+
+    def exists(self, key):
+        try:
+            return self.client.exists(key) > 0
+
+        except RedisConnectionError as exc:
+            raise BackendConnectionError(
+                "Remote backend connection failed"
+            ) from exc
+
+        except RedisError as exc:
+            raise BackendOperationError(
+                f"Failed to check key: {key}"
+            ) from exc
+
+    def clear(self):
+        try:
+            self.client.flushdb()
+
+        except RedisConnectionError as exc:
+            raise BackendConnectionError(
+                "Remote backend connection failed"
+            ) from exc
+
+        except RedisError as exc:
+            raise BackendOperationError(
+                "Failed to clear remote backend"
+            ) from exc
+
+    def get_with_ttl(self, key):
+        try:
+            value = self.client.get(key)
+
+            if value is None:
+                raise KeyError(key)
+
+            ttl = self.client.ttl(key)
+
+            return self.serializer.deserialize(value), ttl
+
+        except RedisConnectionError as exc:
+            raise BackendConnectionError(
+                "Remote backend connection failed"
+            ) from exc
+
+        except RedisError as exc:
+            raise BackendOperationError(
+                f"Failed to get key: {key}"
+            ) from exc
+
+    def __len__(self):
+        try:
+            return self.client.dbsize()
+        except RedisConnectionError as exc:
+            raise BackendConnectionError(
+                "Remote backend connection failed"
+            ) from exc
+        except RedisError as exc:
+            raise BackendOperationError(
+                "Failed to get remote backend size"
+            ) from exc

hydict-0.5.0/src/hydict/config/__init__.py

@@ -0,0 +1,3 @@
+
+from .redis import RedisConfig
+__all__ = ["RedisConfig"]

hydict-0.5.0/src/hydict/config/cache.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class CacheConfig:
+    host: str = "localhost"
+    port: int = 6379
+    db: int = 0
+    password: str | None = None
+    decode_responses: bool = True

hydict-0.5.0/src/hydict/config/redis.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class RedisConfig:
+    host: str = "localhost"
+    port: int = 6379
+    db: int = 0
+    password: str | None = None
+    decode_responses: bool = True
+    max_connections: int | None = None
+    pool_timeout: float | None = None

hydict-0.5.0/src/hydict/core/__init__.py

@@ -0,0 +1,3 @@
+from .hdict import HDict
+
+__all__ = ["HDict"]

hydict-0.5.0/src/hydict/core/hdict.py

@@ -0,0 +1,139 @@
+from ..stampede.protection import StampedeProtection
+
+from ..backends.memory import MemoryBackend
+from ..backends.remote import RemoteBackend
+from ..config.redis import RedisConfig
+from ..invalidation import CacheInvalidator
+from ..metrics import MetricsCollector
+
+class HDict:
+    """
+    Thread-safe hybrid cache.
+
+    Thread-safety guarantees:
+    - Individual public operations are safe to call concurrently.
+    - The in-memory L1 backend protects its internal state with a lock.
+    - L1 and L2 operations are not an atomic transaction.
+    - A thread may observe another thread's update between L1 and L2 operations.
+    """
+    def __init__(self, config=None, max_entries=None):
+        self._memory = MemoryBackend(max_entries=max_entries)
+
+        self._remote = None
+
+        if config is not None:
+            self._remote = RemoteBackend(config)
+            
+        self._invalidator = CacheInvalidator(
+                                    self._memory,
+                                    self._remote,
+                                )
+        self._stampede = StampedeProtection()
+        self._metrics = MetricsCollector()
+
+    def __setitem__(self, key, value):
+        # Write to L1
+        self._memory.set(key, value)
+
+        # Write to L2
+        if self._remote is not None:
+            self._remote.set(key, value)
+
+    def __getitem__(self, key, _record_metrics=True):
+        if self._memory.exists(key):
+            if _record_metrics:
+                self._metrics.record_l1_hit()
+            return self._memory.get(key)
+
+        if self._remote is not None:
+            try:
+                value, ttl = self._remote.get_with_ttl(key)
+            except KeyError:
+                if _record_metrics:
+                    self._metrics.record_miss()
+                raise
+
+            if _record_metrics:
+                self._metrics.record_l2_hit()
+
+            if ttl < 0:
+                self._memory.set(key, value)
+            else:
+                self._memory.set(key, value, ttl=ttl)
+
+            return value
+
+        if _record_metrics:
+            self._metrics.record_miss()
+
+        raise KeyError(key)
+    
+    def __delitem__(self, key):
+        self._memory.delete(key)
+
+        if self._remote is not None:
+            self._remote.delete(key)
+
+    def __contains__(self, key):
+
+        if self._memory.exists(key):
+            return True
+
+        if self._remote is not None:
+            return self._remote.exists(key)
+
+        return False
+
+    def __len__(self):
+        return len(self._memory)
+
+    def get(self, key, default=None):
+        try:
+            return self[key]
+        except KeyError:
+            return default
+
+    def clear(self):
+        self._memory.clear()
+
+        if self._remote is not None:
+            self._remote.clear()
+
+    def set(self, key, value, ttl=None):
+        self._memory.set(key, value, ttl=ttl)
+
+        if self._remote is not None:
+            self._remote.set(key, value, ttl=ttl)
+
+    def invalidate(self, key):
+        self._invalidator.invalidate(key)
+
+    def get_or_set(self, key, loader, ttl=None):
+        try:
+            return self[key]
+        except KeyError:
+            pass
+
+        lock = self._stampede.get_lock(key)
+
+        with lock:
+            try:
+                return self.__getitem__(key, _record_metrics=False)
+            except KeyError:
+                pass
+
+            self._metrics.record_loader_call()
+
+            value = loader()
+            self.set(key, value, ttl=ttl)
+
+            return value
+
+    def stats(self):
+        return {
+            "l1_hits": self._metrics.l1_hits,
+            "l2_hits": self._metrics.l2_hits,
+            "total_hits": self._metrics.l1_hits + self._metrics.l2_hits,
+            "misses": self._metrics.misses,
+            "loader_calls": self._metrics.loader_calls,
+        }

hydict-0.5.0/src/hydict/exceptions.py

@@ -0,0 +1,14 @@
+class HydictError(Exception):
+    """Base exception for hydict."""
+
+
+class BackendError(HydictError):
+    """Base exception for backend failures."""
+
+
+class BackendConnectionError(BackendError):
+    """Raised when a backend cannot be reached."""
+
+
+class BackendOperationError(BackendError):
+    """Raised when a backend operation fails."""

hydict-0.5.0/src/hydict/invalidation/__init__.py

@@ -0,0 +1,3 @@
+from .invalidator import CacheInvalidator
+
+__all__ = ["CacheInvalidator"]

hydict-0.5.0/src/hydict/invalidation/invalidator.py

@@ -0,0 +1,25 @@
+from hydict.backends import Backend
+
+
+class CacheInvalidator:
+
+    def __init__(self, l1: Backend, l2: Backend | None = None):
+        self.l1 = l1
+        self.l2 = l2
+
+    def invalidate(self, key):
+        """
+        Remove a key from both L1 and L2.
+
+        Missing keys are ignored.
+        """
+        self._delete(self.l1, key)
+        if self.l2 is not None:
+            self._delete(self.l2, key)
+
+    @staticmethod
+    def _delete(backend: Backend, key):
+        try:
+            backend.delete(key)
+        except KeyError:
+            pass

hydict-0.5.0/src/hydict/metrics/__init__.py

@@ -0,0 +1,3 @@
+from .collector import MetricsCollector
+
+__all__ = ["MetricsCollector"]

hydict-0.5.0/src/hydict/metrics/collector.py

@@ -0,0 +1,18 @@
+class MetricsCollector:
+    def __init__(self):
+        self.l1_hits = 0
+        self.l2_hits = 0
+        self.misses = 0
+        self.loader_calls = 0
+
+    def record_l1_hit(self):
+        self.l1_hits += 1
+
+    def record_l2_hit(self):
+        self.l2_hits += 1
+
+    def record_miss(self):
+        self.misses += 1
+
+    def record_loader_call(self):
+        self.loader_calls += 1

hydict-0.5.0/src/hydict/serialization/__init__.py

@@ -0,0 +1,3 @@
+from .serializer import Serializer
+
+__all__ = ["Serializer"]

hydict-0.5.0/src/hydict/serialization/serializer.py

@@ -0,0 +1,10 @@
+import json
+
+
+class Serializer:
+
+    def serialize(self, value):
+        return json.dumps(value)
+
+    def deserialize(self, value):
+        return json.loads(value)

hydict-0.5.0/src/hydict/stampede/__init__.py

@@ -0,0 +1,3 @@
+from .protection import StampedeProtection
+
+__all__ = ["StampedeProtection"]

hydict-0.5.0/src/hydict/stampede/protection.py

@@ -0,0 +1,15 @@
+import threading
+
+class StampedeProtection:
+
+    def __init__(self):
+        self._locks = {}
+        self._lock = threading.Lock()
+
+    def get_lock(self, key):
+        with self._lock:
+            if key not in self._locks:
+                self._locks[key] = threading.Lock()
+
+            return self._locks[key]
+