oplnk-python-utils 1.1.9__tar.gz → 1.2.1__tar.gz

{oplnk_python_utils-1.1.9/oplnk_python_utils.egg-info → oplnk_python_utils-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oplnk-python-utils
-Version: 1.1.9
+Version: 1.2.1
 Summary: Reusable utilities for caching, data manipulation, parsing, and MongoDB query building
 Home-page: https://github.com/openlinkspa/oplnk-python-utils
 Author: OpenLink SpA
@@ -623,6 +623,93 @@ relations = [
 ]
 ```
 
+### Reserved Audit Fields (v1.2.1)
+
+The QueryBuilder automatically handles common audit fields without requiring manual configuration:
+
+```python
+# No need to define these in relations anymore:
+query_builder = QueryBuilder(
+    collection_prefix="myapp",
+    relations=[
+        # creation_user and modification_user are automatically handled!
+        ["User", "user_id", "myapp", "users"],
+    ]
+)
+
+# Usage - just populate them:
+query = {
+    "populate": ["creation_user", "modification_user"]
+}
+
+# Result will include (original ID automatically removed, replaced by populated object):
+# {
+#     "data": [{
+#         "_id": "123",
+#         "creation_user": {  // Replaces the original ID field
+#             "_id": "user_id_string",
+#             "name": "John Doe",
+#             "person": "person_id"
+#         }
+#     }]
+# }
+```
+
+**Reserved fields:**
+
+-  `creation_user` → automatically populated, original ID is excluded
+-  `modification_user` → automatically populated, original ID is excluded
+
+These fields are only populated when explicitly requested via the `populate` parameter, following the Strapi philosophy of on-demand loading.
+
+### Populate Field Sanitization (v1.2.1)
+
+By default, when you populate a relation, the original ID field is automatically removed from the response (Strapi-like behavior):
+
+```python
+# Request with populate - establishment_id will be automatically excluded:
+query = {
+    "populate": ["establishment"]
+}
+
+# Response - establishment_id is not present:
+# {
+#     "data": [{
+#         "_id": "123",
+#         "name": "Product",
+#         "establishment": {  // Populated object replaces the ID
+#             "_id": "est_123",
+#             "name": "Main Office"
+#         }
+#         // establishment_id is NOT here
+#     }]
+# }
+```
+
+**To keep both the ID and populated object, explicitly request it in `fields`:**
+
+```python
+query = {
+    "populate": ["establishment"],
+    "fields": ["name", "establishment_id"]  # Request the ID explicitly
+}
+
+# Response - both ID and populated object are present:
+# {
+#     "data": [{
+#         "_id": "123",
+#         "name": "Product",
+#         "establishment_id": "est_123",  // Now included
+#         "establishment": {
+#             "_id": "est_123",
+#             "name": "Main Office"
+#         }
+#     }]
+# }
+```
+
+**For audit fields:** The original ID is always excluded (no option to keep it, since there's no `creation_user_id` field).
+
 ### Custom Pipelines
 
 ```python

{oplnk_python_utils-1.1.9 → oplnk_python_utils-1.2.1}/README.md

@@ -581,6 +581,93 @@ relations = [
 ]
 ```
 
+### Reserved Audit Fields (v1.2.1)
+
+The QueryBuilder automatically handles common audit fields without requiring manual configuration:
+
+```python
+# No need to define these in relations anymore:
+query_builder = QueryBuilder(
+    collection_prefix="myapp",
+    relations=[
+        # creation_user and modification_user are automatically handled!
+        ["User", "user_id", "myapp", "users"],
+    ]
+)
+
+# Usage - just populate them:
+query = {
+    "populate": ["creation_user", "modification_user"]
+}
+
+# Result will include (original ID automatically removed, replaced by populated object):
+# {
+#     "data": [{
+#         "_id": "123",
+#         "creation_user": {  // Replaces the original ID field
+#             "_id": "user_id_string",
+#             "name": "John Doe",
+#             "person": "person_id"
+#         }
+#     }]
+# }
+```
+
+**Reserved fields:**
+
+-  `creation_user` → automatically populated, original ID is excluded
+-  `modification_user` → automatically populated, original ID is excluded
+
+These fields are only populated when explicitly requested via the `populate` parameter, following the Strapi philosophy of on-demand loading.
+
+### Populate Field Sanitization (v1.2.1)
+
+By default, when you populate a relation, the original ID field is automatically removed from the response (Strapi-like behavior):
+
+```python
+# Request with populate - establishment_id will be automatically excluded:
+query = {
+    "populate": ["establishment"]
+}
+
+# Response - establishment_id is not present:
+# {
+#     "data": [{
+#         "_id": "123",
+#         "name": "Product",
+#         "establishment": {  // Populated object replaces the ID
+#             "_id": "est_123",
+#             "name": "Main Office"
+#         }
+#         // establishment_id is NOT here
+#     }]
+# }
+```
+
+**To keep both the ID and populated object, explicitly request it in `fields`:**
+
+```python
+query = {
+    "populate": ["establishment"],
+    "fields": ["name", "establishment_id"]  # Request the ID explicitly
+}
+
+# Response - both ID and populated object are present:
+# {
+#     "data": [{
+#         "_id": "123",
+#         "name": "Product",
+#         "establishment_id": "est_123",  // Now included
+#         "establishment": {
+#             "_id": "est_123",
+#             "name": "Main Office"
+#         }
+#     }]
+# }
+```
+
+**For audit fields:** The original ID is always excluded (no option to keep it, since there's no `creation_user_id` field).
+
 ### Custom Pipelines
 
 ```python

{oplnk_python_utils-1.1.9 → oplnk_python_utils-1.2.1}/oplnk_python_utils/__init__.py

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

{oplnk_python_utils-1.1.9 → oplnk_python_utils-1.2.1}/oplnk_python_utils/query/query_builder.py

@@ -17,6 +17,65 @@ from ..core.parsing import (
     build_aggregation_field_expression,
 )
 
+RESERVED_AUDIT_FIELDS = {
+    "creation_user": {
+        "collection": "users",
+        "field_name": "creation_user",
+        "alias": "creation_user",
+        "field_type": "id",
+        "project_exclude": {
+            "role": 0,
+            "hashed_password": 0,
+            "id": 0,
+            "avatar": 0,
+            "active_directory": 0,
+            "privacy_policy": 0,
+            "terms_condition": 0,
+            "privacy_policy_date": 0,
+            "disabled": 0,
+            "first_name": 0,
+            "last_name": 0,
+            "username": 0,
+            "email": 0,
+            "establishment_asignation_ids": 0,
+            "establishment_type_ids": 0,
+            "permission_by_establishment": 0,
+            "permission_by_establishment_type": 0,
+            "terms_condition_date": 0,
+            "establishment_ids": 0,
+            "establishment_active_id": 0,
+        },
+    },
+    "modification_user": {
+        "collection": "users",
+        "field_name": "modification_user",
+        "alias": "modification_user",
+        "field_type": "id",
+        "project_exclude": {
+            "role": 0,
+            "hashed_password": 0,
+            "id": 0,
+            "avatar": 0,
+            "active_directory": 0,
+            "privacy_policy": 0,
+            "terms_condition": 0,
+            "privacy_policy_date": 0,
+            "disabled": 0,
+            "first_name": 0,
+            "last_name": 0,
+            "username": 0,
+            "email": 0,
+            "establishment_asignation_ids": 0,
+            "establishment_type_ids": 0,
+            "permission_by_establishment": 0,
+            "permission_by_establishment_type": 0,
+            "terms_condition_date": 0,
+            "establishment_ids": 0,
+            "establishment_active_id": 0,
+        },
+    },
+}
+
 
 class QueryBuilder:
     """
@@ -719,6 +778,48 @@ class QueryBuilder:
 
         return pipeline_copy
 
+    def _get_populated_field_mappings(self, query_populate: Any) -> Dict[str, str]:
+        """
+        Build a mapping of populated field names to their original ID field names.
+
+        For example: {"establishment": "establishment_id", "creation_user": "_original_creation_user"}
+
+        Args:
+            query_populate: The populate parameter (list or dict)
+
+        Returns:
+            Dict mapping populated field names to their original ID fields
+        """
+        mappings = {}
+
+        if isinstance(query_populate, list):
+            for field in query_populate:
+                if field in RESERVED_AUDIT_FIELDS:
+                    # Audit fields: map to the temporary original field
+                    mappings[field] = f"_original_{field}"
+                else:
+                    # Normal relations: try to find the ID field
+                    for relation in self.relations:
+                        relation_name = relation[1]
+                        # Remove _id or _ids suffix to get base name
+                        base_name = relation_name.replace("_ids", "").replace("_id", "")
+                        if base_name == field:
+                            mappings[field] = relation_name
+                            break
+        elif isinstance(query_populate, dict):
+            for field in query_populate.keys():
+                if field in RESERVED_AUDIT_FIELDS:
+                    mappings[field] = f"_original_{field}"
+                else:
+                    for relation in self.relations:
+                        relation_name = relation[1]
+                        base_name = relation_name.replace("_ids", "").replace("_id", "")
+                        if base_name == field:
+                            mappings[field] = relation_name
+                            break
+
+        return mappings
+
     def sanitize_result(
         self, query: Dict[str, Any], data_result: Any, meta_result: Any
     ) -> Dict[str, Any]:
@@ -741,8 +842,76 @@ class QueryBuilder:
         if not meta_result or "totalCount" not in meta_result:
             meta_result = {"totalCount": 0}
 
+        # Sanitize populate fields: remove original ID fields when populated
+        if "populate" in query and isinstance(data_result, list):
+            fields_requested = query.get("fields", [])
+            populated_mappings = self._get_populated_field_mappings(query["populate"])
+
+            for doc in data_result:
+                for populated_field, original_id_field in populated_mappings.items():
+                    # If it's a reserved audit field (starts with _original_), always remove the temp field
+                    if original_id_field.startswith("_original_"):
+                        if original_id_field in doc:
+                            del doc[original_id_field]
+                    # For normal relations, only remove if not explicitly requested in fields
+                    else:
+                        if original_id_field not in fields_requested:
+                            if original_id_field in doc:
+                                del doc[original_id_field]
+
         return {"data": data_result, "meta": meta_result}
 
+    def get_reserved_field_lookup(self, field_name: str) -> List[Dict[str, Any]]:
+        """
+        Generate lookup pipeline for reserved audit fields (creation_user, modification_user).
+
+        This allows automatic population of audit fields without needing to define them
+        in the relations list, following the Strapi philosophy of on-demand loading.
+
+        Args:
+            field_name: Name of the reserved field (e.g., "creation_user")
+
+        Returns:
+            List of aggregation stages for the lookup, or None if not a reserved field
+        """
+        if field_name not in RESERVED_AUDIT_FIELDS:
+            return None
+
+        field_config = RESERVED_AUDIT_FIELDS[field_name]
+
+        lookup_pipeline = [
+            # Save the original ID before lookup (will be removed during sanitization)
+            {
+                "$addFields": {
+                    f"_original_{field_config['field_name']}": f"${field_config['field_name']}"
+                }
+            },
+            {
+                "$lookup": {
+                    "from": field_config["collection"],
+                    "let": {"userId": f"${field_config['field_name']}"},
+                    "pipeline": [
+                        {
+                            "$match": {
+                                "$expr": {"$eq": ["$_id", {"$toObjectId": "$$userId"}]}
+                            }
+                        },
+                        {"$project": field_config["project_exclude"]},
+                        {"$addFields": {"_id": {"$toString": "$_id"}}},
+                    ],
+                    "as": field_config["alias"],
+                }
+            },
+            {
+                "$unwind": {
+                    "path": f"${field_config['alias']}",
+                    "preserveNullAndEmptyArrays": True,
+                }
+            },
+        ]
+
+        return lookup_pipeline
+
     def get_lookup_relation(self, relation_field: List[str]) -> tuple:
         """Get lookup relation configuration for a specific relation field"""
         _prefix = self.collection_prefix + "_"
@@ -768,85 +937,44 @@ class QueryBuilder:
         if len(relation_field) > 4 and relation_field[4]:
             _as = relation_field[4]
 
-        if relation_field[0] == "Users":
-            lookup_relation = [
-                {
-                    "$lookup": {
-                        "from": "users",
-                        "let": {"usersId": "$person"},
-                        "pipeline": [
-                            {
-                                "$match": {
-                                    "$expr": {
-                                        "$eq": [
-                                            "$_id",
-                                            {"$toObjectId": "$$usersId"},
-                                        ]
-                                    }
-                                }
-                            },
-                            {
-                                "$project": {
-                                    "role": 0,
-                                    "hashed_password": 0,
-                                    "id": 0,
-                                    "avatar": 0,
-                                    "active_directory": 0,
-                                    "privacy_policy": 0,
-                                    "terms_condition": 0,
-                                    "privacy_policy_date": 0,
-                                    "terms_condition_date": 0,
-                                    "disabled": 0,
-                                    "username": 0,
-                                    "establishment_asignation_ids": 0,
-                                    "establishment_type_ids": 0,
-                                    "permission_by_establishment": 0,
-                                    "permission_by_establishment_type": 0,
-                                    "terms_condition_date": 0,
-                                    "establishment_ids": 0,
-                                    "establishment_active_id": 0,
-                                }
-                            },
-                            {"$addFields": {"_id": {"$toString": "$_id"}}},
-                        ],
-                        "as": "person",
-                    }
-                },
-                {
-                    "$unwind": {
-                        "path": "$person",
-                        "preserveNullAndEmptyArrays": True,
-                    }
-                },
-            ]
+        # Agregar protección $ifNull para arrays
+        if "_ids" in relation_field_name:
+            let_value = {"lid": {"$ifNull": [f"${relation_field_name}", []]}}
         else:
-            lookup_relation = [
-                {
-                    "$lookup": {
-                        "from": f"{_prefix}{collection_name_relation}",
-                        "let": {"lid": f"${relation_field_name}"},
-                        "pipeline": [
-                            {"$addFields": {"_id": {"$toString": "$_id"}}},
-                            match_stage,
-                            {
-                                "$project": {
-                                    "creation_user": 0,
-                                    "creation_date": 0,
-                                    "disable": 0,
-                                }
-                            },
-                        ],
-                        "as": _as,
-                    },
+            let_value = {"lid": f"${relation_field_name}"}
+
+        # Save the original ID field before lookup (will be sanitized unless requested in fields)
+        lookup_relation = [
+            {
+                "$addFields": {
+                    f"_original_{relation_field_name}": f"${relation_field_name}"
+                }
+            },
+            {
+                "$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,
+                            }
+                        },
+                    ],
+                    "as": _as,
                 },
-                {"$unwind": {"path": f"${_as}", "preserveNullAndEmptyArrays": True}},
-            ]
+            },
+        ]
 
         if not "_ids" in relation_field_name:
             lookup_relation.append(
                 {
                     "$unwind": {
-                        "path": f"${collection_name_relation}",
+                        "path": f"${_as}",
                         "preserveNullAndEmptyArrays": True,
                     }
                 }
@@ -860,6 +988,13 @@ class QueryBuilder:
 
         if isinstance(query_relations, list):
             for query_relation in query_relations:
+                # Check if it's a reserved field first
+                if query_relation in RESERVED_AUDIT_FIELDS:
+                    reserved_lookup = self.get_reserved_field_lookup(query_relation)
+                    if reserved_lookup:
+                        query_lookup_relations.extend(reserved_lookup)
+                        continue
+
                 for relation in self.relations:
                     relation_name = relation[1]
                     if re.search(r"_ids$", relation_name):
@@ -876,6 +1011,14 @@ class QueryBuilder:
                         ]
         if isinstance(query_relations, dict):
             for query_relation in query_relations.keys():
+                # Check if it's a reserved field first
+                if query_relation in RESERVED_AUDIT_FIELDS:
+                    if query_relations[query_relation] == True:
+                        reserved_lookup = self.get_reserved_field_lookup(query_relation)
+                        if reserved_lookup:
+                            query_lookup_relations.extend(reserved_lookup)
+                            continue
+
                 for relation in self.relations:
                     relation_name = relation[1]
                     if re.search(r"_ids$", relation_name):
@@ -927,11 +1070,17 @@ class QueryBuilder:
         if len(relation_field) > 4 and relation_field[4]:
             _as = relation_field[4]
 
+        # Agregar protección $ifNull para arrays
+        if "_ids" in relation_field_name:
+            let_value = {"lid": {"$ifNull": [f"${relation_field_name}", []]}}
+        else:
+            let_value = {"lid": f"${relation_field_name}"}
+
         lookup_relation = [
             {
                 "$lookup": {
                     "from": f"{_prefix}{collection_name_relation}",
-                    "let": {"lid": f"${relation_field_name}"},
+                    "let": let_value,
                     "pipeline": [
                         {"$addFields": {"_id": {"$toString": "$_id"}}},
                         match_stage,
@@ -945,7 +1094,7 @@ class QueryBuilder:
             lookup_relation.append(
                 {
                     "$unwind": {
-                        "path": f"${collection_name_relation}",
+                        "path": f"${_as}",
                         "preserveNullAndEmptyArrays": True,
                     }
                 }

{oplnk_python_utils-1.1.9 → oplnk_python_utils-1.2.1/oplnk_python_utils.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oplnk-python-utils
-Version: 1.1.9
+Version: 1.2.1
 Summary: Reusable utilities for caching, data manipulation, parsing, and MongoDB query building
 Home-page: https://github.com/openlinkspa/oplnk-python-utils
 Author: OpenLink SpA
@@ -623,6 +623,93 @@ relations = [
 ]
 ```
 
+### Reserved Audit Fields (v1.2.1)
+
+The QueryBuilder automatically handles common audit fields without requiring manual configuration:
+
+```python
+# No need to define these in relations anymore:
+query_builder = QueryBuilder(
+    collection_prefix="myapp",
+    relations=[
+        # creation_user and modification_user are automatically handled!
+        ["User", "user_id", "myapp", "users"],
+    ]
+)
+
+# Usage - just populate them:
+query = {
+    "populate": ["creation_user", "modification_user"]
+}
+
+# Result will include (original ID automatically removed, replaced by populated object):
+# {
+#     "data": [{
+#         "_id": "123",
+#         "creation_user": {  // Replaces the original ID field
+#             "_id": "user_id_string",
+#             "name": "John Doe",
+#             "person": "person_id"
+#         }
+#     }]
+# }
+```
+
+**Reserved fields:**
+
+-  `creation_user` → automatically populated, original ID is excluded
+-  `modification_user` → automatically populated, original ID is excluded
+
+These fields are only populated when explicitly requested via the `populate` parameter, following the Strapi philosophy of on-demand loading.
+
+### Populate Field Sanitization (v1.2.1)
+
+By default, when you populate a relation, the original ID field is automatically removed from the response (Strapi-like behavior):
+
+```python
+# Request with populate - establishment_id will be automatically excluded:
+query = {
+    "populate": ["establishment"]
+}
+
+# Response - establishment_id is not present:
+# {
+#     "data": [{
+#         "_id": "123",
+#         "name": "Product",
+#         "establishment": {  // Populated object replaces the ID
+#             "_id": "est_123",
+#             "name": "Main Office"
+#         }
+#         // establishment_id is NOT here
+#     }]
+# }
+```
+
+**To keep both the ID and populated object, explicitly request it in `fields`:**
+
+```python
+query = {
+    "populate": ["establishment"],
+    "fields": ["name", "establishment_id"]  # Request the ID explicitly
+}
+
+# Response - both ID and populated object are present:
+# {
+#     "data": [{
+#         "_id": "123",
+#         "name": "Product",
+#         "establishment_id": "est_123",  // Now included
+#         "establishment": {
+#             "_id": "est_123",
+#             "name": "Main Office"
+#         }
+#     }]
+# }
+```
+
+**For audit fields:** The original ID is always excluded (no option to keep it, since there's no `creation_user_id` field).
+
 ### Custom Pipelines
 
 ```python

{oplnk_python_utils-1.1.9 → oplnk_python_utils-1.2.1}/setup.py

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