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

mongo_pipebuilder/__init__.py

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

mongo_pipebuilder/builder.py

@@ -33,8 +33,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}})
@@ -158,36 +157,47 @@ class PipelineBuilder:
             self._stages.append({"$project": fields})
         return self
 
-    def group(self, group_by: Dict[str, Any], accumulators: Dict[str, Any]) -> Self:
+    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)
+            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 arguments are not dictionaries
-            ValueError: If both group_by and accumulators are empty
+            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": "$category"},
+            ...     group_by="$category",  # String field path
+            ...     accumulators={"total": {"$sum": "$amount"}}
+            ... )
+            >>> builder.group(
+            ...     group_by={"category": "$category"},  # Composite key
             ...     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")
+        # 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,
+        # it's likely an error
+        if isinstance(group_by, dict):
+            if not group_by and not accumulators:
+                raise ValueError("group_by and accumulators cannot both be empty")
+        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})
@@ -625,23 +635,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
 
@@ -658,7 +660,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:
         """

{mongo_pipebuilder-0.2.1.dist-info → mongo_pipebuilder-0.2.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mongo-pipebuilder
-Version: 0.2.1
+Version: 0.2.3
 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:
@@ -340,6 +362,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
@@ -373,3 +539,8 @@ See [DEVELOPMENT.md](DEVELOPMENT.md) for development guidelines.
 
 MIT License - see [LICENSE](LICENSE) file for details.
 
+
+
+
+
+

mongo_pipebuilder-0.2.3.dist-info/RECORD

@@ -0,0 +1,7 @@
+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,,

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

@@ -20,3 +20,8 @@ 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/RECORD

@@ -1,7 +0,0 @@
-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,,