mongo-pipebuilder 0.2.1__py3-none-any.whl

mongo_pipebuilder/__init__.py

@@ -0,0 +1,14 @@
+"""
+mongo-pipebuilder: Type-safe, fluent MongoDB aggregation pipeline builder.
+
+This package provides a Builder Pattern implementation for constructing
+MongoDB aggregation pipelines safely and readably.
+
+Author: seligoroff
+"""
+
+from mongo_pipebuilder.builder import PipelineBuilder
+
+__version__ = "0.2.1"
+__all__ = ["PipelineBuilder"]
+

mongo_pipebuilder/builder.py

@@ -0,0 +1,766 @@
+"""
+Pipeline Builder for MongoDB aggregation pipelines.
+
+Builder Pattern implementation for safe construction of MongoDB aggregation pipelines
+
+
+Author: seligoroff
+"""
+from typing import Any, Dict, List, Optional, Union
+
+# For compatibility with Python < 3.11
+try:
+    from typing import Self
+except ImportError:
+    from typing_extensions import Self
+
+
+class PipelineBuilder:
+    """Builder for MongoDB aggregation pipelines with fluent interface."""
+
+    def __init__(self) -> None:
+        """Initialize a new builder with an empty pipeline."""
+        self._stages: List[Dict[str, Any]] = []
+
+    def match(self, conditions: Dict[str, Any]) -> Self:
+        """
+        Add a $match stage for filtering documents.
+        
+        Args:
+            conditions: Dictionary with filtering conditions
+            
+        Returns:
+            Self for method chaining
+            
+        Raises:
+            TypeError: If conditions is not a dictionary
+            ValueError: If conditions is None
+            
+        Example:
+            >>> builder.match({"status": "active", "age": {"$gte": 18}})
+        """
+        if conditions is None:
+            raise TypeError("conditions cannot be None, use empty dict {} instead")
+        if not isinstance(conditions, dict):
+            raise TypeError(f"conditions must be a dict, got {type(conditions)}")
+        if conditions:
+            self._stages.append({"$match": conditions})
+        return self
+
+    def lookup(
+        self,
+        from_collection: str,
+        local_field: str,
+        foreign_field: str,
+        as_field: str,
+        pipeline: Optional[List[Dict[str, Any]]] = None,
+    ) -> Self:
+        """
+        Add a $lookup stage for joining with another collection.
+        
+        Args:
+            from_collection: Name of the collection to join with
+            local_field: Field in the current collection
+            foreign_field: Field in the target collection
+            as_field: Name of the field for join results
+            pipeline: Optional nested pipeline for filtering
+            
+        Returns:
+            Self for method chaining
+            
+        Raises:
+            TypeError: If pipeline is not None and not a list, or if string fields are not strings
+            ValueError: If required string fields are empty
+            
+        Example:
+            >>> builder.lookup(
+            ...     from_collection="users",
+            ...     local_field="userId",
+            ...     foreign_field="_id",
+            ...     as_field="user"
+            ... )
+        """
+        # Validate string parameters
+        if not isinstance(from_collection, str) or not from_collection:
+            raise ValueError("from_collection must be a non-empty string")
+        if not isinstance(local_field, str) or not local_field:
+            raise ValueError("local_field must be a non-empty string")
+        if not isinstance(foreign_field, str) or not foreign_field:
+            raise ValueError("foreign_field must be a non-empty string")
+        if not isinstance(as_field, str) or not as_field:
+            raise ValueError("as_field must be a non-empty string")
+        
+        # Validate pipeline
+        if pipeline is not None:
+            if not isinstance(pipeline, list):
+                raise TypeError(f"pipeline must be a list, got {type(pipeline)}")
+            if not all(isinstance(stage, dict) for stage in pipeline):
+                raise TypeError("All pipeline stages must be dictionaries")
+        
+        lookup_stage: Dict[str, Any] = {
+            "from": from_collection,
+            "localField": local_field,
+            "foreignField": foreign_field,
+            "as": as_field,
+        }
+        if pipeline:
+            lookup_stage["pipeline"] = pipeline
+        self._stages.append({"$lookup": lookup_stage})
+        return self
+
+    def add_fields(self, fields: Dict[str, Any]) -> Self:
+        """
+        Add an $addFields stage for adding or modifying fields.
+        
+        Args:
+            fields: Dictionary with new fields and their expressions
+            
+        Returns:
+            Self for method chaining
+            
+        Raises:
+            TypeError: If fields is not a dictionary
+            
+        Example:
+            >>> builder.add_fields({
+            ...     "fullName": {"$concat": ["$firstName", " ", "$lastName"]}
+            ... })
+        """
+        if fields is None:
+            raise TypeError("fields cannot be None, use empty dict {} instead")
+        if not isinstance(fields, dict):
+            raise TypeError(f"fields must be a dict, got {type(fields)}")
+        if fields:
+            self._stages.append({"$addFields": fields})
+        return self
+
+    def project(self, fields: Dict[str, Any]) -> Self:
+        """
+        Add a $project stage for reshaping documents.
+        
+        Args:
+            fields: Dictionary with fields to include/exclude or transform
+            
+        Returns:
+            Self for method chaining
+            
+        Raises:
+            TypeError: If fields is not a dictionary
+            
+        Example:
+            >>> builder.project({"name": 1, "email": 1, "_id": 0})
+        """
+        if fields is None:
+            raise TypeError("fields cannot be None, use empty dict {} instead")
+        if not isinstance(fields, dict):
+            raise TypeError(f"fields must be a dict, got {type(fields)}")
+        if fields:
+            self._stages.append({"$project": fields})
+        return self
+
+    def group(self, group_by: Dict[str, Any], accumulators: Dict[str, Any]) -> Self:
+        """
+        Add a $group stage for grouping documents.
+        
+        Args:
+            group_by: Expression for grouping (becomes _id)
+            accumulators: Dictionary with accumulators (sum, avg, count, etc.)
+            
+        Returns:
+            Self for method chaining
+            
+        Raises:
+            TypeError: If arguments are not dictionaries
+            ValueError: If both group_by and accumulators are empty
+            
+        Example:
+            >>> builder.group(
+            ...     group_by={"category": "$category"},
+            ...     accumulators={"total": {"$sum": "$amount"}}
+            ... )
+        """
+        if not isinstance(group_by, dict):
+            raise TypeError(f"group_by must be a dict, got {type(group_by)}")
+        if not isinstance(accumulators, dict):
+            raise TypeError(f"accumulators must be a dict, got {type(accumulators)}")
+        
+        # Empty group_by is technically valid in MongoDB (groups all into one document)
+        # But if both are empty, it's likely an error
+        if not group_by and not accumulators:
+            raise ValueError("group_by and accumulators cannot both be empty")
+        
+        group_stage = {"_id": group_by, **accumulators}
+        self._stages.append({"$group": group_stage})
+        return self
+
+    def unwind(
+        self,
+        path: str,
+        preserve_null_and_empty_arrays: bool = False,
+        include_array_index: Optional[str] = None,
+    ) -> Self:
+        """
+        Add an $unwind stage for unwinding arrays.
+        
+        Args:
+            path: Path to the array field
+            preserve_null_and_empty_arrays: Preserve documents with null/empty arrays
+            include_array_index: Name of the field for array element index
+            
+        Returns:
+            Self for method chaining
+            
+        Raises:
+            TypeError: If path is not a string
+            ValueError: If path is empty
+            
+        Example:
+            >>> builder.unwind("tags", preserve_null_and_empty_arrays=True)
+            >>> builder.unwind("items", include_array_index="itemIndex")
+        """
+        if not isinstance(path, str):
+            raise TypeError(f"path must be a string, got {type(path)}")
+        if not path:
+            raise ValueError("path cannot be empty")
+        
+        unwind_stage: Dict[str, Any] = {"path": path}
+        if preserve_null_and_empty_arrays:
+            unwind_stage["preserveNullAndEmptyArrays"] = True
+        if include_array_index:
+            unwind_stage["includeArrayIndex"] = include_array_index
+        self._stages.append({"$unwind": unwind_stage})
+        return self
+
+    def sort(self, fields: Dict[str, int]) -> Self:
+        """
+        Add a $sort stage for sorting documents.
+        
+        Args:
+            fields: Dictionary with fields and sort direction (1 - asc, -1 - desc)
+            
+        Returns:
+            Self for method chaining
+            
+        Raises:
+            TypeError: If fields is not a dictionary
+            
+        Example:
+            >>> builder.sort({"createdAt": -1, "name": 1})
+        """
+        if fields is None:
+            raise TypeError("fields cannot be None, use empty dict {} instead")
+        if not isinstance(fields, dict):
+            raise TypeError(f"fields must be a dict, got {type(fields)}")
+        if fields:
+            self._stages.append({"$sort": fields})
+        return self
+
+    def limit(self, limit: int) -> Self:
+        """
+        Add a $limit stage to limit the number of documents.
+        
+        Args:
+            limit: Maximum number of documents
+            
+        Returns:
+            Self for method chaining
+            
+        Raises:
+            TypeError: If limit is not an integer
+            ValueError: If limit is negative
+            
+        Example:
+            >>> builder.limit(10)
+        """
+        if not isinstance(limit, int):
+            raise TypeError(f"limit must be an integer, got {type(limit)}")
+        if limit < 0:
+            raise ValueError("limit cannot be negative")
+        if limit > 0:
+            self._stages.append({"$limit": limit})
+        return self
+
+    def skip(self, skip: int) -> Self:
+        """
+        Add a $skip stage to skip documents.
+        
+        Args:
+            skip: Number of documents to skip
+            
+        Returns:
+            Self for method chaining
+            
+        Raises:
+            TypeError: If skip is not an integer
+            ValueError: If skip is negative
+            
+        Example:
+            >>> builder.skip(20)
+        """
+        if not isinstance(skip, int):
+            raise TypeError(f"skip must be an integer, got {type(skip)}")
+        if skip < 0:
+            raise ValueError("skip cannot be negative")
+        if skip > 0:
+            self._stages.append({"$skip": skip})
+        return self
+
+    def unset(self, fields: Union[str, List[str]]) -> Self:
+        """
+        Add a $unset stage to remove fields from documents.
+        
+        Args:
+            fields: Field name or list of field names to remove
+            
+        Returns:
+            Self for method chaining
+            
+        Raises:
+            TypeError: If fields is not a string or list of strings
+            ValueError: If fields is empty
+            
+        Example:
+            >>> builder.unset("temp_field")
+            >>> builder.unset(["field1", "field2", "field3"])
+        """
+        if fields is None:
+            raise TypeError("fields cannot be None")
+        
+        if isinstance(fields, str):
+            if not fields:
+                raise ValueError("fields cannot be an empty string")
+            self._stages.append({"$unset": fields})
+        elif isinstance(fields, list):
+            if not fields:
+                raise ValueError("fields cannot be an empty list")
+            if not all(isinstance(f, str) for f in fields):
+                raise TypeError("all items in fields list must be strings")
+            if not all(f for f in fields):  # Check for empty strings
+                raise ValueError("fields list cannot contain empty strings")
+            # MongoDB accepts list for multiple fields, or string for single field
+            self._stages.append({"$unset": fields if len(fields) > 1 else fields[0]})
+        else:
+            raise TypeError(f"fields must be a string or list of strings, got {type(fields)}")
+        
+        return self
+
+    def replace_root(self, new_root: Dict[str, Any]) -> Self:
+        """
+        Add a $replaceRoot stage to replace the root document.
+        
+        Args:
+            new_root: Expression for the new root document (must contain 'newRoot' key)
+            
+        Returns:
+            Self for method chaining
+            
+        Raises:
+            TypeError: If new_root is not a dictionary
+            ValueError: If new_root is empty or missing 'newRoot' key
+            
+        Example:
+            >>> builder.replace_root({"newRoot": "$embedded"})
+            >>> builder.replace_root({"newRoot": {"$mergeObjects": ["$doc1", "$doc2"]}})
+        """
+        if new_root is None:
+            raise TypeError("new_root cannot be None, use empty dict {} instead")
+        if not isinstance(new_root, dict):
+            raise TypeError(f"new_root must be a dict, got {type(new_root)}")
+        if not new_root:
+            raise ValueError("new_root cannot be empty")
+        if "newRoot" not in new_root:
+            raise ValueError("new_root must contain 'newRoot' key")
+        
+        self._stages.append({"$replaceRoot": new_root})
+        return self
+
+    def replace_with(self, replacement: Any) -> Self:
+        """
+        Add a $replaceWith stage (alias for $replaceRoot in MongoDB 4.2+).
+        
+        Args:
+            replacement: Expression for the replacement document
+            
+        Returns:
+            Self for method chaining
+            
+        Raises:
+            ValueError: If replacement is None
+            
+        Example:
+            >>> builder.replace_with("$embedded")
+            >>> builder.replace_with({"$mergeObjects": ["$doc1", "$doc2"]})
+        """
+        if replacement is None:
+            raise ValueError("replacement cannot be None")
+        
+        self._stages.append({"$replaceWith": replacement})
+        return self
+
+    def facet(self, facets: Dict[str, List[Dict[str, Any]]]) -> Self:
+        """
+        Add a $facet stage for parallel execution of multiple sub-pipelines.
+        
+        Args:
+            facets: Dictionary where keys are output field names and values are
+                   lists of pipeline stages for each sub-pipeline
+            
+        Returns:
+            Self for method chaining
+            
+        Raises:
+            TypeError: If facets is not a dictionary
+            ValueError: If facets is empty or contains invalid values
+            
+        Example:
+            >>> builder.facet({
+            ...     "items": [{"$skip": 10}, {"$limit": 20}],
+            ...     "meta": [{"$count": "total"}]
+            ... })
+        """
+        if facets is None:
+            raise TypeError("facets cannot be None, use empty dict {} instead")
+        if not isinstance(facets, dict):
+            raise TypeError(f"facets must be a dict, got {type(facets)}")
+        if not facets:
+            raise ValueError("facets cannot be empty")
+        
+        # Validate that all values are lists of dictionaries
+        for key, value in facets.items():
+            if not isinstance(value, list):
+                raise TypeError(f"facet '{key}' must be a list, got {type(value)}")
+            if not all(isinstance(stage, dict) for stage in value):
+                raise TypeError(f"all stages in facet '{key}' must be dictionaries")
+        
+        self._stages.append({"$facet": facets})
+        return self
+
+    def count(self, field_name: str = "count") -> Self:
+        """
+        Add a $count stage to count documents.
+        
+        Args:
+            field_name: Name of the field for the count result
+            
+        Returns:
+            Self for method chaining
+            
+        Raises:
+            TypeError: If field_name is not a string
+            ValueError: If field_name is empty
+            
+        Example:
+            >>> builder.match({"status": "active"}).count("active_count")
+        """
+        if field_name is None:
+            raise TypeError("field_name cannot be None")
+        if not isinstance(field_name, str):
+            raise TypeError(f"field_name must be a string, got {type(field_name)}")
+        if not field_name:
+            raise ValueError("field_name cannot be empty")
+        
+        self._stages.append({"$count": field_name})
+        return self
+
+    def set_field(self, fields: Dict[str, Any]) -> Self:
+        """
+        Add a $set stage (alias for $addFields in MongoDB 3.4+).
+        
+        Functionally equivalent to add_fields(), but $set is a more intuitive alias.
+        
+        Args:
+            fields: Dictionary with fields and their values/expressions
+            
+        Returns:
+            Self for method chaining
+            
+        Raises:
+            TypeError: If fields is not a dictionary
+            ValueError: If fields is empty
+            
+        Example:
+            >>> builder.set_field({"status": "active", "updatedAt": "$$NOW"})
+        """
+        if fields is None:
+            raise TypeError("fields cannot be None, use empty dict {} instead")
+        if not isinstance(fields, dict):
+            raise TypeError(f"fields must be a dict, got {type(fields)}")
+        if not fields:
+            # Empty dict - valid case, skip (same as add_fields behavior)
+            return self
+        
+        self._stages.append({"$set": fields})
+        return self
+
+    def add_stage(self, stage: Dict[str, Any]) -> Self:
+        """
+        Add an arbitrary pipeline stage for advanced use cases.
+        
+        Args:
+            stage: Dictionary with an arbitrary MongoDB aggregation stage
+            
+        Returns:
+            Self for method chaining
+            
+        Example:
+            >>> builder.add_stage({
+            ...     "$facet": {
+            ...         "categories": [{"$group": {"_id": "$category"}}],
+            ...         "total": [{"$count": "count"}]
+            ...     }
+            ... })
+        """
+        if stage:
+            self._stages.append(stage)
+        return self
+
+    def __len__(self) -> int:
+        """
+        Return the number of stages in the pipeline.
+        
+        Returns:
+            Number of stages
+            
+        Example:
+            >>> builder = PipelineBuilder()
+            >>> builder.match({"status": "active"}).limit(10)
+            >>> len(builder)
+            2
+        """
+        return len(self._stages)
+
+    def __repr__(self) -> str:
+        """
+        Return a string representation of the builder for debugging.
+        
+        Returns:
+            String representation showing stage count and preview
+            
+        Example:
+            >>> builder = PipelineBuilder()
+            >>> builder.match({"status": "active"}).limit(10)
+            >>> repr(builder)
+            'PipelineBuilder(stages=2, preview=[$match, $limit])'
+        """
+        stages_count = len(self._stages)
+        if stages_count == 0:
+            return "PipelineBuilder(stages=0)"
+        
+        stage_types = [list(stage.keys())[0] for stage in self._stages[:3]]
+        stages_preview = ", ".join(stage_types)
+        if stages_count > 3:
+            stages_preview += "..."
+        return f"PipelineBuilder(stages={stages_count}, preview=[{stages_preview}])"
+
+    def clear(self) -> Self:
+        """
+        Clear all stages from the pipeline.
+        
+        Returns:
+            Self for method chaining
+            
+        Example:
+            >>> builder = PipelineBuilder()
+            >>> builder.match({"status": "active"}).clear()
+            >>> len(builder)
+            0
+        """
+        self._stages.clear()
+        return self
+
+    def copy(self) -> "PipelineBuilder":
+        """
+        Create a copy of the builder with current stages.
+        
+        Returns:
+            New PipelineBuilder instance with copied stages
+            
+        Example:
+            >>> builder1 = PipelineBuilder().match({"status": "active"})
+            >>> builder2 = builder1.copy()
+            >>> builder2.limit(10)
+            >>> len(builder1)  # Original unchanged
+            1
+            >>> len(builder2)  # Copy has new stage
+            2
+        """
+        new_builder = PipelineBuilder()
+        new_builder._stages = self._stages.copy()
+        return new_builder
+
+    def validate(self) -> bool:
+        """
+        Validate the pipeline before execution.
+        
+        Checks that the pipeline is not empty and has valid structure.
+        Validates critical MongoDB rules:
+        - $out and $merge stages must be the last stage in the pipeline
+        
+        Returns:
+            True if pipeline is valid
+            
+        Raises:
+            ValueError: If pipeline is empty or has validation errors
+            
+        Example:
+            >>> builder = PipelineBuilder()
+            >>> builder.match({"status": "active"}).validate()
+            True
+            >>> PipelineBuilder().validate()
+            ValueError: Pipeline cannot be empty
+        """
+        if not self._stages:
+            raise ValueError("Pipeline cannot be empty")
+        
+        # Validate that $out and $merge are the last stages (critical MongoDB rule)
+        stage_types = self.get_stage_types()
+        
+        # Check if $out or $merge exist
+        has_out = "$out" in stage_types
+        has_merge = "$merge" in stage_types
+        
+        if has_out and has_merge:
+            raise ValueError(
+                "Pipeline cannot contain both $out and $merge stages. "
+                "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)}."
+                )
+        
+        return True
+
+    def get_stage_types(self) -> List[str]:
+        """
+        Get a list of stage types in the pipeline.
+        
+        Returns:
+            List of stage type strings (e.g., ["$match", "$lookup", "$limit"])
+            
+        Example:
+            >>> builder = PipelineBuilder()
+            >>> builder.match({"status": "active"}).limit(10)
+            >>> builder.get_stage_types()
+            ['$match', '$limit']
+        """
+        return [list(stage.keys())[0] for stage in self._stages]
+
+    def has_stage(self, stage_type: str) -> bool:
+        """
+        Check if the pipeline contains a specific stage type.
+        
+        Args:
+            stage_type: Type of stage to check (e.g., "$match", "$lookup")
+            
+        Returns:
+            True if the stage type is present in the pipeline
+            
+        Raises:
+            TypeError: If stage_type is not a string
+            
+        Example:
+            >>> builder = PipelineBuilder()
+            >>> builder.match({"status": "active"}).limit(10)
+            >>> builder.has_stage("$match")
+            True
+            >>> builder.has_stage("$group")
+            False
+        """
+        if not isinstance(stage_type, str):
+            raise TypeError(f"stage_type must be a string, got {type(stage_type)}")
+        # Check if stage_type is a key in any stage dictionary
+        return any(stage_type in stage for stage in self._stages)
+
+    def prepend(self, stage: Dict[str, Any]) -> Self:
+        """
+        Add a stage at the beginning of the pipeline.
+        
+        Args:
+            stage: Dictionary with a MongoDB aggregation stage
+            
+        Returns:
+            Self for method chaining
+            
+        Raises:
+            TypeError: If stage is not a dictionary
+            
+        Example:
+            >>> builder = PipelineBuilder()
+            >>> builder.match({"status": "active"})
+            >>> builder.prepend({"$match": {"deleted": False}})
+            >>> builder.build()
+            [{"$match": {"deleted": False}}, {"$match": {"status": "active"}}]
+        """
+        if stage is None:
+            raise TypeError("stage cannot be None")
+        if not isinstance(stage, dict):
+            raise TypeError(f"stage must be a dict, got {type(stage)}")
+        if stage:
+            self._stages.insert(0, stage)
+        return self
+
+    def insert_at(self, position: int, stage: Dict[str, Any]) -> Self:
+        """
+        Insert a stage at a specific position in the pipeline.
+        
+        Args:
+            position: Index where to insert (0-based)
+            stage: Dictionary with a MongoDB aggregation stage to insert
+            
+        Returns:
+            Self for method chaining
+            
+        Raises:
+            TypeError: If stage is not a dictionary
+            IndexError: If position is out of range [0, len(stages)]
+            
+        Example:
+            >>> builder = PipelineBuilder()
+            >>> builder.match({"status": "active"}).group({"_id": "$category"}, {})
+            >>> builder.insert_at(1, {"$sort": {"name": 1}})
+            >>> builder.build()
+            [{"$match": {"status": "active"}}, {"$sort": {"name": 1}}, {"$group": {...}}]
+        """
+        if stage is None:
+            raise TypeError("stage cannot be None")
+        if not isinstance(stage, dict):
+            raise TypeError(f"stage must be a dict, got {type(stage)}")
+        if not stage:
+            return self
+        
+        if position < 0 or position > len(self._stages):
+            raise IndexError(
+                f"Position {position} out of range [0, {len(self._stages)}]"
+            )
+        
+        self._stages.insert(position, stage)
+        return self
+
+    def build(self) -> List[Dict[str, Any]]:
+        """
+        Return the completed pipeline.
+        
+        Returns:
+            List of dictionaries with aggregation pipeline stages
+            
+        Example:
+            >>> pipeline = builder.build()
+            >>> collection.aggregate(pipeline)
+        """
+        return self._stages.copy()
+

mongo_pipebuilder-0.2.1.dist-info/METADATA

@@ -0,0 +1,375 @@
+Metadata-Version: 2.4
+Name: mongo-pipebuilder
+Version: 0.2.1
+Summary: Type-safe, fluent MongoDB aggregation pipeline builder
+Author-email: seligoroff <seligoroff@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/seligoroff/mongo-pipebuilder
+Project-URL: Documentation, https://github.com/seligoroff/mongo-pipebuilder#readme
+Project-URL: Repository, https://github.com/seligoroff/mongo-pipebuilder
+Project-URL: Issues, https://github.com/seligoroff/mongo-pipebuilder/issues
+Keywords: mongodb,aggregation,pipeline,builder,query
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing_extensions>=4.0.0; python_version < "3.11"
+Dynamic: license-file
+
+# mongo-pipebuilder
+
+Type-safe, fluent MongoDB aggregation pipeline builder for Python.
+
+## Overview
+
+`mongo-pipebuilder` provides a clean, type-safe way to build MongoDB aggregation pipelines using the Builder Pattern with a fluent interface for maximum readability and safety.
+
+## 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
+
+## Installation
+
+```bash
+pip install mongo-pipebuilder
+```
+
+## Quick Start
+
+```python
+from mongo_pipebuilder import PipelineBuilder
+
+# Build a pipeline
+pipeline = (
+    PipelineBuilder()
+    .match({"status": "active"})
+    .lookup(
+        from_collection="users",
+        local_field="userId",
+        foreign_field="_id",
+        as_field="user"
+    )
+    .project({"name": 1, "user.email": 1})
+    .sort({"name": 1})
+    .limit(10)
+    .build()
+)
+
+# Use with pymongo
+from pymongo import MongoClient
+client = MongoClient()
+collection = client.db.my_collection
+results = collection.aggregate(pipeline)
+```
+
+## API Reference
+
+### PipelineBuilder
+
+Main class for building aggregation pipelines.
+
+#### Methods
+
+##### `match(conditions: Dict[str, Any]) -> Self`
+
+Adds a `$match` stage to filter documents.
+
+```python
+.match({"status": "active", "age": {"$gte": 18}})
+```
+
+##### `lookup(from_collection: str, local_field: str, foreign_field: str, as_field: str, pipeline: Optional[List[Dict[str, Any]]] = None) -> Self`
+
+Adds a `$lookup` stage to join with another collection.
+
+```python
+.lookup(
+    from_collection="users",
+    local_field="userId",
+    foreign_field="_id",
+    as_field="user",
+    pipeline=[{"$match": {"active": True}}]  # Optional nested pipeline
+)
+```
+
+##### `add_fields(fields: Dict[str, Any]) -> Self`
+
+Adds a `$addFields` stage to add or modify fields.
+
+```python
+.add_fields({"fullName": {"$concat": ["$firstName", " ", "$lastName"]}})
+```
+
+##### `project(fields: Dict[str, Any]) -> Self`
+
+Adds a `$project` stage to reshape documents.
+
+```python
+.project({"name": 1, "email": 1, "_id": 0})
+```
+
+##### `group(group_by: Dict[str, Any], accumulators: Dict[str, Any]) -> Self`
+
+Adds a `$group` stage to group documents.
+
+```python
+.group(
+    group_by={"category": "$category"},
+    accumulators={"total": {"$sum": "$amount"}}
+)
+```
+
+##### `unwind(path: str, preserve_null_and_empty_arrays: bool = False, include_array_index: Optional[str] = None) -> Self`
+
+Adds a `$unwind` stage to deconstruct arrays.
+
+```python
+.unwind("tags", preserve_null_and_empty_arrays=True)
+.unwind("items", include_array_index="itemIndex")
+```
+
+##### `sort(fields: Dict[str, int]) -> Self`
+
+Adds a `$sort` stage.
+
+```python
+.sort({"createdAt": -1, "name": 1})
+```
+
+##### `limit(limit: int) -> Self`
+
+Adds a `$limit` stage.
+
+```python
+.limit(10)
+```
+
+##### `skip(skip: int) -> Self`
+
+Adds a `$skip` stage.
+
+```python
+.skip(20)
+```
+
+##### `unset(fields: Union[str, List[str]]) -> Self`
+
+Adds a `$unset` stage to remove fields from documents.
+
+```python
+.unset("temp_field")
+.unset(["field1", "field2", "field3"])
+```
+
+##### `replace_root(new_root: Dict[str, Any]) -> Self`
+
+Adds a `$replaceRoot` stage to replace the root document.
+
+```python
+.replace_root({"newRoot": "$embedded"})
+.replace_root({"newRoot": {"$mergeObjects": ["$doc1", "$doc2"]}})
+```
+
+##### `replace_with(replacement: Any) -> Self`
+
+Adds a `$replaceWith` stage (alias for `$replaceRoot` in MongoDB 4.2+).
+
+```python
+.replace_with("$embedded")
+.replace_with({"$mergeObjects": ["$doc1", "$doc2"]})
+```
+
+##### `facet(facets: Dict[str, List[Dict[str, Any]]]) -> Self`
+
+Adds a `$facet` stage for parallel execution of multiple sub-pipelines.
+
+```python
+.facet({
+    "items": [{"$skip": 10}, {"$limit": 20}],
+    "meta": [{"$count": "total"}]
+})
+```
+
+##### `count(field_name: str = "count") -> Self`
+
+Adds a `$count` stage to count documents.
+
+```python
+.match({"status": "active"}).count("active_count")
+```
+
+##### `set_field(fields: Dict[str, Any]) -> Self`
+
+Adds a `$set` stage (alias for `$addFields` in MongoDB 3.4+).
+
+```python
+.set_field({"status": "active", "updatedAt": "$$NOW"})
+```
+
+##### `add_stage(stage: Dict[str, Any]) -> Self`
+
+Adds a custom stage for advanced use cases.
+
+```python
+.add_stage({"$facet": {
+    "categories": [{"$group": {"_id": "$category"}}],
+    "total": [{"$count": "count"}]
+}})
+```
+
+##### `prepend(stage: Dict[str, Any]) -> Self`
+
+Adds a stage at the beginning of the pipeline.
+
+```python
+builder.match({"status": "active"})
+builder.prepend({"$match": {"deleted": False}})
+# Pipeline: [{"$match": {"deleted": False}}, {"$match": {"status": "active"}}]
+```
+
+##### `insert_at(position: int, stage: Dict[str, Any]) -> Self`
+
+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.insert_at(1, {"$sort": {"name": 1}})
+# Pipeline: [{"$match": {...}}, {"$sort": {...}}, {"$group": {...}}]
+```
+
+**Note:** For inserting before a specific stage type, combine with `get_stage_types()`:
+
+```python
+stage_types = builder.get_stage_types()
+group_index = stage_types.index("$group")
+builder.insert_at(group_index, {"$addFields": {"x": 1}})
+```
+
+##### `validate() -> bool`
+
+Validates the pipeline before execution. Checks that:
+- Pipeline is not empty
+- `$out` and `$merge` stages are the last stages (critical MongoDB rule)
+- `$out` and `$merge` are not used together
+
+```python
+builder = PipelineBuilder()
+builder.match({"status": "active"}).validate()  # Returns True
+
+# Invalid: $out not last
+builder.add_stage({"$out": "output"}).match({"status": "active"})
+builder.validate()  # Raises ValueError: $out stage must be the last stage
+```
+
+##### `build() -> List[Dict[str, Any]]`
+
+Returns the complete pipeline as a list of stage dictionaries.
+
+## Examples
+
+### Complex Pipeline with Nested Lookup
+
+```python
+pipeline = (
+    PipelineBuilder()
+    .match({"status": "published"})
+    .lookup(
+        from_collection="authors",
+        local_field="authorId",
+        foreign_field="_id",
+        as_field="author"
+    )
+    .unwind("author", preserve_null_and_empty_arrays=True)
+    .lookup(
+        from_collection="categories",
+        local_field="categoryId",
+        foreign_field="_id",
+        as_field="category",
+        pipeline=[
+            {"$match": {"active": True}},
+            {"$project": {"name": 1, "slug": 1}}
+        ]
+    )
+    .unwind("category")
+    .add_fields({
+        "authorName": "$author.name",
+        "categoryName": "$category.name"
+    })
+    .project({
+        "title": 1,
+        "authorName": 1,
+        "categoryName": 1,
+        "publishedAt": 1
+    })
+    .sort({"publishedAt": -1})
+    .limit(20)
+    .build()
+)
+```
+
+### Aggregation with Grouping
+
+```python
+pipeline = (
+    PipelineBuilder()
+    .match({"date": {"$gte": "2024-01-01"}})
+    .group(
+        group_by={"month": {"$dateToString": {"format": "%Y-%m", "date": "$date"}}},
+        accumulators={
+            "totalSales": {"$sum": "$amount"},
+            "avgAmount": {"$avg": "$amount"},
+            "count": {"$sum": 1}
+        }
+    )
+    .sort({"month": 1})
+    .build()
+)
+```
+
+## Development
+
+### Project Structure
+
+```
+mongo-pipebuilder/
+├── src/
+│   └── mongo_pipebuilder/
+│       ├── __init__.py
+│       └── builder.py
+├── tests/
+│   └── test_builder.py
+├── examples/
+│   └── examples.py
+├── pyproject.toml
+├── README.md
+└── LICENSE
+```
+
+### Running Tests
+
+```bash
+pytest tests/
+```
+
+### Contributing
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for development guidelines.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+

mongo_pipebuilder-0.2.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+mongo_pipebuilder/__init__.py,sha256=eOj_NuBMA9YbVFPmm13UV25RR5_QK2ctrx8QXV3yGTU,336
+mongo_pipebuilder/builder.py,sha256=kurxcQ5IXErefUQjqQ5XAzkfZEv9siN-PufmWoFA0aE,26545
+mongo_pipebuilder-0.2.1.dist-info/licenses/LICENSE,sha256=GLx_6hrvLsyIL34dpRYvjCSIXyYD8PzhBR09opTrixI,1088
+mongo_pipebuilder-0.2.1.dist-info/METADATA,sha256=Kjav6gd0U9MREeLM3tcLz2b5RfBlCyjnJP0H9gG97XM,9126
+mongo_pipebuilder-0.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mongo_pipebuilder-0.2.1.dist-info/top_level.txt,sha256=wLn7H_v-qaNIws5FeBbKPZBCmYFYgFEhPaLjoCWcisc,18
+mongo_pipebuilder-0.2.1.dist-info/RECORD,,

mongo_pipebuilder-0.2.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mongo_pipebuilder-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 mongo-pipebuilder contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

mongo_pipebuilder-0.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+mongo_pipebuilder