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

{mongo_pipebuilder-0.2.2 → mongo_pipebuilder-0.3.0}/LICENSE

@@ -21,3 +21,18 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

{mongo_pipebuilder-0.2.2/src/mongo_pipebuilder.egg-info → mongo_pipebuilder-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mongo-pipebuilder
-Version: 0.2.2
+Version: 0.3.0
 Summary: Type-safe, fluent MongoDB aggregation pipeline builder
 Author-email: seligoroff <seligoroff@gmail.com>
 License: MIT
@@ -28,6 +28,12 @@ Dynamic: license-file
 
 # mongo-pipebuilder
 
+[![PyPI version](https://badge.fury.io/py/mongo-pipebuilder.svg)](https://badge.fury.io/py/mongo-pipebuilder)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Test Coverage](https://img.shields.io/badge/coverage-96%25-green.svg)](https://github.com/seligoroff/mongo-pipebuilder)
+
 Type-safe, fluent MongoDB aggregation pipeline builder for Python.
 
 ## Overview
@@ -36,11 +42,11 @@ Type-safe, fluent MongoDB aggregation pipeline builder for Python.
 
 ## Features
 
-- ✅ **Type-safe**: Full type hints support with IDE autocomplete
-- ✅ **Fluent interface**: Chain methods for readable, maintainable code
-- ✅ **Zero dependencies**: Pure Python, lightweight package
-- ✅ **Extensible**: Easy to add custom stages via `add_stage()`
-- ✅ **Well tested**: Comprehensive test suite with 96%+ coverage
+- **Type-safe**: Full type hints support with IDE autocomplete
+- **Fluent interface**: Chain methods for readable, maintainable code
+- **Zero dependencies**: Pure Python, lightweight package
+- **Extensible**: Easy to add custom stages via `add_stage()`
+- **Well tested**: Comprehensive test suite with 96%+ coverage
 
 ## Installation
 
@@ -259,6 +265,22 @@ group_index = stage_types.index("$group")
 builder.insert_at(group_index, {"$addFields": {"x": 1}})
 ```
 
+##### `copy() -> PipelineBuilder`
+
+Creates an independent copy of the builder with current stages. Useful for creating immutable variants and composing pipelines.
+
+```python
+builder1 = PipelineBuilder().match({"status": "active"})
+builder2 = builder1.copy()
+builder2.limit(10)
+
+# Original unchanged
+assert len(builder1) == 1
+assert len(builder2) == 2
+```
+
+See [Composing and Reusing Pipelines](#composing-and-reusing-pipelines) for practical examples.
+
 ##### `validate() -> bool`
 
 Validates the pipeline before execution. Checks that:
@@ -275,6 +297,54 @@ 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
+#   }
+# ]
+```
+
+##### `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"}
+)
+```
+
 ##### `build() -> List[Dict[str, Any]]`
 
 Returns the complete pipeline as a list of stage dictionaries.
@@ -340,6 +410,150 @@ pipeline = (
 )
 ```
 
+### Composing and Reusing Pipelines
+
+The `copy()` method allows you to create immutable variants of pipelines, enabling safe composition and reuse. This is useful when you need to:
+- Create multiple variants from a base pipeline
+- Compose pipelines functionally
+- Cache base pipelines safely
+- Pass pipelines to functions without side effects
+
+#### Example: Building Multiple Variants from a Base Pipeline
+
+```python
+from mongo_pipebuilder import PipelineBuilder
+
+# Base pipeline with common filtering and joining
+base_pipeline = (
+    PipelineBuilder()
+    .match({"status": "published", "deleted": False})
+    .lookup(
+        from_collection="authors",
+        local_field="authorId",
+        foreign_field="_id",
+        as_field="author"
+    )
+    .unwind("author", preserve_null_and_empty_arrays=True)
+    .project({
+        "title": 1,
+        "authorName": "$author.name",
+        "publishedAt": 1
+    })
+)
+
+# Create variants with different sorting and limits
+recent_posts = base_pipeline.copy().sort({"publishedAt": -1}).limit(10).build()
+popular_posts = base_pipeline.copy().sort({"views": -1}).limit(5).build()
+author_posts = base_pipeline.copy().match({"authorName": "John Doe"}).build()
+
+# Base pipeline remains unchanged
+assert len(base_pipeline) == 4  # Still has 4 stages
+```
+
+#### Example: Functional Composition Pattern
+
+```python
+def add_pagination(builder, page: int, page_size: int = 10):
+    """Add pagination to a pipeline."""
+    return builder.copy().skip(page * page_size).limit(page_size)
+
+def add_sorting(builder, sort_field: str, ascending: bool = True):
+    """Add sorting to a pipeline."""
+    return builder.copy().sort({sort_field: 1 if ascending else -1})
+
+# Compose pipelines functionally
+base = PipelineBuilder().match({"status": "active"})
+
+# Create different variants
+page1 = add_pagination(add_sorting(base, "createdAt"), page=0)
+page2 = add_pagination(add_sorting(base, "createdAt"), page=1)
+sorted_by_name = add_sorting(base, "name", ascending=True)
+
+# All variants are independent
+assert len(base) == 1  # Base unchanged
+assert len(page1) == 3  # match + sort + skip + limit
+```
+
+#### Example: Caching Base Pipelines
+
+```python
+from functools import lru_cache
+
+@lru_cache(maxsize=100)
+def get_base_pipeline(user_id: str):
+    """Cache base pipeline for a user."""
+    return (
+        PipelineBuilder()
+        .match({"userId": user_id, "status": "active"})
+        .lookup(
+            from_collection="profiles",
+            local_field="userId",
+            foreign_field="_id",
+            as_field="profile"
+        )
+    )
+
+# Reuse cached base pipeline with different modifications
+user_id = "12345"
+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()
+
+# Base pipeline is safely cached and reused
+```
+
+#### Example: Pipeline Factories
+
+```python
+class PipelineFactory:
+    """Factory for creating common pipeline patterns."""
+    
+    @staticmethod
+    def base_article_pipeline():
+        """Base pipeline for articles."""
+        return (
+            PipelineBuilder()
+            .match({"status": "published"})
+            .lookup(
+                from_collection="authors",
+                local_field="authorId",
+                foreign_field="_id",
+                as_field="author"
+            )
+        )
+    
+    @staticmethod
+    def with_author_filter(builder, author_name: str):
+        """Add author filter to pipeline."""
+        return builder.copy().match({"author.name": author_name})
+    
+    @staticmethod
+    def with_date_range(builder, start_date: str, end_date: str):
+        """Add date range filter to pipeline."""
+        return builder.copy().match({
+            "publishedAt": {"$gte": start_date, "$lte": end_date}
+        })
+
+# Usage
+base = PipelineFactory.base_article_pipeline()
+johns_articles = PipelineFactory.with_author_filter(base, "John Doe")
+recent_johns = PipelineFactory.with_date_range(
+    johns_articles, 
+    start_date="2024-01-01",
+    end_date="2024-12-31"
+).sort({"publishedAt": -1}).limit(10).build()
+```
+
+**Key Benefits:**
+- Safe reuse: Base pipelines remain unchanged
+- Functional composition: Build pipelines from smaller parts
+- Caching friendly: Base pipelines can be safely cached
+- No side effects: Functions can safely modify copies
+- Thread-safe: Multiple threads can use copies independently
+
 ## Development
 
 ### Project Structure
@@ -374,3 +588,18 @@ See [DEVELOPMENT.md](DEVELOPMENT.md) for development guidelines.
 MIT License - see [LICENSE](LICENSE) file for details.
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

{mongo_pipebuilder-0.2.2 → mongo_pipebuilder-0.3.0}/README.md

@@ -1,5 +1,11 @@
 # mongo-pipebuilder
 
+[![PyPI version](https://badge.fury.io/py/mongo-pipebuilder.svg)](https://badge.fury.io/py/mongo-pipebuilder)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Test Coverage](https://img.shields.io/badge/coverage-96%25-green.svg)](https://github.com/seligoroff/mongo-pipebuilder)
+
 Type-safe, fluent MongoDB aggregation pipeline builder for Python.
 
 ## Overview
@@ -8,11 +14,11 @@ Type-safe, fluent MongoDB aggregation pipeline builder for Python.
 
 ## Features
 
-- ✅ **Type-safe**: Full type hints support with IDE autocomplete
-- ✅ **Fluent interface**: Chain methods for readable, maintainable code
-- ✅ **Zero dependencies**: Pure Python, lightweight package
-- ✅ **Extensible**: Easy to add custom stages via `add_stage()`
-- ✅ **Well tested**: Comprehensive test suite with 96%+ coverage
+- **Type-safe**: Full type hints support with IDE autocomplete
+- **Fluent interface**: Chain methods for readable, maintainable code
+- **Zero dependencies**: Pure Python, lightweight package
+- **Extensible**: Easy to add custom stages via `add_stage()`
+- **Well tested**: Comprehensive test suite with 96%+ coverage
 
 ## Installation
 
@@ -231,6 +237,22 @@ group_index = stage_types.index("$group")
 builder.insert_at(group_index, {"$addFields": {"x": 1}})
 ```
 
+##### `copy() -> PipelineBuilder`
+
+Creates an independent copy of the builder with current stages. Useful for creating immutable variants and composing pipelines.
+
+```python
+builder1 = PipelineBuilder().match({"status": "active"})
+builder2 = builder1.copy()
+builder2.limit(10)
+
+# Original unchanged
+assert len(builder1) == 1
+assert len(builder2) == 2
+```
+
+See [Composing and Reusing Pipelines](#composing-and-reusing-pipelines) for practical examples.
+
 ##### `validate() -> bool`
 
 Validates the pipeline before execution. Checks that:
@@ -247,6 +269,54 @@ 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
+#   }
+# ]
+```
+
+##### `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"}
+)
+```
+
 ##### `build() -> List[Dict[str, Any]]`
 
 Returns the complete pipeline as a list of stage dictionaries.
@@ -312,6 +382,150 @@ pipeline = (
 )
 ```
 
+### Composing and Reusing Pipelines
+
+The `copy()` method allows you to create immutable variants of pipelines, enabling safe composition and reuse. This is useful when you need to:
+- Create multiple variants from a base pipeline
+- Compose pipelines functionally
+- Cache base pipelines safely
+- Pass pipelines to functions without side effects
+
+#### Example: Building Multiple Variants from a Base Pipeline
+
+```python
+from mongo_pipebuilder import PipelineBuilder
+
+# Base pipeline with common filtering and joining
+base_pipeline = (
+    PipelineBuilder()
+    .match({"status": "published", "deleted": False})
+    .lookup(
+        from_collection="authors",
+        local_field="authorId",
+        foreign_field="_id",
+        as_field="author"
+    )
+    .unwind("author", preserve_null_and_empty_arrays=True)
+    .project({
+        "title": 1,
+        "authorName": "$author.name",
+        "publishedAt": 1
+    })
+)
+
+# Create variants with different sorting and limits
+recent_posts = base_pipeline.copy().sort({"publishedAt": -1}).limit(10).build()
+popular_posts = base_pipeline.copy().sort({"views": -1}).limit(5).build()
+author_posts = base_pipeline.copy().match({"authorName": "John Doe"}).build()
+
+# Base pipeline remains unchanged
+assert len(base_pipeline) == 4  # Still has 4 stages
+```
+
+#### Example: Functional Composition Pattern
+
+```python
+def add_pagination(builder, page: int, page_size: int = 10):
+    """Add pagination to a pipeline."""
+    return builder.copy().skip(page * page_size).limit(page_size)
+
+def add_sorting(builder, sort_field: str, ascending: bool = True):
+    """Add sorting to a pipeline."""
+    return builder.copy().sort({sort_field: 1 if ascending else -1})
+
+# Compose pipelines functionally
+base = PipelineBuilder().match({"status": "active"})
+
+# Create different variants
+page1 = add_pagination(add_sorting(base, "createdAt"), page=0)
+page2 = add_pagination(add_sorting(base, "createdAt"), page=1)
+sorted_by_name = add_sorting(base, "name", ascending=True)
+
+# All variants are independent
+assert len(base) == 1  # Base unchanged
+assert len(page1) == 3  # match + sort + skip + limit
+```
+
+#### Example: Caching Base Pipelines
+
+```python
+from functools import lru_cache
+
+@lru_cache(maxsize=100)
+def get_base_pipeline(user_id: str):
+    """Cache base pipeline for a user."""
+    return (
+        PipelineBuilder()
+        .match({"userId": user_id, "status": "active"})
+        .lookup(
+            from_collection="profiles",
+            local_field="userId",
+            foreign_field="_id",
+            as_field="profile"
+        )
+    )
+
+# Reuse cached base pipeline with different modifications
+user_id = "12345"
+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()
+
+# Base pipeline is safely cached and reused
+```
+
+#### Example: Pipeline Factories
+
+```python
+class PipelineFactory:
+    """Factory for creating common pipeline patterns."""
+    
+    @staticmethod
+    def base_article_pipeline():
+        """Base pipeline for articles."""
+        return (
+            PipelineBuilder()
+            .match({"status": "published"})
+            .lookup(
+                from_collection="authors",
+                local_field="authorId",
+                foreign_field="_id",
+                as_field="author"
+            )
+        )
+    
+    @staticmethod
+    def with_author_filter(builder, author_name: str):
+        """Add author filter to pipeline."""
+        return builder.copy().match({"author.name": author_name})
+    
+    @staticmethod
+    def with_date_range(builder, start_date: str, end_date: str):
+        """Add date range filter to pipeline."""
+        return builder.copy().match({
+            "publishedAt": {"$gte": start_date, "$lte": end_date}
+        })
+
+# Usage
+base = PipelineFactory.base_article_pipeline()
+johns_articles = PipelineFactory.with_author_filter(base, "John Doe")
+recent_johns = PipelineFactory.with_date_range(
+    johns_articles, 
+    start_date="2024-01-01",
+    end_date="2024-12-31"
+).sort({"publishedAt": -1}).limit(10).build()
+```
+
+**Key Benefits:**
+- Safe reuse: Base pipelines remain unchanged
+- Functional composition: Build pipelines from smaller parts
+- Caching friendly: Base pipelines can be safely cached
+- No side effects: Functions can safely modify copies
+- Thread-safe: Multiple threads can use copies independently
+
 ## Development
 
 ### Project Structure
@@ -346,3 +560,18 @@ See [DEVELOPMENT.md](DEVELOPMENT.md) for development guidelines.
 MIT License - see [LICENSE](LICENSE) file for details.
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

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

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

{mongo_pipebuilder-0.2.2 → mongo_pipebuilder-0.3.0}/src/mongo_pipebuilder/__init__.py

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

{mongo_pipebuilder-0.2.2 → mongo_pipebuilder-0.3.0}/src/mongo_pipebuilder/builder.py

@@ -6,6 +6,8 @@ Builder Pattern implementation for safe construction of MongoDB aggregation pipe
 
 Author: seligoroff
 """
+import json
+from pathlib import Path
 from typing import Any, Dict, List, Optional, Union
 
 # For compatibility with Python < 3.11
@@ -33,8 +35,7 @@ class PipelineBuilder:
             Self for method chaining
             
         Raises:
-            TypeError: If conditions is not a dictionary
-            ValueError: If conditions is None
+            TypeError: If conditions is None or not a dictionary
             
         Example:
             >>> builder.match({"status": "active", "age": {"$gte": 18}})
@@ -636,23 +637,15 @@ class PipelineBuilder:
                 "Only one output stage is allowed."
             )
         
-        # If $out exists, it must be the last stage
-        if has_out:
-            out_index = stage_types.index("$out")
-            if out_index != len(stage_types) - 1:
-                raise ValueError(
-                    f"$out stage must be the last stage in the pipeline. "
-                    f"Found at position {out_index + 1} of {len(stage_types)}."
-                )
-        
-        # If $merge exists, it must be the last stage
-        if has_merge:
-            merge_index = stage_types.index("$merge")
-            if merge_index != len(stage_types) - 1:
-                raise ValueError(
-                    f"$merge stage must be the last stage in the pipeline. "
-                    f"Found at position {merge_index + 1} of {len(stage_types)}."
-                )
+        # Check if $out or $merge exist and validate position
+        for stage_name in ["$out", "$merge"]:
+            if stage_name in stage_types:
+                stage_index = stage_types.index(stage_name)
+                if stage_index != len(stage_types) - 1:
+                    raise ValueError(
+                        f"{stage_name} stage must be the last stage in the pipeline. "
+                        f"Found at position {stage_index + 1} of {len(stage_types)}."
+                    )
         
         return True
 
@@ -669,7 +662,7 @@ class PipelineBuilder:
             >>> builder.get_stage_types()
             ['$match', '$limit']
         """
-        return [list(stage.keys())[0] for stage in self._stages]
+        return [next(iter(stage)) for stage in self._stages]
 
     def has_stage(self, stage_type: str) -> bool:
         """
@@ -762,6 +755,106 @@ 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 self._stages[index].copy()
+
+    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 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 build(self) -> List[Dict[str, Any]]:
         """
         Return the completed pipeline.

{mongo_pipebuilder-0.2.2 → mongo_pipebuilder-0.3.0/src/mongo_pipebuilder.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mongo-pipebuilder
-Version: 0.2.2
+Version: 0.3.0
 Summary: Type-safe, fluent MongoDB aggregation pipeline builder
 Author-email: seligoroff <seligoroff@gmail.com>
 License: MIT
@@ -28,6 +28,12 @@ Dynamic: license-file
 
 # mongo-pipebuilder
 
+[![PyPI version](https://badge.fury.io/py/mongo-pipebuilder.svg)](https://badge.fury.io/py/mongo-pipebuilder)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Test Coverage](https://img.shields.io/badge/coverage-96%25-green.svg)](https://github.com/seligoroff/mongo-pipebuilder)
+
 Type-safe, fluent MongoDB aggregation pipeline builder for Python.
 
 ## Overview
@@ -36,11 +42,11 @@ Type-safe, fluent MongoDB aggregation pipeline builder for Python.
 
 ## Features
 
-- ✅ **Type-safe**: Full type hints support with IDE autocomplete
-- ✅ **Fluent interface**: Chain methods for readable, maintainable code
-- ✅ **Zero dependencies**: Pure Python, lightweight package
-- ✅ **Extensible**: Easy to add custom stages via `add_stage()`
-- ✅ **Well tested**: Comprehensive test suite with 96%+ coverage
+- **Type-safe**: Full type hints support with IDE autocomplete
+- **Fluent interface**: Chain methods for readable, maintainable code
+- **Zero dependencies**: Pure Python, lightweight package
+- **Extensible**: Easy to add custom stages via `add_stage()`
+- **Well tested**: Comprehensive test suite with 96%+ coverage
 
 ## Installation
 
@@ -259,6 +265,22 @@ group_index = stage_types.index("$group")
 builder.insert_at(group_index, {"$addFields": {"x": 1}})
 ```
 
+##### `copy() -> PipelineBuilder`
+
+Creates an independent copy of the builder with current stages. Useful for creating immutable variants and composing pipelines.
+
+```python
+builder1 = PipelineBuilder().match({"status": "active"})
+builder2 = builder1.copy()
+builder2.limit(10)
+
+# Original unchanged
+assert len(builder1) == 1
+assert len(builder2) == 2
+```
+
+See [Composing and Reusing Pipelines](#composing-and-reusing-pipelines) for practical examples.
+
 ##### `validate() -> bool`
 
 Validates the pipeline before execution. Checks that:
@@ -275,6 +297,54 @@ 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
+#   }
+# ]
+```
+
+##### `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"}
+)
+```
+
 ##### `build() -> List[Dict[str, Any]]`
 
 Returns the complete pipeline as a list of stage dictionaries.
@@ -340,6 +410,150 @@ pipeline = (
 )
 ```
 
+### Composing and Reusing Pipelines
+
+The `copy()` method allows you to create immutable variants of pipelines, enabling safe composition and reuse. This is useful when you need to:
+- Create multiple variants from a base pipeline
+- Compose pipelines functionally
+- Cache base pipelines safely
+- Pass pipelines to functions without side effects
+
+#### Example: Building Multiple Variants from a Base Pipeline
+
+```python
+from mongo_pipebuilder import PipelineBuilder
+
+# Base pipeline with common filtering and joining
+base_pipeline = (
+    PipelineBuilder()
+    .match({"status": "published", "deleted": False})
+    .lookup(
+        from_collection="authors",
+        local_field="authorId",
+        foreign_field="_id",
+        as_field="author"
+    )
+    .unwind("author", preserve_null_and_empty_arrays=True)
+    .project({
+        "title": 1,
+        "authorName": "$author.name",
+        "publishedAt": 1
+    })
+)
+
+# Create variants with different sorting and limits
+recent_posts = base_pipeline.copy().sort({"publishedAt": -1}).limit(10).build()
+popular_posts = base_pipeline.copy().sort({"views": -1}).limit(5).build()
+author_posts = base_pipeline.copy().match({"authorName": "John Doe"}).build()
+
+# Base pipeline remains unchanged
+assert len(base_pipeline) == 4  # Still has 4 stages
+```
+
+#### Example: Functional Composition Pattern
+
+```python
+def add_pagination(builder, page: int, page_size: int = 10):
+    """Add pagination to a pipeline."""
+    return builder.copy().skip(page * page_size).limit(page_size)
+
+def add_sorting(builder, sort_field: str, ascending: bool = True):
+    """Add sorting to a pipeline."""
+    return builder.copy().sort({sort_field: 1 if ascending else -1})
+
+# Compose pipelines functionally
+base = PipelineBuilder().match({"status": "active"})
+
+# Create different variants
+page1 = add_pagination(add_sorting(base, "createdAt"), page=0)
+page2 = add_pagination(add_sorting(base, "createdAt"), page=1)
+sorted_by_name = add_sorting(base, "name", ascending=True)
+
+# All variants are independent
+assert len(base) == 1  # Base unchanged
+assert len(page1) == 3  # match + sort + skip + limit
+```
+
+#### Example: Caching Base Pipelines
+
+```python
+from functools import lru_cache
+
+@lru_cache(maxsize=100)
+def get_base_pipeline(user_id: str):
+    """Cache base pipeline for a user."""
+    return (
+        PipelineBuilder()
+        .match({"userId": user_id, "status": "active"})
+        .lookup(
+            from_collection="profiles",
+            local_field="userId",
+            foreign_field="_id",
+            as_field="profile"
+        )
+    )
+
+# Reuse cached base pipeline with different modifications
+user_id = "12345"
+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()
+
+# Base pipeline is safely cached and reused
+```
+
+#### Example: Pipeline Factories
+
+```python
+class PipelineFactory:
+    """Factory for creating common pipeline patterns."""
+    
+    @staticmethod
+    def base_article_pipeline():
+        """Base pipeline for articles."""
+        return (
+            PipelineBuilder()
+            .match({"status": "published"})
+            .lookup(
+                from_collection="authors",
+                local_field="authorId",
+                foreign_field="_id",
+                as_field="author"
+            )
+        )
+    
+    @staticmethod
+    def with_author_filter(builder, author_name: str):
+        """Add author filter to pipeline."""
+        return builder.copy().match({"author.name": author_name})
+    
+    @staticmethod
+    def with_date_range(builder, start_date: str, end_date: str):
+        """Add date range filter to pipeline."""
+        return builder.copy().match({
+            "publishedAt": {"$gte": start_date, "$lte": end_date}
+        })
+
+# Usage
+base = PipelineFactory.base_article_pipeline()
+johns_articles = PipelineFactory.with_author_filter(base, "John Doe")
+recent_johns = PipelineFactory.with_date_range(
+    johns_articles, 
+    start_date="2024-01-01",
+    end_date="2024-12-31"
+).sort({"publishedAt": -1}).limit(10).build()
+```
+
+**Key Benefits:**
+- Safe reuse: Base pipelines remain unchanged
+- Functional composition: Build pipelines from smaller parts
+- Caching friendly: Base pipelines can be safely cached
+- No side effects: Functions can safely modify copies
+- Thread-safe: Multiple threads can use copies independently
+
 ## Development
 
 ### Project Structure
@@ -374,3 +588,18 @@ See [DEVELOPMENT.md](DEVELOPMENT.md) for development guidelines.
 MIT License - see [LICENSE](LICENSE) file for details.
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

{mongo_pipebuilder-0.2.2 → mongo_pipebuilder-0.3.0}/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,245 @@ 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"
+

{mongo_pipebuilder-0.2.2 → mongo_pipebuilder-0.3.0}/tests/test_builder_insert.py

@@ -256,3 +256,5 @@ class TestPrependAndInsertAtIntegration:
         assert pipeline[2] == {"$sort": {"name": 1}}
         assert pipeline[3] == {"$limit": 10}
 
+
+

{mongo_pipebuilder-0.2.2 → mongo_pipebuilder-0.3.0}/tests/test_builder_validation.py

@@ -172,3 +172,18 @@ class TestPipelineValidation:
         assert "$limit" in pipeline[6]
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

{mongo_pipebuilder-0.2.2 → mongo_pipebuilder-0.3.0}/tests/test_builder_validation_existing.py

@@ -200,3 +200,5 @@ class TestProjectValidation:
             builder.project(123)
 
 
+
+

{mongo_pipebuilder-0.2.2 → mongo_pipebuilder-0.3.0}/tests/test_builder_validation_new.py

@@ -157,3 +157,5 @@ class TestSetFieldValidation:
             builder.set_field(123)
 
 
+
+