mongo-aggro 0.1.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

mongo_aggro/stages/transform.py

@@ -0,0 +1,136 @@
+"""Document transformation MongoDB aggregation pipeline stages.
+
+This module contains stages for transforming document structure:
+AddFields, Set, Unset, ReplaceRoot, ReplaceWith, and Redact.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AddFields(BaseModel):
+    """
+    $addFields stage - adds new fields to documents.
+
+    Example:
+        >>> AddFields(fields={"isActive": True, "score": {"$sum": "$marks"}})
+        {"$addFields": {"isActive": true, "score": {"$sum": "$marks"}}}
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    fields: dict[str, Any] = Field(..., description="Fields to add")
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        return {"$addFields": self.fields}
+
+
+class Set(BaseModel):
+    """
+    $set stage - alias for $addFields.
+
+    Example:
+        >>> Set(fields={"status": "processed"}).model_dump()
+        {"$set": {"status": "processed"}}
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    fields: dict[str, Any] = Field(..., description="Fields to set")
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        return {"$set": self.fields}
+
+
+class Unset(BaseModel):
+    """
+    $unset stage - removes fields from documents.
+
+    Example:
+        >>> Unset(fields=["password", "secret"]).model_dump()
+        {"$unset": ["password", "secret"]}
+
+        >>> Unset(fields="temporaryField").model_dump()
+        {"$unset": "temporaryField"}
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    fields: str | list[str] = Field(..., description="Field(s) to remove")
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        return {"$unset": self.fields}
+
+
+class ReplaceRoot(BaseModel):
+    """
+    $replaceRoot stage - replaces document with specified embedded document.
+
+    Example:
+        >>> ReplaceRoot(new_root="$nested").model_dump()
+        {"$replaceRoot": {"newRoot": "$nested"}}
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    new_root: str | dict[str, Any] = Field(
+        ...,
+        validation_alias="newRoot",
+        serialization_alias="newRoot",
+        description="Expression for new root",
+    )
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        return {"$replaceRoot": {"newRoot": self.new_root}}
+
+
+class ReplaceWith(BaseModel):
+    """
+    $replaceWith stage - replaces document (alias for $replaceRoot).
+
+    Example:
+        >>> ReplaceWith(expression="$embedded").model_dump()
+        {"$replaceWith": "$embedded"}
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    expression: str | dict[str, Any] = Field(
+        ..., description="Expression for new document"
+    )
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        return {"$replaceWith": self.expression}
+
+
+class Redact(BaseModel):
+    """
+    $redact stage - restricts document content based on stored info.
+
+    Example:
+        >>> Redact(expression={
+        ...     "$cond": {
+        ...         "if": {"$eq": ["$level", 5]},
+        ...         "then": "$$PRUNE",
+        ...         "else": "$$DESCEND"
+        ...     }
+        ... }).model_dump()
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    expression: dict[str, Any] = Field(..., description="Redaction expression")
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        return {"$redact": self.expression}
+
+
+__all__ = [
+    "AddFields",
+    "Set",
+    "Unset",
+    "ReplaceRoot",
+    "ReplaceWith",
+    "Redact",
+]

mongo_aggro/stages/window.py

@@ -0,0 +1,139 @@
+"""Window function MongoDB aggregation pipeline stages.
+
+This module contains stages for window operations and data filling:
+SetWindowFields, Densify, and Fill.
+"""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class SetWindowFields(BaseModel):
+    """
+    $setWindowFields stage - performs window calculations.
+
+    Example:
+        >>> SetWindowFields(
+        ...     partition_by="$state",
+        ...     sort_by={"date": 1},
+        ...     output={
+        ...         "cumulative": {
+        ...             "$sum": "$quantity",
+        ...             "window": {"documents": ["unbounded", "current"]}
+        ...         }
+        ...     }
+        ... ).model_dump()
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    partition_by: str | dict[str, Any] | None = Field(
+        default=None,
+        validation_alias="partitionBy",
+        serialization_alias="partitionBy",
+        description="Partitioning expression",
+    )
+    sort_by: dict[str, Literal[-1, 1]] | None = Field(
+        default=None,
+        validation_alias="sortBy",
+        serialization_alias="sortBy",
+        description="Sort specification",
+    )
+    output: dict[str, Any] = Field(
+        ..., description="Output field specifications"
+    )
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        result: dict[str, Any] = {"output": self.output}
+        if self.partition_by is not None:
+            result["partitionBy"] = self.partition_by
+        if self.sort_by is not None:
+            result["sortBy"] = self.sort_by
+        return {"$setWindowFields": result}
+
+
+class Densify(BaseModel):
+    """
+    $densify stage - fills gaps in data.
+
+    Example:
+        >>> Densify(
+        ...     field="date",
+        ...     range={"step": 1, "unit": "day", "bounds": "full"},
+        ...     partition_by_fields=["series"]
+        ... ).model_dump()
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    field: str = Field(..., description="Field to densify")
+    range: dict[str, Any] = Field(..., description="Range specification")
+    partition_by_fields: list[str] | None = Field(
+        default=None,
+        validation_alias="partitionByFields",
+        serialization_alias="partitionByFields",
+        description="Fields to partition by",
+    )
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        result: dict[str, Any] = {"field": self.field, "range": self.range}
+        if self.partition_by_fields is not None:
+            result["partitionByFields"] = self.partition_by_fields
+        return {"$densify": result}
+
+
+class Fill(BaseModel):
+    """
+    $fill stage - fills null/missing field values.
+
+    Example:
+        >>> Fill(
+        ...     sort_by={"date": 1},
+        ...     output={
+        ...         "score": {"method": "linear"},
+        ...         "bootcamp": {"value": "missing"}
+        ...     }
+        ... ).model_dump()
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    output: dict[str, Any] = Field(
+        ..., description="Output field specifications"
+    )
+    partition_by: str | dict[str, Any] | None = Field(
+        default=None,
+        validation_alias="partitionBy",
+        serialization_alias="partitionBy",
+        description="Partitioning expression",
+    )
+    partition_by_fields: list[str] | None = Field(
+        default=None,
+        validation_alias="partitionByFields",
+        serialization_alias="partitionByFields",
+        description="Fields to partition by",
+    )
+    sort_by: dict[str, Literal[-1, 1]] | None = Field(
+        default=None,
+        validation_alias="sortBy",
+        serialization_alias="sortBy",
+        description="Sort specification",
+    )
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        result: dict[str, Any] = {"output": self.output}
+        if self.partition_by is not None:
+            result["partitionBy"] = self.partition_by
+        if self.partition_by_fields is not None:
+            result["partitionByFields"] = self.partition_by_fields
+        if self.sort_by is not None:
+            result["sortBy"] = self.sort_by
+        return {"$fill": result}
+
+
+__all__ = [
+    "SetWindowFields",
+    "Densify",
+    "Fill",
+]

mongo_aggro-0.2.2.dist-info/METADATA

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: mongo-aggro
+Version: 0.2.2
+Summary: MongoDB Aggregation Pipeline Builder with Pydantic
+Project-URL: Homepage, https://github.com/hamedghenaat/mongo-aggro
+Project-URL: Repository, https://github.com/hamedghenaat/mongo-aggro
+Project-URL: Documentation, https://hamedghenaat.github.io/mongo-aggro/
+Author: Hamed Ghenaat
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aggregation,database,mongodb,pipeline,pydantic
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.10.0
+Provides-Extra: build
+Requires-Dist: build>=1.2.0; extra == 'build'
+Requires-Dist: twine>=6.0.0; extra == 'build'
+Provides-Extra: dev
+Requires-Dist: black>=24.10.0; extra == 'dev'
+Requires-Dist: isort>=5.13.2; extra == 'dev'
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
+Requires-Dist: pyupgrade>=3.19.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
+Requires-Dist: mkdocstrings-python>=1.12.0; extra == 'docs'
+Requires-Dist: mkdocstrings>=0.27.0; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=6.0.0; extra == 'test'
+Requires-Dist: pytest-mock>=3.14.0; extra == 'test'
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Mongo Aggro
+
+A Python package for building MongoDB aggregation pipelines with Pydantic.
+
+[![PyPI](https://img.shields.io/pypi/v/mongo-aggro)](https://pypi.org/project/mongo-aggro/)
+[![Python](https://img.shields.io/pypi/pyversions/mongo-aggro)](https://pypi.org/project/mongo-aggro/)
+[![License](https://img.shields.io/pypi/l/mongo-aggro)](https://github.com/hamedghenaat/mongo-aggro/blob/main/LICENSE)
+
+## Features
+
+- **Type-safe** - Pydantic models with full type hints
+- **Zero-conversion** - Pass `Pipeline` directly to `collection.aggregate()`
+- **Python operators** - Use `F("age") > 18` instead of `{"$gt": ["$age", 18]}`
+- **149 expression operators** - Arithmetic, string, date, array, and more
+- **46 aggregation stages** - All major MongoDB stages supported
+- **31 query predicates** - Comparison, logical, geospatial, bitwise
+- **17 accumulators** - Sum, Avg, Min, Max, Push, TopN, etc.
+
+## Installation
+
+```bash
+uv add mongo-aggro
+# or
+pip install mongo-aggro
+```
+
+## Quick Start
+
+```python
+from mongo_aggro import Pipeline, Match, Group, Sort, Expr
+from mongo_aggro.expressions import F
+
+# Traditional approach
+pipeline = Pipeline([
+    Match(query={"status": "active"}),
+    Group(id="$category", accumulators={"total": {"$sum": "$amount"}}),
+    Sort(fields={"total": -1})
+])
+
+# Python operator syntax
+pipeline = Pipeline([
+    Match(query=Expr(expression=(F("status") == "active")).model_dump()),
+    Group(id="$category", accumulators={"total": {"$sum": "$amount"}}),
+])
+
+# Pass directly to MongoDB
+results = collection.aggregate(pipeline)
+```
+
+## Package Structure
+
+```python
+# Import from root (most common)
+from mongo_aggro import Pipeline, Match, Group, Sort, Expr
+
+# Import expressions from sub-package
+from mongo_aggro.expressions import F, AddExpr, ConcatExpr, CondExpr
+
+# Import stages by category
+from mongo_aggro.stages import Match, Project, Lookup, SetWindowFields
+
+# Import query operators
+from mongo_aggro.operators import In, Regex, GeoWithin, Exists
+```
+
+## Expression Operators with Python Syntax
+
+```python
+from mongo_aggro import Expr, Match
+from mongo_aggro.expressions import F
+
+# Comparison operators
+F("age") > 18        # {"$gt": ["$age", 18]}
+F("status") == "active"  # {"$eq": ["$status", "active"]}
+
+# Logical operators (use & | ~ instead of and or not)
+(F("age") >= 18) & (F("status") == "active")
+(F("type") == "premium") | (F("balance") > 1000)
+
+# Use in Match stage
+Match(query=Expr(expression=(
+    (F("status") == "active") & (F("age") > 18)
+)).model_dump())
+```
+
+## Stages
+
+| Category | Stages |
+|----------|--------|
+| **Core** | Match, Project, Group, Sort, Limit, Skip, Unwind, AddFields, Set, Unset |
+| **Join** | Lookup, GraphLookup, UnionWith |
+| **Aggregation** | Bucket, BucketAuto, Facet, SortByCount, Count |
+| **Output** | Out, Merge |
+| **Window** | SetWindowFields, Densify, Fill |
+| **Geospatial** | GeoNear |
+| **Search** | Search, SearchMeta, VectorSearch, RankFusion |
+| **Change Stream** | ChangeStream, ChangeStreamSplitLargeEvent |
+| **Admin** | CollStats, IndexStats, CurrentOp, ListSessions |
+
+## Expression Operators
+
+| Category | Examples |
+|----------|----------|
+| **Comparison** | Eq, Ne, Gt, Gte, Lt, Lte, Cmp |
+| **Logical** | And, Or, Not |
+| **Arithmetic** | Add, Subtract, Multiply, Divide, Mod, Abs, Ceil, Floor |
+| **String** | Concat, Split, ToLower, ToUpper, Trim, RegexMatch |
+| **Array** | ArraySize, Filter, Map, Reduce, Slice, InArray |
+| **Date** | DateAdd, DateDiff, DateToString, Year, Month, Day |
+| **Type** | ToDate, ToString, ToInt, Convert, Type |
+| **Conditional** | Cond, IfNull, Switch |
+| **Set** | SetUnion, SetIntersection, SetDifference |
+| **Window** | Rank, DenseRank, Shift, ExpMovingAvg |
+
+## Query Predicates
+
+```python
+from mongo_aggro import Match, In, Regex, Exists, GeoWithin
+
+Match(query={
+    "status": In(values=["active", "pending"]).model_dump(),
+    "email": Regex(pattern="@company\\.com$").model_dump(),
+    "profile": Exists(exists=True).model_dump(),
+})
+```
+
+## Accumulators
+
+```python
+from mongo_aggro import Group, Sum, Avg, Max, Push, merge_accumulators
+
+Group(
+    id="$category",
+    accumulators=merge_accumulators(
+        Sum(name="total", field="amount"),
+        Avg(name="average", field="price"),
+        Max(name="highest", field="price"),
+    )
+)
+```
+
+## Documentation
+
+- [User Guide](https://hamedghenaat.github.io/mongo-aggro/guide/)
+- [API Reference](https://hamedghenaat.github.io/mongo-aggro/api/)
+- [Examples](https://hamedghenaat.github.io/mongo-aggro/examples/)
+
+## License
+
+MIT

mongo_aggro-0.2.2.dist-info/RECORD

@@ -0,0 +1,49 @@
+mongo_aggro/__init__.py,sha256=pEKMZyNaS1tawDb0cTc0AA1ztWJiFL2cS-rwx754ErU,11057
+mongo_aggro/accumulators.py,sha256=Q5e_iyuHvy-zxSSXgRv00VNq5zz3ku41yFIQ6FOLb74,14828
+mongo_aggro/base.py,sha256=UImOK0KD12qAouYKKiFwF0gBq8Cduvmm7p08Bs1Rky0,7198
+mongo_aggro/expressions/__init__.py,sha256=S99sz-fFzZCguI3viFQondR_mYSZaxsn0zlBL0w_e_s,7925
+mongo_aggro/expressions/arithmetic.py,sha256=pJ_JU04uImK5AVul0YrcnXqaPRn4UxB_gCyBUegzlm0,7705
+mongo_aggro/expressions/array.py,sha256=0_xAkBEA-lTVLzWP0e8BNOUIvYRpuaqPhgEncD_BVI4,10722
+mongo_aggro/expressions/base.py,sha256=KHMKsYzcwbAHmMFhSVPvuXIODTgRVrdMsyV0dUmicuU,5381
+mongo_aggro/expressions/bitwise.py,sha256=KR5pQc-foDu-3R8pGPUsDaKT_hR2JZItnBc927QyQDs,1979
+mongo_aggro/expressions/comparison.py,sha256=IPKuAA2DuWtFgJ3JhCNZYhWv31eqPVFELBfLsP4Opog,3628
+mongo_aggro/expressions/conditional.py,sha256=wVDgsUKtsKUiOAVrydNxOSavXsbkCxkAWTB-wfoIj2E,2961
+mongo_aggro/expressions/date.py,sha256=Y6qpxH19p8Jp9IzMC-FcF4W2m_3P3O0wS9OaR8mk81U,18725
+mongo_aggro/expressions/encrypted.py,sha256=darNTAu_QXesBY7u84e2kGyMMqiY-Y2PaRJO1kC1AFE,3315
+mongo_aggro/expressions/logical.py,sha256=WcvfIaabBOpXyfxv1l3g5QvDX5Ek5H2Jl4lRaRCNhvE,1758
+mongo_aggro/expressions/object.py,sha256=r6-igAHLvM7uNgHMFxqrI2K60-eV1Gr1qH_BmIMDT_k,3236
+mongo_aggro/expressions/set.py,sha256=eKuOMN63uv3t605wI955FmiJ3uuwfcr7_GWbuPs33CU,3976
+mongo_aggro/expressions/size.py,sha256=HdKwKQFp3wJRE8Y_0B6KRrO6ExEs2ncoYfU-AfbfDqQ,1144
+mongo_aggro/expressions/string.py,sha256=hWT3Nc7G_X5h1WFKlpCP8tefXzXYNIjevgYuQILhlTI,9412
+mongo_aggro/expressions/trigonometry.py,sha256=oGAeB0EHVqd4XgaWDWT16Jyu70D7TGjrRgv8hs7i1WY,6583
+mongo_aggro/expressions/type.py,sha256=9Wkir3L4KIbNBa0WU1Nswqg77ZMjZAvlNk5qTLU0tIo,5043
+mongo_aggro/expressions/variable.py,sha256=W5gO3gKKIuVtvNbAJEdUz9l6fqoVkQsAK00oQYBewrI,1756
+mongo_aggro/expressions/window.py,sha256=BJY-_Q26pSifp5H06ffGQCHusHHOi4UFyu5jPmzBqIk,8582
+mongo_aggro/operators/__init__.py,sha256=vBEFytD3YA68-9-XfrK2rfs23LK35-zaF7I_FsKPgLo,1289
+mongo_aggro/operators/array.py,sha256=MnULX4J12_Rq-dNuVcTiy1gj6_Cp8pJfa82zUjzDPD4,1051
+mongo_aggro/operators/base.py,sha256=TRFaPmOCmokt5z7DSKG6ieaEN3Do75q8msvGQKLfc-I,335
+mongo_aggro/operators/bitwise.py,sha256=ouP8SoKe4qvcsOYG8ecRTc96HOA5dkjvlxRBsAR3CBs,1972
+mongo_aggro/operators/comparison.py,sha256=2xeex4p0knVwUaWIFi0AU-VGv381MgrdyCG6PLicV8k,2150
+mongo_aggro/operators/element.py,sha256=lYbspdyIsFhUXp26NfnP6xXfdf6Z1yKOY54RSIhoQgM,811
+mongo_aggro/operators/geo.py,sha256=dhksA-ZbzA6T63iBtTOrzuDyWg01D44PnFWMfNn6IgQ,5683
+mongo_aggro/operators/logical.py,sha256=qpe37VBvkDJSvwFrJG4UINOq2KaLh7P_ZUN-N5U00p4,3057
+mongo_aggro/operators/misc.py,sha256=_DKOkqwZtUFkTpdVWy8uthKfB5ZIuVfAvLII-sxj9NU,3038
+mongo_aggro/operators/regex.py,sha256=D4Yn7qGiIhH6yTm1F5P6lfpoRz4-Rn8w3rHDe1Jj3EU,645
+mongo_aggro/stages/__init__.py,sha256=OyIr5g_1ostDHzrg-Ql_0elQ8itDYzKTr-D6rAAmmXw,2239
+mongo_aggro/stages/array.py,sha256=mto_Dwvoktazs2Om5w2ahcpSCt1F9c0NSi7pqNL7VG0,2059
+mongo_aggro/stages/change.py,sha256=Dkv0VNkZ7x3hmd3u1pTQFWwh8KmX-bxA_GXZr7rG-wI,3614
+mongo_aggro/stages/core.py,sha256=q0InLKAa3EMHKJAaae2JmuKydc7pkKmSYbQKtdOkf8s,4310
+mongo_aggro/stages/geo.py,sha256=1e7MZP_HRfziBOps37wuYEztkOKshYm5v3xax4Ahlx8,2939
+mongo_aggro/stages/group.py,sha256=ug6JlmS65Bpq5hjaVQExX9WzItMBTFAytyuthR7TjrQ,4587
+mongo_aggro/stages/join.py,sha256=Q77DQXfLvpmWVg6_fE4JS_maVUqfMerFD0sgvNcQGzk,6683
+mongo_aggro/stages/misc.py,sha256=PMYKOJBu4sdR7umYhuWVEqcVclwIWoZSpV-Unq7Na0U,1034
+mongo_aggro/stages/output.py,sha256=6lAnHcFUtVCdKQnELitd4xlO5A_zBLgjVX2EnUIek7w,3901
+mongo_aggro/stages/search.py,sha256=3h5gkMOJZceUy6LM_zPUjepxUwxBiLZUWLkALftjrio,9648
+mongo_aggro/stages/session.py,sha256=fb6U-aL9O-svuE_abDYNk4oJ5KF2K2u-VX1HXkicex4,3226
+mongo_aggro/stages/stats.py,sha256=8UMcG00MxbfIxzFzdCXBk6tAc8VZ8fvXqNBzKgttKh8,4541
+mongo_aggro/stages/transform.py,sha256=AXFIuEgjAY0aaQTEY4uNrxqH6cvkmJlkIqcVbka5Mwo,3621
+mongo_aggro/stages/window.py,sha256=34fUensjsDwJr-jUI_c6PFgVqTmj6n2T2fZvKTJZG9c,4291
+mongo_aggro-0.2.2.dist-info/METADATA,sha256=qx7oBKbbVvHUyw-widcti1f4YJx1zWL7WvGSv-evZhQ,6303
+mongo_aggro-0.2.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mongo_aggro-0.2.2.dist-info/licenses/LICENSE,sha256=XnrHxv3Dgf-ttUmsrNPMnQ69JLMED67bxKk3zrOdB40,1070
+mongo_aggro-0.2.2.dist-info/RECORD,,

{mongo_aggro-0.1.0.dist-info → mongo_aggro-0.2.2.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.2.1
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any