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

mongo_aggro/expressions/type.py

@@ -0,0 +1,205 @@
+"""Type conversion expression operators for MongoDB aggregation."""
+
+from typing import Any
+
+from pydantic import model_serializer
+
+from mongo_aggro.base import serialize_value
+from mongo_aggro.expressions.base import ExpressionBase
+
+
+class ToStringExpr(ExpressionBase):
+    """
+    $toString expression operator - converts value to string.
+
+    Example:
+        >>> ToStringExpr(input=F("numericId")).model_dump()
+        {"$toString": "$numericId"}
+    """
+
+    input: Any
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $toString expression."""
+        return {"$toString": serialize_value(self.input)}
+
+
+class ToIntExpr(ExpressionBase):
+    """
+    $toInt expression operator - converts value to integer.
+
+    Example:
+        >>> ToIntExpr(input=F("stringNum")).model_dump()
+        {"$toInt": "$stringNum"}
+    """
+
+    input: Any
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $toInt expression."""
+        return {"$toInt": serialize_value(self.input)}
+
+
+class ToDoubleExpr(ExpressionBase):
+    """
+    $toDouble expression operator - converts value to double.
+
+    Example:
+        >>> ToDoubleExpr(input=F("intValue")).model_dump()
+        {"$toDouble": "$intValue"}
+    """
+
+    input: Any
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $toDouble expression."""
+        return {"$toDouble": serialize_value(self.input)}
+
+
+class ToBoolExpr(ExpressionBase):
+    """
+    $toBool expression operator - converts value to boolean.
+
+    Example:
+        >>> ToBoolExpr(input=F("flag")).model_dump()
+        {"$toBool": "$flag"}
+    """
+
+    input: Any
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $toBool expression."""
+        return {"$toBool": serialize_value(self.input)}
+
+
+class ToObjectIdExpr(ExpressionBase):
+    """
+    $toObjectId expression operator - converts value to ObjectId.
+
+    Example:
+        >>> ToObjectIdExpr(input=F("idString")).model_dump()
+        {"$toObjectId": "$idString"}
+    """
+
+    input: Any
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $toObjectId expression."""
+        return {"$toObjectId": serialize_value(self.input)}
+
+
+class ToLongExpr(ExpressionBase):
+    """
+    $toLong expression operator - converts value to long integer.
+
+    Example:
+        >>> ToLongExpr(input=F("value")).model_dump()
+        {"$toLong": "$value"}
+    """
+
+    input: Any
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $toLong expression."""
+        return {"$toLong": serialize_value(self.input)}
+
+
+class ToDecimalExpr(ExpressionBase):
+    """
+    $toDecimal expression operator - converts value to Decimal128.
+
+    Example:
+        >>> ToDecimalExpr(input=F("value")).model_dump()
+        {"$toDecimal": "$value"}
+    """
+
+    input: Any
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $toDecimal expression."""
+        return {"$toDecimal": serialize_value(self.input)}
+
+
+class ConvertExpr(ExpressionBase):
+    """
+    $convert expression operator - converts value to specified type.
+
+    Example:
+        >>> ConvertExpr(input=F("value"), to="int").model_dump()
+        {"$convert": {"input": "$value", "to": "int"}}
+    """
+
+    input: Any
+    to: str
+    on_error: Any = None
+    on_null: Any = None
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $convert expression."""
+        result: dict[str, Any] = {
+            "$convert": {
+                "input": serialize_value(self.input),
+                "to": self.to,
+            }
+        }
+        if self.on_error is not None:
+            result["$convert"]["onError"] = serialize_value(self.on_error)
+        if self.on_null is not None:
+            result["$convert"]["onNull"] = serialize_value(self.on_null)
+        return result
+
+
+class TypeExpr(ExpressionBase):
+    """
+    $type expression operator - returns BSON type of a value.
+
+    Example:
+        >>> TypeExpr(input=F("field")).model_dump()
+        {"$type": "$field"}
+    """
+
+    input: Any
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $type expression."""
+        return {"$type": serialize_value(self.input)}
+
+
+class IsNumberExpr(ExpressionBase):
+    """
+    $isNumber expression operator - checks if value is numeric.
+
+    Example:
+        >>> IsNumberExpr(input=F("value")).model_dump()
+        {"$isNumber": "$value"}
+    """
+
+    input: Any
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $isNumber expression."""
+        return {"$isNumber": serialize_value(self.input)}
+
+
+__all__ = [
+    "ToStringExpr",
+    "ToIntExpr",
+    "ToDoubleExpr",
+    "ToBoolExpr",
+    "ToObjectIdExpr",
+    "ToLongExpr",
+    "ToDecimalExpr",
+    "ConvertExpr",
+    "TypeExpr",
+    "IsNumberExpr",
+]

mongo_aggro/expressions/variable.py

@@ -0,0 +1,73 @@
+"""Variable expression operators for MongoDB aggregation."""
+
+from typing import Any
+
+from pydantic import model_serializer
+
+from mongo_aggro.base import serialize_value
+from mongo_aggro.expressions.base import ExpressionBase
+
+
+class LetExpr(ExpressionBase):
+    """
+    $let expression operator - defines variables for use in expression.
+
+    Example:
+        >>> LetExpr(
+        ...     vars={"total": MultiplyExpr(operands=[F("price"), F("qty")])},
+        ...     in_=GtExpr(left=Field("$$total"), right=100)
+        ... ).model_dump()
+        {"$let": {"vars": {"total": {...}}, "in": {...}}}
+    """
+
+    vars: dict[str, Any]
+    in_: Any
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $let expression."""
+        return {
+            "$let": {
+                "vars": {k: serialize_value(v) for k, v in self.vars.items()},
+                "in": serialize_value(self.in_),
+            }
+        }
+
+
+class LiteralExpr(ExpressionBase):
+    """
+    $literal expression operator - returns value without parsing.
+
+    Example:
+        >>> LiteralExpr(value="$field").model_dump()
+        {"$literal": "$field"}
+    """
+
+    value: Any
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $literal expression."""
+        return {"$literal": self.value}
+
+
+class RandExpr(ExpressionBase):
+    """
+    $rand expression operator - returns random float between 0 and 1.
+
+    Example:
+        >>> RandExpr().model_dump()
+        {"$rand": {}}
+    """
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $rand expression."""
+        return {"$rand": {}}
+
+
+__all__ = [
+    "LetExpr",
+    "LiteralExpr",
+    "RandExpr",
+]

mongo_aggro/expressions/window.py

@@ -0,0 +1,327 @@
+"""Window expression operators for MongoDB aggregation."""
+
+from typing import Any
+
+from pydantic import model_serializer
+
+from mongo_aggro.base import serialize_value
+from mongo_aggro.expressions.base import ExpressionBase
+
+
+class RankExpr(ExpressionBase):
+    """
+    $rank window operator - returns document rank in partition.
+
+    Example:
+        >>> RankExpr().model_dump()
+        {"$rank": {}}
+    """
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $rank expression."""
+        return {"$rank": {}}
+
+
+class DenseRankExpr(ExpressionBase):
+    """
+    $denseRank window operator - returns dense rank (no gaps).
+
+    Example:
+        >>> DenseRankExpr().model_dump()
+        {"$denseRank": {}}
+    """
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $denseRank expression."""
+        return {"$denseRank": {}}
+
+
+class DocumentNumberExpr(ExpressionBase):
+    """
+    $documentNumber window operator - returns position in partition.
+
+    Example:
+        >>> DocumentNumberExpr().model_dump()
+        {"$documentNumber": {}}
+    """
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $documentNumber expression."""
+        return {"$documentNumber": {}}
+
+
+class ShiftExpr(ExpressionBase):
+    """
+    $shift window operator - accesses value from different position.
+
+    Example:
+        >>> ShiftExpr(output=F("value"), by=1, default=0).model_dump()
+        {"$shift": {"output": "$value", "by": 1, "default": 0}}
+    """
+
+    output: Any
+    by: int
+    default: Any = None
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $shift expression."""
+        result: dict[str, Any] = {
+            "output": serialize_value(self.output),
+            "by": self.by,
+        }
+        if self.default is not None:
+            result["default"] = serialize_value(self.default)
+        return {"$shift": result}
+
+
+class ExpMovingAvgExpr(ExpressionBase):
+    """
+    $expMovingAvg window operator - exponential moving average.
+
+    Example:
+        >>> ExpMovingAvgExpr(input=F("price"), n=5).model_dump()
+        {"$expMovingAvg": {"input": "$price", "N": 5}}
+    """
+
+    input: Any
+    n: int | None = None
+    alpha: float | None = None
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $expMovingAvg expression."""
+        result: dict[str, Any] = {"input": serialize_value(self.input)}
+        if self.n is not None:
+            result["N"] = self.n
+        elif self.alpha is not None:
+            result["alpha"] = self.alpha
+        return {"$expMovingAvg": result}
+
+
+class DerivativeExpr(ExpressionBase):
+    """
+    $derivative window operator - calculates rate of change.
+
+    Example:
+        >>> DerivativeExpr(input=F("value"), unit="second").model_dump()
+        {"$derivative": {"input": "$value", "unit": "second"}}
+    """
+
+    input: Any
+    unit: str | None = None
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $derivative expression."""
+        result: dict[str, Any] = {"input": serialize_value(self.input)}
+        if self.unit is not None:
+            result["unit"] = self.unit
+        return {"$derivative": result}
+
+
+class IntegralExpr(ExpressionBase):
+    """
+    $integral window operator - calculates area under curve.
+
+    Example:
+        >>> IntegralExpr(input=F("value"), unit="hour").model_dump()
+        {"$integral": {"input": "$value", "unit": "hour"}}
+    """
+
+    input: Any
+    unit: str | None = None
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $integral expression."""
+        result: dict[str, Any] = {"input": serialize_value(self.input)}
+        if self.unit is not None:
+            result["unit"] = self.unit
+        return {"$integral": result}
+
+
+class CovariancePopExpr(ExpressionBase):
+    """
+    $covariancePop window operator - population covariance.
+
+    Example:
+        >>> CovariancePopExpr(array=[F("x"), F("y")]).model_dump()
+        {"$covariancePop": ["$x", "$y"]}
+    """
+
+    array: list[Any]
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $covariancePop expression."""
+        return {"$covariancePop": [serialize_value(a) for a in self.array]}
+
+
+class CovarianceSampExpr(ExpressionBase):
+    """
+    $covarianceSamp window operator - sample covariance.
+
+    Example:
+        >>> CovarianceSampExpr(array=[F("x"), F("y")]).model_dump()
+        {"$covarianceSamp": ["$x", "$y"]}
+    """
+
+    array: list[Any]
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $covarianceSamp expression."""
+        return {"$covarianceSamp": [serialize_value(a) for a in self.array]}
+
+
+class LinearFillExpr(ExpressionBase):
+    """
+    $linearFill window operator - fills nulls with linear interpolation.
+
+    Example:
+        >>> LinearFillExpr(input=F("value")).model_dump()
+        {"$linearFill": "$value"}
+    """
+
+    input: Any
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $linearFill expression."""
+        return {"$linearFill": serialize_value(self.input)}
+
+
+class LocfExpr(ExpressionBase):
+    """
+    $locf window operator - last observation carried forward.
+
+    Example:
+        >>> LocfExpr(input=F("value")).model_dump()
+        {"$locf": "$value"}
+    """
+
+    input: Any
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $locf expression."""
+        return {"$locf": serialize_value(self.input)}
+
+
+class TopExpr(ExpressionBase):
+    """
+    $top accumulator - returns top element based on sort.
+
+    Example:
+        >>> TopExpr(sort_by={"score": -1}, output=F("name")).model_dump()
+        {"$top": {"sortBy": {"score": -1}, "output": "$name"}}
+    """
+
+    sort_by: dict[str, int]
+    output: Any
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $top expression."""
+        return {
+            "$top": {
+                "sortBy": self.sort_by,
+                "output": serialize_value(self.output),
+            }
+        }
+
+
+class BottomExpr(ExpressionBase):
+    """
+    $bottom accumulator - returns bottom element based on sort.
+
+    Example:
+        >>> BottomExpr(sort_by={"score": -1}, output=F("name")).model_dump()
+        {"$bottom": {"sortBy": {"score": -1}, "output": "$name"}}
+    """
+
+    sort_by: dict[str, int]
+    output: Any
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $bottom expression."""
+        return {
+            "$bottom": {
+                "sortBy": self.sort_by,
+                "output": serialize_value(self.output),
+            }
+        }
+
+
+class TopNWindowExpr(ExpressionBase):
+    """
+    $topN accumulator - returns top N elements based on sort.
+
+    Example:
+        >>> TopNWindowExpr(n=3, sort_by={"score": -1}, output=F("name")).model_dump()
+        {"$topN": {"n": 3, "sortBy": {"score": -1}, "output": "$name"}}
+    """
+
+    n: Any
+    sort_by: dict[str, int]
+    output: Any
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $topN expression."""
+        return {
+            "$topN": {
+                "n": serialize_value(self.n),
+                "sortBy": self.sort_by,
+                "output": serialize_value(self.output),
+            }
+        }
+
+
+class BottomNWindowExpr(ExpressionBase):
+    """
+    $bottomN accumulator - returns bottom N elements based on sort.
+
+    Example:
+        >>> BottomNWindowExpr(n=3, sort_by={"score": -1}, output=F("name")).model_dump()
+        {"$bottomN": {"n": 3, "sortBy": {"score": -1}, "output": "$name"}}
+    """
+
+    n: Any
+    sort_by: dict[str, int]
+    output: Any
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        """Serialize to MongoDB $bottomN expression."""
+        return {
+            "$bottomN": {
+                "n": serialize_value(self.n),
+                "sortBy": self.sort_by,
+                "output": serialize_value(self.output),
+            }
+        }
+
+
+__all__ = [
+    "RankExpr",
+    "DenseRankExpr",
+    "DocumentNumberExpr",
+    "ShiftExpr",
+    "ExpMovingAvgExpr",
+    "DerivativeExpr",
+    "IntegralExpr",
+    "CovariancePopExpr",
+    "CovarianceSampExpr",
+    "LinearFillExpr",
+    "LocfExpr",
+    "TopExpr",
+    "BottomExpr",
+    "TopNWindowExpr",
+    "BottomNWindowExpr",
+]

mongo_aggro/operators/__init__.py

@@ -0,0 +1,65 @@
+"""Query and expression operators for MongoDB aggregation."""
+
+from mongo_aggro.operators.array import All, ElemMatch, Size
+from mongo_aggro.operators.base import QueryOperator
+from mongo_aggro.operators.bitwise import (
+    BitsAllClear,
+    BitsAllSet,
+    BitsAnyClear,
+    BitsAnySet,
+)
+from mongo_aggro.operators.comparison import Eq, Gt, Gte, In, Lt, Lte, Ne, Nin
+from mongo_aggro.operators.element import Exists, Type
+from mongo_aggro.operators.geo import (
+    GeoIntersects,
+    GeoWithin,
+    Near,
+    NearSphere,
+)
+from mongo_aggro.operators.logical import And, Expr, Nor, Not, Or
+from mongo_aggro.operators.misc import JsonSchema, Mod, Text, Where
+from mongo_aggro.operators.regex import Regex
+
+__all__ = [
+    # Base
+    "QueryOperator",
+    # Logical
+    "And",
+    "Or",
+    "Not",
+    "Nor",
+    "Expr",
+    # Comparison
+    "Eq",
+    "Ne",
+    "Gt",
+    "Gte",
+    "Lt",
+    "Lte",
+    "In",
+    "Nin",
+    # Element
+    "Exists",
+    "Type",
+    # Array
+    "ElemMatch",
+    "Size",
+    "All",
+    # Regex
+    "Regex",
+    # Bitwise
+    "BitsAllClear",
+    "BitsAllSet",
+    "BitsAnyClear",
+    "BitsAnySet",
+    # Geospatial
+    "GeoIntersects",
+    "GeoWithin",
+    "Near",
+    "NearSphere",
+    # Miscellaneous
+    "Mod",
+    "JsonSchema",
+    "Where",
+    "Text",
+]

mongo_aggro/operators/array.py

@@ -0,0 +1,41 @@
+"""Array query operators for MongoDB aggregation."""
+
+from typing import Any
+
+from pydantic import Field
+
+from mongo_aggro.operators.base import QueryOperator
+
+
+class ElemMatch(QueryOperator):
+    """$elemMatch operator - matches array elements."""
+
+    conditions: dict[str, Any] = Field(
+        ..., description="Conditions for array elements"
+    )
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        return {"$elemMatch": self.conditions}
+
+
+class Size(QueryOperator):
+    """$size operator - matches arrays with specific length."""
+
+    size: int = Field(..., description="Array size to match")
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        return {"$size": self.size}
+
+
+class All(QueryOperator):
+    """$all operator - matches arrays containing all specified elements."""
+
+    values: list[Any] = Field(
+        ..., description="Values that must all be present"
+    )
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        return {"$all": self.values}
+
+
+__all__ = ["ElemMatch", "Size", "All"]