gcache 2.0.0__tar.gz → 2.0.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: gcache
-Version: 2.0.0
+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.
@@ -201,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,
@@ -221,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

{gcache-2.0.0 → 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.
@@ -169,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,
@@ -189,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

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

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