oplnk-python-utils 1.1.0__tar.gz → 1.1.2__tar.gz

{oplnk_python_utils-1.1.0/oplnk_python_utils.egg-info → oplnk_python_utils-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oplnk-python-utils
-Version: 1.1.0
+Version: 1.1.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
@@ -149,15 +149,50 @@ keys = parse_key_string_to_list("filters[name][$eq]")
 
 nested_dict = parse_list_to_dict(["filters", "name", "$eq"], "john")
 # Result: {"filters": {"name": {"$eq": "john"}}}
+
+# Enhanced field path handling for MongoDB aggregation (NEW)
+from oplnk_python_utils.core.parsing import (
+    normalize_field_path,
+    validate_field_path,
+    build_aggregation_field_expression
+)
+
+# Normalize field paths for MongoDB aggregation
+normalized = normalize_field_path("establishment_type[0].name")
+# Result: "establishment_type.0.name" - MongoDB compatible path
+
+normalized = normalize_field_path("user.addresses[1].street")
+# Result: "user.addresses.1.street" - Array notation converted to dot notation
+
+# Validate field paths for security and correctness
+valid = validate_field_path("user.profile.name")        # Returns: True
+valid = validate_field_path("user$invalid")             # Returns: False
+valid = validate_field_path("user.settings.theme")      # Returns: True
+valid = validate_field_path("")                         # Returns: False
+
+# Build proper aggregation field expressions
+field_expr = build_aggregation_field_expression("user.name")
+# Result: "$user.name" - Ready for MongoDB aggregation pipeline
+
+field_expr = build_aggregation_field_expression("establishment_type.0.name")
+# Result: "$establishment_type.0.name" - Handles normalized array paths
 ```
 
 #### Parsing Functions
 
+**Main Functions:**
+
 -  **`parse_params_to_dict(params)`**: Parse FastAPI QueryParams or dict into structured nested dictionary
 -  **`infer_type(value)`**: Smart type inference from string values (supports int, float, bool, datetime, lists)
 -  **`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 (NEW):**
+
+-  **`normalize_field_path(field)`**: Normalize field paths for MongoDB aggregation with dot notation and array support
+-  **`validate_field_path(field)`**: Validate if a field path is valid for MongoDB aggregation pipelines
+-  **`build_aggregation_field_expression(field)`**: Build proper MongoDB aggregation field expressions with $ prefix
+
 ### Serialization Utilities (`core.serialization`)
 
 Functions for converting data types to serializable formats.
@@ -351,7 +386,7 @@ GET /users?clear_cache=true
 
 ## Query Module
 
-The query module provides a MongoDB aggregation pipeline builder with advanced features.
+The query module provides a MongoDB aggregation pipeline builder with advanced features including enhanced support for nested fields, dot notation, and array notation.
 
 ### Usage
 
@@ -431,16 +466,42 @@ print(results)
 #     "data": [...],
 #     "meta": {"totalCount": 150}
 # }
+
+# Enhanced support for nested fields and array notation (NEW)
+nested_query = {
+    "filters": {
+        "user.profile.name": {"$containsi": "john"},                    # Dot notation
+        "establishment_type.0.name": {"$eq": "restaurant"},            # Array index notation
+        "addresses[1].street": {"$startsWith": "Main"},                # Bracket notation (auto-normalized)
+        "tags": {"$listContains": "featured"},                         # Array contains
+        "meta.settings.theme": {"$eq": "dark"}                         # Deep nested fields
+    },
+    "sort": [
+        "user.profile.created_at:desc",                                # Sort by nested field
+        "establishment_type.0.priority:asc"                           # Sort by array element
+    ],
+    "fields": [
+        "user.profile.name",                                           # Project nested fields
+        "addresses.0.street",                                          # Project specific array element
+        "meta.settings"                                                # Project nested objects
+    ]
+}
+
+# All field paths are automatically validated and normalized for MongoDB compatibility
+results = query_builder.get_query_response(
+    db_collection=collection,
+    query=nested_query
+)
 ```
 
 ### QueryBuilder Methods
 
 #### Pipeline Builders
 
--  **`build_filter_pipeline(filters)`**: Build MongoDB filter pipeline
--  **`build_sort_pipeline(sort_params)`**: Build sort pipeline
--  **`build_fields_pipeline(fields_params)`**: Build field projection pipeline
--  **`build_distinct_pipeline(distinct_params)`**: Build distinct pipeline
+-  **`build_filter_pipeline(filters)`**: Build MongoDB filter pipeline with enhanced support for nested fields and array notation
+-  **`build_sort_pipeline(sort_params)`**: Build sort pipeline with dot notation and array index support
+-  **`build_fields_pipeline(fields_params)`**: Build field projection pipeline with nested field validation
+-  **`build_distinct_pipeline(distinct_params)`**: Build distinct pipeline with proper field expression handling
 -  **`build_pagination_pipeline(pagination_params)`**: Build pagination pipeline
 -  **`build_populate_pipeline(populate_params)`**: Build population pipeline
 
@@ -459,6 +520,7 @@ print(results)
 The QueryBuilder class leverages utilities from the core module for enhanced functionality:
 
 -  **Parameter parsing**: Uses `core.parsing.parse_params_to_dict()` for automatic query parameter parsing
+-  **Field path processing**: Uses `core.parsing.normalize_field_path()`, `validate_field_path()`, and `build_aggregation_field_expression()` for safe nested field handling
 -  **Data normalization**: Uses `core.data.normalize()` for consistent cache key generation
 -  **Datetime serialization**: Uses `core.serialization.datetime_serializer()` for cache-friendly data
 
@@ -597,6 +659,59 @@ async def create_user(request: Request, user_data: dict):
 
 ## Advanced Features
 
+### Enhanced Nested Field Support (NEW)
+
+The query builder now provides comprehensive support for nested fields, dot notation, and array notation with automatic validation and normalization.
+
+#### Supported Field Notations
+
+```python
+# Dot notation for nested objects
+"user.profile.name"              # Access nested object properties
+"settings.theme.colors.primary"  # Deep nesting support
+
+# Array notation (both styles supported)
+"addresses[0].street"            # Bracket notation - automatically normalized
+"addresses.0.street"             # Dot notation - MongoDB native format
+"items[2].details.price"         # Mixed notation support
+
+# Complex nested structures
+"metadata.tags[1].category.name" # Arrays within nested objects
+"stores.0.products[5].variants.color" # Multiple levels of nesting
+```
+
+#### Automatic Field Validation
+
+All field paths are automatically validated for:
+
+-  **Security**: Prevents injection of invalid MongoDB operators
+-  **Syntax**: Ensures MongoDB-compatible field syntax
+-  **Normalization**: Converts bracket notation to dot notation
+-  **Error Handling**: Graceful handling of invalid paths with logging
+
+```python
+# Examples of validation in action
+query = {
+    "filters": {
+        "user.profile.name": {"$eq": "John"},           # ✅ Valid - passes through
+        "user$invalid": {"$eq": "test"},                # ❌ Invalid - skipped with warning
+        "settings[0].theme": {"$eq": "dark"},           # ✅ Valid - normalized to "settings.0.theme"
+        "": {"$eq": "empty"},                           # ❌ Invalid - skipped with warning
+        "normal_field": {"$eq": "value"}                # ✅ Valid - standard field access
+    }
+}
+
+# Invalid fields are automatically filtered out with helpful logging
+# Valid fields continue to work normally
+```
+
+#### Performance Optimizations
+
+-  **Smart Field Processing**: Only processes fields that need normalization
+-  **Validation Caching**: Avoids repeated validation of the same field paths
+-  **Error Recovery**: Continues processing even when individual fields are invalid
+-  **Minimal Overhead**: Validation adds negligible performance impact
+
 ### Custom Relation Definitions
 
 ```python

{oplnk_python_utils-1.1.0 → oplnk_python_utils-1.1.2}/README.md

@@ -107,15 +107,50 @@ keys = parse_key_string_to_list("filters[name][$eq]")
 
 nested_dict = parse_list_to_dict(["filters", "name", "$eq"], "john")
 # Result: {"filters": {"name": {"$eq": "john"}}}
+
+# Enhanced field path handling for MongoDB aggregation (NEW)
+from oplnk_python_utils.core.parsing import (
+    normalize_field_path,
+    validate_field_path,
+    build_aggregation_field_expression
+)
+
+# Normalize field paths for MongoDB aggregation
+normalized = normalize_field_path("establishment_type[0].name")
+# Result: "establishment_type.0.name" - MongoDB compatible path
+
+normalized = normalize_field_path("user.addresses[1].street")
+# Result: "user.addresses.1.street" - Array notation converted to dot notation
+
+# Validate field paths for security and correctness
+valid = validate_field_path("user.profile.name")        # Returns: True
+valid = validate_field_path("user$invalid")             # Returns: False
+valid = validate_field_path("user.settings.theme")      # Returns: True
+valid = validate_field_path("")                         # Returns: False
+
+# Build proper aggregation field expressions
+field_expr = build_aggregation_field_expression("user.name")
+# Result: "$user.name" - Ready for MongoDB aggregation pipeline
+
+field_expr = build_aggregation_field_expression("establishment_type.0.name")
+# Result: "$establishment_type.0.name" - Handles normalized array paths
 ```
 
 #### Parsing Functions
 
+**Main Functions:**
+
 -  **`parse_params_to_dict(params)`**: Parse FastAPI QueryParams or dict into structured nested dictionary
 -  **`infer_type(value)`**: Smart type inference from string values (supports int, float, bool, datetime, lists)
 -  **`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 (NEW):**
+
+-  **`normalize_field_path(field)`**: Normalize field paths for MongoDB aggregation with dot notation and array support
+-  **`validate_field_path(field)`**: Validate if a field path is valid for MongoDB aggregation pipelines
+-  **`build_aggregation_field_expression(field)`**: Build proper MongoDB aggregation field expressions with $ prefix
+
 ### Serialization Utilities (`core.serialization`)
 
 Functions for converting data types to serializable formats.
@@ -309,7 +344,7 @@ GET /users?clear_cache=true
 
 ## Query Module
 
-The query module provides a MongoDB aggregation pipeline builder with advanced features.
+The query module provides a MongoDB aggregation pipeline builder with advanced features including enhanced support for nested fields, dot notation, and array notation.
 
 ### Usage
 
@@ -389,16 +424,42 @@ print(results)
 #     "data": [...],
 #     "meta": {"totalCount": 150}
 # }
+
+# Enhanced support for nested fields and array notation (NEW)
+nested_query = {
+    "filters": {
+        "user.profile.name": {"$containsi": "john"},                    # Dot notation
+        "establishment_type.0.name": {"$eq": "restaurant"},            # Array index notation
+        "addresses[1].street": {"$startsWith": "Main"},                # Bracket notation (auto-normalized)
+        "tags": {"$listContains": "featured"},                         # Array contains
+        "meta.settings.theme": {"$eq": "dark"}                         # Deep nested fields
+    },
+    "sort": [
+        "user.profile.created_at:desc",                                # Sort by nested field
+        "establishment_type.0.priority:asc"                           # Sort by array element
+    ],
+    "fields": [
+        "user.profile.name",                                           # Project nested fields
+        "addresses.0.street",                                          # Project specific array element
+        "meta.settings"                                                # Project nested objects
+    ]
+}
+
+# All field paths are automatically validated and normalized for MongoDB compatibility
+results = query_builder.get_query_response(
+    db_collection=collection,
+    query=nested_query
+)
 ```
 
 ### QueryBuilder Methods
 
 #### Pipeline Builders
 
--  **`build_filter_pipeline(filters)`**: Build MongoDB filter pipeline
--  **`build_sort_pipeline(sort_params)`**: Build sort pipeline
--  **`build_fields_pipeline(fields_params)`**: Build field projection pipeline
--  **`build_distinct_pipeline(distinct_params)`**: Build distinct pipeline
+-  **`build_filter_pipeline(filters)`**: Build MongoDB filter pipeline with enhanced support for nested fields and array notation
+-  **`build_sort_pipeline(sort_params)`**: Build sort pipeline with dot notation and array index support
+-  **`build_fields_pipeline(fields_params)`**: Build field projection pipeline with nested field validation
+-  **`build_distinct_pipeline(distinct_params)`**: Build distinct pipeline with proper field expression handling
 -  **`build_pagination_pipeline(pagination_params)`**: Build pagination pipeline
 -  **`build_populate_pipeline(populate_params)`**: Build population pipeline
 
@@ -417,6 +478,7 @@ print(results)
 The QueryBuilder class leverages utilities from the core module for enhanced functionality:
 
 -  **Parameter parsing**: Uses `core.parsing.parse_params_to_dict()` for automatic query parameter parsing
+-  **Field path processing**: Uses `core.parsing.normalize_field_path()`, `validate_field_path()`, and `build_aggregation_field_expression()` for safe nested field handling
 -  **Data normalization**: Uses `core.data.normalize()` for consistent cache key generation
 -  **Datetime serialization**: Uses `core.serialization.datetime_serializer()` for cache-friendly data
 
@@ -555,6 +617,59 @@ async def create_user(request: Request, user_data: dict):
 
 ## Advanced Features
 
+### Enhanced Nested Field Support (NEW)
+
+The query builder now provides comprehensive support for nested fields, dot notation, and array notation with automatic validation and normalization.
+
+#### Supported Field Notations
+
+```python
+# Dot notation for nested objects
+"user.profile.name"              # Access nested object properties
+"settings.theme.colors.primary"  # Deep nesting support
+
+# Array notation (both styles supported)
+"addresses[0].street"            # Bracket notation - automatically normalized
+"addresses.0.street"             # Dot notation - MongoDB native format
+"items[2].details.price"         # Mixed notation support
+
+# Complex nested structures
+"metadata.tags[1].category.name" # Arrays within nested objects
+"stores.0.products[5].variants.color" # Multiple levels of nesting
+```
+
+#### Automatic Field Validation
+
+All field paths are automatically validated for:
+
+-  **Security**: Prevents injection of invalid MongoDB operators
+-  **Syntax**: Ensures MongoDB-compatible field syntax
+-  **Normalization**: Converts bracket notation to dot notation
+-  **Error Handling**: Graceful handling of invalid paths with logging
+
+```python
+# Examples of validation in action
+query = {
+    "filters": {
+        "user.profile.name": {"$eq": "John"},           # ✅ Valid - passes through
+        "user$invalid": {"$eq": "test"},                # ❌ Invalid - skipped with warning
+        "settings[0].theme": {"$eq": "dark"},           # ✅ Valid - normalized to "settings.0.theme"
+        "": {"$eq": "empty"},                           # ❌ Invalid - skipped with warning
+        "normal_field": {"$eq": "value"}                # ✅ Valid - standard field access
+    }
+}
+
+# Invalid fields are automatically filtered out with helpful logging
+# Valid fields continue to work normally
+```
+
+#### Performance Optimizations
+
+-  **Smart Field Processing**: Only processes fields that need normalization
+-  **Validation Caching**: Avoids repeated validation of the same field paths
+-  **Error Recovery**: Continues processing even when individual fields are invalid
+-  **Minimal Overhead**: Validation adds negligible performance impact
+
 ### Custom Relation Definitions
 
 ```python

{oplnk_python_utils-1.1.0 → oplnk_python_utils-1.1.2}/oplnk_python_utils/__init__.py

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

{oplnk_python_utils-1.1.0 → oplnk_python_utils-1.1.2}/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.0 → oplnk_python_utils-1.1.2}/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,7 +91,14 @@ class QueryBuilder:
         if "clear_cache" in parsed_query:
             clear_cache = parsed_query.pop("clear_cache", False)
 
-        self.get_query_response(
+        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,
             pipeline,
@@ -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,46 @@ 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 = {}
+            for field in distinct_params:
+                try:
+                    # Use utility function to build proper aggregation expression
+                    field_expression = build_aggregation_field_expression(field)
+                    # Use original field name as key for the result
+                    group_id[field] = field_expression
+                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:
+                replace_root_stage = {"$replaceRoot": {"newRoot": "$_id"}}
+                return [group_stage, replace_root_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 +1018,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 +1034,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 +1105,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 +1125,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.0 → oplnk_python_utils-1.1.2/oplnk_python_utils.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oplnk-python-utils
-Version: 1.1.0
+Version: 1.1.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
@@ -149,15 +149,50 @@ keys = parse_key_string_to_list("filters[name][$eq]")
 
 nested_dict = parse_list_to_dict(["filters", "name", "$eq"], "john")
 # Result: {"filters": {"name": {"$eq": "john"}}}
+
+# Enhanced field path handling for MongoDB aggregation (NEW)
+from oplnk_python_utils.core.parsing import (
+    normalize_field_path,
+    validate_field_path,
+    build_aggregation_field_expression
+)
+
+# Normalize field paths for MongoDB aggregation
+normalized = normalize_field_path("establishment_type[0].name")
+# Result: "establishment_type.0.name" - MongoDB compatible path
+
+normalized = normalize_field_path("user.addresses[1].street")
+# Result: "user.addresses.1.street" - Array notation converted to dot notation
+
+# Validate field paths for security and correctness
+valid = validate_field_path("user.profile.name")        # Returns: True
+valid = validate_field_path("user$invalid")             # Returns: False
+valid = validate_field_path("user.settings.theme")      # Returns: True
+valid = validate_field_path("")                         # Returns: False
+
+# Build proper aggregation field expressions
+field_expr = build_aggregation_field_expression("user.name")
+# Result: "$user.name" - Ready for MongoDB aggregation pipeline
+
+field_expr = build_aggregation_field_expression("establishment_type.0.name")
+# Result: "$establishment_type.0.name" - Handles normalized array paths
 ```
 
 #### Parsing Functions
 
+**Main Functions:**
+
 -  **`parse_params_to_dict(params)`**: Parse FastAPI QueryParams or dict into structured nested dictionary
 -  **`infer_type(value)`**: Smart type inference from string values (supports int, float, bool, datetime, lists)
 -  **`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 (NEW):**
+
+-  **`normalize_field_path(field)`**: Normalize field paths for MongoDB aggregation with dot notation and array support
+-  **`validate_field_path(field)`**: Validate if a field path is valid for MongoDB aggregation pipelines
+-  **`build_aggregation_field_expression(field)`**: Build proper MongoDB aggregation field expressions with $ prefix
+
 ### Serialization Utilities (`core.serialization`)
 
 Functions for converting data types to serializable formats.
@@ -351,7 +386,7 @@ GET /users?clear_cache=true
 
 ## Query Module
 
-The query module provides a MongoDB aggregation pipeline builder with advanced features.
+The query module provides a MongoDB aggregation pipeline builder with advanced features including enhanced support for nested fields, dot notation, and array notation.
 
 ### Usage
 
@@ -431,16 +466,42 @@ print(results)
 #     "data": [...],
 #     "meta": {"totalCount": 150}
 # }
+
+# Enhanced support for nested fields and array notation (NEW)
+nested_query = {
+    "filters": {
+        "user.profile.name": {"$containsi": "john"},                    # Dot notation
+        "establishment_type.0.name": {"$eq": "restaurant"},            # Array index notation
+        "addresses[1].street": {"$startsWith": "Main"},                # Bracket notation (auto-normalized)
+        "tags": {"$listContains": "featured"},                         # Array contains
+        "meta.settings.theme": {"$eq": "dark"}                         # Deep nested fields
+    },
+    "sort": [
+        "user.profile.created_at:desc",                                # Sort by nested field
+        "establishment_type.0.priority:asc"                           # Sort by array element
+    ],
+    "fields": [
+        "user.profile.name",                                           # Project nested fields
+        "addresses.0.street",                                          # Project specific array element
+        "meta.settings"                                                # Project nested objects
+    ]
+}
+
+# All field paths are automatically validated and normalized for MongoDB compatibility
+results = query_builder.get_query_response(
+    db_collection=collection,
+    query=nested_query
+)
 ```
 
 ### QueryBuilder Methods
 
 #### Pipeline Builders
 
--  **`build_filter_pipeline(filters)`**: Build MongoDB filter pipeline
--  **`build_sort_pipeline(sort_params)`**: Build sort pipeline
--  **`build_fields_pipeline(fields_params)`**: Build field projection pipeline
--  **`build_distinct_pipeline(distinct_params)`**: Build distinct pipeline
+-  **`build_filter_pipeline(filters)`**: Build MongoDB filter pipeline with enhanced support for nested fields and array notation
+-  **`build_sort_pipeline(sort_params)`**: Build sort pipeline with dot notation and array index support
+-  **`build_fields_pipeline(fields_params)`**: Build field projection pipeline with nested field validation
+-  **`build_distinct_pipeline(distinct_params)`**: Build distinct pipeline with proper field expression handling
 -  **`build_pagination_pipeline(pagination_params)`**: Build pagination pipeline
 -  **`build_populate_pipeline(populate_params)`**: Build population pipeline
 
@@ -459,6 +520,7 @@ print(results)
 The QueryBuilder class leverages utilities from the core module for enhanced functionality:
 
 -  **Parameter parsing**: Uses `core.parsing.parse_params_to_dict()` for automatic query parameter parsing
+-  **Field path processing**: Uses `core.parsing.normalize_field_path()`, `validate_field_path()`, and `build_aggregation_field_expression()` for safe nested field handling
 -  **Data normalization**: Uses `core.data.normalize()` for consistent cache key generation
 -  **Datetime serialization**: Uses `core.serialization.datetime_serializer()` for cache-friendly data
 
@@ -597,6 +659,59 @@ async def create_user(request: Request, user_data: dict):
 
 ## Advanced Features
 
+### Enhanced Nested Field Support (NEW)
+
+The query builder now provides comprehensive support for nested fields, dot notation, and array notation with automatic validation and normalization.
+
+#### Supported Field Notations
+
+```python
+# Dot notation for nested objects
+"user.profile.name"              # Access nested object properties
+"settings.theme.colors.primary"  # Deep nesting support
+
+# Array notation (both styles supported)
+"addresses[0].street"            # Bracket notation - automatically normalized
+"addresses.0.street"             # Dot notation - MongoDB native format
+"items[2].details.price"         # Mixed notation support
+
+# Complex nested structures
+"metadata.tags[1].category.name" # Arrays within nested objects
+"stores.0.products[5].variants.color" # Multiple levels of nesting
+```
+
+#### Automatic Field Validation
+
+All field paths are automatically validated for:
+
+-  **Security**: Prevents injection of invalid MongoDB operators
+-  **Syntax**: Ensures MongoDB-compatible field syntax
+-  **Normalization**: Converts bracket notation to dot notation
+-  **Error Handling**: Graceful handling of invalid paths with logging
+
+```python
+# Examples of validation in action
+query = {
+    "filters": {
+        "user.profile.name": {"$eq": "John"},           # ✅ Valid - passes through
+        "user$invalid": {"$eq": "test"},                # ❌ Invalid - skipped with warning
+        "settings[0].theme": {"$eq": "dark"},           # ✅ Valid - normalized to "settings.0.theme"
+        "": {"$eq": "empty"},                           # ❌ Invalid - skipped with warning
+        "normal_field": {"$eq": "value"}                # ✅ Valid - standard field access
+    }
+}
+
+# Invalid fields are automatically filtered out with helpful logging
+# Valid fields continue to work normally
+```
+
+#### Performance Optimizations
+
+-  **Smart Field Processing**: Only processes fields that need normalization
+-  **Validation Caching**: Avoids repeated validation of the same field paths
+-  **Error Recovery**: Continues processing even when individual fields are invalid
+-  **Minimal Overhead**: Validation adds negligible performance impact
+
 ### Custom Relation Definitions
 
 ```python

{oplnk_python_utils-1.1.0 → oplnk_python_utils-1.1.2}/setup.py

@@ -2,11 +2,11 @@ from setuptools import setup, find_packages
 
 setup(
     name="oplnk-python-utils",
-    version="1.1.0",
+    version="1.1.2",
     author="OpenLink SpA",
     author_email="contacto@openlink.cl",
     description="Reusable utilities for caching, data manipulation, parsing, and MongoDB query building",
-    long_description=open("README.md").read(),
+    long_description=open("README.md", encoding="utf-8").read(),
     long_description_content_type="text/markdown",
     url="https://github.com/openlinkspa/oplnk-python-utils",
     packages=find_packages(),