oplnk-python-utils 1.2.1__py3-none-any.whl → 1.2.3__py3-none-any.whl

oplnk_python_utils/__init__.py

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

oplnk_python_utils/query/query_builder.py

@@ -21,7 +21,7 @@ RESERVED_AUDIT_FIELDS = {
     "creation_user": {
         "collection": "users",
         "field_name": "creation_user",
-        "alias": "creation_user",
+        "alias": "creation_user_info",
         "field_type": "id",
         "project_exclude": {
             "role": 0,
@@ -49,7 +49,7 @@ RESERVED_AUDIT_FIELDS = {
     "modification_user": {
         "collection": "users",
         "field_name": "modification_user",
-        "alias": "modification_user",
+        "alias": "modification_user_info",
         "field_type": "id",
         "project_exclude": {
             "role": 0,
@@ -778,47 +778,46 @@ class QueryBuilder:
 
         return pipeline_copy
 
-    def _get_populated_field_mappings(self, query_populate: Any) -> Dict[str, str]:
+    def _get_populated_fields_list(self, query_populate: Any) -> List[str]:
         """
-        Build a mapping of populated field names to their original ID field names.
+        Get list of field names that are being populated.
 
-        For example: {"establishment": "establishment_id", "creation_user": "_original_creation_user"}
+        For example: ["establishment", "creation_user"]
 
         Args:
             query_populate: The populate parameter (list or dict)
 
         Returns:
-            Dict mapping populated field names to their original ID fields
+            List of field names being populated
         """
-        mappings = {}
+        populated = []
 
         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
+            populated = query_populate
         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
+            populated = list(query_populate.keys())
+
+        return populated
+
+    def _get_id_field_for_relation(self, relation_name: str) -> Optional[str]:
+        """
+        Get the ID field name for a given relation.
 
-        return mappings
+        For example: "establishment" -> "establishment_id"
+
+        Args:
+            relation_name: The relation name (e.g., "establishment")
+
+        Returns:
+            The ID field name (e.g., "establishment_id") or None if not found
+        """
+        for relation in self.relations:
+            field_name = relation[1]
+            # Remove _id or _ids suffix to get base name
+            base_name = field_name.replace("_ids", "").replace("_id", "")
+            if base_name == relation_name:
+                return field_name
+        return None
 
     def sanitize_result(
         self, query: Dict[str, Any], data_result: Any, meta_result: Any
@@ -842,22 +841,31 @@ 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
+        # Sanitize populate fields: remove original ID fields when populated (unless requested in fields)
         if "populate" in query and isinstance(data_result, list):
             fields_requested = query.get("fields", [])
-            populated_mappings = self._get_populated_field_mappings(query["populate"])
+            populated_fields = self._get_populated_fields_list(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]
+                # For audit fields: remove original if populated version exists and not requested in fields
+                for field_name, field_config in RESERVED_AUDIT_FIELDS.items():
+                    if field_name in populated_fields:
+                        # If the populated alias exists and original field is not explicitly requested
+                        if (
+                            field_config["alias"] in doc
+                            and field_name not in fields_requested
+                        ):
+                            if field_name in doc:
+                                del doc[field_name]
+
+                # For normal relations: remove original ID unless explicitly requested in fields
+                for populated_field in populated_fields:
+                    if populated_field not in RESERVED_AUDIT_FIELDS:
+                        # Try to find the ID field for this relation
+                        id_field = self._get_id_field_for_relation(populated_field)
+                        if id_field and id_field not in fields_requested:
+                            if id_field in doc:
+                                del doc[id_field]
 
         return {"data": data_result, "meta": meta_result}
 
@@ -880,12 +888,6 @@ class QueryBuilder:
         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"],
@@ -943,13 +945,7 @@ class QueryBuilder:
         else:
             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}",

{oplnk_python_utils-1.2.1.dist-info → oplnk_python_utils-1.2.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oplnk-python-utils
-Version: 1.2.1
+Version: 1.2.3
 Summary: Reusable utilities for caching, data manipulation, parsing, and MongoDB query building
 Home-page: https://github.com/openlinkspa/oplnk-python-utils
 Author: OpenLink SpA
@@ -642,11 +642,11 @@ query = {
     "populate": ["creation_user", "modification_user"]
 }
 
-# Result will include (original ID automatically removed, replaced by populated object):
+# Result will include (original ID removed, replaced by populated object):
 # {
 #     "data": [{
 #         "_id": "123",
-#         "creation_user": {  // Replaces the original ID field
+#         "creation_user_info": {  // Populated object
 #             "_id": "user_id_string",
 #             "name": "John Doe",
 #             "person": "person_id"
@@ -657,49 +657,69 @@ query = {
 
 **Reserved fields:**
 
--  `creation_user` → automatically populated, original ID is excluded
--  `modification_user` → automatically populated, original ID is excluded
+-  `creation_user` → automatically populated as `creation_user_info`, original ID is excluded
+-  `modification_user` → automatically populated as `modification_user_info`, 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):
+The behavior of original ID fields depends on whether they are being populated:
+
+#### Without populate - ID field shown as-is (from database):
 
 ```python
-# Request with populate - establishment_id will be automatically excluded:
+# No populate - field shown normally from database
+query = {
+    "fields": ["name", "establishment_id"]
+}
+
+# Response:
+# {
+#     "data": [{
+#         "_id": "123",
+#         "name": "Product",
+#         "establishment_id": "est_123"  // Shown normally
+#     }]
+# }
+```
+
+#### With populate - ID field removed by default:
+
+```python
+# With populate but no explicit fields request
 query = {
     "populate": ["establishment"]
 }
 
-# Response - establishment_id is not present:
+# Response - establishment_id automatically excluded:
 # {
 #     "data": [{
 #         "_id": "123",
 #         "name": "Product",
-#         "establishment": {  // Populated object replaces the ID
+#         "establishment": {  // Populated object
 #             "_id": "est_123",
 #             "name": "Main Office"
 #         }
-#         // establishment_id is NOT here
 #     }]
 # }
 ```
 
-**To keep both the ID and populated object, explicitly request it in `fields`:**
+#### With populate AND explicit fields request - show both:
 
 ```python
+# Request both populate and the original ID field explicitly
 query = {
     "populate": ["establishment"],
-    "fields": ["name", "establishment_id"]  # Request the ID explicitly
+    "fields": ["name", "establishment_id"]  # Explicitly request the ID
 }
 
-# Response - both ID and populated object are present:
+# Response - both are present:
 # {
 #     "data": [{
 #         "_id": "123",
 #         "name": "Product",
-#         "establishment_id": "est_123",  // Now included
+#         "establishment_id": "est_123",  // Shown because explicitly requested
 #         "establishment": {
 #             "_id": "est_123",
 #             "name": "Main Office"
@@ -708,7 +728,32 @@ query = {
 # }
 ```
 
-**For audit fields:** The original ID is always excluded (no option to keep it, since there's no `creation_user_id` field).
+#### Audit fields behavior:
+
+```python
+# Without populate - original field shown
+query = {
+    "fields": ["name", "creation_user"]
+}
+# Response:
+# { "creation_user": "user_123" }
+
+# With populate - original field removed, *_info shown instead
+query = {
+    "populate": ["creation_user"]
+}
+# Response:
+# { "creation_user_info": { "_id": "user_123", ... } }
+# Note: creation_user field is NOT shown
+
+# With populate AND explicit request for original - show both
+query = {
+    "populate": ["creation_user"],
+    "fields": ["creation_user"]  # Explicitly request the ID
+}
+# Response:
+# { "creation_user": "user_123", "creation_user_info": { "_id": "user_123", ... } }
+```
 
 ### Custom Pipelines
 

{oplnk_python_utils-1.2.1.dist-info → oplnk_python_utils-1.2.3.dist-info}/RECORD

@@ -1,4 +1,4 @@
-oplnk_python_utils/__init__.py,sha256=y5h3Ev7ozXiFlvQFoxcft0QOhznbgQBY6DaDZPeJNxg,354
+oplnk_python_utils/__init__.py,sha256=NWhzsplSiDWjvhirbjOldb804fggxDmskwnOFLs1sww,354
 oplnk_python_utils/cache/__init__.py,sha256=UtCAGUH8WinNMeh-MIOLPZeRMUn5_6Jn_QC2iKWvIN0,646
 oplnk_python_utils/cache/cache_utils.py,sha256=Ln4sRgM1UELekCfMYZdNdUVecsshaqrcoUrvHRfj4jE,8597
 oplnk_python_utils/core/__init__.py,sha256=HmT7BR9WCGcu47Bd-eMdSSTImKnzsaalzYVThgTuyMA,253
@@ -6,10 +6,10 @@ oplnk_python_utils/core/data.py,sha256=BwOIGeS4c7gGOOUcx-2RpFJsznjAtBVETRv63A_3P
 oplnk_python_utils/core/parsing.py,sha256=EdI_uQJWalXL7yen5iyQ6J5PRLgz6Xi_szWaUDOhlgQ,5190
 oplnk_python_utils/core/serialization.py,sha256=B4g3x6yGjmXySNtOHqqFrq8AlguYz4gldxCJY21UNdQ,1164
 oplnk_python_utils/query/__init__.py,sha256=dd-PRf5fkoQvAbcONumwrRveS_Ejnw-3Q0hA7ZcF6Ic,147
-oplnk_python_utils/query/query_builder.py,sha256=4V-d1hcgdU_4aiuqTuCv9WYZKeGxIUCcJY1Ji4HunJo,60300
+oplnk_python_utils/query/query_builder.py,sha256=ax78f0g_2KFXScsPs8pN97NxcT_paG6mzZDWIe7yv9w,59770
 oplnk_python_utils/reports/__init__.py,sha256=CPxWaRgXt9sHK_6mQwsXnUxg9yzJ2GHSlQ4lVNpkanY,94
-oplnk_python_utils-1.2.1.dist-info/licenses/LICENSE,sha256=JgkAUZElZ6gNf7C2aZPq5-GEjUG2t_yYAKvuhy1OKy0,1090
-oplnk_python_utils-1.2.1.dist-info/METADATA,sha256=EIMDkUX9sU7eflp7cFnZs72S4_PrmUhDs7g-BwPWjH8,24003
-oplnk_python_utils-1.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-oplnk_python_utils-1.2.1.dist-info/top_level.txt,sha256=TPZ-emvWspdR-OxTNOvQt-cDrZ4m7P4RMnxsXHOeorc,19
-oplnk_python_utils-1.2.1.dist-info/RECORD,,
+oplnk_python_utils-1.2.3.dist-info/licenses/LICENSE,sha256=JgkAUZElZ6gNf7C2aZPq5-GEjUG2t_yYAKvuhy1OKy0,1090
+oplnk_python_utils-1.2.3.dist-info/METADATA,sha256=QExNyfvgs-Dzp5zCekv41fvmDtbdsVJMZAXnjVCwhG8,24924
+oplnk_python_utils-1.2.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+oplnk_python_utils-1.2.3.dist-info/top_level.txt,sha256=TPZ-emvWspdR-OxTNOvQt-cDrZ4m7P4RMnxsXHOeorc,19
+oplnk_python_utils-1.2.3.dist-info/RECORD,,