caxton 0.1.0__py3-none-any.whl

caxton/__init__.py

@@ -0,0 +1,215 @@
+from .api import (  # noqa: WPS347
+    AggregateExpr,
+    AggregateFunction,
+    BlockDirection,
+    BorderLine,
+    BorderLineStyle,
+    Borders,
+    CellAlignment,
+    ChartKind,
+    Column,
+    CorporateTheme,
+    CustomFormat,
+    DateFormat,
+    DecimalFormat,
+    DocumentTheme,
+    Expression,
+    FieldRef,
+    FillStyle,
+    FontStyle,
+    Freeze,
+    Grouping,
+    GroupOrder,
+    Matrix,
+    MoneyFormat,
+    PercentageFormat,
+    Style,
+    StyleSheet,
+    TemplateRepeat,
+    TemplateSpecification,
+    TimeFormat,
+    Total,
+    Totals,
+    VerticalAlignment,
+    absolute,
+    boolean,
+    chart,
+    col,
+    custom_format,
+    data_source,
+    date,
+    date_format,
+    datetime,
+    decimal,
+    decimal_format,
+    duration,
+    field,
+    image,
+    integer,
+    link,
+    matrix,
+    money,
+    money_format,
+    path,
+    percentage,
+    percentage_format,
+    ref,
+    render,
+    repeat,
+    sheet,
+    sheet_ref,
+    spacer,
+    spreadsheet,
+    stack,
+    table,
+    table_ref,
+    template,
+    text,
+    time,
+    time_format,
+    title,
+    validate,
+    when,
+    write,
+    xlsx,
+)
+from .core.errors import (
+    AggregateEvaluationError,
+    AmbiguousTemplateRefError,
+    BackendError,
+    CaxtonError,
+    CaxtonTypeError,
+    CaxtonValueError,
+    ColumnNotFoundError,
+    CyclicColumnError,
+    DataEvaluationError,
+    DataSourceConsumedError,
+    DataSourceError,
+    DataSourceIterationError,
+    DuplicateColumnError,
+    FieldAccessError,
+    GroupingError,
+    IncompatibleTemplateRefError,
+    InvalidOperationError,
+    InvalidTemplateRefError,
+    MatrixConflictError,
+    MissingFieldError,
+    MissingTemplateRefError,
+    RenderError,
+    SchemaError,
+    SourceEvaluationError,
+    TemplateError,
+    TemplateFormatError,
+    TemplateRefError,
+    UnsupportedDataSourceError,
+    UnsupportedFeatureError,
+    ValidationError,
+)
+from .core.rendering import ExecutionMode
+
+__all__ = (
+    "AggregateEvaluationError",
+    "AggregateExpr",
+    "AggregateFunction",
+    "AmbiguousTemplateRefError",
+    "BackendError",
+    "BlockDirection",
+    "BorderLine",
+    "BorderLineStyle",
+    "Borders",
+    "CaxtonError",
+    "CaxtonTypeError",
+    "CaxtonValueError",
+    "CellAlignment",
+    "ChartKind",
+    "Column",
+    "ColumnNotFoundError",
+    "CorporateTheme",
+    "CustomFormat",
+    "CyclicColumnError",
+    "DataEvaluationError",
+    "DataSourceConsumedError",
+    "DataSourceError",
+    "DataSourceIterationError",
+    "DateFormat",
+    "DecimalFormat",
+    "DocumentTheme",
+    "DuplicateColumnError",
+    "ExecutionMode",
+    "Expression",
+    "FieldAccessError",
+    "FieldRef",
+    "FillStyle",
+    "FontStyle",
+    "Freeze",
+    "GroupOrder",
+    "Grouping",
+    "GroupingError",
+    "IncompatibleTemplateRefError",
+    "InvalidOperationError",
+    "InvalidTemplateRefError",
+    "Matrix",
+    "MatrixConflictError",
+    "MissingFieldError",
+    "MissingTemplateRefError",
+    "MoneyFormat",
+    "PercentageFormat",
+    "RenderError",
+    "SchemaError",
+    "SourceEvaluationError",
+    "Style",
+    "StyleSheet",
+    "TemplateError",
+    "TemplateFormatError",
+    "TemplateRefError",
+    "TemplateRepeat",
+    "TemplateSpecification",
+    "TimeFormat",
+    "Total",
+    "Totals",
+    "UnsupportedDataSourceError",
+    "UnsupportedFeatureError",
+    "ValidationError",
+    "VerticalAlignment",
+    "absolute",
+    "boolean",
+    "chart",
+    "col",
+    "custom_format",
+    "data_source",
+    "date",
+    "date_format",
+    "datetime",
+    "decimal",
+    "decimal_format",
+    "duration",
+    "field",
+    "image",
+    "integer",
+    "link",
+    "matrix",
+    "money",
+    "money_format",
+    "path",
+    "percentage",
+    "percentage_format",
+    "ref",
+    "render",
+    "repeat",
+    "sheet",
+    "sheet_ref",
+    "spacer",
+    "spreadsheet",
+    "stack",
+    "table",
+    "table_ref",
+    "template",
+    "text",
+    "time",
+    "time_format",
+    "title",
+    "validate",
+    "when",
+    "write",
+    "xlsx",
+)

caxton/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

caxton/_internal/aggregation/__init__.py

@@ -0,0 +1,11 @@
+from .matrices import prepare_matrix
+from .models import PreparedColumn, PreparedTabularData, RelativeMerge
+from .tables import prepare_table
+
+__all__ = (
+    "PreparedColumn",
+    "PreparedTabularData",
+    "RelativeMerge",
+    "prepare_matrix",
+    "prepare_table",
+)

caxton/_internal/aggregation/execution.py

@@ -0,0 +1,315 @@
+from __future__ import annotations
+
+import dataclasses
+import warnings
+from collections.abc import Mapping, MutableMapping, Sequence
+from types import MappingProxyType
+from typing import Any
+
+from caxton._internal.semantic import SemanticRowEvaluator
+from caxton.core._values import normalize_cell_value
+from caxton.core.errors import AggregateEvaluationError, CaxtonError, PerformanceWarning
+from caxton.core.models import AggregateExpr, Column, Expression
+from caxton.core.protocols import DataSource
+from caxton.core.values import CellValue
+
+_BUFFERED_ROW_WARNING_THRESHOLD = 1_000_000
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class InputRow:
+    """Retained values needed after the original source row is released."""
+
+    index: int
+    values: Mapping[str, CellValue]
+    expressions: Mapping[Expression, object]
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self,
+            "expressions",
+            MappingProxyType(dict(self.expressions)),
+        )
+
+
+def read_rows(
+    source: DataSource[Any],
+    columns: Sequence[Column],
+    evaluator: SemanticRowEvaluator,
+    *,
+    aggregates: Sequence[AggregateExpr] = (),
+    path: str = "table",
+) -> tuple[InputRow, ...]:
+    """Read and evaluate retained row state in exactly one source pass.
+
+    Returns:
+        Buffered semantic and aggregate-input values.
+    """
+    rows: list[InputRow] = []
+    column_catalog = {column.id: column for column in columns}
+    for index, raw in evaluator.iter_source_rows(source):
+        rows.append(
+            evaluate_input_row(
+                source,
+                raw,
+                index,
+                columns,
+                aggregates,
+                evaluator,
+                column_catalog=column_catalog,
+            ),
+        )
+    output = tuple(rows)
+    warn_if_large_buffer(len(output), path=path, reason="grouping or aggregation")
+    return output
+
+
+def evaluate_input_row(  # noqa: WPS211
+    source: DataSource[Any],
+    raw: object,
+    index: int,
+    columns: Sequence[Column],
+    aggregates: Sequence[AggregateExpr],
+    evaluator: SemanticRowEvaluator,
+    *,
+    column_catalog: Mapping[str, Column],
+) -> InputRow:
+    """Evaluate all retained state before releasing an original row.
+
+    Returns:
+        A buffered input row without the original source object.
+    """
+    semantic = evaluator.evaluate_row(
+        source,
+        raw,
+        columns,
+        row_index=index,
+        column_catalog=column_catalog,
+    )
+    expressions = _evaluate_aggregate_expressions(
+        aggregates,
+        source=source,
+        raw=raw,
+        index=index,
+        columns=column_catalog,
+        values=semantic.values,
+        evaluator=evaluator,
+    )
+    return InputRow(
+        index=index,
+        values=semantic.values,
+        expressions=expressions,
+    )
+
+
+def _evaluate_aggregate_expressions(  # noqa: WPS211
+    aggregates: Sequence[AggregateExpr],
+    *,
+    source: DataSource[Any],
+    raw: object,
+    index: int,
+    columns: Mapping[str, Column],
+    values: Mapping[str, CellValue],
+    evaluator: SemanticRowEvaluator,
+) -> Mapping[Expression, object]:
+    filters = _unique_expressions(
+        tuple(aggregate.where for aggregate in aggregates),
+    )
+    output = _evaluate_expression_mapping(
+        filters,
+        source=source,
+        raw=raw,
+        index=index,
+        columns=columns,
+        values=values,
+        evaluator=evaluator,
+    )
+    inputs = _unique_expressions(
+        tuple(
+            expression
+            for aggregate in aggregates
+            if aggregate.where is None or bool(output[aggregate.where])
+            for expression in aggregate.expressions
+        ),
+    )
+    output.update(
+        _evaluate_expression_mapping(
+            inputs,
+            source=source,
+            raw=raw,
+            index=index,
+            columns=columns,
+            values=values,
+            evaluator=evaluator,
+        ),
+    )
+    return output
+
+
+def _evaluate_expression_mapping(  # noqa: WPS211
+    expressions: Sequence[Expression],
+    *,
+    source: DataSource[Any],
+    raw: object,
+    index: int,
+    columns: Mapping[str, Column],
+    values: Mapping[str, CellValue],
+    evaluator: SemanticRowEvaluator,
+) -> dict[Expression, object]:
+    results = evaluator.evaluate_expressions(
+        source,
+        raw,
+        columns,
+        expressions,
+        row_index=index,
+        values=values,
+    )
+    return dict(zip(expressions, results, strict=True))
+
+
+def _unique_expressions(
+    expressions: Sequence[Expression | None],
+) -> tuple[Expression, ...]:
+    output: dict[Expression, None] = {}
+    for expression in expressions:
+        if expression is not None:
+            output.setdefault(expression, None)
+    return tuple(output)
+
+
+def warn_if_large_buffer(row_count: int, *, path: str, reason: str) -> None:
+    """Warn once when a shape-dependent block retains a very large source."""
+    if row_count <= _BUFFERED_ROW_WARNING_THRESHOLD:
+        return
+    warnings.warn(
+        f"{path} buffered {row_count:,} rows for {reason}",
+        PerformanceWarning,
+        stacklevel=3,
+    )
+
+
+def execute_aggregate(
+    expression: AggregateExpr,
+    rows: Sequence[InputRow],
+    *,
+    path: str,
+    filter_cache: MutableMapping[
+        Expression | None,
+        tuple[InputRow, ...],
+    ]
+    | None = None,
+) -> CellValue:
+    """Execute one aggregate from captured values.
+
+    Returns:
+        The normalized aggregate result.
+    """
+    included = _included_rows(
+        expression.where,
+        rows,
+        filter_cache=filter_cache,
+    )
+    if not included and expression.has_default:
+        return normalize_cell_value(expression.default)
+    inputs = tuple(
+        tuple(row.expressions[item] for row in included)
+        for item in expression.expressions
+    )
+    function_name = getattr(
+        expression.function,
+        "__name__",
+        type(expression.function).__name__,
+    )
+    result = _call_aggregate(
+        expression,
+        inputs,
+        function_name=function_name,
+        scope_size=len(included),
+        path=path,
+    )
+    return _normalize_aggregate_result(
+        result,
+        function_name=function_name,
+        scope_size=len(included),
+        path=path,
+    )
+
+
+def _included_rows(
+    where: Expression | None,
+    rows: Sequence[InputRow],
+    *,
+    filter_cache: MutableMapping[
+        Expression | None,
+        tuple[InputRow, ...],
+    ]
+    | None,
+) -> tuple[InputRow, ...]:
+    if filter_cache is not None and where in filter_cache:
+        return filter_cache[where]
+    included = (
+        tuple(rows)
+        if where is None
+        else tuple(row for row in rows if bool(row.expressions[where]))
+    )
+    if filter_cache is not None:
+        filter_cache[where] = included
+    return included
+
+
+def _call_aggregate(
+    expression: AggregateExpr,
+    inputs: Sequence[Sequence[object]],
+    *,
+    function_name: str,
+    scope_size: int,
+    path: str,
+) -> object:
+    try:
+        return expression.function(*inputs)
+    except CaxtonError:
+        raise
+    except Exception as error:
+        message = f"Aggregate {function_name!r} failed"
+        raise AggregateEvaluationError(
+            message,
+            path=path,
+            context={
+                "exception_type": type(error).__name__,
+                "function": function_name,
+                "phase": "callable",
+                "scope_size": scope_size,
+            },
+        ) from error
+
+
+def _normalize_aggregate_result(
+    result: object,
+    *,
+    function_name: str,
+    scope_size: int,
+    path: str,
+) -> CellValue:
+    try:
+        return normalize_cell_value(result)
+    except Exception as error:
+        message = f"Aggregate {function_name!r} returned an unsupported result"
+        raise AggregateEvaluationError(
+            message,
+            path=path,
+            context={
+                "exception_type": type(error).__name__,
+                "function": function_name,
+                "phase": "result_normalization",
+                "scope_size": scope_size,
+            },
+        ) from error
+
+
+__all__ = (
+    "InputRow",
+    "evaluate_input_row",
+    "execute_aggregate",
+    "read_rows",
+    "warn_if_large_buffer",
+)

caxton/_internal/aggregation/keys.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import decimal
+from collections.abc import Callable, Sequence
+from typing import Any, TypeAlias, TypeVar, cast
+
+from caxton.core.errors import GroupingError
+from caxton.core.models import Column, GroupOrder
+from caxton.core.values import CellValue
+
+DimensionToken: TypeAlias = tuple[str, object]
+GroupKey: TypeAlias = tuple[CellValue, ...]
+TokenKey: TypeAlias = tuple[DimensionToken, ...]
+_Item = TypeVar("_Item")
+
+
+def dimension_token(value: object) -> DimensionToken:
+    """Return the stable, type-sensitive identity of one dimension value."""
+    type_name = f"{type(value).__module__}.{type(value).__qualname__}"
+    if isinstance(value, decimal.Decimal):
+        return type_name, value.as_tuple()
+    if isinstance(value, float):
+        if not value:
+            return type_name, value.hex().lstrip("-")
+        return type_name, value.hex()
+    return type_name, value
+
+
+def order_group_values(
+    items: Sequence[_Item],
+    column: Column,
+    value: Callable[[_Item], CellValue],
+    *,
+    path: str,
+) -> list[_Item]:
+    """Order dimension items with grouping's nulls-last semantics.
+
+    Returns:
+        A new list in the declared group order.
+
+    Raises:
+        GroupingError: If sorted values cannot be compared.
+    """
+    grouping = column.grouping
+    if grouping is None or grouping.order is GroupOrder.FIRST_SEEN:
+        return list(items)
+    non_null = [item for item in items if value(item) is not None]
+    nulls = [item for item in items if value(item) is None]
+    try:
+        ordered = sorted(
+            non_null,
+            key=lambda item: cast("Any", value(item)),
+            reverse=grouping.order is GroupOrder.DESCENDING,
+        )
+    except TypeError as error:
+        message = f"Group column {column.id!r} contains incomparable values"
+        raise GroupingError(
+            message,
+            path=f'{path}.column["{column.id}"].grouping',
+            context={
+                "column": column.id,
+                "order": grouping.order.value,
+                "value_types": sorted({type(value(item)).__name__ for item in items}),
+            },
+        ) from error
+    return [*ordered, *nulls]
+
+
+def key_token(key: GroupKey) -> TokenKey:
+    """Return the strict identity of one compound dimension key."""
+    return tuple(dimension_token(value) for value in key)
+
+
+__all__ = (
+    "GroupKey",
+    "TokenKey",
+    "dimension_token",
+    "key_token",
+    "order_group_values",
+)