AxiomQuery 0.1.0__py3-none-any.whl

axiom_query/__init__.py

@@ -0,0 +1,22 @@
+"""axiom_query — standalone specification-based query engine for SQLAlchemy ORM models."""
+
+__version__ = "0.1.0"
+
+from axiom_query.engine import QueryEngine
+from axiom_query.errors import QueryError
+from axiom_query.operators import Op
+from axiom_query.ast import Condition, And, Or, Not, Bool, QuerySpec
+from axiom_query.parser import parse_domain
+
+__all__ = [
+    "QueryEngine",
+    "QueryError",
+    "Op",
+    "Condition",
+    "And",
+    "Or",
+    "Not",
+    "Bool",
+    "QuerySpec",
+    "parse_domain",
+]

axiom_query/aggregation.py

@@ -0,0 +1,111 @@
+"""Immutable AST nodes for read_group (GROUP BY + aggregation) queries."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from axiom_query.ast import QuerySpec
+
+
+class AggFunc(str, Enum):
+    """Supported SQL aggregate functions."""
+
+    COUNT = "count"
+    SUM = "sum"
+    AVG = "avg"
+    MIN = "min"
+    MAX = "max"
+
+    @classmethod
+    def from_str(cls, s: str) -> AggFunc:
+        try:
+            return cls(s.lower())
+        except ValueError:
+            valid = ", ".join(m.value for m in cls)
+            raise ValueError(
+                f"Unknown aggregate function '{s}'. Valid: {valid}"
+            )
+
+
+class DateGranularity(str, Enum):
+    """Date truncation granularities for GROUP BY on date/datetime fields."""
+
+    DAY = "day"
+    WEEK = "week"
+    MONTH = "month"
+    QUARTER = "quarter"
+    YEAR = "year"
+
+    @classmethod
+    def from_str(cls, s: str) -> DateGranularity:
+        try:
+            return cls(s.lower())
+        except ValueError:
+            valid = ", ".join(m.value for m in cls)
+            raise ValueError(
+                f"Unknown date granularity '{s}'. Valid: {valid}"
+            )
+
+
+@dataclass(frozen=True)
+class AggregateSpec:
+    """One aggregate expression in the SELECT list."""
+
+    field_path: str | None
+    function: AggFunc
+    alias: str
+
+
+@dataclass(frozen=True)
+class GroupBySpec:
+    """One GROUP BY expression."""
+
+    field_path: str
+    granularity: DateGranularity | None = None
+
+    @property
+    def alias(self) -> str:
+        base = self.field_path.replace(".", "__")
+        if self.granularity is not None:
+            return f"{base}__{self.granularity.value}"
+        return base
+
+
+@dataclass(frozen=True)
+class Pagination:
+    """Presentation concerns for grouped queries."""
+
+    order_by: list[tuple[str, str]] | None = None
+    limit: int | None = None
+    offset: int | None = None
+
+
+@dataclass(frozen=True)
+class ReadGroupQuery:
+    """Complete read_group query specification."""
+
+    groupby: list[GroupBySpec]
+    aggregates: list[AggregateSpec]
+    domain: QuerySpec | None = None
+    having: QuerySpec | None = None
+
+    @property
+    def alias_map(self) -> dict[str, AggregateSpec | GroupBySpec]:
+        m: dict[str, AggregateSpec | GroupBySpec] = {}
+        for g in self.groupby:
+            m[g.alias] = g
+        for a in self.aggregates:
+            m[a.alias] = a
+        return m
+
+    @property
+    def referenced_child_entities(self) -> set[str]:
+        children: set[str] = set()
+        for g in self.groupby:
+            if "." in g.field_path:
+                children.add(g.field_path.split(".")[0])
+        for a in self.aggregates:
+            if a.field_path and "." in a.field_path:
+                children.add(a.field_path.split(".")[0])
+        return children

axiom_query/aggregation_parser.py

@@ -0,0 +1,186 @@
+"""Parse frontend JSON read_group requests into ReadGroupQuery AST nodes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from axiom_query.aggregation import (
+    AggFunc,
+    AggregateSpec,
+    DateGranularity,
+    GroupBySpec,
+    Pagination,
+    ReadGroupQuery,
+)
+
+
+def parse_read_group(raw: dict[str, Any]) -> tuple[ReadGroupQuery, Pagination]:
+    """Parse a JSON read_group request body into a (ReadGroupQuery, Pagination) tuple."""
+    from axiom_query.errors import QueryError
+
+    if not isinstance(raw, dict):
+        raise QueryError(
+            "INVALID_READ_GROUP",
+            f"read_group body must be a dict, got {type(raw).__name__}",
+        )
+
+    raw_groupby = raw.get("groupby", [])
+    if not isinstance(raw_groupby, list):
+        raise QueryError("INVALID_READ_GROUP", "groupby must be a list of strings")
+    groupby = [parse_groupby_spec(s) for s in raw_groupby]
+
+    raw_aggregates = raw.get("aggregates", ["__count"])
+    if not isinstance(raw_aggregates, list):
+        raise QueryError("INVALID_READ_GROUP", "aggregates must be a list of strings")
+    if not raw_aggregates:
+        raise QueryError(
+            "INVALID_READ_GROUP",
+            "aggregates must contain at least one spec (e.g. '__count')",
+        )
+    aggregates = [parse_aggregate_spec(s) for s in raw_aggregates]
+
+    domain = None
+    raw_domain = raw.get("domain")
+    if raw_domain is not None:
+        from axiom_query.parser import parse_domain
+        domain = parse_domain(raw_domain)
+
+    having = None
+    raw_having = raw.get("having")
+    if raw_having is not None:
+        from axiom_query.parser import parse_domain
+        having = parse_domain(raw_having)
+
+    order_by = None
+    raw_order = raw.get("order_by")
+    if raw_order is not None:
+        if not isinstance(raw_order, list):
+            raise QueryError(
+                "INVALID_READ_GROUP",
+                "order_by must be a list of [alias, direction] pairs",
+            )
+        order_by = _parse_order_by(raw_order)
+
+    limit = raw.get("limit")
+    if limit is not None and (not isinstance(limit, int) or limit < 0):
+        raise QueryError("INVALID_READ_GROUP", "limit must be a non-negative integer")
+
+    offset = raw.get("offset")
+    if offset is not None and (not isinstance(offset, int) or offset < 0):
+        raise QueryError("INVALID_READ_GROUP", "offset must be a non-negative integer")
+
+    query = ReadGroupQuery(
+        groupby=groupby,
+        aggregates=aggregates,
+        domain=domain,
+        having=having,
+    )
+
+    pagination = Pagination(
+        order_by=order_by,
+        limit=limit,
+        offset=offset,
+    )
+
+    return query, pagination
+
+
+def parse_aggregate_spec(spec: str) -> AggregateSpec:
+    """Parse a single aggregate spec string."""
+    from axiom_query.errors import QueryError
+
+    if not isinstance(spec, str) or not spec.strip():
+        raise QueryError(
+            "INVALID_AGGREGATION",
+            f"Aggregate spec must be a non-empty string, got {spec!r}",
+        )
+
+    spec = spec.strip()
+
+    if spec == "__count":
+        return AggregateSpec(field_path=None, function=AggFunc.COUNT, alias="__count")
+
+    if ":" not in spec:
+        raise QueryError(
+            "INVALID_AGGREGATION",
+            f"Aggregate spec must be 'field:function' or '__count', got '{spec}'",
+        )
+
+    parts = spec.rsplit(":", 1)
+    if len(parts) != 2 or not parts[0] or not parts[1]:
+        raise QueryError(
+            "INVALID_AGGREGATION",
+            f"Invalid aggregate spec format: '{spec}'. Expected 'field:function'.",
+        )
+
+    field_path, func_str = parts
+
+    try:
+        func = AggFunc.from_str(func_str)
+    except ValueError as e:
+        raise QueryError("INVALID_AGGREGATION", str(e))
+
+    alias = f"{field_path.replace('.', '__')}__{func.value}"
+
+    return AggregateSpec(field_path=field_path, function=func, alias=alias)
+
+
+def parse_groupby_spec(spec: str) -> GroupBySpec:
+    """Parse a single groupby spec string."""
+    from axiom_query.errors import QueryError
+
+    if not isinstance(spec, str) or not spec.strip():
+        raise QueryError(
+            "INVALID_AGGREGATION",
+            f"Groupby spec must be a non-empty string, got {spec!r}",
+        )
+
+    spec = spec.strip()
+
+    if ":" not in spec:
+        return GroupBySpec(field_path=spec)
+
+    parts = spec.rsplit(":", 1)
+    if len(parts) != 2 or not parts[0] or not parts[1]:
+        raise QueryError(
+            "INVALID_AGGREGATION",
+            f"Invalid groupby spec format: '{spec}'. Expected 'field:granularity'.",
+        )
+
+    field_path, granularity_str = parts
+
+    try:
+        granularity = DateGranularity.from_str(granularity_str)
+    except ValueError as e:
+        raise QueryError("INVALID_AGGREGATION", str(e))
+
+    return GroupBySpec(field_path=field_path, granularity=granularity)
+
+
+def _parse_order_by(raw: list[Any]) -> list[tuple[str, str]]:
+    from axiom_query.errors import QueryError
+
+    result: list[tuple[str, str]] = []
+    for item in raw:
+        if isinstance(item, str):
+            result.append((item, "asc"))
+        elif isinstance(item, (list, tuple)) and len(item) == 2:
+            alias, direction = item
+            if not isinstance(alias, str):
+                raise QueryError(
+                    "INVALID_READ_GROUP",
+                    f"order_by alias must be a string, got {type(alias).__name__}",
+                )
+            direction = str(direction).lower()
+            if direction not in ("asc", "desc"):
+                raise QueryError(
+                    "INVALID_READ_GROUP",
+                    f"order_by direction must be 'asc' or 'desc', got '{direction}'",
+                )
+            result.append((alias, direction))
+        else:
+            raise QueryError(
+                "INVALID_READ_GROUP",
+                "order_by items must be 'alias' or ['alias', 'asc'|'desc']",
+            )
+    return result

axiom_query/ast.py

@@ -0,0 +1,64 @@
+"""Immutable AST nodes for the query specification DSL."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Union
+
+from axiom_query.operators import Op
+
+
+@dataclass(frozen=True)
+class _Composable:
+    """Shared boolean composition operators."""
+
+    def __and__(self, other: QuerySpec) -> And:
+        return And(left=self, right=other)
+
+    def __or__(self, other: QuerySpec) -> Or:
+        return Or(left=self, right=other)
+
+    def __invert__(self) -> Not:
+        return Not(operand=self)
+
+
+@dataclass(frozen=True)
+class Condition(_Composable):
+    """Leaf node: ``field_path <operator> value``."""
+
+    field_path: str
+    operator: Op
+    value: Any
+
+
+@dataclass(frozen=True)
+class And(_Composable):
+    """Conjunction of two specs."""
+
+    left: QuerySpec
+    right: QuerySpec
+
+
+@dataclass(frozen=True)
+class Or(_Composable):
+    """Disjunction of two specs."""
+
+    left: QuerySpec
+    right: QuerySpec
+
+
+@dataclass(frozen=True)
+class Not(_Composable):
+    """Negation of a spec."""
+
+    operand: QuerySpec
+
+
+@dataclass(frozen=True)
+class Bool(_Composable):
+    """Constant true/false."""
+
+    value: bool
+
+
+QuerySpec = Union[Condition, And, Or, Not, Bool]

axiom_query/compiler.py

@@ -0,0 +1,207 @@
+"""Compile a QuerySpec AST into SQLAlchemy WHERE clause expressions."""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import Any, Callable
+
+from sqlalchemy import Date, DateTime, and_, exists, not_, or_, select, true, false
+from sqlalchemy.sql.expression import ColumnElement
+
+from axiom_query.ast import And, Bool, Condition, Not, Or, QuerySpec
+from axiom_query.operators import Op
+from axiom_query.schema import ModelSchema
+
+SAResolver = Callable[[str, Op, Any], ColumnElement]
+
+
+def _walk_ast(spec: QuerySpec, resolver: SAResolver) -> ColumnElement:
+    """Recursively compile a QuerySpec AST using the given resolver."""
+    match spec:
+        case Bool(value=True):
+            return true()
+        case Bool(value=False):
+            return false()
+        case And(left=left, right=right):
+            return and_(
+                _walk_ast(left, resolver),
+                _walk_ast(right, resolver),
+            )
+        case Or(left=left, right=right):
+            return or_(
+                _walk_ast(left, resolver),
+                _walk_ast(right, resolver),
+            )
+        case Not(operand=operand):
+            return not_(_walk_ast(operand, resolver))
+        case Condition(field_path=fp, operator=op, value=val):
+            return resolver(fp, op, val)
+        case _:
+            raise TypeError(f"Unknown QuerySpec node: {type(spec)}")
+
+
+def _make_alias_resolver(alias_map: dict[str, ColumnElement]) -> SAResolver:
+    """Create a HAVING resolver that resolves field paths against aggregate alias expressions."""
+    from axiom_query.errors import QueryError
+
+    def resolve(fp: str, op: Op, val: Any) -> ColumnElement:
+        expr = alias_map.get(fp)
+        if expr is None:
+            available = ", ".join(sorted(alias_map.keys()))
+            raise QueryError(
+                "INVALID_HAVING_FIELD",
+                f"HAVING field '{fp}' is not a groupby or aggregate alias. "
+                f"Available: {available}",
+            )
+        return _apply_having_operator(expr, op, val)
+
+    return resolve
+
+
+def _resolve_column(schema: ModelSchema, field_path: str) -> ColumnElement:
+    """Resolve a field path to its SA column, or raise QueryError."""
+    from axiom_query.errors import QueryError
+
+    if "." in field_path:
+        child_name, field_name = field_path.split(".", 1)
+        child = schema.children.get(child_name)
+        if child is None:
+            raise QueryError(
+                "INVALID_FILTER_FIELD",
+                f"No child relation '{child_name}' on {schema.model_class.__name__}. "
+                f"Available: {', '.join(schema.children.keys()) or 'none'}",
+            )
+        col = child.columns.get(field_name)
+        if col is None:
+            raise QueryError(
+                "INVALID_FILTER_FIELD",
+                f"No field '{field_name}' on child '{child_name}'",
+            )
+        return child.table.c[field_name]
+    else:
+        col = schema.columns.get(field_path)
+        if col is None:
+            raise QueryError(
+                "INVALID_FILTER_FIELD",
+                f"No field '{field_path}' on {schema.model_class.__name__}. "
+                f"Available: {', '.join(schema.columns.keys())}",
+            )
+        return schema.table.c[field_path]
+
+
+def _make_table_resolver(schema: ModelSchema) -> SAResolver:
+    """Create a WHERE resolver that resolves field paths against table columns."""
+
+    def resolve(fp: str, op: Op, val: Any) -> ColumnElement:
+        if "." in fp:
+            child_name, field_name = fp.split(".", 1)
+            from axiom_query.errors import QueryError
+
+            child = schema.children.get(child_name)
+            if child is None:
+                raise QueryError(
+                    "INVALID_FILTER_FIELD",
+                    f"No child relation '{child_name}' on {schema.model_class.__name__}",
+                )
+            fk_col = child.table.c[child.fk_field]
+            field_col = child.table.c[field_name]
+            condition = _apply_operator(field_col, op, val)
+            return exists(
+                select(1)
+                .select_from(child.table)
+                .where(and_(fk_col == schema.table.c.id, condition))
+            )
+        else:
+            col = _resolve_column(schema, fp)
+            return _apply_operator(col, op, val)
+
+    return resolve
+
+
+def compile_domain(spec: QuerySpec, schema: ModelSchema) -> ColumnElement:
+    """Compile a QuerySpec AST into a SQLAlchemy WHERE clause."""
+    resolver = _make_table_resolver(schema)
+    return _walk_ast(spec, resolver)
+
+
+def _coerce_value(col: Any, value: Any) -> Any:
+    """Coerce a string value to the column's Python type when needed."""
+    if not isinstance(value, str):
+        return value
+    col_type = getattr(col, "type", None)
+    if col_type is None:
+        return value
+    if isinstance(col_type, Date) and not isinstance(col_type, DateTime):
+        try:
+            return date.fromisoformat(value)
+        except ValueError:
+            try:
+                return datetime.fromisoformat(value).date()
+            except ValueError:
+                return value
+    if isinstance(col_type, DateTime):
+        try:
+            return datetime.fromisoformat(value)
+        except ValueError:
+            return value
+    return value
+
+
+def _apply_operator(col: Any, op: Op, value: Any) -> ColumnElement:
+    """Apply a comparison operator to a SQLAlchemy column."""
+    value = _coerce_value(col, value)
+    match op:
+        case Op.EQ:
+            return col == value
+        case Op.NE:
+            return col != value
+        case Op.GT:
+            return col > value
+        case Op.LT:
+            return col < value
+        case Op.GTE:
+            return col >= value
+        case Op.LTE:
+            return col <= value
+        case Op.IN:
+            items = [_coerce_value(col, v) for v in value] if isinstance(value, list) else value
+            return col.in_(items)
+        case Op.NOT_IN:
+            items = [_coerce_value(col, v) for v in value] if isinstance(value, list) else value
+            return col.not_in(items)
+        case Op.LIKE:
+            return col.like(value)
+        case Op.ILIKE:
+            return col.ilike(value)
+        case Op.IS_NULL:
+            return col.is_(None) if value else col.is_not(None)
+        case _:
+            raise ValueError(f"Unsupported operator: {op}")
+
+
+def _apply_having_operator(expr: ColumnElement, op: Op, value: Any) -> ColumnElement:
+    """Apply a comparison operator in HAVING context."""
+    match op:
+        case Op.EQ:
+            return expr == value
+        case Op.NE:
+            return expr != value
+        case Op.GT:
+            return expr > value
+        case Op.LT:
+            return expr < value
+        case Op.GTE:
+            return expr >= value
+        case Op.LTE:
+            return expr <= value
+        case Op.IN:
+            return expr.in_(value if isinstance(value, list) else [value])
+        case Op.NOT_IN:
+            return expr.not_in(value if isinstance(value, list) else [value])
+        case _:
+            from axiom_query.errors import QueryError
+
+            raise QueryError(
+                "INVALID_HAVING_OPERATOR",
+                f"Operator '{op.value}' is not supported in HAVING clauses",
+            )