oplnk-python-utils 1.0.1__tar.gz → 1.0.2__tar.gz

{oplnk_python_utils-1.0.1/oplnk_python_utils.egg-info → oplnk_python_utils-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oplnk-python-utils
-Version: 1.0.1
+Version: 1.0.2
 Summary: Reusable utilities for caching, data manipulation, parsing, and MongoDB query building
 Home-page: https://github.com/openlinkspa/oplnk-python-utils
 Author: OpenLink SpA
@@ -189,7 +189,9 @@ serialized = datetime_serializer(data)
 
 ## Cache Module
 
-Advanced caching utilities with Redis integration and intelligent cache key management.
+Advanced caching utilities with Redis integration and intelligent cache key management. The module provides both low-level caching utilities and high-level endpoint decorators for comprehensive caching strategies.
+
+### Low-Level Cache Utilities
 
 ```python
 from oplnk_python_utils.cache import generate_cache_id, get_or_set_cache, invalidate_cache_keys
@@ -199,7 +201,7 @@ cache_key = generate_cache_id({
     "filters": {"name": "John", "status": "active"},
     "sort": ["created_at:desc"]
 })
-# Automatically normalizes data internally and creates MD5 hash
+# Automatically normalizes data internally and creates SHA256 hash
 
 # Get from cache or execute function and cache result
 async def expensive_operation(query):
@@ -207,37 +209,145 @@ async def expensive_operation(query):
     return await db.collection.find(query).to_list()
 
 result = await get_or_set_cache(
+    redis_client=redis,
     cache_key="user_query_abc123",
-    fetch_function=expensive_operation,
-    query={"status": "active"},
-    expiration=3600  # 1 hour
+    fetch_func=expensive_operation,
+    ttl=3600,  # 1 hour
+    serializer=datetime_serializer
 )
 
-# Cache with automatic serialization of datetime objects
-from datetime import datetime
-async def get_user_data():
-    return {
-        "user": "john",
-        "last_login": datetime.now(),
-        "preferences": {"theme": "dark"}
-    }
+# Invalidate multiple cache keys by pattern
+invalidated_count = invalidate_cache_keys(redis, "user_*")
+print(f"Invalidated {invalidated_count} cache entries")
+```
+
+### Endpoint-Level Caching (NEW)
+
+High-level decorators for caching entire endpoint responses with automatic cache key generation and tag-based invalidation.
 
-cached_data = await get_or_set_cache(
-    cache_key="user_john_data",
-    fetch_function=get_user_data,
-    expiration=1800
+```python
+from oplnk_python_utils.cache import cache_response, cache_factory, build_cache_key, invalidate_tag
+from fastapi import FastAPI, Request
+import redis
+
+app = FastAPI()
+redis_client = redis.Redis(host='localhost', port=6379, db=0)
+
+# Method 1: Direct decorator usage
+@app.get("/users")
+@cache_response(
+    redis_client=redis_client,
+    api_name="myapi",
+    collection="users",
+    endpoint_type="read",
+    tags=["users", "all_data"],
+    ttl=3600,  # 1 hour
+    use_cache=True
 )
+async def get_users(request: Request):
+    # Your endpoint logic here
+    return {"users": [...]}
+
+# Method 2: Factory pattern for reusable decorators
+users_cache = cache_factory(redis_client, "myapi", "users")
+
+@app.get("/users")
+@users_cache(
+    endpoint_type="read",
+    tags=["users", "public"],
+    ttl=1800  # 30 minutes
+)
+async def get_users(request: Request):
+    return {"users": [...]}
+
+@app.post("/users")
+@users_cache(
+    endpoint_type="create",
+    tags=["users"],
+    ttl=0  # No caching for write operations
+)
+async def create_user(request: Request):
+    # Automatically invalidates 'users' tag after creation
+    return {"created": True}
+
+# Manual cache key building
+@app.get("/custom")
+async def custom_endpoint(request: Request):
+    cache_key = build_cache_key(request, "myapi", "custom", "read")
+    # Use cache_key for custom caching logic
+    return {"data": "custom"}
+
+# Tag-based cache invalidation
+@app.delete("/users/{user_id}")
+async def delete_user(user_id: str):
+    # Delete user logic here
+    # ...
+
+    # Invalidate all cached responses tagged with 'users'
+    invalidate_tag(redis_client, "users")
+    return {"deleted": True}
+```
 
-# Invalidate multiple cache keys by pattern
-invalidated_count = await invalidate_cache_keys("user_*")
-print(f"Invalidated {invalidated_count} cache entries")
+### Cache Key Structure
+
+The caching system generates structured cache keys based on:
+
+-  **API Name**: Namespace for your application
+-  **Collection**: The data collection being cached
+-  **Endpoint Type**: Type of operation (read, create, update, delete)
+-  **Query Hash**: SHA256 hash of normalized query parameters
+
+Example cache key: `myapi:users:read:a1b2c3d4e5f6...`
+
+### Tag-Based Cache Management
+
+```python
+# Cache responses with multiple tags
+@cache_response(
+    redis_client=redis_client,
+    api_name="ecommerce",
+    collection="products",
+    endpoint_type="read",
+    tags=["products", "catalog", "public_data"],
+    ttl=7200  # 2 hours
+)
+async def get_products(request: Request):
+    return {"products": [...]}
+
+# Invalidate specific tag groups
+invalidate_tag(redis_client, "products")      # Invalidates all product-related cache
+invalidate_tag(redis_client, "catalog")       # Invalidates all catalog cache
+invalidate_tag(redis_client, "public_data")   # Invalidates all public data cache
 ```
 
-### Cache Functions
+### Cache Functions Reference
+
+#### Low-Level Functions
+
+-  **`generate_cache_id(params)`**: Generate SHA256 hash from normalized data for consistent cache keys
+-  **`get_or_set_cache(redis_client, cache_key, fetch_func, clear_cache=False, ttl=None, serializer=None)`**: Get cached result or execute function and cache with automatic serialization
+-  **`invalidate_cache_keys(redis_client, pattern)`**: Delete cache keys matching pattern (supports wildcards)
+
+#### Endpoint Caching Functions
+
+-  **`build_cache_key(request, api_name, collection, endpoint_type)`**: Build structured cache key from request parameters
+-  **`cache_response(redis_client, api_name, collection, endpoint_type, tags, ttl=None, use_cache=True)`**: Decorator for caching endpoint responses
+-  **`cache_factory(redis_client, api_name, collection)`**: Factory function to create reusable cache decorators
+-  **`invalidate_tag(redis_client, tag)`**: Invalidate all cache keys associated with a specific tag
+
+### Automatic Cache Invalidation
 
--  **`generate_cache_id(data, prefix="")`**: Generate MD5 hash from normalized data for consistent cache keys
--  **`get_or_set_cache(cache_key, fetch_function, expiration=3600, **kwargs)`\*\*: Get cached result or execute function and cache with automatic datetime serialization
--  **`invalidate_cache_keys(pattern)`**: Delete cache keys matching pattern (supports wildcards)
+The caching system supports automatic cache clearing via query parameters:
+
+```python
+# Clear cache before executing endpoint
+GET /users?clear_cache=true
+
+# This will:
+# 1. Invalidate the collection tag (e.g., "users")
+# 2. Execute the endpoint normally
+# 3. Cache the fresh response
+```
 
 ## Query Module
 
@@ -313,7 +423,7 @@ results = query_builder.read_query(
     params=raw_params,  # Will be parsed automatically using core.parsing
     cache_client=redis_client,
     cache_key_prefix="users",
-    use_cache=True
+    use_cache=False  # Note: Endpoint-level caching is now preferred over query-level caching
 )
 
 print(results)
@@ -441,30 +551,48 @@ class CRUD(QueryBuilder):
         self.db = db[self.collection]
         super().__init__(collection_prefix=PREFIX, relations=relations)
 
-    def read_query(self, params=None, query=None, pipeline=None, pipeline_count=None, use_cache=False):
-        # Just 6 lines! All complexity abstracted away
+    def read_query(self, params=None, query=None, pipeline=None, pipeline_count=None):
+        # Just 4 lines! All complexity abstracted away
         return super().read_query(
             db_collection=self.db, params=params, query=query,
-            pipeline=pipeline, pipeline_count=pipeline_count,
-            use_cache=use_cache, cache_client=redis,
-            cache_key_prefix=f"app:{self.collection}"
+            pipeline=pipeline, pipeline_count=pipeline_count
         )
 
-# Endpoint - Even simpler with explicit imports!
+# Endpoint - With new endpoint-level caching!
+from oplnk_python_utils.cache import cache_factory
 from oplnk_python_utils.core.parsing import parse_params_to_dict
 
+# Create reusable cache decorator for this collection
+users_cache = cache_factory(redis_client, "myapp", "users")
+
 @router.get("/query")
+@users_cache(
+    endpoint_type="read",
+    tags=["users", "queries"],
+    ttl=3600  # Cache for 1 hour
+)
 async def get_data(request: Request):
     # Option 1: Manual parsing (explicit control)
     query = parse_params_to_dict(request.query_params)
-    return crud.read_query(query=query, pipeline=base_pipeline, use_cache=True)
+    return crud.read_query(query=query, pipeline=base_pipeline)
 
     # Option 2: Automatic parsing (convenience)
     return crud.read_query(
         params=request.query_params,  # Parsed automatically
-        pipeline=base_pipeline,
-        use_cache=True
+        pipeline=base_pipeline
     )
+
+# Write operations with cache invalidation
+@router.post("/users")
+@users_cache(
+    endpoint_type="create",
+    tags=["users"],
+    ttl=0  # No caching for write operations
+)
+async def create_user(request: Request, user_data: dict):
+    result = crud.create(user_data)
+    # Cache is automatically invalidated due to 'users' tag
+    return result
 ```
 
 ## Advanced Features

{oplnk_python_utils-1.0.1 → oplnk_python_utils-1.0.2}/README.md

@@ -147,7 +147,9 @@ serialized = datetime_serializer(data)
 
 ## Cache Module
 
-Advanced caching utilities with Redis integration and intelligent cache key management.
+Advanced caching utilities with Redis integration and intelligent cache key management. The module provides both low-level caching utilities and high-level endpoint decorators for comprehensive caching strategies.
+
+### Low-Level Cache Utilities
 
 ```python
 from oplnk_python_utils.cache import generate_cache_id, get_or_set_cache, invalidate_cache_keys
@@ -157,7 +159,7 @@ cache_key = generate_cache_id({
     "filters": {"name": "John", "status": "active"},
     "sort": ["created_at:desc"]
 })
-# Automatically normalizes data internally and creates MD5 hash
+# Automatically normalizes data internally and creates SHA256 hash
 
 # Get from cache or execute function and cache result
 async def expensive_operation(query):
@@ -165,37 +167,145 @@ async def expensive_operation(query):
     return await db.collection.find(query).to_list()
 
 result = await get_or_set_cache(
+    redis_client=redis,
     cache_key="user_query_abc123",
-    fetch_function=expensive_operation,
-    query={"status": "active"},
-    expiration=3600  # 1 hour
+    fetch_func=expensive_operation,
+    ttl=3600,  # 1 hour
+    serializer=datetime_serializer
 )
 
-# Cache with automatic serialization of datetime objects
-from datetime import datetime
-async def get_user_data():
-    return {
-        "user": "john",
-        "last_login": datetime.now(),
-        "preferences": {"theme": "dark"}
-    }
+# Invalidate multiple cache keys by pattern
+invalidated_count = invalidate_cache_keys(redis, "user_*")
+print(f"Invalidated {invalidated_count} cache entries")
+```
+
+### Endpoint-Level Caching (NEW)
+
+High-level decorators for caching entire endpoint responses with automatic cache key generation and tag-based invalidation.
 
-cached_data = await get_or_set_cache(
-    cache_key="user_john_data",
-    fetch_function=get_user_data,
-    expiration=1800
+```python
+from oplnk_python_utils.cache import cache_response, cache_factory, build_cache_key, invalidate_tag
+from fastapi import FastAPI, Request
+import redis
+
+app = FastAPI()
+redis_client = redis.Redis(host='localhost', port=6379, db=0)
+
+# Method 1: Direct decorator usage
+@app.get("/users")
+@cache_response(
+    redis_client=redis_client,
+    api_name="myapi",
+    collection="users",
+    endpoint_type="read",
+    tags=["users", "all_data"],
+    ttl=3600,  # 1 hour
+    use_cache=True
 )
+async def get_users(request: Request):
+    # Your endpoint logic here
+    return {"users": [...]}
+
+# Method 2: Factory pattern for reusable decorators
+users_cache = cache_factory(redis_client, "myapi", "users")
+
+@app.get("/users")
+@users_cache(
+    endpoint_type="read",
+    tags=["users", "public"],
+    ttl=1800  # 30 minutes
+)
+async def get_users(request: Request):
+    return {"users": [...]}
+
+@app.post("/users")
+@users_cache(
+    endpoint_type="create",
+    tags=["users"],
+    ttl=0  # No caching for write operations
+)
+async def create_user(request: Request):
+    # Automatically invalidates 'users' tag after creation
+    return {"created": True}
+
+# Manual cache key building
+@app.get("/custom")
+async def custom_endpoint(request: Request):
+    cache_key = build_cache_key(request, "myapi", "custom", "read")
+    # Use cache_key for custom caching logic
+    return {"data": "custom"}
+
+# Tag-based cache invalidation
+@app.delete("/users/{user_id}")
+async def delete_user(user_id: str):
+    # Delete user logic here
+    # ...
+
+    # Invalidate all cached responses tagged with 'users'
+    invalidate_tag(redis_client, "users")
+    return {"deleted": True}
+```
 
-# Invalidate multiple cache keys by pattern
-invalidated_count = await invalidate_cache_keys("user_*")
-print(f"Invalidated {invalidated_count} cache entries")
+### Cache Key Structure
+
+The caching system generates structured cache keys based on:
+
+-  **API Name**: Namespace for your application
+-  **Collection**: The data collection being cached
+-  **Endpoint Type**: Type of operation (read, create, update, delete)
+-  **Query Hash**: SHA256 hash of normalized query parameters
+
+Example cache key: `myapi:users:read:a1b2c3d4e5f6...`
+
+### Tag-Based Cache Management
+
+```python
+# Cache responses with multiple tags
+@cache_response(
+    redis_client=redis_client,
+    api_name="ecommerce",
+    collection="products",
+    endpoint_type="read",
+    tags=["products", "catalog", "public_data"],
+    ttl=7200  # 2 hours
+)
+async def get_products(request: Request):
+    return {"products": [...]}
+
+# Invalidate specific tag groups
+invalidate_tag(redis_client, "products")      # Invalidates all product-related cache
+invalidate_tag(redis_client, "catalog")       # Invalidates all catalog cache
+invalidate_tag(redis_client, "public_data")   # Invalidates all public data cache
 ```
 
-### Cache Functions
+### Cache Functions Reference
+
+#### Low-Level Functions
+
+-  **`generate_cache_id(params)`**: Generate SHA256 hash from normalized data for consistent cache keys
+-  **`get_or_set_cache(redis_client, cache_key, fetch_func, clear_cache=False, ttl=None, serializer=None)`**: Get cached result or execute function and cache with automatic serialization
+-  **`invalidate_cache_keys(redis_client, pattern)`**: Delete cache keys matching pattern (supports wildcards)
+
+#### Endpoint Caching Functions
+
+-  **`build_cache_key(request, api_name, collection, endpoint_type)`**: Build structured cache key from request parameters
+-  **`cache_response(redis_client, api_name, collection, endpoint_type, tags, ttl=None, use_cache=True)`**: Decorator for caching endpoint responses
+-  **`cache_factory(redis_client, api_name, collection)`**: Factory function to create reusable cache decorators
+-  **`invalidate_tag(redis_client, tag)`**: Invalidate all cache keys associated with a specific tag
+
+### Automatic Cache Invalidation
 
--  **`generate_cache_id(data, prefix="")`**: Generate MD5 hash from normalized data for consistent cache keys
--  **`get_or_set_cache(cache_key, fetch_function, expiration=3600, **kwargs)`\*\*: Get cached result or execute function and cache with automatic datetime serialization
--  **`invalidate_cache_keys(pattern)`**: Delete cache keys matching pattern (supports wildcards)
+The caching system supports automatic cache clearing via query parameters:
+
+```python
+# Clear cache before executing endpoint
+GET /users?clear_cache=true
+
+# This will:
+# 1. Invalidate the collection tag (e.g., "users")
+# 2. Execute the endpoint normally
+# 3. Cache the fresh response
+```
 
 ## Query Module
 
@@ -271,7 +381,7 @@ results = query_builder.read_query(
     params=raw_params,  # Will be parsed automatically using core.parsing
     cache_client=redis_client,
     cache_key_prefix="users",
-    use_cache=True
+    use_cache=False  # Note: Endpoint-level caching is now preferred over query-level caching
 )
 
 print(results)
@@ -399,30 +509,48 @@ class CRUD(QueryBuilder):
         self.db = db[self.collection]
         super().__init__(collection_prefix=PREFIX, relations=relations)
 
-    def read_query(self, params=None, query=None, pipeline=None, pipeline_count=None, use_cache=False):
-        # Just 6 lines! All complexity abstracted away
+    def read_query(self, params=None, query=None, pipeline=None, pipeline_count=None):
+        # Just 4 lines! All complexity abstracted away
         return super().read_query(
             db_collection=self.db, params=params, query=query,
-            pipeline=pipeline, pipeline_count=pipeline_count,
-            use_cache=use_cache, cache_client=redis,
-            cache_key_prefix=f"app:{self.collection}"
+            pipeline=pipeline, pipeline_count=pipeline_count
         )
 
-# Endpoint - Even simpler with explicit imports!
+# Endpoint - With new endpoint-level caching!
+from oplnk_python_utils.cache import cache_factory
 from oplnk_python_utils.core.parsing import parse_params_to_dict
 
+# Create reusable cache decorator for this collection
+users_cache = cache_factory(redis_client, "myapp", "users")
+
 @router.get("/query")
+@users_cache(
+    endpoint_type="read",
+    tags=["users", "queries"],
+    ttl=3600  # Cache for 1 hour
+)
 async def get_data(request: Request):
     # Option 1: Manual parsing (explicit control)
     query = parse_params_to_dict(request.query_params)
-    return crud.read_query(query=query, pipeline=base_pipeline, use_cache=True)
+    return crud.read_query(query=query, pipeline=base_pipeline)
 
     # Option 2: Automatic parsing (convenience)
     return crud.read_query(
         params=request.query_params,  # Parsed automatically
-        pipeline=base_pipeline,
-        use_cache=True
+        pipeline=base_pipeline
     )
+
+# Write operations with cache invalidation
+@router.post("/users")
+@users_cache(
+    endpoint_type="create",
+    tags=["users"],
+    ttl=0  # No caching for write operations
+)
+async def create_user(request: Request, user_data: dict):
+    result = crud.create(user_data)
+    # Cache is automatically invalidated due to 'users' tag
+    return result
 ```
 
 ## Advanced Features

{oplnk_python_utils-1.0.1 → oplnk_python_utils-1.0.2}/oplnk_python_utils/__init__.py

@@ -2,17 +2,12 @@
 OpenLink Python Utils - Reusable utilities for caching, data manipulation, parsing, and MongoDB query building
 """
 
-# Import modules only - no function re-exports  
+# Import modules only - no function re-exports
 from . import core
 from . import cache
 from . import query
 
-__version__ = "1.0.1"
+__version__ = "1.0.2"
 __author__ = "OpenLink SpA"
 
-__all__ = [
-    "core",
-    "cache", 
-    "query",
-    "__version__"
-] 
+__all__ = ["core", "cache", "query", "__version__"]

{oplnk_python_utils-1.0.1 → oplnk_python_utils-1.0.2}/oplnk_python_utils/cache/__init__.py

@@ -5,7 +5,11 @@ Cache utilities module - Reusable caching functionality
 from .cache_utils import (
     generate_cache_id,
     get_or_set_cache,
-    invalidate_cache_keys
+    invalidate_cache_keys,
+    build_cache_key,
+    cache_response,
+    invalidate_tag,
+    cache_factory,
 )
 
 # Re-export core utilities for convenience in this domain
@@ -14,8 +18,12 @@ from ..core.serialization import datetime_serializer
 
 __all__ = [
     "generate_cache_id",
-    "datetime_serializer", 
+    "datetime_serializer",
     "get_or_set_cache",
     "invalidate_cache_keys",
-    "normalize"
-] 
+    "normalize",
+    "build_cache_key",
+    "cache_response",
+    "invalidate_tag",
+    "cache_factory",
+]