gcache 1.2.1__tar.gz → 2.0.2__tar.gz

{gcache-1.2.1 → gcache-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: gcache
-Version: 1.2.1
+Version: 2.0.2
 Summary: Fine grained caching.
 License: MIT
 Author: Galileo Technologies Inc.
@@ -35,6 +35,7 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://badge.fury.io/py/gcache.svg)](https://badge.fury.io/py/gcache)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![codecov](https://codecov.io/gh/rungalileo/gcache/graph/badge.svg)](https://codecov.io/gh/rungalileo/gcache)
 
 A caching library built for moving fast without breaking things. GCache lets you rapidly add new caching use cases while maintaining structure and runtime control guardrails—so you can ramp up gradually, kill a bad cache instantly, and have full observability into what's cached across your system.
 
@@ -67,6 +68,7 @@ gcache = GCache(GCacheConfig())
 @gcache.cached(
     key_type="user_id",
     id_arg="user_id",
+    use_case="GetUser",
     default_config=GCacheKeyConfig(
         ttl_sec={CacheLayer.LOCAL: 60, CacheLayer.REMOTE: 300},
         ramp={CacheLayer.LOCAL: 100, CacheLayer.REMOTE: 100},
@@ -77,7 +79,7 @@ async def get_user(user_id: str) -> dict:
 
 # Use it — caching only happens inside enable() blocks
 with gcache.enable():
-    user = await get_user("123")  # Cached!
+    user = await get_user("123")  # Cache key: urn:gcache:user_id:123#GetUser
 ```
 
 That's it. The function works normally outside `enable()` blocks, and caches results inside them.
@@ -136,6 +138,24 @@ Caching doesn't happen automatically—you control when it's active:
 
 - **Dynamic config** — The config provider runs on each request, so you can adjust TTLs or ramp percentages without redeploying.
 
+### Why Explicit `enable()`?
+
+GCache requires you to explicitly enable caching with `with gcache.enable():`. This is intentional.
+
+Caching in write paths can cause subtle bugs—a stale read might get cached right before a write, leading to inconsistent data. By requiring explicit opt-in, GCache forces you to consciously decide where caching is safe:
+
+```python
+# Read path — caching is safe
+with gcache.enable():
+    user = await get_user(user_id)
+
+# Write path — no caching, function runs normally
+await update_user(user_id, new_data)
+await gcache.ainvalidate("user_id", user_id)
+```
+
+This design prevents accidental caching in dangerous places.
+
 ## Runtime Configuration
 
 For dynamic control, provide a config provider when creating GCache. This lets you adjust caching behavior without redeploying:
@@ -183,17 +203,49 @@ async def get_user_profile(user_id: str) -> dict:
 
 ### Working with Complex Arguments
 
-Real functions have complex arguments. Use `id_arg` tuples and `arg_adapters` to handle them:
+Options for mapping function arguments to cache keys.
+
+#### `id_arg` (required)
+
+Specifies which argument contains the entity ID for the cache key.
+
+**String form** — use when the argument itself is the ID:
+```python
+id_arg="user_id"  # user_id argument is the ID
+```
+
+**Tuple form** — use when the ID needs to be extracted from an object:
+```python
+id_arg=("user", lambda u: u.id)  # Extract ID from User object
+```
+
+#### `arg_adapters`
+
+Converts complex arguments to strings for the cache key. Only needed for non-primitive types.
+
+```python
+arg_adapters={
+    "filters": lambda f: f.to_cache_key(),  # Complex object
+    "page": str,                             # Simple conversion
+}
+```
+
+#### `ignore_args`
+
+Excludes arguments that don't affect the cached result.
+
+```python
+ignore_args=["db_session", "logger"]
+```
+
+#### Example
 
 ```python
 @gcache.cached(
     key_type="user_id",
-    id_arg=("user", lambda u: u.id),  # Extract ID from User object
-    arg_adapters={
-        "filters": lambda f: f.to_cache_key(),  # Convert complex objects
-        "page": str,  # Simple conversion
-    },
-    ignore_args=["db_session", "logger"],  # Don't include these in cache key
+    id_arg=("user", lambda u: u.id),
+    arg_adapters={"filters": lambda f: f.to_cache_key()},
+    ignore_args=["db_session", "logger"],
 )
 async def search_user_posts(
     user: User,
@@ -203,8 +255,12 @@ async def search_user_posts(
     logger: Logger,
 ) -> list[Post]:
     ...
+
+# Cache key: urn:gcache:user_id:123?filters=active&page=2#SearchUserPosts
 ```
 
+The `id_arg` becomes `:123`, `arg_adapters` produce `?filters=active&page=2`, and `ignore_args` are excluded.
+
 ### Sync Functions Work Too
 
 ```python
@@ -230,7 +286,6 @@ from gcache import RedisConfig
 
 gcache = GCache(
     GCacheConfig(
-        cache_config_provider=config_provider,
         redis_config=RedisConfig(
             host="redis.example.com",
             port=6379,
@@ -261,7 +316,6 @@ def make_redis_factory():
 
 gcache = GCache(
     GCacheConfig(
-        cache_config_provider=config_provider,
         redis_client_factory=make_redis_factory(),
     )
 )
@@ -337,7 +391,6 @@ You can add a prefix to avoid collisions:
 
 ```python
 GCacheConfig(
-    cache_config_provider=config_provider,
     metrics_prefix="myapp_",  # Metrics become myapp_gcache_request_counter, etc.
 )
 ```

{gcache-1.2.1 → gcache-2.0.2}/README.md

@@ -3,6 +3,7 @@
 [![PyPI version](https://badge.fury.io/py/gcache.svg)](https://badge.fury.io/py/gcache)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![codecov](https://codecov.io/gh/rungalileo/gcache/graph/badge.svg)](https://codecov.io/gh/rungalileo/gcache)
 
 A caching library built for moving fast without breaking things. GCache lets you rapidly add new caching use cases while maintaining structure and runtime control guardrails—so you can ramp up gradually, kill a bad cache instantly, and have full observability into what's cached across your system.
 
@@ -35,6 +36,7 @@ gcache = GCache(GCacheConfig())
 @gcache.cached(
     key_type="user_id",
     id_arg="user_id",
+    use_case="GetUser",
     default_config=GCacheKeyConfig(
         ttl_sec={CacheLayer.LOCAL: 60, CacheLayer.REMOTE: 300},
         ramp={CacheLayer.LOCAL: 100, CacheLayer.REMOTE: 100},
@@ -45,7 +47,7 @@ async def get_user(user_id: str) -> dict:
 
 # Use it — caching only happens inside enable() blocks
 with gcache.enable():
-    user = await get_user("123")  # Cached!
+    user = await get_user("123")  # Cache key: urn:gcache:user_id:123#GetUser
 ```
 
 That's it. The function works normally outside `enable()` blocks, and caches results inside them.
@@ -104,6 +106,24 @@ Caching doesn't happen automatically—you control when it's active:
 
 - **Dynamic config** — The config provider runs on each request, so you can adjust TTLs or ramp percentages without redeploying.
 
+### Why Explicit `enable()`?
+
+GCache requires you to explicitly enable caching with `with gcache.enable():`. This is intentional.
+
+Caching in write paths can cause subtle bugs—a stale read might get cached right before a write, leading to inconsistent data. By requiring explicit opt-in, GCache forces you to consciously decide where caching is safe:
+
+```python
+# Read path — caching is safe
+with gcache.enable():
+    user = await get_user(user_id)
+
+# Write path — no caching, function runs normally
+await update_user(user_id, new_data)
+await gcache.ainvalidate("user_id", user_id)
+```
+
+This design prevents accidental caching in dangerous places.
+
 ## Runtime Configuration
 
 For dynamic control, provide a config provider when creating GCache. This lets you adjust caching behavior without redeploying:
@@ -151,17 +171,49 @@ async def get_user_profile(user_id: str) -> dict:
 
 ### Working with Complex Arguments
 
-Real functions have complex arguments. Use `id_arg` tuples and `arg_adapters` to handle them:
+Options for mapping function arguments to cache keys.
+
+#### `id_arg` (required)
+
+Specifies which argument contains the entity ID for the cache key.
+
+**String form** — use when the argument itself is the ID:
+```python
+id_arg="user_id"  # user_id argument is the ID
+```
+
+**Tuple form** — use when the ID needs to be extracted from an object:
+```python
+id_arg=("user", lambda u: u.id)  # Extract ID from User object
+```
+
+#### `arg_adapters`
+
+Converts complex arguments to strings for the cache key. Only needed for non-primitive types.
+
+```python
+arg_adapters={
+    "filters": lambda f: f.to_cache_key(),  # Complex object
+    "page": str,                             # Simple conversion
+}
+```
+
+#### `ignore_args`
+
+Excludes arguments that don't affect the cached result.
+
+```python
+ignore_args=["db_session", "logger"]
+```
+
+#### Example
 
 ```python
 @gcache.cached(
     key_type="user_id",
-    id_arg=("user", lambda u: u.id),  # Extract ID from User object
-    arg_adapters={
-        "filters": lambda f: f.to_cache_key(),  # Convert complex objects
-        "page": str,  # Simple conversion
-    },
-    ignore_args=["db_session", "logger"],  # Don't include these in cache key
+    id_arg=("user", lambda u: u.id),
+    arg_adapters={"filters": lambda f: f.to_cache_key()},
+    ignore_args=["db_session", "logger"],
 )
 async def search_user_posts(
     user: User,
@@ -171,8 +223,12 @@ async def search_user_posts(
     logger: Logger,
 ) -> list[Post]:
     ...
+
+# Cache key: urn:gcache:user_id:123?filters=active&page=2#SearchUserPosts
 ```
 
+The `id_arg` becomes `:123`, `arg_adapters` produce `?filters=active&page=2`, and `ignore_args` are excluded.
+
 ### Sync Functions Work Too
 
 ```python
@@ -198,7 +254,6 @@ from gcache import RedisConfig
 
 gcache = GCache(
     GCacheConfig(
-        cache_config_provider=config_provider,
         redis_config=RedisConfig(
             host="redis.example.com",
             port=6379,
@@ -229,7 +284,6 @@ def make_redis_factory():
 
 gcache = GCache(
     GCacheConfig(
-        cache_config_provider=config_provider,
         redis_client_factory=make_redis_factory(),
     )
 )
@@ -305,7 +359,6 @@ You can add a prefix to avoid collisions:
 
 ```python
 GCacheConfig(
-    cache_config_provider=config_provider,
     metrics_prefix="myapp_",  # Metrics become myapp_gcache_request_counter, etc.
 )
 ```

{gcache-1.2.1 → gcache-2.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gcache"
-version = "1.2.1"
+version = "2.0.2"
 description = "Fine grained caching."
 authors = [{ name = "Galileo Technologies Inc.", email = "team@rungalileo.io" }]
 readme = "README.md"

{gcache-1.2.1 → gcache-2.0.2}/src/gcache/__init__.py

@@ -1,3 +1,4 @@
-from .base import CacheConfigProvider, CacheLayer, GCache, GCacheConfig, GCacheKey, GCacheKeyConfig, RedisConfig
+from gcache.config import CacheConfigProvider, CacheLayer, GCacheConfig, GCacheKey, GCacheKeyConfig, RedisConfig
+from gcache.gcache import GCache
 
 __all__ = ["CacheConfigProvider", "CacheLayer", "GCache", "GCacheConfig", "GCacheKey", "GCacheKeyConfig", "RedisConfig"]

gcache-2.0.2/src/gcache/_internal/__init__.py

@@ -0,0 +1 @@
+# Internal implementation modules - not part of public API

gcache-2.0.2/src/gcache/_internal/cache_interface.py

@@ -0,0 +1,69 @@
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from gcache.config import CacheConfigProvider, CacheLayer, GCacheKey, GCacheKeyConfig
+
+#: Async callable that fetches the actual value on cache miss.
+#: Invoked by cache implementations when the requested key is not found or is stale.
+Fallback = Callable[..., Awaitable[Any]]
+
+
+class CacheInterface(ABC):
+    def __init__(self, cache_config_provider: CacheConfigProvider):
+        self.config_provider = cache_config_provider
+
+    async def _resolve_config(self, key: GCacheKey) -> GCacheKeyConfig | None:
+        """
+        Resolve the cache config for a key.
+
+        First tries the config provider, then falls back to the key's default_config.
+        Returns None if neither provides a config.
+        """
+        config = await self.config_provider(key)
+        if config is None:
+            config = key.default_config
+        return config
+
+    @abstractmethod
+    async def get(self, key: GCacheKey, fallback: Fallback) -> Any:
+        pass
+
+    @abstractmethod
+    async def put(self, key: GCacheKey, value: Any) -> None:
+        pass
+
+    @abstractmethod
+    async def delete(self, key: GCacheKey) -> bool:
+        pass
+
+    async def invalidate(self, key_type: str, id: str, future_buffer_ms: int) -> None:
+        """
+        Invalidate all cache entries matching key_type and id.
+
+        Sets a watermark timestamp so that any cached value created before
+        (now + future_buffer_ms) is considered stale on subsequent reads.
+
+        :param key_type: The entity type (e.g., 'user', 'project') matching the
+            key_type used in @cached decorators.
+        :param id: The entity identifier to invalidate.
+        :param future_buffer_ms: Extends invalidation window into the future.
+            Useful to handle race conditions where a read starts before a write
+            completes but finishes after, preventing caching of stale data.
+        """
+        pass
+
+    @abstractmethod
+    def layer(self) -> CacheLayer:
+        pass
+
+    async def flushall(self) -> None:
+        """
+        Remove all entries from this cache layer.
+
+        Used primarily for testing to reset cache state between tests.
+        Default implementation is a no-op; subclasses should override if
+        they support flushing (e.g., LocalCache clears its TTLCache dict,
+        RedisCache calls FLUSHALL on Redis).
+        """
+        pass

gcache-2.0.2/src/gcache/_internal/constants.py

@@ -0,0 +1,18 @@
+# Cache sizes
+# Default max entries per use case to prevent unbounded memory growth.
+LOCAL_CACHE_MAX_SIZE = 10_000
+
+# Thresholds
+# Threshold above which pickling runs in a thread to avoid blocking the event loop.
+ASYNC_PICKLE_THRESHOLD_BYTES = 50_000
+
+# TTLs (seconds)
+# Watermark TTL must be longer than any invalidatable cache's TTL to ensure
+# invalidation works correctly. 4 hours is a heuristic that covers most use cases.
+# If your cache TTLs exceed 4 hours, consider making this configurable.
+WATERMARK_TTL_SECONDS = 3600 * 4  # 4 hours
+
+# Thread pool
+# Default thread pool size for running async operations from sync code.
+# Balances concurrency for I/O-bound Redis operations without excessive resource usage.
+EVENT_LOOP_THREAD_POOL_SIZE = 16

{gcache-1.2.1/src/gcache → gcache-2.0.2/src/gcache/_internal}/event_loop_thread.py

@@ -7,7 +7,21 @@ from concurrent.futures import Future
 from logging import getLogger
 from typing import Any
 
-import uvloop
+from gcache._internal.constants import EVENT_LOOP_THREAD_POOL_SIZE
+
+# uvloop is optional - provides better performance on Linux/macOS but
+# doesn't work on Windows or PyPy. Fall back to standard asyncio if unavailable.
+try:
+    import uvloop
+
+    def _new_event_loop() -> asyncio.AbstractEventLoop:
+        return uvloop.new_event_loop()
+
+except ImportError:
+
+    def _new_event_loop() -> asyncio.AbstractEventLoop:
+        return asyncio.new_event_loop()
+
 
 logger = getLogger(__name__)
 
@@ -31,7 +45,7 @@ class EventLoopThread(EventLoopThreadInterface, threading.Thread):
     def __init__(self, name: str = "EventLoopThread", daemon: bool = True) -> None:
         super().__init__(name=name)
         self.daemon = daemon
-        self.loop = uvloop.new_event_loop()
+        self.loop = _new_event_loop()
 
     def run(self) -> None:
         # Set the event loop for this thread.
@@ -68,12 +82,12 @@ class EventLoopThread(EventLoopThreadInterface, threading.Thread):
 
 class EventLoopThreadPool(EventLoopThreadInterface):
     """
-    Manage collection of EventLoopThread instances and also initailize them lazily.
+    Manage collection of EventLoopThread instances and also initialize them lazily.
 
     Lazy initialization is important when running in forked processes.
     """
 
-    def __init__(self, name: str = "EventLoopThreadPool", num_threads: int = 16) -> None:
+    def __init__(self, name: str = "EventLoopThreadPool", num_threads: int = EVENT_LOOP_THREAD_POOL_SIZE) -> None:
         self.name = name
         self.num_threads = num_threads
         self.threads: list[EventLoopThread] | None = None

gcache-2.0.2/src/gcache/_internal/local_cache.py

@@ -0,0 +1,71 @@
+import asyncio
+from typing import Any
+
+from cachetools import TTLCache
+
+from gcache._internal.cache_interface import CacheInterface, Fallback
+from gcache._internal.constants import LOCAL_CACHE_MAX_SIZE
+from gcache._internal.state import _GLOBAL_GCACHE_STATE
+from gcache.config import CacheConfigProvider, CacheLayer, GCacheKey
+from gcache.exceptions import MissingKeyConfig
+
+
+class LocalCache(CacheInterface):
+    """
+    In-memory cache layer using TTLCache from cachetools.
+
+    Maintains a separate TTLCache instance per use_case, each with a configurable
+    TTL and a max size of LOCAL_CACHE_MAX_SIZE entries. This is the first layer
+    in the cache chain, checked before Redis.
+
+    Note: LocalCache does not support invalidation (watermarks). If you need
+    invalidation support, rely on the Redis layer with track_for_invalidation=True.
+    """
+
+    def __init__(self, cache_config_provider: CacheConfigProvider):
+        super().__init__(cache_config_provider)
+        self.caches: dict[str, TTLCache] = {}  # use_case -> TTLCache instance
+        self.lock = asyncio.Lock()  # Protects cache creation
+
+    async def _get_ttl_cache(self, key: GCacheKey) -> TTLCache:
+        cache = self.caches.get(key.use_case, None)
+        if cache is None:
+            config = await self._resolve_config(key)
+            if config is None:
+                raise MissingKeyConfig(key.use_case)
+
+            async with self.lock:
+                # See if cache was already created by another worker.
+                cache = self.caches.get(key.use_case, None)
+                if cache is None:
+                    self.caches[key.use_case] = cache = TTLCache(
+                        maxsize=LOCAL_CACHE_MAX_SIZE, ttl=config.ttl_sec[self.layer()]
+                    )
+
+        return cache
+
+    async def get(self, key: GCacheKey, fallback: Fallback) -> Any:
+        _GLOBAL_GCACHE_STATE.logger.debug("Calling local cache")
+        cache = await self._get_ttl_cache(key)
+
+        if key not in cache:
+            await self.put(key, await fallback())
+
+        return cache[key]
+
+    async def put(self, key: GCacheKey, value: Any) -> None:
+        (await self._get_ttl_cache(key))[key] = value
+
+    async def delete(self, key: GCacheKey) -> bool:
+        try:
+            (await self._get_ttl_cache(key)).pop(key)
+        except KeyError:
+            return False
+        return True
+
+    def layer(self) -> CacheLayer:
+        return CacheLayer.LOCAL
+
+    async def flushall(self) -> None:
+        async with self.lock:
+            self.caches.clear()

gcache-2.0.2/src/gcache/_internal/metrics.py

@@ -0,0 +1,86 @@
+from prometheus_client import Counter, Histogram
+
+
+class GCacheMetrics:
+    """Centralized Prometheus metrics for GCache."""
+
+    _initialized: bool = False
+
+    # Counters
+    DISABLED_COUNTER: Counter
+    MISS_COUNTER: Counter
+    REQUEST_COUNTER: Counter
+    ERROR_COUNTER: Counter
+    INVALIDATION_COUNTER: Counter
+
+    # Histograms
+    GET_TIMER: Histogram
+    FALLBACK_TIMER: Histogram
+    SERIALIZATION_TIMER: Histogram
+    SIZE_HISTOGRAM: Histogram
+
+    @classmethod
+    def initialize(cls, prefix: str = "") -> None:
+        """Initialize all metrics with the given prefix. Only initializes once."""
+        if cls._initialized:
+            return
+
+        cls.DISABLED_COUNTER = Counter(
+            name=prefix + "gcache_disabled_counter",
+            labelnames=["use_case", "key_type", "layer", "reason"],
+            documentation="Cache disabled counter",
+        )
+
+        cls.MISS_COUNTER = Counter(
+            name=prefix + "gcache_miss_counter",
+            labelnames=["use_case", "key_type", "layer"],
+            documentation="Cache miss counter",
+        )
+
+        cls.REQUEST_COUNTER = Counter(
+            name=prefix + "gcache_request_counter",
+            labelnames=["use_case", "key_type", "layer"],
+            documentation="Cache request counter",
+        )
+
+        cls.ERROR_COUNTER = Counter(
+            name=prefix + "gcache_error_counter",
+            labelnames=["use_case", "key_type", "layer", "error", "in_fallback"],
+            documentation="Cache error counter",
+        )
+
+        cls.INVALIDATION_COUNTER = Counter(
+            name=prefix + "gcache_invalidation_counter",
+            labelnames=["key_type", "layer"],
+            documentation="Cache invalidation counter",
+        )
+
+        cls.GET_TIMER = Histogram(
+            name=prefix + "gcache_get_timer",
+            labelnames=["use_case", "key_type", "layer"],
+            documentation="Cache get timer",
+            buckets=[0.001] + list(Histogram.DEFAULT_BUCKETS),
+        )
+
+        cls.FALLBACK_TIMER = Histogram(
+            name=prefix + "gcache_fallback_timer",
+            labelnames=["use_case", "key_type", "layer"],
+            documentation="Fallback timer",
+            buckets=[0.001] + list(Histogram.DEFAULT_BUCKETS),
+        )
+
+        cls.SERIALIZATION_TIMER = Histogram(
+            name=prefix + "gcache_serialization_timer",
+            labelnames=["use_case", "key_type", "layer", "operation"],
+            documentation="Cache serialization timer",
+            buckets=[0.001] + list(Histogram.DEFAULT_BUCKETS),
+        )
+
+        cls.SIZE_HISTOGRAM = Histogram(
+            name=prefix + "gcache_size_histogram",
+            labelnames=["use_case", "key_type", "layer"],
+            documentation="Cache size histogram",
+            buckets=[100, 1000, 10_000, 100_000, 1_000_000, 10_000_000],
+        )
+
+        cls._initialized = True

gcache-2.0.2/src/gcache/_internal/noop_cache.py

@@ -0,0 +1,22 @@
+from typing import Any
+
+from gcache._internal.cache_interface import CacheInterface, Fallback
+from gcache.config import CacheLayer, GCacheKey
+
+
+class NoopCache(CacheInterface):
+    """
+    NOOP Cache that does nothing but invoke fallback on get.
+    """
+
+    async def get(self, key: GCacheKey, fallback: Fallback) -> Any:
+        return await fallback()
+
+    async def put(self, key: GCacheKey, value: Any) -> None:
+        pass
+
+    async def delete(self, key: GCacheKey) -> bool:
+        return False
+
+    def layer(self) -> CacheLayer:
+        return CacheLayer.NOOP