athena-kit 1.0.0__py3-none-any.whl

athena_kit/__init__.py

@@ -0,0 +1,5 @@
+"""Athena Kit public namespace."""
+
+__all__ = ("__version__",)
+
+__version__ = "1.0.0"

athena_kit/_import_utils.py

@@ -0,0 +1,41 @@
+from importlib import import_module
+
+
+def import_attr(
+    attr_name: str,
+    module_name: str | None,
+    package: str | None,
+) -> object:
+    """Import an attribute from a module located in a package.
+
+    This utility function is used in custom `__getattr__` methods within `__init__.py`
+    files to dynamically import attributes.
+
+    Args:
+        attr_name: The name of the attribute to import.
+        module_name: The name of the module to import from.
+
+            If `None`, the attribute is imported from the package itself.
+        package: The name of the package where the module is located.
+
+    Returns:
+        The imported attribute.
+
+    Raises:
+        ImportError: If the module cannot be found.
+        AttributeError: If the attribute does not exist in the module or package.
+    """
+    if module_name == "__module__" or module_name is None:
+        try:
+            result = import_module(f".{attr_name}", package=package)
+        except ModuleNotFoundError:
+            msg = f"module '{package!r}' has no attribute {attr_name!r}"
+            raise AttributeError(msg) from None
+    else:
+        try:
+            module = import_module(f".{module_name}", package=package)
+        except ModuleNotFoundError as err:
+            msg = f"module '{package!r}.{module_name!r}' not found ({err})"
+            raise ImportError(msg) from None
+        result = getattr(module, attr_name)
+    return result

athena_kit/bosun/__init__.py

@@ -0,0 +1,32 @@
+from typing import TYPE_CHECKING
+
+from athena_kit._import_utils import import_attr
+
+if TYPE_CHECKING:
+    from athena_kit.bosun.parser import Lexer, Parser
+    from athena_kit.bosun.parser.preprocess import preprocess
+
+__all__ = (
+    "Lexer",
+    "Parser",
+    "preprocess",
+)
+
+_dynamic_imports = {
+    "Lexer": "parser",
+    "Parser": "parser",
+    "preprocess": "parser.preprocess",
+}
+
+
+def __getattr__(attr_name: str) -> object:
+    module_name = _dynamic_imports.get(attr_name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {attr_name!r}")
+    result = import_attr(attr_name, module_name, __spec__.parent)
+    globals()[attr_name] = result
+    return result
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

athena_kit/bosun/ast/__init__.py

@@ -0,0 +1,71 @@
+from typing import TYPE_CHECKING
+
+from athena_kit._import_utils import import_attr
+
+if TYPE_CHECKING:
+    from athena_kit.bosun.ast.nodes import (
+        BinaryOperatorExpression,
+        CallExpression,
+        Expression,
+        FloatLiteralExpression,
+        IntLiteralExpression,
+        LiteralExpression,
+        LiteralValue,
+        NameExpression,
+        Program,
+        StrLiteralExpression,
+        UnaryOperatorExpression,
+    )
+    from athena_kit.bosun.ast.queries import (
+        extract_all_queries,
+        extract_query,
+        render_calc_formula,
+        render_expression_formula,
+    )
+
+__all__ = (
+    "BinaryOperatorExpression",
+    "CallExpression",
+    "Expression",
+    "FloatLiteralExpression",
+    "IntLiteralExpression",
+    "LiteralExpression",
+    "LiteralValue",
+    "NameExpression",
+    "Program",
+    "StrLiteralExpression",
+    "UnaryOperatorExpression",
+    "extract_all_queries",
+    "extract_query",
+    "render_calc_formula",
+    "render_expression_formula",
+)
+
+_dynamic_imports = {
+    "BinaryOperatorExpression": "nodes",
+    "CallExpression": "nodes",
+    "Expression": "nodes",
+    "FloatLiteralExpression": "nodes",
+    "IntLiteralExpression": "nodes",
+    "LiteralExpression": "nodes",
+    "LiteralValue": "nodes",
+    "NameExpression": "nodes",
+    "Program": "nodes",
+    "StrLiteralExpression": "nodes",
+    "UnaryOperatorExpression": "nodes",
+    "extract_all_queries": "queries",
+    "extract_query": "queries",
+    "render_calc_formula": "queries",
+    "render_expression_formula": "queries",
+}
+
+
+def __getattr__(attr_name: str) -> object:
+    module_name = _dynamic_imports.get(attr_name)
+    result = import_attr(attr_name, module_name, __spec__.parent)
+    globals()[attr_name] = result
+    return result
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

athena_kit/bosun/ast/nodes.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from athena_kit.bosun.parser.tokens import Token
+
+type LiteralValue = int | float | str
+
+
+@dataclass(frozen=True, slots=True)
+class Program:
+    """Bosun 表达式 AST 根节点。
+
+    不承载 query 提取、公式生成等业务逻辑，需要分析 AST 时，请使用 `athena_kit.bosun.ast.queries` 中的函数。
+    """
+
+    expression: Expression
+
+
+class Expression:
+    """Bosun 表达式 AST 节点基类。
+
+    该基类用于统一表达式节点类型，方便 parser 和后续分析函数做类型标注与模式匹配。
+    它不定义行为，具体语义由子类表达。
+    """
+
+
+@dataclass(frozen=True, slots=True)
+class NameExpression(Expression):
+    """名称表达式。
+
+    当前主要用于表示函数调用左侧的函数名，例如 `q`、`avg`、`nv`。
+    """
+
+    name: str
+
+    def __str__(self) -> str:
+        return self.name
+
+
+@dataclass(frozen=True, slots=True)
+class LiteralExpression(Expression):
+    """字面量表达式基类。
+
+    保存 parser 从 token 中解析出的 Python 字面量值，具体子类用于区分整数、浮点数和字符串。
+    """
+
+    literal: LiteralValue
+
+    def __str__(self) -> str:
+        return str(self.literal)
+
+
+class IntLiteralExpression(LiteralExpression): ...
+
+
+class FloatLiteralExpression(LiteralExpression): ...
+
+
+class StrLiteralExpression(LiteralExpression):
+    """字符串字面量表达式。
+
+    `literal` 保存去掉外层双引号后的字符串内容，`__str__` 会重新补回双引号，用于表达式调试输出。
+    """
+
+    literal: str
+
+    def __str__(self) -> str:
+        return f'"{self.literal}"'
+
+
+@dataclass(frozen=True, slots=True)
+class UnaryOperatorExpression(Expression):
+    """一元运算表达式，表示 `+x`、`-x`、`!x` 这类前缀运算。
+
+    - `operator` 保留原始运算符 token。
+    - `right` 保存一元运算的右操作数。
+    """
+
+    operator: Token
+    right: Expression
+
+    def __str__(self) -> str:
+        return f"({self.operator.text}{self.right})"
+
+
+@dataclass(frozen=True, slots=True)
+class BinaryOperatorExpression(Expression):
+    """二元运算表达式，表示算术、比较和逻辑二元运算。
+
+    - `operator` 保留原始运算符 token。
+    - `left` 与 `right` 保存左右操作数。
+    """
+
+    left: Expression
+    operator: Token
+    right: Expression
+
+    def __str__(self) -> str:
+        return f"({self.left} {self.operator.text} {self.right})"
+
+
+@dataclass(frozen=True, slots=True)
+class CallExpression(Expression):
+    """函数调用表达式，表示 `func(arg1, arg2, ...)`。
+
+    - `function` 保存函数名。
+    - `args` 保存按原始顺序解析出的参数表达式列表。
+    """
+
+    function: str
+    args: list[Expression]
+
+    def __str__(self) -> str:
+        return f"{self.function}({','.join(str(arg) for arg in self.args)})"

athena_kit/bosun/ast/queries.py

@@ -0,0 +1,130 @@
+from athena_kit.bosun.ast.nodes import (
+    BinaryOperatorExpression,
+    CallExpression,
+    Expression,
+    LiteralExpression,
+    NameExpression,
+    Program,
+    StrLiteralExpression,
+    UnaryOperatorExpression,
+)
+from athena_kit.bosun.opentsdb import Query, parse_query
+
+_QUERY_WRAPPER_FUNCTIONS = frozenset({
+    "shift",
+    "sum",
+    "avg",
+    "max",
+    "min",
+    "fv",
+    "nv",
+    "nanas",
+})
+
+
+def extract_query(expr: Expression, queries: list[Query]) -> None:
+    """从表达式树中收集所有 `q(...)` 调用中的 OpenTSDB `Query`。
+
+    该函数会递归遍历表达式树，并把每个 `q(query_string, start, end)`
+    的第一个字符串参数解析为 `Query` 后追加到 `queries`。
+    `sum`、`avg`、`shift`、`nv` 等包装函数会继续向第一个参数内部递归，暂不支持的函数会抛出 `NotImplementedError`。
+    """
+    match expr:
+        case NameExpression() | LiteralExpression():
+            return
+
+        case UnaryOperatorExpression(right=right):
+            extract_query(right, queries)
+
+        case BinaryOperatorExpression(left=left, right=right):
+            extract_query(left, queries)
+            extract_query(right, queries)
+
+        case CallExpression(function="q", args=args):
+            queries.append(parse_query(_require_string_literal(args, "q")))
+        case CallExpression(function=function, args=args) if function in _QUERY_WRAPPER_FUNCTIONS:
+            extract_query(args[0], queries)
+        case CallExpression(function=function):
+            raise NotImplementedError(f"[Extract Expr Queries] Not implemented call function: {function}.")
+
+        case _:
+            raise NotImplementedError(f"[Extract Expr Queries] Not implemented expression: {expr}.")
+
+
+def extract_all_queries(program: Program) -> list[Query]:
+    """提取程序中出现的 OpenTSDB `Query`，并按首次出现顺序去重。
+
+    `Query` 的相等性由 `athena_kit.bosun.opentsdb.models.Query.__eq__` 决定，同一个查询即使出现在多个位置，
+    也只会保留第一次出现的实例。返回顺序用于后续生成 `$kpi0`、`$kpi1` 等稳定命名。
+    """
+    queries: list[Query] = []
+    extract_query(program.expression, queries)
+
+    distinct_queries: list[Query] = []
+    for query in queries:
+        if query not in distinct_queries:
+            distinct_queries.append(query)
+
+    return distinct_queries
+
+
+def render_expression_formula(expr: Expression, named_queries: dict[str, Query]) -> str:
+    """将表达式树中的 `q(...)` 调用替换为命名查询变量。
+
+    - `named_queries` 是变量名到 `Query` 的映射，例如 `{"$kpi0": query}`。
+    - 遍历过程中遇到 `q(...)` 时，会解析其查询字符串并查找等价 `Query`，然后返回对应变量名。
+    - 普通运算表达式会保留括号结构，包装函数会继续向第一个参数内部递归。
+    """
+    match expr:
+        case NameExpression(name=name):
+            return name
+
+        case LiteralExpression(literal=literal):
+            return str(literal)
+
+        case UnaryOperatorExpression(operator=operator, right=right):
+            return f"({operator.text}{render_expression_formula(right, named_queries)})"
+
+        case BinaryOperatorExpression(left=left, operator=operator, right=right):
+            left_formula = render_expression_formula(left, named_queries)
+            right_formula = render_expression_formula(right, named_queries)
+            return f"({left_formula}{operator.text}{right_formula})"
+
+        case CallExpression(function="q", args=args):
+            query: Query = parse_query(_require_string_literal(args, "q"))
+            for name, named_query in named_queries.items():
+                if query == named_query:
+                    return name
+            raise ValueError(f"Query is not registered in named_queries: {query}.")
+        case CallExpression(function=function, args=args) if function in _QUERY_WRAPPER_FUNCTIONS:
+            return render_expression_formula(args[0], named_queries)
+        case CallExpression(function=function):
+            raise NotImplementedError(f"[Extract Expr Queries Formula] Not implemented call function: {function}.")
+
+        case _:
+            raise NotImplementedError(f"[Extract Expr Queries Formula] Not implemented expression: {expr}.")
+
+
+def render_calc_formula(program: Program) -> str:
+    """生成命名查询定义和替换后的计算公式。
+
+    输出由两部分组成：
+
+    - 前半部分是 `$kpiN=query` 的查询定义列表。
+    - 后半部分是把原始表达式中的 `q(...)` 替换为 `$kpiN` 后的计算公式。
+
+    两部分之间使用空行分隔，便于直接展示或写入 Bosun 风格文本。
+    """
+    named_queries = {f"$kpi{index}": query for index, query in enumerate(extract_all_queries(program))}
+    formula = render_expression_formula(program.expression, named_queries)
+
+    query_definitions = "\n\n".join(f"{name}={query}" for name, query in named_queries.items())
+
+    return f"{query_definitions}\n\n{formula}"
+
+
+def _require_string_literal(args: list[Expression], function: str) -> str:
+    if not args or not isinstance(args[0], StrLiteralExpression):
+        raise ValueError(f"`{function}` first argument must be a string literal.")
+
+    return args[0].literal

athena_kit/bosun/opentsdb/__init__.py

@@ -0,0 +1,95 @@
+from typing import TYPE_CHECKING
+
+from athena_kit._import_utils import import_attr
+
+if TYPE_CHECKING:
+    from athena_kit.bosun.opentsdb.enums import Aggregator, FilterType, MultiFunction
+    from athena_kit.bosun.opentsdb.exceptions import OpenTSDBParseError
+    from athena_kit.bosun.opentsdb.intervals import calc_interval_seconds
+    from athena_kit.bosun.opentsdb.models import (
+        Downsampling,
+        MultiField,
+        Query,
+        Rate,
+        TagKv,
+        TopK,
+    )
+    from athena_kit.bosun.opentsdb.parser import (
+        parse_downsampling,
+        parse_multifield,
+        parse_query,
+        parse_rate,
+        parse_tagkv,
+        parse_topk,
+    )
+    from athena_kit.bosun.opentsdb.serializer import (
+        serialize_downsampling,
+        serialize_multifield,
+        serialize_query,
+        serialize_rate,
+        serialize_tagkv,
+        serialize_topk,
+    )
+
+__all__ = (
+    "Aggregator",
+    "FilterType",
+    "MultiFunction",
+    "OpenTSDBParseError",
+    "calc_interval_seconds",
+    "Downsampling",
+    "MultiField",
+    "Query",
+    "Rate",
+    "TagKv",
+    "TopK",
+    "parse_downsampling",
+    "parse_multifield",
+    "parse_query",
+    "parse_rate",
+    "parse_tagkv",
+    "parse_topk",
+    "serialize_downsampling",
+    "serialize_multifield",
+    "serialize_query",
+    "serialize_rate",
+    "serialize_tagkv",
+    "serialize_topk",
+)
+
+_dynamic_imports = {
+    "Aggregator": "enums",
+    "FilterType": "enums",
+    "MultiFunction": "enums",
+    "OpenTSDBParseError": "exceptions",
+    "calc_interval_seconds": "intervals",
+    "Downsampling": "models",
+    "MultiField": "models",
+    "Query": "models",
+    "Rate": "models",
+    "TagKv": "models",
+    "TopK": "models",
+    "parse_downsampling": "parser",
+    "parse_multifield": "parser",
+    "parse_query": "parser",
+    "parse_rate": "parser",
+    "parse_tagkv": "parser",
+    "parse_topk": "parser",
+    "serialize_downsampling": "serializer",
+    "serialize_multifield": "serializer",
+    "serialize_query": "serializer",
+    "serialize_rate": "serializer",
+    "serialize_tagkv": "serializer",
+    "serialize_topk": "serializer",
+}
+
+
+def __getattr__(attr_name: str) -> object:
+    module_name = _dynamic_imports.get(attr_name)
+    result = import_attr(attr_name, module_name, __spec__.parent)
+    globals()[attr_name] = result
+    return result
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

athena_kit/bosun/opentsdb/enums.py

@@ -0,0 +1,38 @@
+from enum import StrEnum
+
+
+class Aggregator(StrEnum):
+    SUM = "sum"
+    AVG = "avg"
+    MIN = "min"
+    MAX = "max"
+    COUNT = "count"
+    P50 = "p50"
+    P90 = "p90"
+    P99 = "p99"
+    P999 = "p999"
+    P9999 = "p9999"
+    P99999 = "p99999"
+    DEV = "dev"
+    ZIMSUM = "zimsum"
+    MINMIN = "minmin"
+    MINMAX = "minmax"
+
+
+class FilterType(StrEnum):
+    LITERAL_OR = "literal_or"
+    ILITERAL_OR = "iliteral_or"
+    NOT_LITERAL_OR = "not_literal_or"
+    NOT_ILITERAL_OR = "not_iliteral_or"
+    WILDCARD = "wildcard"
+    IWILDCARD = "iwildcard"
+    REGEXP = "regexp"
+
+
+class MultiFunction(StrEnum):
+    HIST_HEATMAP = "hist_heatmap"
+    HIST_SUM = "hist_sum"
+    HIST_COUNT = "hist_count"
+    HIST_AVG = "hist_avg"
+    HIST_PERCENTILE = "hist_percentile"
+    WEIGHTED_AVG = "weighted_avg"

athena_kit/bosun/opentsdb/exceptions.py

@@ -0,0 +1,2 @@
+class OpenTSDBParseError(ValueError):
+    """OpenTSDB 查询字符串解析失败。"""

athena_kit/bosun/opentsdb/intervals.py

@@ -0,0 +1,45 @@
+import re
+
+
+def calc_interval_seconds(interval: str) -> float:
+    """计算 OpenTSDB 时间间隔字符串对应的秒数。
+
+    支持由多个 `数字 + 单位` 片段连续组成的 interval，例如 `1m`、`1d12h30m`、`1s500ms`。
+    年份和月份使用固定近似值计算：`y` 按 365 天计算，`n` 按 30 天计算，`ms` 会转换为小数秒。
+
+    输入格式非法时抛出 `ValueError`。
+    """
+    # Time unit: y=years, n=months, w=weeks, d=days, h=hours, m=minutes, s=seconds, ms=milliseconds
+    if not re.fullmatch(r"(\d+(?:ms|[smhdwny]))+", interval):
+        raise ValueError(f"Illegal interval format: `{interval}`.")
+
+    duration_and_units = [du for du in re.split(r"(ms|y|n|w|d|h|m|s)", interval) if du != ""]
+    if len(duration_and_units) % 2 != 0:
+        raise ValueError(f"Illegal interval format: `{interval}`, duration and unit must appear in pairs.")
+
+    seconds = 0
+    for index, duration_str in enumerate(duration_and_units):
+        if index % 2 == 0:
+            duration = int(duration_str)
+            unit = duration_and_units[index + 1]
+            match unit:
+                case "y":
+                    base = 365 * 24 * 3600
+                case "n":
+                    base = 30 * 24 * 3600
+                case "w":
+                    base = 7 * 24 * 3600
+                case "d":
+                    base = 1 * 24 * 3600
+                case "h":
+                    base = 1 * 3600
+                case "m":
+                    base = 60
+                case "s":
+                    base = 1
+                case "ms":
+                    base = 0.001
+                case _:
+                    raise NotImplementedError(f"Unsupported time unit: {unit}.")
+            seconds += duration * base
+    return seconds