oplnk-python-utils 1.1.7__tar.gz → 1.1.8__tar.gz

{oplnk_python_utils-1.1.7/oplnk_python_utils.egg-info → oplnk_python_utils-1.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oplnk-python-utils
-Version: 1.1.7
+Version: 1.1.8
 Summary: Reusable utilities for caching, data manipulation, parsing, and MongoDB query building
 Home-page: https://github.com/openlinkspa/oplnk-python-utils
 Author: OpenLink SpA
@@ -109,7 +109,7 @@ merged = merge_dicts(dict1, dict2)
 
 ### Parsing Utilities (`core.parsing`)
 
-Functions for parsing query parameters and type conversion.
+Functions for parsing query parameters, type conversion, and safe field-path handling for MongoDB aggregation.
 
 ```python
 from oplnk_python_utils.core.parsing import (
@@ -158,6 +158,14 @@ nested_dict = parse_list_to_dict(["filters", "name", "$eq"], "john")
 -  **`parse_key_string_to_list(s)`**: Parse bracketed notation strings like `"filters[name][$eq]"`
 -  **`parse_list_to_dict(lst, value)`**: Convert key list and value into nested dictionary structure
 
+#### Field Path Utilities for Aggregation (NEW)
+
+-  **`normalize_field_path(field)`**: Normalize paths with array notation for MongoDB aggregation.
+   -  Example: `"user.addresses[1].street" -> "user.addresses.1.street"`
+-  **`validate_field_path(field)`**: Validate field paths for invalid characters before using them in pipelines.
+-  **`build_aggregation_field_expression(field)`**: Produce a proper aggregation expression, automatically prefixing with `$` when needed.
+   -  Example: `"user.addresses[1].street" -> "$user.addresses.1.street"`
+
 ### Serialization Utilities (`core.serialization`)
 
 Functions for converting data types to serializable formats.
@@ -203,15 +211,15 @@ cache_key = generate_cache_id({
 })
 # Automatically normalizes data internally and creates SHA256 hash
 
-# Get from cache or execute function and cache result
-async def expensive_operation(query):
-    # Some expensive database operation
-    return await db.collection.find(query).to_list()
+# Get from cache or execute a function and cache result (sync fetch_func)
+def fetch_users():
+    # Some expensive database operation (sync example)
+    return list(db.collection.find({"status": "active"}))
 
-result = await get_or_set_cache(
+result = get_or_set_cache(
     redis_client=redis,
     cache_key="user_query_abc123",
-    fetch_func=expensive_operation,
+    fetch_func=fetch_users,  # zero-arg callable
     ttl=3600,  # 1 hour
     serializer=datetime_serializer
 )
@@ -270,10 +278,10 @@ async def create_user(request: Request):
     # Automatically invalidates 'users' tag after creation
     return {"created": True}
 
-# Manual cache key building
+# Manual cache key building (build_cache_key is async)
 @app.get("/custom")
 async def custom_endpoint(request: Request):
-    cache_key = build_cache_key(request, "myapi", "custom", "read")
+    cache_key = await build_cache_key(request, "myapi", "custom", "read")
     # Use cache_key for custom caching logic
     return {"data": "custom"}
 

{oplnk_python_utils-1.1.7 → oplnk_python_utils-1.1.8}/README.md

@@ -67,7 +67,7 @@ merged = merge_dicts(dict1, dict2)
 
 ### Parsing Utilities (`core.parsing`)
 
-Functions for parsing query parameters and type conversion.
+Functions for parsing query parameters, type conversion, and safe field-path handling for MongoDB aggregation.
 
 ```python
 from oplnk_python_utils.core.parsing import (
@@ -116,6 +116,14 @@ nested_dict = parse_list_to_dict(["filters", "name", "$eq"], "john")
 -  **`parse_key_string_to_list(s)`**: Parse bracketed notation strings like `"filters[name][$eq]"`
 -  **`parse_list_to_dict(lst, value)`**: Convert key list and value into nested dictionary structure
 
+#### Field Path Utilities for Aggregation (NEW)
+
+-  **`normalize_field_path(field)`**: Normalize paths with array notation for MongoDB aggregation.
+   -  Example: `"user.addresses[1].street" -> "user.addresses.1.street"`
+-  **`validate_field_path(field)`**: Validate field paths for invalid characters before using them in pipelines.
+-  **`build_aggregation_field_expression(field)`**: Produce a proper aggregation expression, automatically prefixing with `$` when needed.
+   -  Example: `"user.addresses[1].street" -> "$user.addresses.1.street"`
+
 ### Serialization Utilities (`core.serialization`)
 
 Functions for converting data types to serializable formats.
@@ -161,15 +169,15 @@ cache_key = generate_cache_id({
 })
 # Automatically normalizes data internally and creates SHA256 hash
 
-# Get from cache or execute function and cache result
-async def expensive_operation(query):
-    # Some expensive database operation
-    return await db.collection.find(query).to_list()
+# Get from cache or execute a function and cache result (sync fetch_func)
+def fetch_users():
+    # Some expensive database operation (sync example)
+    return list(db.collection.find({"status": "active"}))
 
-result = await get_or_set_cache(
+result = get_or_set_cache(
     redis_client=redis,
     cache_key="user_query_abc123",
-    fetch_func=expensive_operation,
+    fetch_func=fetch_users,  # zero-arg callable
     ttl=3600,  # 1 hour
     serializer=datetime_serializer
 )
@@ -228,10 +236,10 @@ async def create_user(request: Request):
     # Automatically invalidates 'users' tag after creation
     return {"created": True}
 
-# Manual cache key building
+# Manual cache key building (build_cache_key is async)
 @app.get("/custom")
 async def custom_endpoint(request: Request):
-    cache_key = build_cache_key(request, "myapi", "custom", "read")
+    cache_key = await build_cache_key(request, "myapi", "custom", "read")
     # Use cache_key for custom caching logic
     return {"data": "custom"}
 

{oplnk_python_utils-1.1.7 → oplnk_python_utils-1.1.8}/oplnk_python_utils/__init__.py

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

{oplnk_python_utils-1.1.7 → oplnk_python_utils-1.1.8}/oplnk_python_utils/core/parsing.py

@@ -11,10 +11,10 @@ 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
     """
@@ -54,10 +54,10 @@ def infer_type(value: Union[str, List, Any]) -> Any:
 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
     """
@@ -69,11 +69,11 @@ def parse_key_string_to_list(s: str) -> List[str]:
 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
     """
@@ -93,16 +93,16 @@ 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)
+    if hasattr(params, "items"):
+        param_dict = dict(params.items()) if hasattr(params, "items") else dict(params)
     else:
         param_dict = params
 
@@ -111,4 +111,83 @@ def parse_params_to_dict(params: Union[Dict[str, str], Any]) -> Dict[str, Any]:
         args = parse_key_string_to_list(key)
         dictionary = parse_list_to_dict(args, value)
         result = merge_dicts(result, dictionary)
-    return result 
+    return result
+
+
+# Field handling utilities for MongoDB aggregation pipelines
+
+
+def normalize_field_path(field: str) -> str:
+    """
+    Normalize field path for MongoDB aggregation pipeline.
+    Handles dot notation and prepares for array notation.
+
+    Examples:
+        "establishment_type.name" -> "establishment_type.name"
+        "establishment_type[0].name" -> "establishment_type.0.name"
+        "user.addresses[1].street" -> "user.addresses.1.street"
+
+    Args:
+        field: Field path to normalize
+
+    Returns:
+        Normalized field path compatible with MongoDB aggregation
+    """
+    # Convert array notation to dot notation for MongoDB
+    # establishment_type[0].name -> establishment_type.0.name
+
+    # Pattern to match array notation like [0], [1], etc.
+    array_pattern = r"\[(\d+)\]"
+    normalized = re.sub(array_pattern, r".\1", field)
+
+    return normalized
+
+
+def validate_field_path(field: str) -> bool:
+    """
+    Validate if a field path is valid for MongoDB aggregation.
+
+    Args:
+        field: Field path to validate
+
+    Returns:
+        bool: True if valid, False otherwise
+    """
+    if not field or not isinstance(field, str):
+        return False
+
+    # Check for invalid characters
+    invalid_chars = ["$", " ", "\t", "\n", "\r"]
+    if any(
+        char in field
+        for char in invalid_chars
+        if char != "$" or not field.startswith("$")
+    ):
+        return False
+
+    return True
+
+
+def build_aggregation_field_expression(field: str) -> str:
+    """
+    Build proper MongoDB aggregation field expression.
+
+    Args:
+        field: Field name or path
+
+    Returns:
+        str: Properly formatted field expression for aggregation
+
+    Raises:
+        ValueError: If field path is invalid
+    """
+    if not validate_field_path(field):
+        raise ValueError(f"Invalid field path: {field}")
+
+    normalized_field = normalize_field_path(field)
+
+    # If field doesn't start with $, add it for aggregation
+    if not normalized_field.startswith("$"):
+        return f"${normalized_field}"
+
+    return normalized_field

{oplnk_python_utils-1.1.7 → oplnk_python_utils-1.1.8}/oplnk_python_utils/query/query_builder.py

@@ -3,18 +3,18 @@ Query Builder - Generic query building functionality for MongoDB aggregation pip
 """
 
 import re
+import time
 from copy import deepcopy
-from typing import List, Dict, Any, Optional, Union, Callable
-from datetime import datetime
-from bson import ObjectId
+from typing import List, Dict, Any, Optional, Union
 from fastapi import HTTPException, status
+from pprint import pprint
 
 # Import core utilities
 from ..core.parsing import (
-    infer_type,
-    parse_key_string_to_list,
-    parse_list_to_dict,
     parse_params_to_dict,
+    normalize_field_path,
+    validate_field_path,
+    build_aggregation_field_expression,
 )
 
 
@@ -46,6 +46,7 @@ class QueryBuilder:
         cache_client=None,
         cache_key_prefix: str = "",
         clear_cache: bool = False,
+        debug: bool = False,
     ) -> Dict[str, Any]:
         """
         Complete query method that handles parameter parsing and query execution.
@@ -60,8 +61,25 @@ class QueryBuilder:
             cache_client: Cache client (Redis)
             cache_key_prefix: Prefix for cache keys
             clear_cache: Whether to clear cache before query
+            debug: Whether to enable debug output
         """
+        # Start timing
+        start_time = time.time()
+
+        if debug:
+            print("🔵 [DEBUG] Parámetros de entrada:")
+            pprint(
+                {
+                    "params": params if params is not None else "None",
+                    "query": query if query is not None else "None",
+                    "use_cache": use_cache,
+                    "cache_key_prefix": cache_key_prefix,
+                    "clear_cache": clear_cache,
+                }
+            )
+
         # Parse params if provided, otherwise use query directly
+        parsing_start_time = time.time()
         if params is not None:
             parsed_query = parse_params_to_dict(params)
         elif query is not None:
@@ -73,6 +91,13 @@ class QueryBuilder:
         if "clear_cache" in parsed_query:
             clear_cache = parsed_query.pop("clear_cache", False)
 
+        parsing_time = time.time() - parsing_start_time
+
+        if debug:
+            print("🔵 [DEBUG] Query parseada:")
+            pprint(parsed_query)
+            print(f"🔵 [DEBUG] Tiempo de parsing: {parsing_time:.3f}s")
+
         return self.get_query_response(
             db_collection,
             parsed_query,
@@ -82,6 +107,9 @@ class QueryBuilder:
             cache_key_prefix=cache_key_prefix,
             use_cache=use_cache,
             clear_cache=clear_cache,
+            debug=debug,
+            start_time=start_time,
+            parsing_time=parsing_time,
         )
 
     def build_filter_pipeline(self, filters: Dict[str, Any]) -> Dict[str, Any]:
@@ -421,6 +449,9 @@ class QueryBuilder:
                         field_name = list(condition.keys())[0]
                         field_conditions = condition[field_name]
 
+                        # Normalize field name for dot notation support
+                        normalized_field_name = normalize_field_path(field_name)
+
                         if isinstance(field_conditions, dict):
                             operator = list(field_conditions.keys())[0]
                             value = field_conditions[operator]
@@ -443,38 +474,68 @@ class QueryBuilder:
                                 # Expand this condition into multiple alternatives
                                 value_type, str_value = get_value_type_and_string(value)
                                 expanded_conditions = expand_text_search_condition(
-                                    field_name, operator, str_value
+                                    normalized_field_name, operator, str_value
                                 )
 
                                 # Add all expanded conditions to the $or
                                 or_conditions.extend(expanded_conditions)
                             else:
-                                # Regular condition, process normally
-                                sub_pipeline = self.build_filter_pipeline(condition)
+                                # Regular condition, process normally with normalized field
+                                normalized_condition = {
+                                    normalized_field_name: field_conditions
+                                }
+                                sub_pipeline = self.build_filter_pipeline(
+                                    normalized_condition
+                                )
                                 or_conditions.append(sub_pipeline)
                         else:
-                            # Regular condition, process normally
-                            sub_pipeline = self.build_filter_pipeline(condition)
+                            # Regular condition, process normally with normalized field
+                            normalized_condition = {
+                                normalized_field_name: field_conditions
+                            }
+                            sub_pipeline = self.build_filter_pipeline(
+                                normalized_condition
+                            )
                             or_conditions.append(sub_pipeline)
 
                     pipeline["$or"] = or_conditions
                 case "$and":
                     and_conditions = []
                     for condition in conditions:
-                        sub_pipeline = self.build_filter_pipeline(condition)
+                        # Normalize field names in condition for dot notation support
+                        normalized_condition = {}
+                        for field_name, field_conditions in condition.items():
+                            normalized_field_name = normalize_field_path(field_name)
+                            normalized_condition[normalized_field_name] = (
+                                field_conditions
+                            )
+
+                        sub_pipeline = self.build_filter_pipeline(normalized_condition)
                         and_conditions.append(sub_pipeline)
                     pipeline["$and"] = and_conditions
                 case _:
                     try:
-                        sub_pipeline = build_sub_pipeline(conditions, field)
+                        # Normalize field path for dot notation and array notation support
+                        normalized_field = normalize_field_path(field)
+
+                        # Validate the field path
+                        if not validate_field_path(normalized_field):
+                            print(
+                                f"Warning: Invalid field path '{field}', skipping filter condition"
+                            )
+                            continue
+
+                        sub_pipeline = build_sub_pipeline(conditions, normalized_field)
 
                         if isinstance(sub_pipeline, dict):
                             if "_field" in sub_pipeline:
-                                new_field = f"{field}.{sub_pipeline['_field']}"
+                                new_field = (
+                                    f"{normalized_field}.{sub_pipeline['_field']}"
+                                )
                                 pipeline[new_field] = sub_pipeline["_conditions"]
                                 continue
 
-                        pipeline[field] = sub_pipeline
+                        pipeline[normalized_field] = sub_pipeline
                     except (ValueError, TypeError) as e:
                         # Log the error and skip this filter condition
                         print(f"Error processing filter for field '{field}': {e}")
@@ -483,22 +544,64 @@ class QueryBuilder:
         return pipeline
 
     def build_sort_pipeline(self, sort_params: List[str]) -> Dict[str, Any]:
-        """Build sort pipeline from sort parameters"""
+        """
+        Build sort pipeline from sort parameters with support for dot notation and array notation.
+        """
         sort_pipeline = {}
         for item in sort_params:
-            field, order = item.split(":")
-            sort_pipeline[field] = 1 if order == "asc" else -1
+            try:
+                field, order = item.split(":")
+                normalized_field = normalize_field_path(field)
+
+                if validate_field_path(normalized_field):
+                    sort_pipeline[normalized_field] = 1 if order == "asc" else -1
+                else:
+                    print(f"Warning: Invalid field path '{field}', skipping in sort")
+            except ValueError as e:
+                print(
+                    f"Warning: Invalid sort parameter '{item}', expected format 'field:order': {e}"
+                )
+            except Exception as e:
+                print(f"Warning: Error processing sort parameter '{item}': {e}")
+
         return {"$sort": sort_pipeline}
 
     def build_fields_pipeline(
         self, fields_params: List[str], populate_params: Optional[List] = None
     ) -> Dict[str, Any]:
-        """Build fields projection pipeline"""
-        fields_pipeline = {field: 1 for field in fields_params}
+        """
+        Build fields projection pipeline with support for dot notation and array notation.
+        """
+        fields_pipeline = {}
 
+        # Process fields_params with normalization
+        for field in fields_params:
+            try:
+                normalized_field = normalize_field_path(field)
+                if validate_field_path(normalized_field):
+                    fields_pipeline[normalized_field] = 1
+                else:
+                    print(
+                        f"Warning: Invalid field path '{field}', skipping in projection"
+                    )
+            except Exception as e:
+                print(f"Warning: Error processing field '{field}' in projection: {e}")
+
+        # Process populate_params if provided
         if populate_params:
             for field in populate_params:
-                fields_pipeline[field] = 1
+                try:
+                    normalized_field = normalize_field_path(field)
+                    if validate_field_path(normalized_field):
+                        fields_pipeline[normalized_field] = 1
+                    else:
+                        print(
+                            f"Warning: Invalid populate field path '{field}', skipping in projection"
+                        )
+                except Exception as e:
+                    print(
+                        f"Warning: Error processing populate field '{field}' in projection: {e}"
+                    )
 
         return {"$project": fields_pipeline}
 
@@ -508,14 +611,84 @@ class QueryBuilder:
         include_project: bool = True,
         pipeline: Optional[List] = None,
     ) -> List[Dict[str, Any]]:
-        """Build distinct pipeline"""
-        group_id = {field: f"${field}" for field in distinct_params}
-        group_stage = {"$group": {"_id": group_id}}
-        if include_project:
-            replace_root_stage = {"$replaceRoot": {"newRoot": "$_id"}}
-            return [group_stage, replace_root_stage]
-        else:
-            return [group_stage]
+        """
+        Build distinct pipeline with support for dot notation and array notation.
+        """
+        try:
+            # Build group_id with proper field expressions
+            group_id = {}
+            project_fields = {}
+
+            for field in distinct_params:
+                try:
+                    # Use utility function to build proper aggregation expression
+                    field_expression = build_aggregation_field_expression(field)
+
+                    print(f"🔵 [DEBUG] Field: {field}")
+                    print(f"🔵 [DEBUG] Field expression: {field_expression}")
+
+                    # For MongoDB $group stage, we need to use a safe key name (no dots)
+                    # We'll use the original field name as key, but replace dots with underscores for the group
+                    safe_key = (
+                        field.replace(".", "_").replace("[", "_").replace("]", "_")
+                    )
+                    group_id[safe_key] = field_expression
+
+                    print(f"🔵 [DEBUG] Safe key: {safe_key}")
+                    print(f"🔵 [DEBUG] Group ID entry: {safe_key} = {field_expression}")
+
+                    # Build nested structure for the projection to maintain original field structure
+                    parts = field.split(".")
+                    current = project_fields
+                    for i, part in enumerate(parts[:-1]):
+                        if part not in current:
+                            current[part] = {}
+                        current = current[part]
+
+                    # Set the final value
+                    current[parts[-1]] = f"$_id.{safe_key}"
+
+                    print(
+                        f"🔵 [DEBUG] Project fields after processing {field}: {project_fields}"
+                    )
+
+                    # Debug: Check if field exists in pipeline before distinct
+                    print(
+                        f"🔵 [DEBUG] Pipeline before distinct contains establishment_type lookup: {any('establishment_type' in str(stage) for stage in pipeline) if pipeline else 'No pipeline provided'}"
+                    )
+                    print(
+                        f"🔵 [DEBUG] Available relations: {[rel[1] for rel in self.relations]}"
+                    )
+
+                except ValueError as e:
+                    # Log error and skip invalid field
+                    print(f"Warning: Skipping invalid field '{field}' in distinct: {e}")
+                    continue
+
+            if not group_id:
+                raise ValueError("No valid fields provided for distinct operation")
+
+            group_stage = {"$group": {"_id": group_id}}
+
+            if include_project:
+                # Use $project to create the nested structure
+                project_stage = {"$project": project_fields}
+                return [group_stage, project_stage]
+            else:
+                return [group_stage]
+
+        except Exception as e:
+            # Fallback to original behavior for backwards compatibility
+            print(
+                f"Warning: Error in enhanced distinct pipeline, falling back to original: {e}"
+            )
+            group_id = {field: f"${field}" for field in distinct_params}
+            group_stage = {"$group": {"_id": group_id}}
+            if include_project:
+                replace_root_stage = {"$replaceRoot": {"newRoot": "$_id"}}
+                return [group_stage, replace_root_stage]
+            else:
+                return [group_stage]
 
     def build_pagination_pipeline(
         self, pagination_params: Dict[str, Any], pipeline: Optional[List] = None
@@ -883,6 +1056,9 @@ class QueryBuilder:
         cache_key_prefix: str = "",
         use_cache: bool = False,
         clear_cache: bool = False,
+        debug: bool = False,
+        start_time: float = 0,
+        parsing_time: float = 0,
     ) -> Dict[str, Any]:
         """
         Get query response with optional caching support
@@ -896,16 +1072,64 @@ class QueryBuilder:
             cache_key_prefix: Prefix for cache keys
             use_cache: Whether to use caching
             clear_cache: Whether to clear cache before query
+            debug: Whether to enable debug output
+            start_time: Start time of the query
+            parsing_time: Time spent parsing parameters
         """
         try:
+            # Build pipelines
+            pipeline_build_start = time.time()
             base_pipeline = self.make_aggregation_query(query, pipeline)
             count_pipeline = self.make_count_aggregation_query(query, pipeline_count)
+            pipeline_build_time = time.time() - pipeline_build_start
+
+            if debug:
+                print("🔵 [DEBUG] Pipeline de agregación construido:")
+                pprint(base_pipeline)
+                print("🔵 [DEBUG] Pipeline de count construido:")
+                pprint(count_pipeline)
+
+                # Debug filters
+                if "filters" in query:
+                    filter_pipeline = self.build_filter_pipeline(query["filters"])
+                    print("🔵 [DEBUG] Filtros aplicados:")
+                    pprint(filter_pipeline)
+
+                # Debug special operations
+                if "populate" in query:
+                    print("🔵 [DEBUG] Relaciones a popular:")
+                    pprint(query["populate"])
+
+                if "distinct" in query:
+                    print("🔵 [DEBUG] Campos distinct:")
+                    pprint(query["distinct"])
+
+                if "sort" in query:
+                    print("🔵 [DEBUG] Ordenamiento aplicado:")
+                    pprint(query["sort"])
+
+                if "pagination" in query:
+                    print("🔵 [DEBUG] Paginación aplicada:")
+                    pprint(query["pagination"])
+
+            # Start MongoDB query timing
+            mongodb_start_time = time.time()
 
             # Get data
             data_result = list(db_collection.aggregate(base_pipeline))
 
             # Get count
             if use_cache and cache_client:
+                if debug:
+                    print("🔵 [DEBUG] Configuración de cache:")
+                    pprint(
+                        {
+                            "cache_key_prefix": cache_key_prefix,
+                            "clear_cache": clear_cache,
+                            "use_cache": use_cache,
+                        }
+                    )
+
                 # Import cache utilities
                 from ..cache import (
                     generate_cache_id,
@@ -919,6 +1143,10 @@ class QueryBuilder:
                 query_hash = generate_cache_id(query_for_hash)
                 count_key = f"{cache_key_prefix}:query:count:{query_hash}"
 
+                if debug:
+                    print("🔵 [DEBUG] Cache key generada:")
+                    print(f"count_key: {count_key}")
+
                 # Get or set meta from cache
                 meta_result = get_or_set_cache(
                     cache_client,
@@ -935,8 +1163,54 @@ class QueryBuilder:
             else:
                 meta_result = list(db_collection.aggregate(count_pipeline))
 
-            return self.sanitize_result(query, data_result, meta_result)
+            # End MongoDB query timing
+            mongodb_time = time.time() - mongodb_start_time
+
+            if debug:
+                print("🔵 [DEBUG] Resultado de query de datos:")
+                print(f"Registros encontrados: {len(data_result)}")
+                if data_result:
+                    print("Muestra del primer registro:")
+                    pprint(data_result[0])
+                    if len(data_result) > 1:
+                        print(f"... y {len(data_result) - 1} registros más")
+                else:
+                    print("Sin datos encontrados")
+
+                print("🔵 [DEBUG] Resultado de count:")
+                pprint(meta_result)
+
+            result = self.sanitize_result(query, data_result, meta_result)
+
+            if debug:
+                # Calculate total time
+                total_time = time.time() - start_time
+
+                print("🔵 [DEBUG] Respuesta final sanitizada:")
+                preview_data = result.get("data", [])
+                data_preview = {
+                    "data_count": len(preview_data),
+                    "first_record": preview_data[0] if preview_data else None,
+                    "remaining_records": (
+                        f"... y {len(preview_data) - 1} más"
+                        if len(preview_data) > 1
+                        else "ninguno más"
+                    ),
+                    "meta": result.get("meta", {}),
+                    "has_pagination": "pagination" in query,
+                }
+                pprint(data_preview)
+
+                print("🔵 [DEBUG] ⏱️  MÉTRICAS DE PERFORMANCE:")
+                print(f"  📊 Tiempo de parsing/pre-consulta: {parsing_time:.3f}s")
+                print(f"  🗄️  Tiempo real de consulta MongoDB: {mongodb_time:.3f}s")
+                print(f"  🚀 Tiempo total de procesamiento: {total_time:.3f}s")
+                print("=" * 60)
+
+            return result
         except Exception as e:
+            if debug:
+                print(f"🔴 [DEBUG] Error en get_query_response: {str(e)}")
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                 detail=str(e),

{oplnk_python_utils-1.1.7 → oplnk_python_utils-1.1.8/oplnk_python_utils.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oplnk-python-utils
-Version: 1.1.7
+Version: 1.1.8
 Summary: Reusable utilities for caching, data manipulation, parsing, and MongoDB query building
 Home-page: https://github.com/openlinkspa/oplnk-python-utils
 Author: OpenLink SpA
@@ -109,7 +109,7 @@ merged = merge_dicts(dict1, dict2)
 
 ### Parsing Utilities (`core.parsing`)
 
-Functions for parsing query parameters and type conversion.
+Functions for parsing query parameters, type conversion, and safe field-path handling for MongoDB aggregation.
 
 ```python
 from oplnk_python_utils.core.parsing import (
@@ -158,6 +158,14 @@ nested_dict = parse_list_to_dict(["filters", "name", "$eq"], "john")
 -  **`parse_key_string_to_list(s)`**: Parse bracketed notation strings like `"filters[name][$eq]"`
 -  **`parse_list_to_dict(lst, value)`**: Convert key list and value into nested dictionary structure
 
+#### Field Path Utilities for Aggregation (NEW)
+
+-  **`normalize_field_path(field)`**: Normalize paths with array notation for MongoDB aggregation.
+   -  Example: `"user.addresses[1].street" -> "user.addresses.1.street"`
+-  **`validate_field_path(field)`**: Validate field paths for invalid characters before using them in pipelines.
+-  **`build_aggregation_field_expression(field)`**: Produce a proper aggregation expression, automatically prefixing with `$` when needed.
+   -  Example: `"user.addresses[1].street" -> "$user.addresses.1.street"`
+
 ### Serialization Utilities (`core.serialization`)
 
 Functions for converting data types to serializable formats.
@@ -203,15 +211,15 @@ cache_key = generate_cache_id({
 })
 # Automatically normalizes data internally and creates SHA256 hash
 
-# Get from cache or execute function and cache result
-async def expensive_operation(query):
-    # Some expensive database operation
-    return await db.collection.find(query).to_list()
+# Get from cache or execute a function and cache result (sync fetch_func)
+def fetch_users():
+    # Some expensive database operation (sync example)
+    return list(db.collection.find({"status": "active"}))
 
-result = await get_or_set_cache(
+result = get_or_set_cache(
     redis_client=redis,
     cache_key="user_query_abc123",
-    fetch_func=expensive_operation,
+    fetch_func=fetch_users,  # zero-arg callable
     ttl=3600,  # 1 hour
     serializer=datetime_serializer
 )
@@ -270,10 +278,10 @@ async def create_user(request: Request):
     # Automatically invalidates 'users' tag after creation
     return {"created": True}
 
-# Manual cache key building
+# Manual cache key building (build_cache_key is async)
 @app.get("/custom")
 async def custom_endpoint(request: Request):
-    cache_key = build_cache_key(request, "myapi", "custom", "read")
+    cache_key = await build_cache_key(request, "myapi", "custom", "read")
     # Use cache_key for custom caching logic
     return {"data": "custom"}
 

{oplnk_python_utils-1.1.7 → oplnk_python_utils-1.1.8}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="oplnk-python-utils",
-    version="1.1.7",
+    version="1.1.8",
     author="OpenLink SpA",
     author_email="contacto@openlink.cl",
     description="Reusable utilities for caching, data manipulation, parsing, and MongoDB query building",