mongo-pipebuilder 0.2.3__tar.gz → 0.3.1__tar.gz

{mongo_pipebuilder-0.2.3 → mongo_pipebuilder-0.3.1}/LICENSE

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

{mongo_pipebuilder-0.2.3/src/mongo_pipebuilder.egg-info → mongo_pipebuilder-0.3.1}/PKG-INFO

@@ -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.2.3 → mongo_pipebuilder-0.3.1}/README.md

@@ -224,7 +224,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": {...}}]
 ```
@@ -269,6 +269,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.
@@ -424,11 +492,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
@@ -516,3 +612,14 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 
 
+
+
+
+
+
+
+
+
+
+
+

{mongo_pipebuilder-0.2.3 → mongo_pipebuilder-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mongo-pipebuilder"
-version = "0.2.3"
+version = "0.3.1"
 description = "Type-safe, fluent MongoDB aggregation pipeline builder"
 readme = "README.md"
 requires-python = ">=3.8"

{mongo_pipebuilder-0.2.3 → mongo_pipebuilder-0.3.1}/src/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-0.2.3 → mongo_pipebuilder-0.3.1}/src/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 → mongo_pipebuilder-0.3.1/src/mongo_pipebuilder.egg-info}/PKG-INFO

@@ -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.2.3 → mongo_pipebuilder-0.3.1}/tests/test_builder_debug.py

@@ -5,6 +5,10 @@ Tests for methods from Proposal 2 (debug/validation) and Proposal 4 (pipeline an
 
 Author: seligoroff
 """
+import json
+import tempfile
+from pathlib import Path
+
 import pytest
 from mongo_pipebuilder import PipelineBuilder
 
@@ -289,3 +293,296 @@ class TestPipelineBuilderAnalysis:
         for stage_type in stage_types:
             assert builder.has_stage(stage_type) is True
 
+
+class TestPipelineBuilderDebugMethods:
+    """Tests for Phase 1 debug methods: pretty_print, to_json_file, get_stage_at."""
+
+    def test_get_stage_at_valid_index(self):
+        """Test get_stage_at() with valid index."""
+        builder = PipelineBuilder()
+        builder.match({"status": "active"}).limit(10).sort({"name": 1})
+        
+        stage0 = builder.get_stage_at(0)
+        assert stage0 == {"$match": {"status": "active"}}
+        
+        stage1 = builder.get_stage_at(1)
+        assert stage1 == {"$limit": 10}
+        
+        stage2 = builder.get_stage_at(2)
+        assert stage2 == {"$sort": {"name": 1}}
+
+    def test_get_stage_at_returns_copy(self):
+        """Test that get_stage_at() returns a copy, not reference."""
+        builder = PipelineBuilder()
+        builder.match({"status": "active"})
+        
+        stage = builder.get_stage_at(0)
+        stage["$match"]["new_field"] = "value"
+        
+        # Original should be unchanged
+        original_stage = builder.get_stage_at(0)
+        assert "new_field" not in original_stage["$match"]
+
+    def test_get_stage_at_invalid_index_negative(self):
+        """Test get_stage_at() raises IndexError for negative index."""
+        builder = PipelineBuilder()
+        builder.match({"status": "active"})
+        
+        with pytest.raises(IndexError, match="Index -1 out of range"):
+            builder.get_stage_at(-1)
+
+    def test_get_stage_at_invalid_index_too_large(self):
+        """Test get_stage_at() raises IndexError for index too large."""
+        builder = PipelineBuilder()
+        builder.match({"status": "active"})
+        
+        with pytest.raises(IndexError, match="Index 10 out of range"):
+            builder.get_stage_at(10)
+
+    def test_get_stage_at_empty_builder(self):
+        """Test get_stage_at() raises IndexError on empty builder."""
+        builder = PipelineBuilder()
+        
+        with pytest.raises(IndexError, match="Index 0 out of range"):
+            builder.get_stage_at(0)
+
+    def test_pretty_print_empty_builder(self):
+        """Test pretty_print() with empty builder."""
+        builder = PipelineBuilder()
+        result = builder.pretty_print()
+        
+        assert result == "[]"
+        # Should be valid JSON
+        json.loads(result)
+
+    def test_pretty_print_single_stage(self):
+        """Test pretty_print() with single stage."""
+        builder = PipelineBuilder()
+        builder.match({"status": "active"})
+        result = builder.pretty_print()
+        
+        # Should be valid JSON
+        parsed = json.loads(result)
+        assert parsed == [{"$match": {"status": "active"}}]
+        
+        # Should contain expected content
+        assert "$match" in result
+        assert "status" in result
+        assert "active" in result
+
+    def test_pretty_print_multiple_stages(self):
+        """Test pretty_print() with multiple stages."""
+        builder = PipelineBuilder()
+        builder.match({"status": "active"}).limit(10).sort({"name": 1})
+        result = builder.pretty_print()
+        
+        # Should be valid JSON
+        parsed = json.loads(result)
+        assert len(parsed) == 3
+        assert parsed[0] == {"$match": {"status": "active"}}
+        assert parsed[1] == {"$limit": 10}
+        assert parsed[2] == {"$sort": {"name": 1}}
+
+    def test_pretty_print_custom_indent(self):
+        """Test pretty_print() with custom indent."""
+        builder = PipelineBuilder()
+        builder.match({"status": "active"})
+        result = builder.pretty_print(indent=4)
+        
+        # Should be valid JSON
+        parsed = json.loads(result)
+        assert parsed == [{"$match": {"status": "active"}}]
+        
+        # Should use 4 spaces for indentation
+        lines = result.split("\n")
+        if len(lines) > 1:
+            assert lines[1].startswith("    ")  # 4 spaces
+
+    def test_pretty_print_ensure_ascii(self):
+        """Test pretty_print() with ensure_ascii=True."""
+        builder = PipelineBuilder()
+        builder.match({"name": "тест"})  # Non-ASCII characters
+        result_ascii = builder.pretty_print(ensure_ascii=True)
+        result_no_ascii = builder.pretty_print(ensure_ascii=False)
+        
+        # Both should be valid JSON
+        json.loads(result_ascii)
+        json.loads(result_no_ascii)
+        
+        # Non-ASCII version should contain original characters
+        assert "тест" in result_no_ascii
+
+    def test_to_json_file_basic(self):
+        """Test to_json_file() saves pipeline correctly."""
+        builder = PipelineBuilder()
+        builder.match({"status": "active"}).limit(10)
+        
+        with tempfile.TemporaryDirectory() as tmpdir:
+            filepath = Path(tmpdir) / "test_pipeline.json"
+            builder.to_json_file(filepath)
+            
+            # File should exist
+            assert filepath.exists()
+            
+            # Should contain valid JSON
+            with open(filepath, "r", encoding="utf-8") as f:
+                data = json.load(f)
+            
+            assert "pipeline" in data
+            assert data["pipeline"] == [
+                {"$match": {"status": "active"}},
+                {"$limit": 10}
+            ]
+
+    def test_to_json_file_with_metadata(self):
+        """Test to_json_file() with metadata."""
+        builder = PipelineBuilder()
+        builder.match({"status": "active"})
+        
+        metadata = {
+            "version": "1.0",
+            "author": "developer",
+            "description": "Test pipeline"
+        }
+        
+        with tempfile.TemporaryDirectory() as tmpdir:
+            filepath = Path(tmpdir) / "test_pipeline.json"
+            builder.to_json_file(filepath, metadata=metadata)
+            
+            with open(filepath, "r", encoding="utf-8") as f:
+                data = json.load(f)
+            
+            assert "pipeline" in data
+            assert "metadata" in data
+            assert data["metadata"] == metadata
+
+    def test_to_json_file_creates_directory(self):
+        """Test to_json_file() creates parent directories if they don't exist."""
+        builder = PipelineBuilder()
+        builder.match({"status": "active"})
+        
+        with tempfile.TemporaryDirectory() as tmpdir:
+            filepath = Path(tmpdir) / "nested" / "path" / "test_pipeline.json"
+            
+            # Directory shouldn't exist yet
+            assert not filepath.parent.exists()
+            
+            builder.to_json_file(filepath)
+            
+            # File and directory should be created
+            assert filepath.exists()
+            assert filepath.parent.exists()
+
+    def test_to_json_file_string_path(self):
+        """Test to_json_file() accepts string path."""
+        builder = PipelineBuilder()
+        builder.match({"status": "active"})
+        
+        with tempfile.TemporaryDirectory() as tmpdir:
+            filepath = str(Path(tmpdir) / "test_pipeline.json")
+            builder.to_json_file(filepath)
+            
+            assert Path(filepath).exists()
+
+    def test_to_json_file_custom_indent(self):
+        """Test to_json_file() with custom indent."""
+        builder = PipelineBuilder()
+        builder.match({"status": "active"})
+        
+        with tempfile.TemporaryDirectory() as tmpdir:
+            filepath = Path(tmpdir) / "test_pipeline.json"
+            builder.to_json_file(filepath, indent=4)
+            
+            with open(filepath, "r", encoding="utf-8") as f:
+                content = f.read()
+                lines = content.split("\n")
+                if len(lines) > 1:
+                    assert lines[1].startswith("    ")  # 4 spaces
+
+    def test_pretty_print_and_to_json_file_consistency(self):
+        """Test that pretty_print() and to_json_file() produce consistent output."""
+        builder = PipelineBuilder()
+        builder.match({"status": "active"}).limit(10)
+        
+        pretty_output = builder.pretty_print()
+        
+        with tempfile.TemporaryDirectory() as tmpdir:
+            filepath = Path(tmpdir) / "test_pipeline.json"
+            builder.to_json_file(filepath)
+            
+            with open(filepath, "r", encoding="utf-8") as f:
+                file_data = json.load(f)
+            
+            # Pipeline in file should match pretty_print output when parsed
+            pretty_parsed = json.loads(pretty_output)
+            assert file_data["pipeline"] == pretty_parsed
+
+    def test_get_stage_at_with_complex_stage(self):
+        """Test get_stage_at() with complex stage (e.g., lookup)."""
+        builder = PipelineBuilder()
+        builder.match({"status": "active"})
+        builder.lookup(
+            from_collection="users",
+            local_field="userId",
+            foreign_field="_id",
+            as_field="user"
+        )
+        
+        stage = builder.get_stage_at(1)
+        assert "$lookup" in stage
+        assert stage["$lookup"]["from"] == "users"
+        assert stage["$lookup"]["localField"] == "userId"
+        assert stage["$lookup"]["foreignField"] == "_id"
+        assert stage["$lookup"]["as"] == "user"
+
+    def test_compare_with_no_differences(self):
+        """Test compare_with() returns 'No differences.' for identical pipelines."""
+        a = PipelineBuilder().match({"status": "active"}).limit(10)
+        b = PipelineBuilder().match({"status": "active"}).limit(10)
+        assert a.compare_with(b) == "No differences."
+
+    def test_compare_with_has_diff(self):
+        """Test compare_with() returns unified diff when pipelines differ."""
+        legacy = PipelineBuilder().match({"status": "active"})
+        new = PipelineBuilder().match({"status": "inactive"})
+        diff = new.compare_with(legacy)
+        assert diff != "No differences."
+        assert "--- new" in diff
+        assert "+++ other" in diff
+        assert "\"active\"" in diff or "active" in diff
+        assert "\"inactive\"" in diff or "inactive" in diff
+
+    def test_compare_with_invalid_other_raises(self):
+        """Test compare_with() validates 'other' argument."""
+        builder = PipelineBuilder().match({"status": "active"})
+        with pytest.raises(TypeError, match="other must be a PipelineBuilder"):
+            builder.compare_with([])  # type: ignore[arg-type]
+
+    def test_compare_with_negative_context_lines_raises(self):
+        """Test compare_with() validates context_lines."""
+        a = PipelineBuilder().match({"status": "active"})
+        b = PipelineBuilder().match({"status": "inactive"})
+        with pytest.raises(ValueError, match="context_lines cannot be negative"):
+            a.compare_with(b, context_lines=-1)
+
+    def test_pretty_print_stage_by_index(self):
+        """Test pretty_print_stage() with stage index."""
+        builder = PipelineBuilder().match({"status": "active"}).limit(10)
+        s = builder.pretty_print_stage(0)
+        parsed = json.loads(s)
+        assert parsed == {"$match": {"status": "active"}}
+
+    def test_pretty_print_stage_by_dict(self):
+        """Test pretty_print_stage() with stage dict."""
+        builder = PipelineBuilder()
+        stage = {"$limit": 5}
+        s = builder.pretty_print_stage(stage, indent=4)
+        parsed = json.loads(s)
+        assert parsed == stage
+
+    def test_pretty_print_stage_invalid_type_raises(self):
+        """Test pretty_print_stage() validates stage argument."""
+        builder = PipelineBuilder().match({"status": "active"})
+        with pytest.raises(TypeError, match="stage must be an int index or a dict"):
+            builder.pretty_print_stage("0")  # type: ignore[arg-type]
+

{mongo_pipebuilder-0.2.3 → mongo_pipebuilder-0.3.1}/tests/test_builder_insert.py

@@ -95,7 +95,7 @@ class TestInsertAt:
     def test_insert_at_middle(self):
         """Test insert_at() inserts in the middle."""
         builder = PipelineBuilder()
-        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 = builder.build()
@@ -188,7 +188,7 @@ class TestInsertAt:
         builder.match({"status": "active"})
         builder.lookup("users", "userId", "_id", "user")
         builder.unwind("user")
-        builder.group({"_id": "$category"}, {"count": {"$sum": 1}})
+        builder.group("$category", {"count": {"$sum": 1}})
         
         # Insert $addFields before $group
         builder.insert_at(3, {"$addFields": {"categoryUpper": {"$toUpper": "$category"}}})
@@ -224,7 +224,7 @@ class TestPrependAndInsertAtIntegration:
         builder = PipelineBuilder()
         builder.match({"status": "active"})
         builder.lookup("users", "userId", "_id", "user")
-        builder.group({"_id": "$category"}, {"count": {"$sum": 1}})
+        builder.group("$category", {"count": {"$sum": 1}})
         
         # Find position of $group and insert before it
         stage_types = builder.get_stage_types()
@@ -257,3 +257,4 @@ class TestPrependAndInsertAtIntegration:
         assert pipeline[3] == {"$limit": 10}
 
 
+

{mongo_pipebuilder-0.2.3 → mongo_pipebuilder-0.3.1}/tests/test_builder_validation.py

@@ -176,3 +176,14 @@ class TestPipelineValidation:
 
 
 
+
+
+
+
+
+
+
+
+
+
+

{mongo_pipebuilder-0.2.3 → mongo_pipebuilder-0.3.1}/tests/test_builder_validation_existing.py

@@ -91,6 +91,12 @@ class TestGroupValidation:
         with pytest.raises(TypeError, match="accumulators must be a dict"):
             builder.group({}, 123)
 
+    def test_group_nested_id_wrapper_raises_error(self):
+        """Test that group({'_id': ...}, ...) raises ValueError with guidance."""
+        builder = PipelineBuilder()
+        with pytest.raises(ValueError, match="Invalid group_by: you passed a dict wrapper"):
+            builder.group({"_id": ["$a", "$b"]}, {"count": {"$sum": 1}})
+
 
 class TestUnwindValidation:
     """Tests for $unwind stage validation."""
@@ -201,3 +207,4 @@ class TestProjectValidation:
 
 
 
+

{mongo_pipebuilder-0.2.3 → mongo_pipebuilder-0.3.1}/tests/test_builder_validation_new.py

@@ -158,3 +158,4 @@ class TestSetFieldValidation:
 
 
 
+