mongo-pipebuilder 0.3.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

mongo_pipebuilder/__init__.py

@@ -9,6 +9,6 @@ Author: seligoroff
 
 from mongo_pipebuilder.builder import PipelineBuilder
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 __all__ = ["PipelineBuilder"]
 

mongo_pipebuilder/builder.py

@@ -6,6 +6,8 @@ Builder Pattern implementation for safe construction of MongoDB aggregation pipe
 
 Author: seligoroff
 """
+import copy
+import difflib
 import json
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Union
@@ -189,6 +191,29 @@ class PipelineBuilder:
         """
         if not isinstance(accumulators, dict):
             raise TypeError(f"accumulators must be a dict, got {type(accumulators)}")
+
+        # Guard against a common mistake: passing {"_id": ...} as group_by.
+        # group_by should be the expression that becomes the $group _id.
+        # If users pass {"_id": expr}, MongoDB will create nested _id and later
+        # expressions like $first: "$_id" may fail because $_id becomes an object.
+        if isinstance(group_by, dict) and set(group_by.keys()) == {"_id"}:
+            inner = group_by["_id"]
+            raise ValueError(
+                "Invalid group_by: you passed a dict wrapper {'_id': ...} to PipelineBuilder.group().\n"
+                "PipelineBuilder.group(group_by=...) expects the expression that becomes $group._id.\n"
+                "\n"
+                "Did you mean one of these?\n"
+                f"- builder.group(group_by={inner!r}, accumulators=...)\n"
+                f"- builder.group(group_by={inner!r}, accumulators={{...}})  # same, explicit\n"
+                "\n"
+                "Examples:\n"
+                "- Array _id: builder.group(group_by=['$idSeason', '$idTournament'], accumulators={...})\n"
+                "- Field path: builder.group(group_by='$category', accumulators={...})\n"
+                "- Composite key: builder.group(group_by={'category': '$category'}, accumulators={...})\n"
+                "\n"
+                "Why this matters: {'_id': expr} would create a nested _id object in MongoDB, and later\n"
+                "operators like $first/$last on '$_id' may fail with: \"$first's argument must be an array, but is object\"."
+            )
         
         # Validate empty cases
         # group_by can be None, empty string, empty dict, etc. - all are valid in MongoDB
@@ -779,7 +804,8 @@ class PipelineBuilder:
             raise IndexError(
                 f"Index {index} out of range [0, {len(self._stages)}]"
             )
-        return self._stages[index].copy()
+        # Return a deep copy so callers can safely mutate nested structures
+        return copy.deepcopy(self._stages[index])
 
     def pretty_print(self, indent: int = 2, ensure_ascii: bool = False) -> str:
         """
@@ -811,6 +837,36 @@ class PipelineBuilder:
         """
         return json.dumps(self._stages, indent=indent, ensure_ascii=ensure_ascii)
 
+    def pretty_print_stage(
+        self,
+        stage: Union[int, Dict[str, Any]],
+        indent: int = 2,
+        ensure_ascii: bool = False,
+    ) -> str:
+        """
+        Return a formatted JSON string representation of a single stage.
+
+        Args:
+            stage: Stage index (0-based) or a stage dict
+            indent: Number of spaces for indentation (default: 2)
+            ensure_ascii: If False, non-ASCII characters are output as-is (default: False)
+
+        Returns:
+            Formatted JSON string of the stage
+
+        Raises:
+            TypeError: If stage is not an int or dict
+            IndexError: If stage is an int out of range
+        """
+        if isinstance(stage, int):
+            stage_dict = self.get_stage_at(stage)
+        elif isinstance(stage, dict):
+            stage_dict = copy.deepcopy(stage)
+        else:
+            raise TypeError(f"stage must be an int index or a dict, got {type(stage)}")
+
+        return json.dumps(stage_dict, indent=indent, ensure_ascii=ensure_ascii)
+
     def to_json_file(
         self,
         filepath: Union[str, Path],
@@ -855,6 +911,52 @@ class PipelineBuilder:
         with open(filepath, "w", encoding="utf-8") as f:
             json.dump(output, f, indent=indent, ensure_ascii=ensure_ascii)
 
+    def compare_with(self, other: "PipelineBuilder", context_lines: int = 3) -> str:
+        """
+        Compare this pipeline with another pipeline and return a unified diff.
+        
+        This is useful when migrating legacy pipelines (e.g., templates) to builder code.
+        
+        Args:
+            other: Another PipelineBuilder instance to compare with
+            context_lines: Number of context lines in the unified diff (default: 3)
+        
+        Returns:
+            Unified diff as a string. Returns "No differences." if pipelines are identical.
+        
+        Raises:
+            TypeError: If other is not a PipelineBuilder
+            ValueError: If context_lines is negative
+        
+        Example:
+            >>> legacy = PipelineBuilder().match({"a": 1})
+            >>> new = PipelineBuilder().match({"a": 2})
+            >>> print(new.compare_with(legacy))
+        """
+        if not isinstance(other, PipelineBuilder):
+            raise TypeError(f"other must be a PipelineBuilder, got {type(other)}")
+        if not isinstance(context_lines, int):
+            raise TypeError(f"context_lines must be an int, got {type(context_lines)}")
+        if context_lines < 0:
+            raise ValueError("context_lines cannot be negative")
+
+        a = json.dumps(
+            self.build(),
+            indent=2,
+            ensure_ascii=False,
+            sort_keys=True,
+        ).splitlines(keepends=True)
+        b = json.dumps(
+            other.build(),
+            indent=2,
+            ensure_ascii=False,
+            sort_keys=True,
+        ).splitlines(keepends=True)
+
+        diff = difflib.unified_diff(a, b, fromfile="new", tofile="other", n=context_lines)
+        out = "".join(diff)
+        return out if out else "No differences."
+
     def build(self) -> List[Dict[str, Any]]:
         """
         Return the completed pipeline.

{mongo_pipebuilder-0.3.0.dist-info → mongo_pipebuilder-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mongo-pipebuilder
-Version: 0.3.0
+Version: 0.3.1
 Summary: Type-safe, fluent MongoDB aggregation pipeline builder
 Author-email: seligoroff <seligoroff@gmail.com>
 License: MIT
@@ -252,7 +252,7 @@ builder.prepend({"$match": {"deleted": False}})
 Inserts a stage at a specific position (0-based index) in the pipeline.
 
 ```python
-builder.match({"status": "active"}).group({"_id": "$category"}, {"count": {"$sum": 1}})
+builder.match({"status": "active"}).group("$category", {"count": {"$sum": 1}})
 builder.insert_at(1, {"$sort": {"name": 1}})
 # Pipeline: [{"$match": {...}}, {"$sort": {...}}, {"$group": {...}}]
 ```
@@ -327,6 +327,15 @@ print(builder.pretty_print())
 # ]
 ```
 
+##### `pretty_print_stage(stage: Union[int, Dict[str, Any]], indent: int = 2, ensure_ascii: bool = False) -> str`
+
+Returns a formatted JSON string representation of a single stage (by index or by dict).
+
+```python
+builder = PipelineBuilder().match({"status": "active"}).limit(10)
+print(builder.pretty_print_stage(0))  # Prints the $match stage
+```
+
 ##### `to_json_file(filepath: Union[str, Path], indent: int = 2, ensure_ascii: bool = False, metadata: Optional[Dict[str, Any]] = None) -> None`
 
 Saves the pipeline to a JSON file. Useful for debugging, comparison, or versioning.
@@ -345,6 +354,17 @@ builder.to_json_file(
 )
 ```
 
+##### `compare_with(other: PipelineBuilder, context_lines: int = 3) -> str`
+
+Returns a unified diff between two pipelines (useful for comparing “new” builder pipelines vs legacy/template pipelines).
+
+```python
+legacy = PipelineBuilder().match({"status": "active"}).limit(10)
+new = PipelineBuilder().match({"status": "inactive"}).limit(10)
+
+print(new.compare_with(legacy))
+```
+
 ##### `build() -> List[Dict[str, Any]]`
 
 Returns the complete pipeline as a list of stage dictionaries.
@@ -500,11 +520,39 @@ base = get_base_pipeline(user_id)
 # Create multiple queries from cached base
 recent = base.copy().sort({"createdAt": -1}).limit(10).build()
 by_category = base.copy().match({"category": "tech"}).build()
-with_stats = base.copy().group({"_id": "$category"}, {"count": {"$sum": 1}}).build()
+with_stats = base.copy().group("$category", {"count": {"$sum": 1}}).build()
 
 # Base pipeline is safely cached and reused
 ```
 
+## Best Practices
+
+### Array `_id` after `$group`: prefer `$arrayElemAt` and materialize fields
+
+If you use `$group` with an array `_id` (e.g. `["_idSeason", "_idTournament"]`), avoid relying on `$_id` later in the pipeline.
+Instead, **extract elements with `$arrayElemAt` and store them into explicit fields**, then use those fields in subsequent stages.
+
+```python
+pipeline = (
+    PipelineBuilder()
+    .group(
+        group_by=["$idSeason", "$idTournament"],
+        accumulators={"idTeams": {"$addToSet": "$idTeam"}},
+    )
+    .project({
+        "idSeason": {"$arrayElemAt": ["$_id", 0]},
+        "idTournament": {"$arrayElemAt": ["$_id", 1]},
+        "idTeams": 1,
+        # Optional: preserve array _id explicitly if you really need it later
+        # "_id": "$_id",
+    })
+    .build()
+)
+```
+
+This pattern reduces surprises and helps avoid errors like:
+`$first's argument must be an array, but is object`.
+
 #### Example: Pipeline Factories
 
 ```python

mongo_pipebuilder-0.3.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+mongo_pipebuilder/__init__.py,sha256=dvekji4j1j9v5MzJOJIqyO2znWVia1opBn8Y1Sc_Y3k,336
+mongo_pipebuilder/builder.py,sha256=Fz7oUiB9FpqnIwnGgamof2ZEBaUGjfYSuB7mYCJO9Qc,34731
+mongo_pipebuilder-0.3.1.dist-info/licenses/LICENSE,sha256=-ZkZpDLHDQAc-YBIojJ6eDsMwxwx5pRuQz3RHnl9Y8w,1104
+mongo_pipebuilder-0.3.1.dist-info/METADATA,sha256=hYFQkwz1xtJK-MPAV2Vp4PuwKLvC7CLc5U-emp4yOzw,17478
+mongo_pipebuilder-0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mongo_pipebuilder-0.3.1.dist-info/top_level.txt,sha256=wLn7H_v-qaNIws5FeBbKPZBCmYFYgFEhPaLjoCWcisc,18
+mongo_pipebuilder-0.3.1.dist-info/RECORD,,

mongo_pipebuilder-0.3.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-mongo_pipebuilder/__init__.py,sha256=pP27GA8G6dttP-gMq9uNCJoS66-cb3JJiVVdI340er4,336
-mongo_pipebuilder/builder.py,sha256=oQxRYL9ycjYCv2ErP_YHz-Uoo2pPRaRBaaaCLEsL5Mo,30286
-mongo_pipebuilder-0.3.0.dist-info/licenses/LICENSE,sha256=-ZkZpDLHDQAc-YBIojJ6eDsMwxwx5pRuQz3RHnl9Y8w,1104
-mongo_pipebuilder-0.3.0.dist-info/METADATA,sha256=KkgWrj5TD22yDj915Jrri_JftYMEpTz6hXSeHKEM7mk,15850
-mongo_pipebuilder-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-mongo_pipebuilder-0.3.0.dist-info/top_level.txt,sha256=wLn7H_v-qaNIws5FeBbKPZBCmYFYgFEhPaLjoCWcisc,18
-mongo_pipebuilder-0.3.0.dist-info/RECORD,,