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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oplnk-python-utils
-Version: 1.1.8
+Version: 1.2.0
 Summary: Reusable utilities for caching, data manipulation, parsing, and MongoDB query building
 Home-page: https://github.com/openlinkspa/oplnk-python-utils
 Author: OpenLink SpA
@@ -623,6 +623,45 @@ relations = [
 ]
 ```
 
+### Reserved Audit Fields (NEW in v1.2.0)
+
+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:
+# {
+#     "data": [{
+#         "_id": "123",
+#         "creation_user": "user_id_string",
+#         "creation_user_info": {  // Automatically populated
+#             "_id": "user_id_string",
+#             "name": "John Doe",
+#             "person": "person_id"
+#         }
+#     }]
+# }
+```
+
+**Reserved fields:**
+- `creation_user` → populated as `creation_user_info`
+- `modification_user` → populated as `modification_user_info`
+
+These fields are only populated when explicitly requested via the `populate` parameter, following the Strapi philosophy of on-demand loading.
+
 ### Custom Pipelines
 
 ```python

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

@@ -581,6 +581,45 @@ relations = [
 ]
 ```
 
+### Reserved Audit Fields (NEW in v1.2.0)
+
+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:
+# {
+#     "data": [{
+#         "_id": "123",
+#         "creation_user": "user_id_string",
+#         "creation_user_info": {  // Automatically populated
+#             "_id": "user_id_string",
+#             "name": "John Doe",
+#             "person": "person_id"
+#         }
+#     }]
+# }
+```
+
+**Reserved fields:**
+- `creation_user` → populated as `creation_user_info`
+- `modification_user` → populated as `modification_user_info`
+
+These fields are only populated when explicitly requested via the `populate` parameter, following the Strapi philosophy of on-demand loading.
+
 ### Custom Pipelines
 
 ```python

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

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

{oplnk_python_utils-1.1.8 → oplnk_python_utils-1.2.0}/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_info",
+        "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_info",
+        "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:
     """
@@ -743,6 +802,51 @@ class QueryBuilder:
 
         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 = [
+            {
+                "$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 +872,38 @@ 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}"}
+
+        lookup_relation = [
+            {
+                "$lookup": {
+                    "from": f"{_prefix}{collection_name_relation}",
+                    "let": let_value,
+                    "pipeline": [
+                        {"$addFields": {"_id": {"$toString": "$_id"}}},
+                        match_stage,
+                        {
+                            "$project": {
+                                "creation_user": 0,
+                                "creation_date": 0,
+                                "disable": 0,
+                            }
+                        },
+                    ],
+                    "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 +917,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 +940,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 +999,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 +1023,7 @@ class QueryBuilder:
             lookup_relation.append(
                 {
                     "$unwind": {
-                        "path": f"${collection_name_relation}",
+                        "path": f"${_as}",
                         "preserveNullAndEmptyArrays": True,
                     }
                 }
@@ -1020,15 +1098,47 @@ class QueryBuilder:
 
         if "filters" in query:
             if not pipeline:
-                lookup_filters = {
-                    field: value
-                    for field, value in query["filters"].items()
-                    if list(value.keys())[0][0] != "$"
-                }
-
-                if list(lookup_filters.keys()):
+                # Extract potential relation field names from filters, supporting
+                # logical operators ($or/$and) and dot-notation (e.g., "company.name").
+                def extract_relation_candidates(filters_dict):
+                    relation_names = set()
+
+                    def walk(node):
+                        if isinstance(node, dict):
+                            for k, v in node.items():
+                                if k in ("$or", "$and"):
+                                    # Value can be a list of conditions or a nested dict
+                                    if isinstance(v, list):
+                                        for item in v:
+                                            walk(item)
+                                    else:
+                                        walk(v)
+                                else:
+                                    # Field key: take root before dot and strip _id/_ids
+                                    if (
+                                        isinstance(k, str)
+                                        and k
+                                        and not k.startswith("$")
+                                    ):
+                                        root = k.split(".")[0]
+                                        root = re.sub(r"(_ids|_id)$", "", root)
+                                        if root:
+                                            relation_names.add(root)
+                                    # Continue walking nested structures like
+                                    # {"company": {"name": {"$containsi": "x"}}}
+                                    walk(v)
+                        elif isinstance(node, list):
+                            for item in node:
+                                walk(item)
+                        # Primitives are ignored
+
+                    walk(filters_dict)
+                    return list(relation_names)
+
+                relation_candidates = extract_relation_candidates(query["filters"])
+                if relation_candidates:
                     populate_from_filters = self.get_count_lookup_relations(
-                        list(lookup_filters.keys())
+                        relation_candidates
                     )
                     pipeline.extend(populate_from_filters)
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oplnk-python-utils
-Version: 1.1.8
+Version: 1.2.0
 Summary: Reusable utilities for caching, data manipulation, parsing, and MongoDB query building
 Home-page: https://github.com/openlinkspa/oplnk-python-utils
 Author: OpenLink SpA
@@ -623,6 +623,45 @@ relations = [
 ]
 ```
 
+### Reserved Audit Fields (NEW in v1.2.0)
+
+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:
+# {
+#     "data": [{
+#         "_id": "123",
+#         "creation_user": "user_id_string",
+#         "creation_user_info": {  // Automatically populated
+#             "_id": "user_id_string",
+#             "name": "John Doe",
+#             "person": "person_id"
+#         }
+#     }]
+# }
+```
+
+**Reserved fields:**
+- `creation_user` → populated as `creation_user_info`
+- `modification_user` → populated as `modification_user_info`
+
+These fields are only populated when explicitly requested via the `populate` parameter, following the Strapi philosophy of on-demand loading.
+
 ### Custom Pipelines
 
 ```python

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

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