mongo-pipebuilder 0.2.3__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.2.3"
+__version__ = "0.3.1"
 __all__ = ["PipelineBuilder"]
 

mongo_pipebuilder/builder.py

@@ -6,6 +6,10 @@ 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
 
 # For compatibility with Python < 3.11
@@ -187,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
@@ -753,6 +780,183 @@ class PipelineBuilder:
         self._stages.insert(position, stage)
         return self
 
+    def get_stage_at(self, index: int) -> Dict[str, Any]:
+        """
+        Get a specific stage from the pipeline by index.
+        
+        Args:
+            index: Zero-based index of the stage to retrieve
+            
+        Returns:
+            Dictionary representing the stage at the given index
+            
+        Raises:
+            IndexError: If index is out of range
+            
+        Example:
+            >>> builder = PipelineBuilder()
+            >>> builder.match({"status": "active"}).limit(10)
+            >>> stage = builder.get_stage_at(0)
+            >>> stage
+            {"$match": {"status": "active"}}
+        """
+        if index < 0 or index >= len(self._stages):
+            raise IndexError(
+                f"Index {index} out of range [0, {len(self._stages)}]"
+            )
+        # 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:
+        """
+        Return a formatted JSON string representation of the pipeline.
+        
+        Useful for debugging and understanding pipeline structure.
+        
+        Args:
+            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 pipeline
+            
+        Example:
+            >>> builder = PipelineBuilder()
+            >>> builder.match({"status": "active"}).limit(10)
+            >>> print(builder.pretty_print())
+            [
+              {
+                "$match": {
+                  "status": "active"
+                }
+              },
+              {
+                "$limit": 10
+              }
+            ]
+        """
+        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],
+        indent: int = 2,
+        ensure_ascii: bool = False,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Save the pipeline to a JSON file.
+        
+        Useful for debugging, comparison with other pipelines, or versioning.
+        
+        Args:
+            filepath: Path to the output JSON file (str or Path)
+            indent: Number of spaces for indentation (default: 2)
+            ensure_ascii: If False, non-ASCII characters are output as-is (default: False)
+            metadata: Optional metadata to include in the JSON file
+            
+        Raises:
+            IOError: If file cannot be written
+            
+        Example:
+            >>> builder = PipelineBuilder()
+            >>> builder.match({"status": "active"}).limit(10)
+            >>> builder.to_json_file("debug_pipeline.json")
+            
+            >>> # With metadata
+            >>> builder.to_json_file(
+            ...     "pipeline.json",
+            ...     metadata={"version": "1.0", "author": "developer"}
+            ... )
+        """
+        filepath = Path(filepath)
+        filepath.parent.mkdir(parents=True, exist_ok=True)
+        
+        output: Dict[str, Any] = {
+            "pipeline": self._stages,
+        }
+        if metadata:
+            output["metadata"] = metadata
+        
+        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.2.3.dist-info → mongo_pipebuilder-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mongo-pipebuilder
-Version: 0.2.3
+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": {...}}]
 ```
@@ -297,6 +297,74 @@ builder.add_stage({"$out": "output"}).match({"status": "active"})
 builder.validate()  # Raises ValueError: $out stage must be the last stage
 ```
 
+##### `get_stage_at(index: int) -> Dict[str, Any]`
+
+Gets a specific stage from the pipeline by index. Returns a copy of the stage.
+
+```python
+builder = PipelineBuilder()
+builder.match({"status": "active"}).limit(10)
+stage = builder.get_stage_at(0)  # Returns {"$match": {"status": "active"}}
+```
+
+##### `pretty_print(indent: int = 2, ensure_ascii: bool = False) -> str`
+
+Returns a formatted JSON string representation of the pipeline. Useful for debugging.
+
+```python
+builder = PipelineBuilder()
+builder.match({"status": "active"}).limit(10)
+print(builder.pretty_print())
+# [
+#   {
+#     "$match": {
+#       "status": "active"
+#     }
+#   },
+#   {
+#     "$limit": 10
+#   }
+# ]
+```
+
+##### `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.
+
+```python
+builder = PipelineBuilder()
+builder.match({"status": "active"}).limit(10)
+
+# Basic usage
+builder.to_json_file("debug_pipeline.json")
+
+# With metadata
+builder.to_json_file(
+    "pipeline.json",
+    metadata={"version": "1.0", "author": "developer"}
+)
+```
+
+##### `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.
@@ -452,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
@@ -544,3 +640,14 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 
 
+
+
+
+
+
+
+
+
+
+
+

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.2.3.dist-info → mongo_pipebuilder-0.3.1.dist-info}/licenses/LICENSE

@@ -25,3 +25,14 @@ SOFTWARE.
 
 
 
+
+
+
+
+
+
+
+
+
+
+

mongo_pipebuilder-0.2.3.dist-info/RECORD

@@ -1,7 +0,0 @@
-mongo_pipebuilder/__init__.py,sha256=82PaAyv4VoEvfvVhlYnMTPnZEMiOI24Q4Nw9RSrEjdA,336
-mongo_pipebuilder/builder.py,sha256=GivmjNqk2K5v3fX1TWMFFH7jx3WxlWWhlggWoRxCNl4,26875
-mongo_pipebuilder-0.2.3.dist-info/licenses/LICENSE,sha256=ITJa-Zkh2Qc1_xRiHcfkL5zsmTicbSxqsMih4cjtBM4,1093
-mongo_pipebuilder-0.2.3.dist-info/METADATA,sha256=eh6i_U365QAqWhERNAsFOgEVpjokTt4VEEJH8SqDAtA,14661
-mongo_pipebuilder-0.2.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-mongo_pipebuilder-0.2.3.dist-info/top_level.txt,sha256=wLn7H_v-qaNIws5FeBbKPZBCmYFYgFEhPaLjoCWcisc,18
-mongo_pipebuilder-0.2.3.dist-info/RECORD,,