oplnk-python-utils 1.2.6__py3-none-any.whl → 1.3.0__py3-none-any.whl

oplnk_python_utils/__init__.py

@@ -7,7 +7,7 @@ from . import core
 from . import cache
 from . import query
 
-__version__ = "1.2.6"
+__version__ = "1.3.0"
 __author__ = "OpenLink SpA"
 
 __all__ = ["core", "cache", "query", "reports", "__version__"]

oplnk_python_utils/cache/cache_utils.py

@@ -4,16 +4,25 @@ Cache utilities - Generic caching functions that can be used across projects
 
 import hashlib
 import json
+import logging
+import time
+import asyncio
 from typing import Callable, Any, Optional, Union
 from fastapi.encoders import jsonable_encoder
 from bson.objectid import ObjectId
 from fastapi import Request
 import functools
+from redis.exceptions import (
+    ConnectionError as RedisConnectionError,
+    TimeoutError as RedisTimeoutError,
+)
 
 # Import core utilities
 from ..core.data import normalize
 from ..core.serialization import datetime_serializer
 
+logger = logging.getLogger(__name__)
+
 
 def generate_cache_id(params: dict) -> str:
     """
@@ -39,6 +48,8 @@ def get_or_set_cache(
     clear_cache: Union[str, bool] = False,
     ttl: Optional[int] = None,
     serializer: Optional[Callable] = None,
+    max_retries: int = 3,
+    retry_delay: float = 0.1,
 ) -> Any:
     """
     Retrieve data from cache if available, otherwise fetch, cache, and return it.
@@ -51,24 +62,45 @@ def get_or_set_cache(
         clear_cache: Pattern to clear or boolean to clear specific key
         ttl: Time to live in seconds
         serializer: Function to serialize data before caching
+        max_retries: Maximum number of retry attempts for Redis operations
+        retry_delay: Delay between retry attempts in seconds
 
     Returns:
         Cached or fetched data
     """
+    # Intentar limpiar cache si se solicita
     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))
+    # Intentar obtener del cache
+    cached_data = _execute_redis_op(
+        lambda: redis_client.get(cache_key) if redis_client.exists(cache_key) else None,
+        max_retries=max_retries,
+        retry_delay=retry_delay,
+    )
+
+    if cached_data is not None:
+        try:
+            return json.loads(cached_data)
+        except (json.JSONDecodeError, TypeError) as e:
+            logger.warning(f"Failed to decode cached data for key {cache_key}: {e}")
 
+    # Cache miss o error: obtener datos frescos
     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)
+
+    # Intentar guardar en cache (falla silenciosamente si Redis no está disponible)
+    _execute_redis_op(
+        lambda: redis_client.set(cache_key, json.dumps(encoded_data), ex=ttl),
+        max_retries=max_retries,
+        retry_delay=retry_delay,
+    )
+
     return encoded_data
 
 
@@ -81,21 +113,27 @@ def invalidate_cache_keys(redis_client, pattern: str) -> int:
         pattern: Pattern to match keys for deletion
 
     Returns:
-        Number of keys deleted
+        Number of keys deleted (0 if Redis is unavailable)
     """
-    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
+    try:
+        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
+        return total_deleted
+    except (RedisConnectionError, RedisTimeoutError) as e:
+        logger.warning(f"Redis connection error during cache invalidation: {e}")
+        return 0
 
 
 async def build_cache_key(
@@ -157,6 +195,71 @@ async def build_cache_key(
     return f"{api_name}:{collection}:{endpoint_type}:{hashed}"
 
 
+def _is_async_client(redis_client) -> bool:
+    """
+    Detecta si el cliente Redis es asíncrono.
+
+    Args:
+        redis_client: Cliente Redis a verificar
+
+    Returns:
+        True si es asíncrono, False si es síncrono
+    """
+    return (
+        hasattr(redis_client, "__aenter__") or "async" in type(redis_client).__module__
+    )
+
+
+def _execute_redis_op(
+    operation: Callable, max_retries: int = 3, retry_delay: float = 0.1
+) -> Any:
+    """
+    Ejecuta operación Redis síncrona con reintentos y degradación elegante.
+
+    Args:
+        operation: Función que ejecuta la operación Redis
+        max_retries: Número máximo de reintentos
+        retry_delay: Tiempo de espera entre reintentos en segundos
+
+    Returns:
+        Resultado de la operación o None si falla después de todos los reintentos
+    """
+    for attempt in range(max_retries):
+        try:
+            return operation()
+        except (RedisConnectionError, RedisTimeoutError) as e:
+            if attempt == max_retries - 1:
+                logger.warning(f"Redis unavailable after {max_retries} attempts: {e}")
+                return None
+            time.sleep(retry_delay)
+    return None
+
+
+async def _execute_redis_op_async(
+    operation: Callable, max_retries: int = 3, retry_delay: float = 0.1
+) -> Any:
+    """
+    Ejecuta operación Redis asíncrona con reintentos y degradación elegante.
+
+    Args:
+        operation: Función async que ejecuta la operación Redis
+        max_retries: Número máximo de reintentos
+        retry_delay: Tiempo de espera entre reintentos en segundos
+
+    Returns:
+        Resultado de la operación o None si falla después de todos los reintentos
+    """
+    for attempt in range(max_retries):
+        try:
+            return await operation()
+        except (RedisConnectionError, RedisTimeoutError) as e:
+            if attempt == max_retries - 1:
+                logger.warning(f"Redis unavailable after {max_retries} attempts: {e}")
+                return None
+            await asyncio.sleep(retry_delay)
+    return None
+
+
 def cache_response(
     redis_client,
     api_name: str,
@@ -165,22 +268,25 @@ def cache_response(
     tags: list[str],
     ttl: int | None = None,
     use_cache: bool = True,
+    max_retries: int = 3,
 ):
     """
     Decorator to cache the response of an endpoint.
 
     Args:
-        redis_client: Redis client instance
+        redis_client: Redis client instance (sync or async)
         api_name: Name of the API
         collection: Name of the collection
         endpoint_type: Type of endpoint
         tags: List of tags to use for caching
         ttl: Time to live in seconds
         use_cache: Whether to use cache
+        max_retries: Maximum number of retry attempts for Redis operations
 
     Returns:
         Decorator function
     """
+    is_async = _is_async_client(redis_client)
 
     def decorator(func: Callable):
         @functools.wraps(func)
@@ -209,21 +315,81 @@ def cache_response(
                 }
             else:
                 clear_cache_flag = bool(clear_cache_value)
+
+            # Intentar limpiar cache si se solicita
             if clear_cache_flag:
-                invalidate_tag(redis_client, f"{collection}")
+                try:
+                    invalidate_tag(redis_client, f"{collection}")
+                except (RedisConnectionError, RedisTimeoutError) as e:
+                    logger.warning(f"Redis connection error during cache clear: {e}")
 
             # Construir clave
             cache_key = await build_cache_key(
                 request, api_name, collection, endpoint_type
             )
-            if redis_client.exists(cache_key):
-                return json.loads(redis_client.get(cache_key))
 
+            # Intentar obtener del cache
+            cached_data = None
+            if is_async:
+
+                async def get_cached_data():
+                    exists_result = await redis_client.exists(cache_key)
+                    if exists_result:
+                        return await redis_client.get(cache_key)
+                    return None
+
+                cached_data = await _execute_redis_op_async(
+                    get_cached_data, max_retries=max_retries
+                )
+            else:
+                cached_data = _execute_redis_op(
+                    lambda: (
+                        redis_client.get(cache_key)
+                        if redis_client.exists(cache_key)
+                        else None
+                    ),
+                    max_retries=max_retries,
+                )
+
+            if cached_data is not None:
+                try:
+                    return json.loads(cached_data)
+                except (json.JSONDecodeError, TypeError) as e:
+                    logger.warning(
+                        f"Failed to decode cached data for key {cache_key}: {e}"
+                    )
+
+            # Cache miss o error: ejecutar función y cachear respuesta
             response = await func(*args, **kwargs)
             encoded_data = jsonable_encoder(response, custom_encoder={ObjectId: str})
-            redis_client.set(cache_key, json.dumps(encoded_data), ex=ttl)
-            for tag in tags:
-                redis_client.sadd(f"tag:{tag}", cache_key)
+
+            # Intentar guardar en cache (falla silenciosamente si Redis no está disponible)
+            if is_async:
+
+                async def set_cache_data():
+                    await redis_client.set(cache_key, json.dumps(encoded_data), ex=ttl)
+
+                await _execute_redis_op_async(set_cache_data, max_retries=max_retries)
+                # Agregar tags
+                for tag in tags:
+                    # Capturar el valor de tag en la closure usando parámetro por defecto
+                    async def add_tag(tag_name=tag):
+                        await redis_client.sadd(f"tag:{tag_name}", cache_key)
+
+                    await _execute_redis_op_async(add_tag, max_retries=max_retries)
+            else:
+                _execute_redis_op(
+                    lambda: redis_client.set(
+                        cache_key, json.dumps(encoded_data), ex=ttl
+                    ),
+                    max_retries=max_retries,
+                )
+                # Agregar tags
+                for tag in tags:
+                    _execute_redis_op(
+                        lambda t=tag: redis_client.sadd(f"tag:{t}", cache_key),
+                        max_retries=max_retries,
+                    )
 
             return encoded_data
 
@@ -272,7 +438,10 @@ def invalidate_tag(redis_client, tag: str):
         redis_client: Redis client instance
         tag: Tag to invalidate
     """
-    keys = redis_client.smembers(f"tag:{tag}")
-    for key in keys:
-        redis_client.delete(key)
-    redis_client.delete(f"tag:{tag}")
+    try:
+        keys = redis_client.smembers(f"tag:{tag}")
+        for key in keys:
+            redis_client.delete(key)
+        redis_client.delete(f"tag:{tag}")
+    except (RedisConnectionError, RedisTimeoutError) as e:
+        logger.warning(f"Redis connection error during tag invalidation: {e}")

oplnk_python_utils/query/query_builder.py

@@ -927,7 +927,9 @@ class QueryBuilder:
 
         return {"data": data_result, "meta": meta_result}
 
-    def get_reserved_field_lookup(self, field_name: str) -> List[Dict[str, Any]]:
+    def get_reserved_field_lookup(
+        self, field_name: str, populate_options: Optional[Dict[str, Any]] = None
+    ) -> List[Dict[str, Any]]:
         """
         Generate lookup pipeline for reserved audit fields (creation_user, modification_user).
 
@@ -936,6 +938,8 @@ class QueryBuilder:
 
         Args:
             field_name: Name of the reserved field (e.g., "creation_user")
+            populate_options: Optional dict with populate options:
+                - fields: List of fields to include in projection (e.g., ['full_name'])
 
         Returns:
             List of aggregation stages for the lookup, or None if not a reserved field
@@ -945,6 +949,21 @@ class QueryBuilder:
 
         field_config = RESERVED_AUDIT_FIELDS[field_name]
 
+        # Build projection based on populate_options
+        if populate_options and isinstance(populate_options, dict):
+            fields = populate_options.get("fields", [])
+            if fields and isinstance(fields, list):
+                # Include specified fields + always include _id
+                project_stage = {"_id": 1}
+                for field in fields:
+                    project_stage[field] = 1
+            else:
+                # Default exclusion projection from config
+                project_stage = field_config["project_exclude"]
+        else:
+            # Default exclusion projection from config
+            project_stage = field_config["project_exclude"]
+
         lookup_pipeline = [
             {
                 "$lookup": {
@@ -956,7 +975,7 @@ class QueryBuilder:
                                 "$expr": {"$eq": ["$_id", {"$toObjectId": "$$userId"}]}
                             }
                         },
-                        {"$project": field_config["project_exclude"]},
+                        {"$project": project_stage},
                         {"$addFields": {"_id": {"$toString": "$_id"}}},
                     ],
                     "as": field_config["alias"],
@@ -972,8 +991,23 @@ class QueryBuilder:
 
         return lookup_pipeline
 
-    def get_lookup_relation(self, relation_field: List[str]) -> tuple:
-        """Get lookup relation configuration for a specific relation field"""
+    def get_lookup_relation(
+        self,
+        relation_field: List[str],
+        populate_options: Optional[Dict[str, Any]] = None,
+    ) -> tuple:
+        """
+        Get lookup relation configuration for a specific relation field.
+
+        Args:
+            relation_field: Relation configuration list [collection, field_name, prefix, ...]
+            populate_options: Optional dict with populate options:
+                - fields: List of fields to include in projection (e.g., ['name', 'code'])
+                - filters: Dict of filters to apply to the lookup (future feature)
+
+        Returns:
+            Tuple of (lookup_pipeline, collection_name)
+        """
         _prefix = self.collection_prefix + "_"
         if len(relation_field) > 2 and relation_field[2]:
             _prefix = relation_field[2] + "_"
@@ -1003,22 +1037,50 @@ class QueryBuilder:
         else:
             let_value = {"lid": f"${relation_field_name}"}
 
+        # Build the pipeline for the lookup
+        lookup_pipeline_stages = [
+            {"$addFields": {"_id": {"$toString": "$_id"}}},
+            match_stage,
+        ]
+
+        # Build projection based on populate_options
+        if populate_options and isinstance(populate_options, dict):
+            fields = populate_options.get("fields", [])
+            if fields and isinstance(fields, list):
+                # Include specified fields + always include _id
+                project_stage = {"_id": 1}
+                for field in fields:
+                    project_stage[field] = 1
+                lookup_pipeline_stages.append({"$project": project_stage})
+            else:
+                # Default exclusion projection
+                lookup_pipeline_stages.append(
+                    {
+                        "$project": {
+                            "creation_user": 0,
+                            "creation_date": 0,
+                            "disable": 0,
+                        }
+                    }
+                )
+        else:
+            # Default exclusion projection
+            lookup_pipeline_stages.append(
+                {
+                    "$project": {
+                        "creation_user": 0,
+                        "creation_date": 0,
+                        "disable": 0,
+                    }
+                }
+            )
+
         lookup_relation = [
             {
                 "$lookup": {
                     "from": f"{_prefix}{collection_name_relation}",
                     "let": let_value,
-                    "pipeline": [
-                        {"$addFields": {"_id": {"$toString": "$_id"}}},
-                        match_stage,
-                        {
-                            "$project": {
-                                "creation_user": 0,
-                                "creation_date": 0,
-                                "disable": 0,
-                            }
-                        },
-                    ],
+                    "pipeline": lookup_pipeline_stages,
                     "as": _as,
                 },
             },
@@ -1067,9 +1129,16 @@ class QueryBuilder:
             for query_relation in query_relations.keys():
                 # Check if it's a reserved field first
                 if query_relation in RESERVED_AUDIT_FIELDS:
-                    # Handle both True and dict with options (options are currently ignored)
                     if query_relations[query_relation]:
-                        reserved_lookup = self.get_reserved_field_lookup(query_relation)
+                        # Pass options if it's a dict, otherwise None
+                        populate_opts = (
+                            query_relations[query_relation]
+                            if isinstance(query_relations[query_relation], dict)
+                            else None
+                        )
+                        reserved_lookup = self.get_reserved_field_lookup(
+                            query_relation, populate_opts
+                        )
                         if reserved_lookup:
                             query_lookup_relations.extend(reserved_lookup)
                             continue
@@ -1091,9 +1160,10 @@ class QueryBuilder:
                             ]
 
                         if isinstance(query_relations[query_relation], dict):
-                            # Note: populate options (like fields) are currently ignored
-                            # The lookup returns all fields, projection can be applied separately
-                            lookup_relation = self.get_lookup_relation(relation)
+                            # Pass populate options (fields, filters, etc.) to the lookup
+                            lookup_relation = self.get_lookup_relation(
+                                relation, query_relations[query_relation]
+                            )
                             query_lookup_relations = [
                                 *query_lookup_relations,
                                 *lookup_relation[0],

{oplnk_python_utils-1.2.6.dist-info → oplnk_python_utils-1.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oplnk-python-utils
-Version: 1.2.6
+Version: 1.3.0
 Summary: Reusable utilities for caching, data manipulation, parsing, and MongoDB query building
 Home-page: https://github.com/openlinkspa/oplnk-python-utils
 Author: OpenLink SpA

{oplnk_python_utils-1.2.6.dist-info → oplnk_python_utils-1.3.0.dist-info}/RECORD

@@ -1,15 +1,15 @@
-oplnk_python_utils/__init__.py,sha256=Fp27KetC5NjB7ib42ehcxvIdVzRAKRe-X65B425IXrA,354
+oplnk_python_utils/__init__.py,sha256=EZKfDHMpt3vBb3qmOBCja0UU08uwGaqnYBPXOQADlsk,354
 oplnk_python_utils/cache/__init__.py,sha256=UtCAGUH8WinNMeh-MIOLPZeRMUn5_6Jn_QC2iKWvIN0,646
-oplnk_python_utils/cache/cache_utils.py,sha256=Ln4sRgM1UELekCfMYZdNdUVecsshaqrcoUrvHRfj4jE,8597
+oplnk_python_utils/cache/cache_utils.py,sha256=2L4Yyarn0y7sREeLGJANTjq55UXy6YvJ8Sqd6wSEXSM,14856
 oplnk_python_utils/core/__init__.py,sha256=HmT7BR9WCGcu47Bd-eMdSSTImKnzsaalzYVThgTuyMA,253
 oplnk_python_utils/core/data.py,sha256=BwOIGeS4c7gGOOUcx-2RpFJsznjAtBVETRv63A_3PDY,1936
 oplnk_python_utils/core/parsing.py,sha256=EdI_uQJWalXL7yen5iyQ6J5PRLgz6Xi_szWaUDOhlgQ,5190
 oplnk_python_utils/core/serialization.py,sha256=B4g3x6yGjmXySNtOHqqFrq8AlguYz4gldxCJY21UNdQ,1164
 oplnk_python_utils/query/__init__.py,sha256=dd-PRf5fkoQvAbcONumwrRveS_Ejnw-3Q0hA7ZcF6Ic,147
-oplnk_python_utils/query/query_builder.py,sha256=eR54mApCqmqhlgg9b8ZUKzRt0U8GelLAEn9mU7khgag,61547
+oplnk_python_utils/query/query_builder.py,sha256=54VLb_67ncdhehnQp0vKenfSsSUTfMzp_jD9YIt8CgU,64246
 oplnk_python_utils/reports/__init__.py,sha256=CPxWaRgXt9sHK_6mQwsXnUxg9yzJ2GHSlQ4lVNpkanY,94
-oplnk_python_utils-1.2.6.dist-info/licenses/LICENSE,sha256=JgkAUZElZ6gNf7C2aZPq5-GEjUG2t_yYAKvuhy1OKy0,1090
-oplnk_python_utils-1.2.6.dist-info/METADATA,sha256=so9C8zxJtzr6QLWQqW8XPcbdkyvD8o8TBHPlvyRvS5g,24924
-oplnk_python_utils-1.2.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-oplnk_python_utils-1.2.6.dist-info/top_level.txt,sha256=TPZ-emvWspdR-OxTNOvQt-cDrZ4m7P4RMnxsXHOeorc,19
-oplnk_python_utils-1.2.6.dist-info/RECORD,,
+oplnk_python_utils-1.3.0.dist-info/licenses/LICENSE,sha256=JgkAUZElZ6gNf7C2aZPq5-GEjUG2t_yYAKvuhy1OKy0,1090
+oplnk_python_utils-1.3.0.dist-info/METADATA,sha256=s98cLEa9nzgwIsRR5sF0ZkMeKPCj6ZsNQB8M3VruZvc,24924
+oplnk_python_utils-1.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+oplnk_python_utils-1.3.0.dist-info/top_level.txt,sha256=TPZ-emvWspdR-OxTNOvQt-cDrZ4m7P4RMnxsXHOeorc,19
+oplnk_python_utils-1.3.0.dist-info/RECORD,,