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

mongo_aggro/__init__.py

@@ -16,6 +16,13 @@ Example:
     >>>
     >>> # Pass directly to MongoDB - no need to call any methods
     >>> results = collection.aggregate(pipeline)
+
+Expression operators with Python syntax:
+    >>> from mongo_aggro import Match, Expr
+    >>> from mongo_aggro.expressions import F
+    >>>
+    >>> # Use Python operators for MongoDB expressions
+    >>> Match(query=Expr((F("status") == "active") & (F("age") > 18)))
 """
 
 from .accumulators import (
@@ -48,20 +55,185 @@ from .base import (
     BaseStage,
     Pipeline,
     SortSpec,
+    serialize_value,
+)
+from .expressions import (  # Arithmetic expressions; Set expressions; Comparison expressions; Array expressions; Conditional expressions; Type conversion expressions; Date expressions; Encrypted string expressions; Object expressions; Additional array expressions; Variable expressions; Miscellaneous expressions; Logical expressions; Window expressions; Regex expressions; String expressions
+    AbsExpr,
+    AcosExpr,
+    AcoshExpr,
+    AddExpr,
+    AllElementsTrueExpr,
+    AndExpr,
+    AnyElementTrueExpr,
+    ArrayElemAtExpr,
+    ArraySizeExpr,
+    ArrayToObjectExpr,
+    AsinExpr,
+    AsinhExpr,
+    Atan2Expr,
+    AtanExpr,
+    AtanhExpr,
+    BinarySizeExpr,
+    BitAndExpr,
+    BitNotExpr,
+    BitOrExpr,
+    BitXorExpr,
+    BottomExpr,
+    BottomNWindowExpr,
+    BsonSizeExpr,
+    CeilExpr,
+    CmpExpr,
+    ConcatArraysExpr,
+    ConcatExpr,
+    CondExpr,
+    ConvertExpr,
+    CosExpr,
+    CoshExpr,
+    CovariancePopExpr,
+    CovarianceSampExpr,
+    DateAddExpr,
+    DateDiffExpr,
+    DateFromPartsExpr,
+    DateFromStringExpr,
+    DateSubtractExpr,
+    DateToPartsExpr,
+    DateToStringExpr,
+    DateTruncExpr,
+    DayOfMonthExpr,
+    DayOfWeekExpr,
+    DayOfYearExpr,
+    DegreesToRadiansExpr,
+    DenseRankExpr,
+    DerivativeExpr,
+    DivideExpr,
+    DocumentNumberExpr,
+    EncStrContainsExpr,
+    EncStrEndsWithExpr,
+    EncStrNormalizedEqExpr,
+    EncStrStartsWithExpr,
+    EqExpr,
+    ExpExpr,
+    ExpMovingAvgExpr,
+    ExpressionBase,
+    F,
+    Field,
+    FilterExpr,
+    FirstNExpr,
+    FloorExpr,
+    GetFieldExpr,
+    GteExpr,
+    GtExpr,
+    HourExpr,
+    IfNullExpr,
+    InArrayExpr,
+    IndexOfArrayExpr,
+    IntegralExpr,
+    IsArrayExpr,
+    IsNumberExpr,
+    IsoDayOfWeekExpr,
+    IsoWeekExpr,
+    IsoWeekYearExpr,
+    LastNExpr,
+    LetExpr,
+    LinearFillExpr,
+    LiteralExpr,
+    LnExpr,
+    LocfExpr,
+    Log10Expr,
+    LogExpr,
+    LteExpr,
+    LtExpr,
+    LTrimExpr,
+    MapExpr,
+    MaxNExpr,
+    MergeObjectsExpr,
+    MillisecondExpr,
+    MinNExpr,
+    MinuteExpr,
+    ModExpr,
+    MonthExpr,
+    MultiplyExpr,
+    NeExpr,
+    NotExpr,
+    ObjectToArrayExpr,
+    OrExpr,
+    PowExpr,
+    RadiansToDegreesExpr,
+    RandExpr,
+    RangeExpr,
+    RankExpr,
+    ReduceExpr,
+    RegexFindAllExpr,
+    RegexFindExpr,
+    RegexMatchExpr,
+    ReplaceAllExpr,
+    ReplaceOneExpr,
+    ReverseArrayExpr,
+    RoundExpr,
+    RTrimExpr,
+    SecondExpr,
+    SetDifferenceExpr,
+    SetEqualsExpr,
+    SetFieldExpr,
+    SetIntersectionExpr,
+    SetIsSubsetExpr,
+    SetUnionExpr,
+    ShiftExpr,
+    SinExpr,
+    SinhExpr,
+    SliceExpr,
+    SortArrayExpr,
+    SplitExpr,
+    SqrtExpr,
+    StrCaseCmpExpr,
+    StrLenCPExpr,
+    SubstrCPExpr,
+    SubtractExpr,
+    SwitchBranch,
+    SwitchExpr,
+    TanExpr,
+    TanhExpr,
+    ToBoolExpr,
+    ToDateExpr,
+    ToDecimalExpr,
+    ToDoubleExpr,
+    ToIntExpr,
+    ToLongExpr,
+    ToLowerExpr,
+    ToObjectIdExpr,
+    TopExpr,
+    TopNWindowExpr,
+    ToStringExpr,
+    ToUpperExpr,
+    TrimExpr,
+    TruncExpr,
+    TypeExpr,
+    WeekExpr,
+    YearExpr,
 )
 from .operators import (
     All,
     And,
+    BitsAllClear,
+    BitsAllSet,
+    BitsAnyClear,
+    BitsAnySet,
     ElemMatch,
     Eq,
     Exists,
     Expr,
+    GeoIntersects,
+    GeoWithin,
     Gt,
     Gte,
     In,
+    JsonSchema,
     Lt,
     Lte,
+    Mod,
     Ne,
+    Near,
+    NearSphere,
     Nin,
     Nor,
     Not,
@@ -69,13 +241,19 @@ from .operators import (
     QueryOperator,
     Regex,
     Size,
+    Text,
     Type,
+    Where,
 )
 from .stages import (
     AddFields,
     Bucket,
     BucketAuto,
+    ChangeStream,
+    ChangeStreamSplitLargeEvent,
+    CollStats,
     Count,
+    CurrentOp,
     Densify,
     Documents,
     Facet,
@@ -83,16 +261,27 @@ from .stages import (
     GeoNear,
     GraphLookup,
     Group,
+    IndexStats,
     Limit,
+    ListClusterCatalog,
+    ListLocalSessions,
+    ListSampledQueries,
+    ListSearchIndexes,
+    ListSessions,
     Lookup,
     Match,
     Merge,
     Out,
+    PlanCacheStats,
     Project,
+    QuerySettings,
+    RankFusion,
     Redact,
     ReplaceRoot,
     ReplaceWith,
     Sample,
+    Search,
+    SearchMeta,
     Set,
     SetWindowFields,
     Skip,
@@ -101,6 +290,7 @@ from .stages import (
     UnionWith,
     Unset,
     Unwind,
+    VectorSearch,
 )
 
 __all__ = [
@@ -109,9 +299,182 @@ __all__ = [
     "BaseStage",
     "SortSpec",
     "AggregationInput",
+    "serialize_value",
     # Sort direction constants
     "ASCENDING",
     "DESCENDING",
+    # Expression operators (new)
+    "F",
+    "Field",
+    "ExpressionBase",
+    "EqExpr",
+    "NeExpr",
+    "GtExpr",
+    "GteExpr",
+    "LtExpr",
+    "LteExpr",
+    "CmpExpr",
+    "AndExpr",
+    "OrExpr",
+    "NotExpr",
+    # Arithmetic expressions
+    "AddExpr",
+    "SubtractExpr",
+    "MultiplyExpr",
+    "DivideExpr",
+    "AbsExpr",
+    "ModExpr",
+    # Conditional expressions
+    "CondExpr",
+    "IfNullExpr",
+    "SwitchExpr",
+    "SwitchBranch",
+    # String expressions
+    "ConcatExpr",
+    "SplitExpr",
+    "ToLowerExpr",
+    "ToUpperExpr",
+    # Array expressions
+    "ArraySizeExpr",
+    "SliceExpr",
+    "FilterExpr",
+    "MapExpr",
+    "ReduceExpr",
+    # Date expressions
+    "DateAddExpr",
+    "DateSubtractExpr",
+    "DateDiffExpr",
+    "DateToStringExpr",
+    "DateFromStringExpr",
+    # Type conversion expressions
+    "ToDateExpr",
+    "ToStringExpr",
+    "ToIntExpr",
+    "ToDoubleExpr",
+    "ToBoolExpr",
+    "ToObjectIdExpr",
+    "ConvertExpr",
+    "TypeExpr",
+    "ToLongExpr",
+    "ToDecimalExpr",
+    "IsNumberExpr",
+    # Set expressions
+    "SetUnionExpr",
+    "SetIntersectionExpr",
+    "SetDifferenceExpr",
+    "SetEqualsExpr",
+    "SetIsSubsetExpr",
+    "AnyElementTrueExpr",
+    "AllElementsTrueExpr",
+    # Object expressions
+    "MergeObjectsExpr",
+    "ObjectToArrayExpr",
+    "ArrayToObjectExpr",
+    "GetFieldExpr",
+    "SetFieldExpr",
+    # Variable expressions
+    "LetExpr",
+    # Miscellaneous expressions
+    "LiteralExpr",
+    "RandExpr",
+    # Additional array expressions
+    "ArrayElemAtExpr",
+    "ConcatArraysExpr",
+    "InArrayExpr",
+    "IndexOfArrayExpr",
+    "IsArrayExpr",
+    "ReverseArrayExpr",
+    "SortArrayExpr",
+    "RangeExpr",
+    "FirstNExpr",
+    "LastNExpr",
+    "MaxNExpr",
+    "MinNExpr",
+    # Additional string expressions
+    "TrimExpr",
+    "LTrimExpr",
+    "RTrimExpr",
+    "ReplaceOneExpr",
+    "ReplaceAllExpr",
+    "RegexMatchExpr",
+    "RegexFindExpr",
+    "RegexFindAllExpr",
+    "SubstrCPExpr",
+    "StrLenCPExpr",
+    "StrCaseCmpExpr",
+    # Additional arithmetic expressions
+    "CeilExpr",
+    "FloorExpr",
+    "RoundExpr",
+    "TruncExpr",
+    "SqrtExpr",
+    "PowExpr",
+    "ExpExpr",
+    "LnExpr",
+    "Log10Expr",
+    "LogExpr",
+    # Trigonometry expressions
+    "SinExpr",
+    "CosExpr",
+    "TanExpr",
+    "AsinExpr",
+    "AcosExpr",
+    "AtanExpr",
+    "Atan2Expr",
+    "SinhExpr",
+    "CoshExpr",
+    "TanhExpr",
+    "AsinhExpr",
+    "AcoshExpr",
+    "AtanhExpr",
+    "DegreesToRadiansExpr",
+    "RadiansToDegreesExpr",
+    # Bitwise expressions
+    "BitAndExpr",
+    "BitOrExpr",
+    "BitXorExpr",
+    "BitNotExpr",
+    # Data size expressions
+    "BsonSizeExpr",
+    "BinarySizeExpr",
+    # Date part expressions
+    "YearExpr",
+    "MonthExpr",
+    "DayOfMonthExpr",
+    "DayOfWeekExpr",
+    "DayOfYearExpr",
+    "HourExpr",
+    "MinuteExpr",
+    "SecondExpr",
+    "MillisecondExpr",
+    "WeekExpr",
+    "IsoWeekExpr",
+    "IsoWeekYearExpr",
+    "IsoDayOfWeekExpr",
+    "DateFromPartsExpr",
+    "DateToPartsExpr",
+    "DateTruncExpr",
+    # Window expressions
+    "RankExpr",
+    "DenseRankExpr",
+    "DocumentNumberExpr",
+    "ShiftExpr",
+    "ExpMovingAvgExpr",
+    "DerivativeExpr",
+    "IntegralExpr",
+    "CovariancePopExpr",
+    "CovarianceSampExpr",
+    "LinearFillExpr",
+    "LocfExpr",
+    "TopExpr",
+    "BottomExpr",
+    "TopNWindowExpr",
+    "BottomNWindowExpr",
+    # Encrypted string expressions
+    "EncStrContainsExpr",
+    "EncStrStartsWithExpr",
+    "EncStrEndsWithExpr",
+    "EncStrNormalizedEqExpr",
     # Query operators
     "QueryOperator",
     "And",
@@ -133,6 +496,21 @@ __all__ = [
     "ElemMatch",
     "Size",
     "All",
+    # Bitwise query operators
+    "BitsAllClear",
+    "BitsAllSet",
+    "BitsAnyClear",
+    "BitsAnySet",
+    # Geospatial query operators
+    "GeoIntersects",
+    "GeoWithin",
+    "Near",
+    "NearSphere",
+    # Misc query operators
+    "Mod",
+    "JsonSchema",
+    "Where",
+    "Text",
     # Accumulators
     "Accumulator",
     "Sum",
@@ -185,4 +563,26 @@ __all__ = [
     "Densify",
     "Fill",
     "Documents",
+    # Statistics stages
+    "CollStats",
+    "IndexStats",
+    "PlanCacheStats",
+    # Session stages
+    "ListSessions",
+    "ListLocalSessions",
+    "ListSampledQueries",
+    # Change stream stages
+    "ChangeStream",
+    "ChangeStreamSplitLargeEvent",
+    # Admin stages
+    "CurrentOp",
+    "ListClusterCatalog",
+    "ListSearchIndexes",
+    # Atlas search stages
+    "Search",
+    "SearchMeta",
+    "VectorSearch",
+    # Advanced stages
+    "QuerySettings",
+    "RankFusion",
 ]

mongo_aggro/accumulators.py

@@ -452,21 +452,39 @@ class MinN(Accumulator):
 
 def merge_accumulators(*accumulators: Accumulator) -> dict[str, Any]:
     """
-    Merge multiple accumulators into a single dictionary for Group stage.
+    Combine typed accumulator instances into a dict for Group stage.
+
+    This helper provides type-safe accumulator definitions with IDE
+    autocomplete and validation, instead of writing raw MongoDB dicts.
+
+    Args:
+        *accumulators: Accumulator instances (Sum, Avg, Max, etc.)
+
+    Returns:
+        Combined dict suitable for Group's accumulators parameter.
 
     Example:
-        >>> merge_accumulators(
-        ...     Sum(name="total", field="amount"),
-        ...     Avg(name="average", field="amount"),
-        ...     Count_(name="count")
+        Using typed accumulators (recommended for type safety):
+
+        >>> Group(
+        ...     id="$category",
+        ...     accumulators=merge_accumulators(
+        ...         Sum(name="total", field="amount"),
+        ...         Avg(name="average", field="price"),
+        ...         Count_(name="count"),
+        ...     )
+        ... )
+
+        Equivalent raw dict (less type safety):
+
+        >>> Group(
+        ...     id="$category",
+        ...     accumulators={
+        ...         "total": {"$sum": "$amount"},
+        ...         "average": {"$avg": "$price"},
+        ...         "count": {"$count": {}},
+        ...     }
         ... )
-        {
-            "total": {
-                "$sum": "$amount"},
-                "average": {"$avg": "$amount"},
-                "count": {"$count": {}
-            }
-        }
     """
     result: dict[str, Any] = {}
     for acc in accumulators:

mongo_aggro/base.py

@@ -1,12 +1,14 @@
 """Base classes for MongoDB aggregation pipeline stages."""
 
-from abc import ABC, abstractmethod
 from collections.abc import Iterator
-from typing import Any, Self
+from typing import TYPE_CHECKING, Any, Protocol, Self, runtime_checkable
 
-from pydantic import GetCoreSchemaHandler
+from pydantic import BaseModel, GetCoreSchemaHandler
 from pydantic_core import CoreSchema, core_schema
 
+if TYPE_CHECKING:
+    pass
+
 # Sort direction constants for use with Sort stage and with_sort method
 ASCENDING: int = 1
 DESCENDING: int = -1
@@ -18,10 +20,45 @@ SortSpec = dict[str, int]
 AggregationInput = tuple[list[dict[str, Any]], SortSpec]
 
 
-class BaseStage(ABC):
-    """Abstract base class for all MongoDB aggregation pipeline stages."""
+def serialize_value(v: Any) -> Any:
+    """
+    Recursively serialize values for MongoDB expressions.
+
+    Handles:
+    - Field objects: returns the field path string (e.g., "$status")
+    - BaseModel instances: calls model_dump() for Pydantic serialization
+    - Lists: recursively serializes each element
+    - Dicts: recursively serializes each value
+    - Other values: returns as-is
+
+    Args:
+        v: Any value to serialize
+
+    Returns:
+        MongoDB-compatible serialized value
+    """
+    # Import here to avoid circular imports
+    from mongo_aggro.expressions import Field
+
+    if isinstance(v, Field):
+        return str(v)
+    elif isinstance(v, BaseModel):
+        return v.model_dump()
+    elif isinstance(v, list):
+        return [serialize_value(item) for item in v]
+    elif isinstance(v, dict):
+        return {k: serialize_value(val) for k, val in v.items()}
+    return v
+
+
+@runtime_checkable
+class BaseStage(Protocol):
+    """Protocol for MongoDB aggregation pipeline stages.
+
+    Any class implementing model_dump() -> dict[str, Any] is a valid stage.
+    This enables structural typing - no inheritance required.
+    """
 
-    @abstractmethod
     def model_dump(self) -> dict[str, Any]:
         """
         Convert the stage to its MongoDB dictionary representation.
@@ -29,7 +66,7 @@ class BaseStage(ABC):
         Returns:
             dict[str, Any]: MongoDB aggregation stage dictionary
         """
-        pass
+        ...
 
 
 class Pipeline:
@@ -185,8 +222,11 @@ class Pipeline:
         return core_schema.is_instance_schema(cls)
 
 
-class _RawStage(BaseStage):
-    """Internal class for wrapping raw dictionary stages."""
+class _RawStage:
+    """Internal class for wrapping raw dictionary stages.
+
+    Implements BaseStage protocol.
+    """
 
     def __init__(self, raw: dict[str, Any]) -> None:
         self._raw = raw