mongo-pipebuilder 0.3.1__py3-none-any.whl → 0.5.0__py3-none-any.whl

mongo_pipebuilder/__init__.py

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

mongo_pipebuilder/builder.py

@@ -10,13 +10,10 @@ import copy
 import difflib
 import json
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, Iterable, List, Optional, Union
 
-# For compatibility with Python < 3.11
-try:
-    from typing import Self
-except ImportError:
-    from typing_extensions import Self
+# For compatibility with Python < 3.11 (Self is in typing from 3.11)
+from typing_extensions import Self
 
 
 class PipelineBuilder:
@@ -29,16 +26,16 @@ class PipelineBuilder:
     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 None or not a dictionary
-            
+
         Example:
             >>> builder.match({"status": "active", "age": {"$gte": 18}})
         """
@@ -50,6 +47,29 @@ class PipelineBuilder:
             self._stages.append({"$match": conditions})
         return self
 
+    def match_expr(self, expr: Dict[str, Any]) -> Self:
+        """
+        Add a $match stage with $expr condition (expression-based filter).
+
+        Args:
+            expr: The expression for $expr (e.g. {"$eq": ["$id", "$$teamId"]}).
+
+        Returns:
+            Self for method chaining.
+
+        Raises:
+            TypeError: If expr is None or not a dict.
+
+        Example:
+            >>> builder.match_expr({"$eq": ["$id", "$$teamId"]})
+        """
+        if expr is None:
+            raise TypeError("expr cannot be None, use empty dict {} instead")
+        if not isinstance(expr, dict):
+            raise TypeError(f"expr must be a dict, got {type(expr)}")
+        self._stages.append({"$match": {"$expr": expr}})
+        return self
+
     def lookup(
         self,
         from_collection: str,
@@ -60,21 +80,21 @@ class PipelineBuilder:
     ) -> 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",
@@ -92,14 +112,14 @@ class PipelineBuilder:
             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,
@@ -111,19 +131,133 @@ class PipelineBuilder:
         self._stages.append({"$lookup": lookup_stage})
         return self
 
+    def lookup_let(
+        self,
+        from_collection: str,
+        let: Dict[str, Any],
+        pipeline: Union[List[Dict[str, Any]], "PipelineBuilder"],
+        as_field: str,
+    ) -> Self:
+        """
+        Add a $lookup stage with let and pipeline (join by expression, variables from document).
+
+        Args:
+            from_collection: Name of the collection to join with.
+            let: Variables for the subpipeline (available in pipeline as $$key).
+            pipeline: Subpipeline as list of stages or PipelineBuilder (will call .build()).
+            as_field: Name of the field for join results.
+
+        Returns:
+            Self for method chaining.
+
+        Raises:
+            TypeError: If from_collection, as_field are not strings; if let is not a dict;
+                if pipeline is None or not a list/PipelineBuilder; if pipeline list has non-dict stages.
+            ValueError: If from_collection or as_field are empty; if pipeline list is empty.
+
+        Example:
+            >>> builder.lookup_let(
+            ...     from_collection="teams",
+            ...     let={"teamId": "$idTeam"},
+            ...     pipeline=[{"$match": {"$expr": {"$eq": ["$_id", "$$teamId"]}}}],
+            ...     as_field="team"
+            ... )
+        """
+        if not isinstance(from_collection, str):
+            raise TypeError("from_collection must be a string")
+        if not from_collection:
+            raise ValueError("from_collection must be a non-empty string")
+        if let is None:
+            raise TypeError("let cannot be None")
+        if not isinstance(let, dict):
+            raise TypeError("let must be a dict")
+        if not isinstance(as_field, str):
+            raise TypeError("as_field must be a string")
+        if not as_field:
+            raise ValueError("as_field must be a non-empty string")
+        if pipeline is None:
+            raise TypeError("pipeline cannot be None")
+        if isinstance(pipeline, PipelineBuilder):
+            pipeline = pipeline.build()
+        if not isinstance(pipeline, list):
+            raise TypeError("pipeline must be a list or PipelineBuilder")
+        if not pipeline:
+            raise ValueError("pipeline cannot be empty")
+        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,
+            "let": let,
+            "pipeline": pipeline,
+            "as": as_field,
+        }
+        self._stages.append({"$lookup": lookup_stage})
+        return self
+
+    def union_with(
+        self,
+        coll: str,
+        pipeline: Optional[Union[List[Dict[str, Any]], "PipelineBuilder"]] = None,
+    ) -> Self:
+        """
+        Add a $unionWith stage to combine documents from another collection.
+
+        Merges all documents from the current pipeline with documents from the
+        given collection. If pipeline is provided, it is run on the other
+        collection before merging; you can pass a list of stages or a
+        PipelineBuilder (its .build() is used internally).
+
+        Args:
+            coll: Name of the collection to union with.
+            pipeline: Optional subpipeline (list of stages or PipelineBuilder).
+                Defaults to [].
+
+        Returns:
+            Self for method chaining.
+
+        Raises:
+            TypeError: If coll is not a string; if pipeline is not None and not
+                a list or PipelineBuilder; if pipeline list contains non-dict
+                stages.
+            ValueError: If coll is empty.
+
+        Example:
+            >>> builder.union_with("other_coll")
+            >>> builder.union_with("logs", [{"$match": {"level": "error"}}])
+            >>> sub = PipelineBuilder().match({"source": "x"}).project({"n": 1})
+            >>> builder.union_with("stats", sub)
+        """
+        if not isinstance(coll, str):
+            raise TypeError("coll must be a string")
+        if not coll:
+            raise ValueError("coll must be a non-empty string")
+        pipeline_list: List[Dict[str, Any]] = []
+        if pipeline is not None:
+            if isinstance(pipeline, PipelineBuilder):
+                pipeline_list = pipeline.build()
+            elif isinstance(pipeline, list):
+                if not all(isinstance(stage, dict) for stage in pipeline):
+                    raise TypeError("All pipeline stages must be dictionaries")
+                pipeline_list = pipeline
+            else:
+                raise TypeError("pipeline must be a list or PipelineBuilder")
+        self._stages.append({"$unionWith": {"coll": coll, "pipeline": pipeline_list}})
+        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"]}
@@ -140,16 +274,16 @@ class PipelineBuilder:
     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})
         """
@@ -164,21 +298,21 @@ class PipelineBuilder:
     def group(self, group_by: Union[str, Dict[str, Any], Any], accumulators: Dict[str, Any]) -> Self:
         """
         Add a $group stage for grouping documents.
-        
+
         Args:
             group_by: Expression for grouping (becomes _id). Can be:
                      - A string (field path, e.g., "$category")
                      - A dict (composite key, e.g., {"category": "$category"})
                      - Any other value (null, number, etc.)
             accumulators: Dictionary with accumulators (sum, avg, count, etc.)
-            
+
         Returns:
             Self for method chaining
-            
+
         Raises:
             TypeError: If accumulators is not a dictionary
             ValueError: If both group_by and accumulators are empty (when group_by is dict/str)
-            
+
         Example:
             >>> builder.group(
             ...     group_by="$category",  # String field path
@@ -212,9 +346,10 @@ class PipelineBuilder:
                 "- 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\"."
+                "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
         # But if it's a string and empty, or dict and empty, and accumulators is also empty,
@@ -225,7 +360,7 @@ class PipelineBuilder:
         elif isinstance(group_by, str):
             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
@@ -238,19 +373,19 @@ class PipelineBuilder:
     ) -> 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")
@@ -259,7 +394,7 @@ class PipelineBuilder:
             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
@@ -271,16 +406,16 @@ class PipelineBuilder:
     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})
         """
@@ -295,17 +430,17 @@ class PipelineBuilder:
     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)
         """
@@ -320,17 +455,17 @@ class PipelineBuilder:
     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)
         """
@@ -345,24 +480,24 @@ class PipelineBuilder:
     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")
@@ -378,23 +513,23 @@ class PipelineBuilder:
             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"]}})
@@ -407,48 +542,48 @@ class PipelineBuilder:
             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}],
@@ -461,31 +596,31 @@ class PipelineBuilder:
             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")
         """
@@ -495,26 +630,26 @@ class PipelineBuilder:
             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"})
         """
@@ -525,20 +660,20 @@ class PipelineBuilder:
         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": {
@@ -551,13 +686,42 @@ class PipelineBuilder:
             self._stages.append(stage)
         return self
 
+    def add_stages(self, stages: Iterable[Dict[str, Any]]) -> Self:
+        """
+        Add multiple pipeline stages at once (e.g. a subpipeline from another builder).
+
+        Empty dict stages are skipped, as with add_stage. Each element must be a
+        dictionary.
+
+        Args:
+            stages: Iterable of stage dictionaries (e.g. list, or result of .build()).
+
+        Returns:
+            Self for method chaining.
+
+        Raises:
+            TypeError: If stages is None or any element is not a dictionary.
+
+        Example:
+            >>> builder.add_stages([{"$match": {"x": 1}}, {"$limit": 10}])
+            >>> builder.add_stages(other_builder.build())
+        """
+        if stages is None:
+            raise TypeError("stages must not be None")
+        for stage in stages:
+            if not isinstance(stage, dict):
+                raise TypeError("All stages must be dictionaries")
+            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)
@@ -569,10 +733,10 @@ class PipelineBuilder:
     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)
@@ -582,7 +746,7 @@ class PipelineBuilder:
         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:
@@ -592,10 +756,10 @@ class PipelineBuilder:
     def clear(self) -> Self:
         """
         Clear all stages from the pipeline.
-        
+
         Returns:
             Self for method chaining
-            
+
         Example:
             >>> builder = PipelineBuilder()
             >>> builder.match({"status": "active"}).clear()
@@ -608,10 +772,10 @@ class PipelineBuilder:
     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()
@@ -628,17 +792,17 @@ class PipelineBuilder:
     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()
@@ -648,20 +812,20 @@ class PipelineBuilder:
         """
         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."
             )
-        
+
         # Check if $out or $merge exist and validate position
         for stage_name in ["$out", "$merge"]:
             if stage_name in stage_types:
@@ -671,16 +835,16 @@ class PipelineBuilder:
                         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
 
     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)
@@ -692,16 +856,16 @@ class PipelineBuilder:
     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)
@@ -718,16 +882,16 @@ class PipelineBuilder:
     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"})
@@ -746,18 +910,18 @@ class PipelineBuilder:
     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"}, {})
@@ -771,28 +935,28 @@ class PipelineBuilder:
             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 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)
@@ -810,16 +974,16 @@ class PipelineBuilder:
     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)
@@ -876,23 +1040,23 @@ class PipelineBuilder:
     ) -> 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",
@@ -901,33 +1065,33 @@ class PipelineBuilder:
         """
         filepath = Path(filepath)
         filepath.parent.mkdir(parents=True, exist_ok=True)
-        
+
         output: Dict[str, Any] = {
             "pipeline": self._stages,
         }
         if metadata:
             output["metadata"] = metadata
-        
+
         with open(filepath, "w", encoding="utf-8") as f:
             json.dump(output, f, indent=indent, ensure_ascii=ensure_ascii)
 
     def compare_with(self, other: "PipelineBuilder", context_lines: int = 3) -> str:
         """
         Compare this pipeline with another pipeline and return a unified diff.
-        
+
         This is useful when migrating legacy pipelines (e.g., templates) to builder code.
-        
+
         Args:
             other: Another PipelineBuilder instance to compare with
             context_lines: Number of context lines in the unified diff (default: 3)
-        
+
         Returns:
             Unified diff as a string. Returns "No differences." if pipelines are identical.
-        
+
         Raises:
             TypeError: If other is not a PipelineBuilder
             ValueError: If context_lines is negative
-        
+
         Example:
             >>> legacy = PipelineBuilder().match({"a": 1})
             >>> new = PipelineBuilder().match({"a": 2})
@@ -960,10 +1124,10 @@ class PipelineBuilder:
     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)

{mongo_pipebuilder-0.3.1.dist-info → mongo_pipebuilder-0.5.0.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: mongo-pipebuilder
-Version: 0.3.1
+Version: 0.5.0
 Summary: Type-safe, fluent MongoDB aggregation pipeline builder
 Author-email: seligoroff <seligoroff@gmail.com>
-License: MIT
+License-Expression: 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
@@ -11,16 +11,14 @@ 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
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: typing_extensions>=4.0.0; python_version < "3.11"
@@ -29,7 +27,7 @@ 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/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-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)
@@ -98,6 +96,15 @@ Adds a `$match` stage to filter documents.
 .match({"status": "active", "age": {"$gte": 18}})
 ```
 
+##### `match_expr(expr: Dict[str, Any]) -> Self`
+
+Adds a `$match` stage with an `$expr` condition (expression-based filter; useful for comparing fields or using variables from `let` in subpipelines).
+
+```python
+.match_expr({"$eq": ["$id", "$$teamId"]})
+.match_expr({"$and": [{"$gte": ["$field", "$other"]}, {"$lte": ["$score", 100]}]})
+```
+
 ##### `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.
@@ -112,6 +119,43 @@ Adds a `$lookup` stage to join with another collection.
 )
 ```
 
+##### `lookup_let(from_collection: str, let: Dict[str, Any], pipeline: Union[List[Dict[str, Any]], PipelineBuilder], as_field: str) -> Self`
+
+Adds a `$lookup` stage with `let` and `pipeline` (join by expression; variables from the current document are available in the subpipeline as `$$var`). Use this when the join condition is an expression (e.g. `$expr`) rather than equality of two fields.
+
+```python
+# With list of stages
+.lookup_let(
+    from_collection="teams",
+    let={"teamId": "$idTeam"},
+    pipeline=[
+        {"$match": {"$expr": {"$eq": ["$_id", "$$teamId"]}}},
+        {"$project": {"name": 1, "_id": 0}}
+    ],
+    as_field="team"
+)
+
+# With PipelineBuilder for the subpipeline (optionally using match_expr)
+sub = PipelineBuilder().match_expr({"$eq": ["$_id", "$$teamId"]}).project({"name": 1, "_id": 0})
+.lookup_let("teams", {"teamId": "$idTeam"}, sub, as_field="team")
+```
+
+##### `union_with(coll: str, pipeline: Optional[Union[List[Dict[str, Any]], PipelineBuilder]] = None) -> Self`
+
+Adds a `$unionWith` stage to combine documents from the current pipeline with documents from another collection. Optionally runs a subpipeline on the other collection before merging.
+
+```python
+# Union with another collection (no subpipeline)
+.union_with("other_coll")
+
+# With subpipeline as list of stages
+.union_with("logs", [{"$match": {"level": "error"}}, {"$limit": 100}])
+
+# With PipelineBuilder for the subpipeline
+sub = PipelineBuilder().match({"source": "individual"}).project({"name": 1})
+.union_with("sso_individual_statistics", sub)
+```
+
 ##### `add_fields(fields: Dict[str, Any]) -> Self`
 
 Adds a `$addFields` stage to add or modify fields.
@@ -237,6 +281,19 @@ Adds a custom stage for advanced use cases.
 }})
 ```
 
+##### `add_stages(stages: Iterable[Dict[str, Any]]) -> Self`
+
+Adds multiple stages at once (e.g. a subpipeline from another builder). Empty dicts are skipped. Useful to avoid loops when inserting a ready-made list of stages.
+
+```python
+# From a list
+.add_stages([{"$match": {"level": "error"}}, {"$limit": 100}])
+
+# From another builder
+sub = PipelineBuilder().match({"source": "api"}).project({"name": 1})
+.add_stages(sub.build())
+```
+
 ##### `prepend(stage: Dict[str, Any]) -> Self`
 
 Adds a stage at the beginning of the pipeline.
@@ -411,6 +468,31 @@ pipeline = (
 )
 ```
 
+### Lookup by expression (lookup_let)
+
+When the join condition is an expression (e.g. `$expr`) rather than matching two fields, use `lookup_let`. The subpipeline can be built with `match_expr()`:
+
+```python
+sub = (
+    PipelineBuilder()
+    .match_expr({"$eq": ["$_id", "$$teamId"]})
+    .project({"name": 1, "slug": 1, "_id": 0})
+)
+pipeline = (
+    PipelineBuilder()
+    .match({"status": "active"})
+    .lookup_let(
+        from_collection="teams",
+        let={"teamId": "$idTeam"},
+        pipeline=sub,
+        as_field="team"
+    )
+    .unwind("team", preserve_null_and_empty_arrays=True)
+    .project({"title": 1, "teamName": "$team.name"})
+    .build()
+)
+```
+
 ### Aggregation with Grouping
 
 ```python

mongo_pipebuilder-0.5.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+mongo_pipebuilder/__init__.py,sha256=cn4_tymz00r4iA4ES-qe6lP3k9K6TvuUsagf6_Ajaxc,336
+mongo_pipebuilder/builder.py,sha256=r_umLKj79j7dmBDKoauo5GC2h7ZFRrc1uYd3_aKcwO0,39834
+mongo_pipebuilder-0.5.0.dist-info/licenses/LICENSE,sha256=-ZkZpDLHDQAc-YBIojJ6eDsMwxwx5pRuQz3RHnl9Y8w,1104
+mongo_pipebuilder-0.5.0.dist-info/METADATA,sha256=aUjgx7ENKyXI3eNyv2gt3YmgL2HeRDpUCav-ucJGBFg,20389
+mongo_pipebuilder-0.5.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+mongo_pipebuilder-0.5.0.dist-info/top_level.txt,sha256=wLn7H_v-qaNIws5FeBbKPZBCmYFYgFEhPaLjoCWcisc,18
+mongo_pipebuilder-0.5.0.dist-info/RECORD,,

{mongo_pipebuilder-0.3.1.dist-info → mongo_pipebuilder-0.5.0.dist-info}/WHEEL

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

mongo_pipebuilder-0.3.1.dist-info/RECORD

@@ -1,7 +0,0 @@
-mongo_pipebuilder/__init__.py,sha256=dvekji4j1j9v5MzJOJIqyO2znWVia1opBn8Y1Sc_Y3k,336
-mongo_pipebuilder/builder.py,sha256=Fz7oUiB9FpqnIwnGgamof2ZEBaUGjfYSuB7mYCJO9Qc,34731
-mongo_pipebuilder-0.3.1.dist-info/licenses/LICENSE,sha256=-ZkZpDLHDQAc-YBIojJ6eDsMwxwx5pRuQz3RHnl9Y8w,1104
-mongo_pipebuilder-0.3.1.dist-info/METADATA,sha256=hYFQkwz1xtJK-MPAV2Vp4PuwKLvC7CLc5U-emp4yOzw,17478
-mongo_pipebuilder-0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-mongo_pipebuilder-0.3.1.dist-info/top_level.txt,sha256=wLn7H_v-qaNIws5FeBbKPZBCmYFYgFEhPaLjoCWcisc,18
-mongo_pipebuilder-0.3.1.dist-info/RECORD,,