oplnk-python-utils 1.0.0__py3-none-any.whl

oplnk_python_utils/__init__.py

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

oplnk_python_utils/cache/__init__.py

@@ -0,0 +1,21 @@
+"""
+Cache utilities module - Reusable caching functionality
+"""
+
+from .cache_utils import (
+    generate_cache_id,
+    get_or_set_cache,
+    invalidate_cache_keys
+)
+
+# Re-export core utilities for convenience in this domain
+from ..core.data import normalize
+from ..core.serialization import datetime_serializer
+
+__all__ = [
+    "generate_cache_id",
+    "datetime_serializer", 
+    "get_or_set_cache",
+    "invalidate_cache_keys",
+    "normalize"
+] 

oplnk_python_utils/cache/cache_utils.py

@@ -0,0 +1,88 @@
+"""
+Cache utilities - Generic caching functions that can be used across projects
+"""
+
+import hashlib
+import json
+from typing import Callable, Any, Optional, Union
+from fastapi.encoders import jsonable_encoder
+from bson.objectid import ObjectId
+
+# Import core utilities
+from ..core.data import normalize
+from ..core.serialization import datetime_serializer
+
+
+def generate_cache_id(params: dict) -> str:
+    """
+    Utility to generate a cache key hash from a dictionary.
+    Creates a consistent hash based on normalized dictionary content.
+    """
+    normalized = normalize(params)
+    encoded_data = jsonable_encoder(normalized, custom_encoder={ObjectId: str})
+    serialized = json.dumps(encoded_data, separators=(",", ":"), ensure_ascii=True)
+    return hashlib.sha256(serialized.encode("utf-8")).hexdigest()
+
+
+def get_or_set_cache(
+    redis_client,
+    cache_key: str,
+    fetch_func: Callable,
+    clear_cache: Union[str, bool] = False,
+    ttl: Optional[int] = None,
+    serializer: Optional[Callable] = None,
+) -> Any:
+    """
+    Retrieve data from cache if available, otherwise fetch, cache, and return it.
+    Optionally clear cache before fetching.
+    
+    Args:
+        redis_client: Redis client instance
+        cache_key: Key to use for caching
+        fetch_func: Function to call if cache miss
+        clear_cache: Pattern to clear or boolean to clear specific key
+        ttl: Time to live in seconds
+        serializer: Function to serialize data before caching
+    """
+    if clear_cache:
+        invalidate_cache_keys(
+            redis_client,
+            clear_cache if isinstance(clear_cache, str) else cache_key
+        )
+    
+    if redis_client.exists(cache_key):
+        return json.loads(redis_client.get(cache_key))
+    
+    data = fetch_func()
+    if serializer:
+        data = serializer(data)
+    
+    encoded_data = jsonable_encoder(data, custom_encoder={ObjectId: str})
+    redis_client.set(cache_key, json.dumps(encoded_data), ex=ttl)
+    return encoded_data
+
+
+def invalidate_cache_keys(redis_client, pattern: str) -> int:
+    """
+    Utility to invalidate cache keys matching a pattern.
+    
+    Args:
+        redis_client: Redis client instance
+        pattern: Pattern to match keys for deletion
+        
+    Returns:
+        Number of keys deleted
+    """
+    cursor = 0
+    batch_size = 1000
+    total_deleted = 0
+
+    while True:
+        cursor, keys = redis_client.scan(cursor=cursor, match=pattern, count=batch_size)
+        if keys:
+            redis_client.unlink(*keys)
+            total_deleted += len(keys)
+        if cursor == 0:
+            break
+
+    return total_deleted 

oplnk_python_utils/core/__init__.py

@@ -0,0 +1,13 @@
+"""
+Core utilities module - General-purpose utilities for data manipulation, parsing, and serialization
+"""
+
+from . import data
+from . import parsing
+from . import serialization
+
+__all__ = [
+    "data",
+    "parsing", 
+    "serialization"
+] 

oplnk_python_utils/core/data.py

@@ -0,0 +1,58 @@
+"""
+Data manipulation utilities - Functions for normalizing and merging data structures
+"""
+
+from typing import Dict, Any, Union, List
+
+
+def normalize(value: Union[Dict, List, Any]) -> Union[Dict, List, Any]:
+    """
+    Utility to normalize a dictionary for consistent cache key generation.
+    Recursively sorts dictionary keys and normalizes nested structures.
+    
+    Args:
+        value: The value to normalize (dict, list, or primitive)
+        
+    Returns:
+        Normalized value with sorted keys for dictionaries
+    """
+    if isinstance(value, dict):
+        return {k: normalize(value[k]) for k in sorted(value)}
+    elif isinstance(value, list):
+        return [normalize(v) for v in value]
+    else:
+        return value
+
+
+def merge_dicts(*dicts: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Merge multiple dictionaries, handling nested structures and arrays.
+    
+    Args:
+        *dicts: Variable number of dictionaries to merge
+        
+    Returns:
+        Merged dictionary with nested structures properly combined
+    """
+    def merge(a: Dict[str, Any], b: Dict[str, Any]) -> None:
+        """Internal merge function that modifies dictionary a in place"""
+        for key in b:
+            if key in a:
+                if isinstance(a[key], dict) and isinstance(b[key], dict):
+                    merge(a[key], b[key])
+                elif isinstance(a[key], list) and isinstance(b[key], list):
+                    a[key].extend(b[key])
+                elif isinstance(a[key], list):
+                    a[key].append(b[key])
+                elif isinstance(b[key], list):
+                    b[key].insert(0, a[key])
+                    a[key] = b[key]
+                else:
+                    a[key] = [a[key], b[key]]
+            else:
+                a[key] = b[key]
+
+    result = {}
+    for d in dicts:
+        merge(result, d)
+    return result 

oplnk_python_utils/core/parsing.py

@@ -0,0 +1,114 @@
+"""
+Parsing utilities - Functions for parsing and type conversion
+"""
+
+import re
+from typing import List, Dict, Any, Union
+from datetime import datetime
+from .data import merge_dicts
+
+
+def infer_type(value: Union[str, List, Any]) -> Any:
+    """
+    Infer the correct Python type from a string value.
+    
+    Args:
+        value: The value to convert (string, list, or other)
+        
+    Returns:
+        Value converted to appropriate Python type
+    """
+    if isinstance(value, list):
+        return [infer_type(v) for v in value]
+
+    if not isinstance(value, str):
+        return value  # Skip non-string non-list
+
+    # Now it's safe to do .lower()
+    value_lower = value.lower()
+    if value_lower in {"true", "false"}:
+        return value_lower == "true"
+
+    # Try to convert to int
+    try:
+        return int(value)
+    except ValueError:
+        pass
+
+    # Try to convert to float
+    try:
+        return float(value)
+    except ValueError:
+        pass
+
+    # Try to convert to datetime
+    try:
+        return datetime.strptime(value, "%Y-%m-%dT%H:%M:%S.%fZ")
+    except ValueError:
+        pass
+
+    # If nothing works, return the original string
+    return value
+
+
+def parse_key_string_to_list(s: str) -> List[str]:
+    """
+    Parse a string like 'filters[name][$containsi]' into ['filters', 'name', '$containsi'].
+    
+    Args:
+        s: String with bracketed notation
+        
+    Returns:
+        List of parsed key components
+    """
+    parts = re.findall(r"\[([^\]]+)\]", s)
+    parts.insert(0, s.split("[")[0])
+    return parts
+
+
+def parse_list_to_dict(lst: List[str], value: str) -> Dict[str, Any]:
+    """
+    Convert a list of keys and a value into a nested dictionary.
+    
+    Args:
+        lst: List of keys for nested structure
+        value: Value to place at the deepest level
+        
+    Returns:
+        Nested dictionary structure
+    """
+    result = None
+    new_value = infer_type(value)
+
+    for key in reversed(lst):
+        if key.isdigit():
+            result = [new_value] if result is None else [result]
+        else:
+            result = {key: new_value} if result is None else {key: result}
+
+    return result
+
+
+def parse_params_to_dict(params: Union[Dict[str, str], Any]) -> Dict[str, Any]:
+    """
+    Parse query parameters into a structured dictionary.
+    Handles nested parameters like filters[name][$containsi]=john
+    
+    Args:
+        params: Query parameters (FastAPI QueryParams or dict-like object)
+        
+    Returns:
+        Structured dictionary with nested parameters
+    """
+    # Handle FastAPI QueryParams or similar objects
+    if hasattr(params, 'items'):
+        param_dict = dict(params.items()) if hasattr(params, 'items') else dict(params)
+    else:
+        param_dict = params
+
+    result = {}
+    for key, value in param_dict.items():
+        args = parse_key_string_to_list(key)
+        dictionary = parse_list_to_dict(args, value)
+        result = merge_dicts(result, dictionary)
+    return result 

oplnk_python_utils/core/serialization.py

@@ -0,0 +1,32 @@
+"""
+Serialization utilities - Functions for converting data types to serializable formats
+"""
+
+from typing import Any, Union, Dict, List
+from datetime import datetime
+
+
+def datetime_serializer(data: Union[Dict, List, Any]) -> Union[Dict, List, Any]:
+    """
+    Utility to serialize datetime objects to ISO format for cache storage.
+    Recursively processes dictionaries and lists to convert all datetime objects.
+    
+    Args:
+        data: Data structure that may contain datetime objects
+        
+    Returns:
+        Data structure with datetime objects converted to ISO format strings
+    """
+    if isinstance(data, dict):
+        for key, value in data.items():
+            if isinstance(value, datetime):
+                data[key] = value.isoformat()
+            elif isinstance(value, (dict, list)):
+                datetime_serializer(value)
+    elif isinstance(data, list):
+        for index, value in enumerate(data):
+            if isinstance(value, datetime):
+                data[index] = value.isoformat()
+            elif isinstance(value, (dict, list)):
+                datetime_serializer(value)
+    return data 

oplnk_python_utils/query/__init__.py

@@ -0,0 +1,9 @@
+"""
+Query utilities module - Reusable query building functionality
+"""
+
+from .query_builder import QueryBuilder
+ 
+__all__ = [
+    "QueryBuilder"
+]