promcraft 0.1.0__py3-none-any.whl

promcraft/__init__.py

@@ -0,0 +1,251 @@
+from promcraft.aggregation import (
+    AggregationOperator,
+    Grouping,
+    avg,
+    bottomk,
+    count,
+    count_values,
+    group,
+    limit_ratio,
+    limitk,
+    max,
+    min,
+    quantile,
+    stddev,
+    stdvar,
+    sum,
+    topk,
+)
+from promcraft.base import Query
+from promcraft.operator import (
+    BinaryOprator,
+    Group,
+    Match,
+    add,
+    and_,
+    atan2,
+    div,
+    eq,
+    gt,
+    gte,
+    lt,
+    lte,
+    mod,
+    mul,
+    neq,
+    or_,
+    pow,
+    sub,
+    unless,
+)
+from promcraft.scalar import Duration, Float, Hex, Scalar
+from promcraft.string import String
+from promcraft.vector import InstantVector, Label, RangeVector
+
+# isort: split
+# promcraft.functions must be imported AFTER promcraft.scalar and promcraft.vector so that
+# our 'scalar' and 'vector' function names overwrite the submodule bindings that Python
+# injects automatically when a submodule is imported.
+from promcraft.functions import (
+    Function,
+    abs,
+    absent,
+    absent_over_time,
+    acos,
+    acosh,
+    asin,
+    asinh,
+    atan,
+    atanh,
+    avg_over_time,
+    ceil,
+    changes,
+    clamp,
+    clamp_max,
+    clamp_min,
+    cos,
+    cosh,
+    count_over_time,
+    day_of_month,
+    day_of_week,
+    day_of_year,
+    days_in_month,
+    deg,
+    delta,
+    deriv,
+    double_exponential_smoothing,
+    exp,
+    floor,
+    histogram_avg,
+    histogram_count,
+    histogram_fraction,
+    histogram_quantile,
+    histogram_stddev,
+    histogram_stdvar,
+    histogram_sum,
+    hour,
+    idelta,
+    increase,
+    info,
+    irate,
+    label_join,
+    label_replace,
+    last_over_time,
+    ln,
+    log2,
+    log10,
+    max_over_time,
+    min_over_time,
+    minute,
+    month,
+    pi,
+    predict_linear,
+    present_over_time,
+    quantile_over_time,
+    rad,
+    rate,
+    resets,
+    round,
+    scalar,
+    sgn,
+    sin,
+    sinh,
+    sort,
+    sort_by_label,
+    sort_by_label_desc,
+    sort_desc,
+    sqrt,
+    stddev_over_time,
+    stdvar_over_time,
+    sum_over_time,
+    tan,
+    tanh,
+    time,
+    timestamp,
+    vector,
+    year,
+)
+
+__all__ = [
+    "AggregationOperator",
+    "BinaryOprator",
+    "Duration",
+    "Float",
+    "Function",
+    "Group",
+    "Grouping",
+    "Hex",
+    "InstantVector",
+    "Label",
+    "Match",
+    "Query",
+    "RangeVector",
+    "Scalar",
+    "String",
+    "abs",
+    "absent",
+    "absent_over_time",
+    "acos",
+    "acosh",
+    "add",
+    "and_",
+    "asin",
+    "asinh",
+    "atan",
+    "atan2",
+    "atanh",
+    "avg",
+    "avg_over_time",
+    "bottomk",
+    "ceil",
+    "changes",
+    "clamp",
+    "clamp_max",
+    "clamp_min",
+    "cos",
+    "cosh",
+    "count",
+    "count_over_time",
+    "count_values",
+    "day_of_month",
+    "day_of_week",
+    "day_of_year",
+    "days_in_month",
+    "deg",
+    "delta",
+    "deriv",
+    "div",
+    "double_exponential_smoothing",
+    "eq",
+    "exp",
+    "floor",
+    "group",
+    "gt",
+    "gte",
+    "histogram_avg",
+    "histogram_count",
+    "histogram_fraction",
+    "histogram_quantile",
+    "histogram_stddev",
+    "histogram_stdvar",
+    "histogram_sum",
+    "hour",
+    "idelta",
+    "increase",
+    "info",
+    "irate",
+    "label_join",
+    "label_replace",
+    "last_over_time",
+    "limit_ratio",
+    "limitk",
+    "ln",
+    "log2",
+    "log10",
+    "lt",
+    "lte",
+    "max",
+    "max_over_time",
+    "min",
+    "min_over_time",
+    "minute",
+    "mod",
+    "month",
+    "mul",
+    "neq",
+    "or_",
+    "pi",
+    "pow",
+    "predict_linear",
+    "present_over_time",
+    "quantile",
+    "quantile_over_time",
+    "rad",
+    "rate",
+    "resets",
+    "round",
+    "scalar",
+    "sgn",
+    "sin",
+    "sinh",
+    "sort",
+    "sort_by_label",
+    "sort_by_label_desc",
+    "sort_desc",
+    "sqrt",
+    "stddev",
+    "stddev_over_time",
+    "stdvar",
+    "stdvar_over_time",
+    "sub",
+    "sum",
+    "sum_over_time",
+    "tan",
+    "tanh",
+    "time",
+    "timestamp",
+    "topk",
+    "unless",
+    "vector",
+    "year",
+]

promcraft/aggregation.py

@@ -0,0 +1,225 @@
+import enum
+from typing import Literal
+
+from promcraft.base import Query
+from promcraft.scalar import Scalar
+from promcraft.string import String
+
+
+class Grouping:
+    """Aggregation grouping clause that controls which label dimensions appear in results.
+
+    - ``by(labels)``      — keep only the listed labels in the output.
+    - ``without(labels)`` — drop the listed labels; preserve all others.
+
+    Example::
+
+        Grouping.by(["job", "env"])  # → 'by(job, env)'
+        Grouping.without(["instance"])  # → 'without(instance)'
+    """
+
+    def __init__(self, type: Literal["by", "without"], labels: list[str]) -> None:
+        self.type = type
+        self.labels = labels
+
+    @classmethod
+    def by(cls, labels: list[str]) -> "Grouping":
+        """Return a ``by(labels)`` grouping clause."""
+        return cls("by", labels)
+
+    @classmethod
+    def without(cls, labels: list[str]) -> "Grouping":
+        """Return a ``without(labels)`` grouping clause."""
+        return cls("without", labels)
+
+    def __str__(self) -> str:
+        labels_str = ", ".join(self.labels)
+        return f"{self.type}({labels_str})"
+
+
+class AggregationOperator(Query):
+    """A PromQL aggregation expression that collapses multiple time series into fewer results.
+
+    Aggregation operators reduce a set of series by computing a single
+    output value per group.  An optional :class:`Grouping` clause
+    (``by`` / ``without``) controls which label dimensions define the groups.
+    Some operators (``topk``, ``bottomk``, ``count_values``, ``quantile``,
+    ``limitk``, ``limit_ratio``) require an additional scalar or string
+    ``parameter``.
+
+    The fluent :meth:`by` and :meth:`without` methods return new immutable
+    instances with the grouping applied.
+
+    Example::
+
+        AggregationOperator(AggregationOperator.Operator.SUM, v).by(["job"])
+        # → 'sum(v) by(job)'
+
+        AggregationOperator(AggregationOperator.Operator.TOPK, v, parameter=Float(5))
+        # → 'topk(5.0, v)'
+    """
+
+    class Operator(enum.Enum):
+        """Enum of all PromQL aggregation operators."""
+
+        SUM = "sum"
+        AVG = "avg"
+        MIN = "min"
+        MAX = "max"
+        COUNT = "count"
+        GROUP = "group"
+        STDDEV = "stddev"
+        STDVAR = "stdvar"
+        TOPK = "topk"
+        BOTTOMK = "bottomk"
+        COUNT_VALUES = "count_values"
+        QUANTILE = "quantile"
+        LIMITK = "limitk"
+        LIMIT_RATIO = "limit_ratio"
+
+        def __str__(self) -> str:
+            return self.value
+
+    def __init__(
+        self,
+        op: Operator,
+        vector: Query,
+        parameter: Scalar | String | None = None,
+        grouping: Grouping | None = None,
+    ) -> None:
+        self.op = op
+        self.vector = vector
+        self.parameter = parameter
+        self.grouping = grouping
+
+    def __str__(self) -> str:
+        grouping_str = f" {self.grouping}" if self.grouping else ""
+        if self.parameter is not None:
+            args = f"{self.parameter}, {self.vector}"
+        else:
+            args = str(self.vector)
+        return f"{self.op}({args}){grouping_str}"
+
+    def by(self, labels: list[str]) -> "AggregationOperator":
+        """Return a copy of this aggregation with a ``by(labels)`` grouping clause."""
+        return AggregationOperator(
+            op=self.op,
+            vector=self.vector,
+            parameter=self.parameter,
+            grouping=Grouping.by(labels),
+        )
+
+    def without(self, labels: list[str]) -> "AggregationOperator":
+        """Return a copy of this aggregation with a ``without(labels)`` grouping clause."""
+        return AggregationOperator(
+            op=self.op,
+            vector=self.vector,
+            parameter=self.parameter,
+            grouping=Grouping.without(labels),
+        )
+
+
+def sum(vector: Query, grouping: Grouping | None = None) -> AggregationOperator:
+    """Sum of all sample values across the aggregated dimensions (``sum(v)``)."""
+    return AggregationOperator(AggregationOperator.Operator.SUM, vector, grouping=grouping)
+
+
+def avg(vector: Query, grouping: Grouping | None = None) -> AggregationOperator:
+    """Arithmetic mean of sample values across the aggregated dimensions (``avg(v)``)."""
+    return AggregationOperator(AggregationOperator.Operator.AVG, vector, grouping=grouping)
+
+
+def min(vector: Query, grouping: Grouping | None = None) -> AggregationOperator:
+    """Smallest sample value across the aggregated dimensions (``min(v)``)."""
+    return AggregationOperator(AggregationOperator.Operator.MIN, vector, grouping=grouping)
+
+
+def max(vector: Query, grouping: Grouping | None = None) -> AggregationOperator:
+    """Largest sample value across the aggregated dimensions (``max(v)``)."""
+    return AggregationOperator(AggregationOperator.Operator.MAX, vector, grouping=grouping)
+
+
+def count(vector: Query, grouping: Grouping | None = None) -> AggregationOperator:
+    """Number of time series in the aggregated dimensions (``count(v)``)."""
+    return AggregationOperator(AggregationOperator.Operator.COUNT, vector, grouping=grouping)
+
+
+def group(vector: Query, grouping: Grouping | None = None) -> AggregationOperator:
+    """Return 1 for each group that contains at least one element (``group(v)``)."""
+    return AggregationOperator(AggregationOperator.Operator.GROUP, vector, grouping=grouping)
+
+
+def stddev(vector: Query, grouping: Grouping | None = None) -> AggregationOperator:
+    """Population standard deviation of sample values across the aggregated dimensions.
+
+    PromQL: ``stddev(v)``
+    """
+    return AggregationOperator(AggregationOperator.Operator.STDDEV, vector, grouping=grouping)
+
+
+def stdvar(vector: Query, grouping: Grouping | None = None) -> AggregationOperator:
+    """Population standard variance of sample values across the aggregated dimensions.
+
+    PromQL: ``stdvar(v)``
+    """
+    return AggregationOperator(AggregationOperator.Operator.STDVAR, vector, grouping=grouping)
+
+
+def topk(
+    parameter: Scalar, vector: Query, grouping: Grouping | None = None
+) -> AggregationOperator:
+    """Largest ``k`` sample values across the aggregated dimensions (``topk(k, v)``)."""
+    return AggregationOperator(
+        AggregationOperator.Operator.TOPK, vector, parameter=parameter, grouping=grouping
+    )
+
+
+def bottomk(
+    parameter: Scalar, vector: Query, grouping: Grouping | None = None
+) -> AggregationOperator:
+    """Smallest ``k`` sample values across the aggregated dimensions (``bottomk(k, v)``)."""
+    return AggregationOperator(
+        AggregationOperator.Operator.BOTTOMK, vector, parameter=parameter, grouping=grouping
+    )
+
+
+def count_values(
+    parameter: String, vector: Query, grouping: Grouping | None = None
+) -> AggregationOperator:
+    """Count the number of series per unique sample value, writing counts to ``parameter`` label.
+
+    PromQL: ``count_values(label, v)``
+    """
+    return AggregationOperator(
+        AggregationOperator.Operator.COUNT_VALUES, vector, parameter=parameter, grouping=grouping
+    )
+
+
+def quantile(
+    parameter: Scalar, vector: Query, grouping: Grouping | None = None
+) -> AggregationOperator:
+    """φ-quantile (0 ≤ φ ≤ 1) of sample values across the aggregated dimensions.
+
+    PromQL: ``quantile(φ, v)``
+    """
+    return AggregationOperator(
+        AggregationOperator.Operator.QUANTILE, vector, parameter=parameter, grouping=grouping
+    )
+
+
+def limitk(
+    parameter: Scalar, vector: Query, grouping: Grouping | None = None
+) -> AggregationOperator:
+    """Pseudo-randomly sample at most ``k`` series from the input (``limitk(k, v)``)."""
+    return AggregationOperator(
+        AggregationOperator.Operator.LIMITK, vector, parameter=parameter, grouping=grouping
+    )
+
+
+def limit_ratio(
+    parameter: Scalar, vector: Query, grouping: Grouping | None = None
+) -> AggregationOperator:
+    """Pseudo-randomly sample fraction ``r`` of series from the input (``limit_ratio(r, v)``)."""
+    return AggregationOperator(
+        AggregationOperator.Operator.LIMIT_RATIO, vector, parameter=parameter, grouping=grouping
+    )

promcraft/base.py

@@ -0,0 +1,90 @@
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from promcraft.operator import BinaryOprator
+
+
+class Query(ABC):
+    @abstractmethod
+    def __str__(self) -> str:
+        raise NotImplementedError(
+            "Subclasses must implement __str__ method",
+        )
+
+    def __add__(self, other: "Query") -> "BinaryOprator":
+        from promcraft.operator import add
+
+        return add(self, other)
+
+    def __sub__(self, other: "Query") -> "BinaryOprator":
+        from promcraft.operator import sub
+
+        return sub(self, other)
+
+    def __mul__(self, other: "Query") -> "BinaryOprator":
+        from promcraft.operator import mul
+
+        return mul(self, other)
+
+    def __truediv__(self, other: "Query") -> "BinaryOprator":
+        from promcraft.operator import div
+
+        return div(self, other)
+
+    def __mod__(self, other: "Query") -> "BinaryOprator":
+        from promcraft.operator import mod
+
+        return mod(self, other)
+
+    def __pow__(self, other: "Query") -> "BinaryOprator":
+        from promcraft.operator import pow
+
+        return pow(self, other)
+
+    def __eq__(self, other: object) -> "BinaryOprator":  # type: ignore[override]
+        from promcraft.operator import eq
+
+        if not isinstance(other, Query):
+            raise NotImplementedError("Cannot compare Query with non-Query object")
+        return eq(self, other)
+
+    def __hash__(self) -> int:
+        return id(self)
+
+    def __ne__(self, other: object) -> "BinaryOprator":  # type: ignore[override]
+        from promcraft.operator import neq
+
+        if not isinstance(other, Query):
+            raise NotImplementedError("Cannot compare Query with non-Query object")
+        return neq(self, other)
+
+    def __lt__(self, other: "Query") -> "BinaryOprator":
+        from promcraft.operator import lt
+
+        return lt(self, other)
+
+    def __le__(self, other: "Query") -> "BinaryOprator":
+        from promcraft.operator import lte
+
+        return lte(self, other)
+
+    def __gt__(self, other: "Query") -> "BinaryOprator":
+        from promcraft.operator import gt
+
+        return gt(self, other)
+
+    def __ge__(self, other: "Query") -> "BinaryOprator":
+        from promcraft.operator import gte
+
+        return gte(self, other)
+
+    def __and__(self, other: "Query") -> "BinaryOprator":
+        from promcraft.operator import and_
+
+        return and_(self, other)
+
+    def __or__(self, other: "Query") -> "BinaryOprator":
+        from promcraft.operator import or_
+
+        return or_(self, other)