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

{mongo_pipebuilder-0.3.0/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.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.0 → 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": {...}}]
 ```
@@ -299,6 +299,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.
@@ -317,6 +326,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.
@@ -472,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

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

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

{mongo_pipebuilder-0.3.0 → mongo_pipebuilder-0.3.1}/src/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-0.3.0 → mongo_pipebuilder-0.3.1}/src/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 → 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.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.0 → mongo_pipebuilder-0.3.1}/tests/test_builder_debug.py

@@ -535,3 +535,54 @@ class TestPipelineBuilderDebugMethods:
         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.3.0 → 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()

{mongo_pipebuilder-0.3.0 → 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."""