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

mongo_pipebuilder/__init__.py

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

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
@@ -753,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.3.dist-info → mongo_pipebuilder-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mongo-pipebuilder
-Version: 0.2.3
+Version: 0.3.0
 Summary: Type-safe, fluent MongoDB aggregation pipeline builder
 Author-email: seligoroff <seligoroff@gmail.com>
 License: MIT
@@ -297,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.
@@ -544,3 +592,14 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 
 
+
+
+
+
+
+
+
+
+
+
+

mongo_pipebuilder-0.3.0.dist-info/RECORD

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

{mongo_pipebuilder-0.2.3.dist-info → mongo_pipebuilder-0.3.0.dist-info}/licenses/LICENSE

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

mongo_pipebuilder-0.2.3.dist-info/RECORD

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