sanjaya-sqlalchemy 0.1.0__tar.gz

sanjaya_sqlalchemy-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+node_modules/
+tsp-output/
+
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+.pytest_cache/
+
+# Internal planning docs (not for public repo)
+permissions.md
+docs/implementation-plan.md

sanjaya_sqlalchemy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Brennan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sanjaya_sqlalchemy-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: sanjaya-sqlalchemy
+Version: 0.1.0
+Summary: SQLAlchemy Core data-provider implementation for the Sanjaya reporting platform
+Project-URL: Repository, https://github.com/tjb1982/sanjaya
+Project-URL: Issues, https://github.com/tjb1982/sanjaya/issues
+Author: Tom Brennan
+License-Expression: MIT
+License-File: LICENSE
+Keywords: analytics,data-provider,reporting,sqlalchemy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: sanjaya-core~=0.1
+Requires-Dist: sqlalchemy<3,>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sanjaya-sqlalchemy
+
+SQLAlchemy Core data-provider implementation for the Sanjaya reporting platform.
+
+Translates the `DataProvider` interface from `sanjaya-core` into SQL queries using SQLAlchemy Core expressions. No ORM required.
+
+## Installation
+
+```
+pip install sanjaya-sqlalchemy
+```
+
+## Usage
+
+```python
+from sqlalchemy import MetaData, create_engine
+from sanjaya_core.types import ColumnMeta, DatasetCapabilities
+from sanjaya_core.enums import ColumnType
+from sanjaya_sqlalchemy import SQLAlchemyProvider
+
+engine = create_engine("postgresql://...")
+metadata = MetaData()
+metadata.reflect(bind=engine)
+
+provider = SQLAlchemyProvider(
+    key="trade_activity",
+    label="Trade Activity",
+    engine=engine,
+    selectable=metadata.tables["trade_activity"],
+    columns=[
+        ColumnMeta(name="id", label="ID", type=ColumnType.NUMBER),
+        ColumnMeta(name="desk", label="Desk", type=ColumnType.STRING),
+        ColumnMeta(name="amount", label="Amount", type=ColumnType.CURRENCY),
+    ],
+    capabilities=DatasetCapabilities(pivot=True),
+)
+```

sanjaya_sqlalchemy-0.1.0/README.md

@@ -0,0 +1,37 @@
+# sanjaya-sqlalchemy
+
+SQLAlchemy Core data-provider implementation for the Sanjaya reporting platform.
+
+Translates the `DataProvider` interface from `sanjaya-core` into SQL queries using SQLAlchemy Core expressions. No ORM required.
+
+## Installation
+
+```
+pip install sanjaya-sqlalchemy
+```
+
+## Usage
+
+```python
+from sqlalchemy import MetaData, create_engine
+from sanjaya_core.types import ColumnMeta, DatasetCapabilities
+from sanjaya_core.enums import ColumnType
+from sanjaya_sqlalchemy import SQLAlchemyProvider
+
+engine = create_engine("postgresql://...")
+metadata = MetaData()
+metadata.reflect(bind=engine)
+
+provider = SQLAlchemyProvider(
+    key="trade_activity",
+    label="Trade Activity",
+    engine=engine,
+    selectable=metadata.tables["trade_activity"],
+    columns=[
+        ColumnMeta(name="id", label="ID", type=ColumnType.NUMBER),
+        ColumnMeta(name="desk", label="Desk", type=ColumnType.STRING),
+        ColumnMeta(name="amount", label="Amount", type=ColumnType.CURRENCY),
+    ],
+    capabilities=DatasetCapabilities(pivot=True),
+)
+```

sanjaya_sqlalchemy-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sanjaya-sqlalchemy"
+version = "0.1.0"
+description = "SQLAlchemy Core data-provider implementation for the Sanjaya reporting platform"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Tom Brennan" },
+]
+keywords = ["reporting", "sqlalchemy", "data-provider", "analytics"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "sanjaya-core~=0.1",
+    "sqlalchemy>=2.0,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-cov",
+]
+
+[project.urls]
+Repository = "https://github.com/tjb1982/sanjaya"
+Issues = "https://github.com/tjb1982/sanjaya/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sanjaya_sqlalchemy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

sanjaya_sqlalchemy-0.1.0/src/sanjaya_sqlalchemy/__init__.py

@@ -0,0 +1,7 @@
+"""SQLAlchemy Core data-provider for the Sanjaya reporting platform."""
+
+__version__ = "0.1.0"
+
+from sanjaya_sqlalchemy.provider import SQLAlchemyProvider
+
+__all__ = ["SQLAlchemyProvider"]

sanjaya_sqlalchemy-0.1.0/src/sanjaya_sqlalchemy/filters.py

@@ -0,0 +1,109 @@
+"""Compile :class:`~sanjaya_core.filters.FilterGroup` trees into SQLAlchemy
+``WHERE`` clause expressions.
+
+The compiler walks the recursive filter model from *sanjaya-core* and
+produces a :class:`sqlalchemy.sql.expression.ColumnElement[bool]` that can be
+appended to any ``SELECT`` statement via ``.where()``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import sqlalchemy as sa
+from sqlalchemy.sql.expression import ColumnElement
+
+from sanjaya_core.enums import FilterCombinator, FilterOperator
+from sanjaya_core.filters import FilterCondition, FilterGroup
+
+
+def compile_filter_group(
+    fg: FilterGroup,
+    column_lookup: dict[str, ColumnElement[Any]],
+) -> ColumnElement[bool]:
+    """Translate a :class:`FilterGroup` into a SQLAlchemy boolean expression.
+
+    Parameters
+    ----------
+    fg:
+        The recursive filter tree to compile.
+    column_lookup:
+        Mapping of column *name* → SQLAlchemy :class:`Column`.  The compiler
+        looks up each :attr:`FilterCondition.column` here.
+
+    Returns
+    -------
+    A composable SQLAlchemy expression suitable for ``stmt.where(expr)``.
+
+    Raises
+    ------
+    KeyError
+        If a condition references a column not present in *column_lookup*.
+    """
+    parts: list[ColumnElement[bool]] = []
+
+    for cond in fg.conditions:
+        parts.append(_compile_condition(cond, column_lookup))
+
+    for sub in fg.groups:
+        parts.append(compile_filter_group(sub, column_lookup))
+
+    if not parts:
+        expr: ColumnElement[bool] = sa.literal(True)
+    elif fg.combinator == FilterCombinator.AND:
+        expr = sa.and_(*parts)
+    else:
+        expr = sa.or_(*parts)
+
+    if fg.negate:
+        expr = sa.not_(expr)
+
+    return expr
+
+
+def _compile_condition(
+    cond: FilterCondition,
+    column_lookup: dict[str, ColumnElement[Any]],
+) -> ColumnElement[bool]:
+    """Compile a single :class:`FilterCondition` to a SQLAlchemy expression."""
+    col = column_lookup[cond.column]
+    v = cond.value
+
+    expr: ColumnElement[bool]
+
+    match cond.operator:
+        case FilterOperator.EQ:
+            expr = col == v
+        case FilterOperator.NEQ:
+            expr = col != v
+        case FilterOperator.GT:
+            expr = col > v
+        case FilterOperator.LT:
+            expr = col < v
+        case FilterOperator.GTE:
+            expr = col >= v
+        case FilterOperator.LTE:
+            expr = col <= v
+        case FilterOperator.CONTAINS:
+            expr = col.contains(str(v), autoescape=True)
+        case FilterOperator.STARTSWITH:
+            expr = col.startswith(str(v), autoescape=True)
+        case FilterOperator.ENDSWITH:
+            expr = col.endswith(str(v), autoescape=True)
+        case FilterOperator.IS_NULL:
+            expr = col.is_(None)
+        case FilterOperator.IS_NOT_NULL:
+            expr = col.isnot(None)
+        case FilterOperator.BETWEEN:
+            lo, hi = v[0], v[1]
+            expr = col.between(lo, hi)
+        case FilterOperator.IN:
+            expr = col.in_(list(v))
+        case _:
+            # Unknown operator — match everything (safe fallback).
+            expr = sa.literal(True)
+
+    if cond.negate:
+        expr = sa.not_(expr)
+
+    return expr

sanjaya_sqlalchemy-0.1.0/src/sanjaya_sqlalchemy/provider.py

@@ -0,0 +1,409 @@
+"""SQLAlchemy Core implementation of :class:`~sanjaya_core.provider.DataProvider`.
+
+``SQLAlchemyProvider`` is configured with a SQLAlchemy :class:`~sqlalchemy.Table`
+(or selectable), a list of :class:`~sanjaya_core.types.ColumnMeta` definitions,
+and a :class:`~sqlalchemy.engine.Engine`.  It translates every provider
+method into SQL using SQLAlchemy Core expressions — no ORM required.
+
+Usage example::
+
+    from sqlalchemy import MetaData, create_engine
+    from sanjaya_core.types import ColumnMeta, DatasetCapabilities
+    from sanjaya_core.enums import ColumnType
+    from sanjaya_sqlalchemy import SQLAlchemyProvider
+
+    engine = create_engine("postgresql://...")
+    metadata = MetaData()
+    metadata.reflect(bind=engine)
+    trade_table = metadata.tables["trade_activity"]
+
+    provider = SQLAlchemyProvider(
+        key="trade_activity",
+        label="Trade Activity",
+        engine=engine,
+        selectable=trade_table,
+        columns=[
+            ColumnMeta(name="id", label="ID", type=ColumnType.NUMBER),
+            ColumnMeta(name="desk", label="Desk", type=ColumnType.STRING),
+            ColumnMeta(name="amount", label="Amount", type=ColumnType.CURRENCY),
+            ...
+        ],
+        capabilities=DatasetCapabilities(pivot=True),
+    )
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import sqlalchemy as sa
+from sqlalchemy import FromClause
+from sqlalchemy.engine import Engine
+from sqlalchemy.sql.expression import ColumnElement
+
+from sanjaya_core.context import RequestContext
+from sanjaya_core.enums import AggFunc, SortDirection
+from sanjaya_core.filters import FilterGroup
+from sanjaya_core.provider import DataProvider
+from sanjaya_core.types import (
+    AggregateColumn,
+    AggregateResult,
+    ColumnMeta,
+    DatasetCapabilities,
+    SortSpec,
+    TabularResult,
+    ValueSpec,
+)
+
+from sanjaya_sqlalchemy.filters import compile_filter_group
+
+
+class SQLAlchemyProvider(DataProvider):
+    """A :class:`DataProvider` backed by a SQLAlchemy selectable + engine.
+
+    Parameters
+    ----------
+    key:
+        Dataset identifier.
+    label:
+        Human-readable name.
+    engine:
+        A SQLAlchemy :class:`~sqlalchemy.engine.Engine` used to execute
+        queries.
+    selectable:
+        The table or subquery to query against (e.g. a
+        :class:`~sqlalchemy.Table` or ``select()``).
+    columns:
+        Column metadata definitions.  Each
+        :attr:`~sanjaya_core.types.ColumnMeta.name` must match a column
+        name in *selectable*.
+    description:
+        Optional description.
+    capabilities:
+        Optional capability flags.
+    """
+
+    def __init__(
+        self,
+        *,
+        key: str,
+        label: str,
+        engine: Engine,
+        selectable: FromClause,
+        columns: list[ColumnMeta],
+        description: str = "",
+        capabilities: DatasetCapabilities | None = None,
+    ) -> None:
+        super().__init__(
+            key=key,
+            label=label,
+            description=description,
+            capabilities=capabilities or DatasetCapabilities(pivot=True),
+        )
+        self._engine = engine
+        self._selectable = selectable
+        self._columns = columns
+        self._column_lookup: dict[str, ColumnElement[Any]] = {
+            c.name: selectable.c[c.name] for c in columns
+        }
+
+    # ------------------------------------------------------------------
+    # DataProvider interface
+    # ------------------------------------------------------------------
+
+    def get_columns(self) -> list[ColumnMeta]:
+        return list(self._columns)
+
+    def query(
+        self,
+        selected_columns: list[str],
+        *,
+        filter_group: FilterGroup | None = None,
+        sort: list[SortSpec] | None = None,
+        limit: int = 100,
+        offset: int = 0,
+        ctx: RequestContext | None = None,
+    ) -> TabularResult:
+        # --- count ---
+        count_stmt = sa.select(sa.func.count()).select_from(self._selectable)
+        if filter_group:
+            count_stmt = count_stmt.where(
+                compile_filter_group(filter_group, self._column_lookup)
+            )
+
+        # --- data ---
+        cols = [self._column_lookup[c] for c in selected_columns]
+        data_stmt = sa.select(*cols).select_from(self._selectable)
+        if filter_group:
+            data_stmt = data_stmt.where(
+                compile_filter_group(filter_group, self._column_lookup)
+            )
+        data_stmt = self._apply_sort(data_stmt, sort)
+        data_stmt = data_stmt.limit(limit).offset(offset)
+
+        with self._engine.connect() as conn:
+            total = conn.execute(count_stmt).scalar_one()
+            rows = [dict(r._mapping) for r in conn.execute(data_stmt)]
+
+        return TabularResult(columns=selected_columns, rows=rows, total=total)
+
+    def aggregate(
+        self,
+        group_by_rows: list[str],
+        group_by_cols: list[str],
+        values: list[ValueSpec],
+        *,
+        filter_group: FilterGroup | None = None,
+        sort: list[SortSpec] | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+        ctx: RequestContext | None = None,
+    ) -> AggregateResult:
+        if group_by_cols:
+            return self._pivot_aggregate(
+                group_by_rows, group_by_cols, values,
+                filter_group=filter_group, sort=sort,
+                limit=limit, offset=offset,
+            )
+        return self._simple_aggregate(
+            group_by_rows, values,
+            filter_group=filter_group, sort=sort,
+            limit=limit, offset=offset,
+        )
+
+    # ------------------------------------------------------------------
+    # Internal: simple (non-pivot) aggregation
+    # ------------------------------------------------------------------
+
+    def _simple_aggregate(
+        self,
+        group_by_rows: list[str],
+        values: list[ValueSpec],
+        *,
+        filter_group: FilterGroup | None = None,
+        sort: list[SortSpec] | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+    ) -> AggregateResult:
+        # Build SELECT clause: group-by columns + aggregate expressions.
+        group_cols = [self._column_lookup[c] for c in group_by_rows]
+        agg_exprs: list[tuple[str, ColumnElement[Any]]] = []
+        result_columns: list[AggregateColumn] = []
+
+        for col_name in group_by_rows:
+            result_columns.append(
+                AggregateColumn(key=col_name, header=col_name)
+            )
+
+        for vs in values:
+            key = f"{vs.agg}_{vs.column}"
+            sa_expr = self._agg_expression(vs)
+            agg_exprs.append((key, sa_expr))
+            result_columns.append(
+                AggregateColumn(
+                    key=key,
+                    header=vs.label or key,
+                    measure=vs.column,
+                    agg=vs.agg,
+                )
+            )
+
+        select_cols = [
+            *[c.label(c.name) for c in group_cols],
+            *[expr.label(key) for key, expr in agg_exprs],
+        ]
+
+        # --- count (total groups) ---
+        count_sub = (
+            sa.select(*[c.label(c.name) for c in group_cols])
+            .select_from(self._selectable)
+            .group_by(*group_cols)
+        )
+        if filter_group:
+            count_sub = count_sub.where(
+                compile_filter_group(filter_group, self._column_lookup)
+            )
+        count_stmt = sa.select(sa.func.count()).select_from(count_sub.subquery())
+
+        # --- data ---
+        data_stmt = (
+            sa.select(*select_cols)
+            .select_from(self._selectable)
+            .group_by(*group_cols)
+        )
+        if filter_group:
+            data_stmt = data_stmt.where(
+                compile_filter_group(filter_group, self._column_lookup)
+            )
+        data_stmt = self._apply_sort(data_stmt, sort)
+        if limit is not None:
+            data_stmt = data_stmt.limit(limit)
+        data_stmt = data_stmt.offset(offset)
+
+        with self._engine.connect() as conn:
+            total = conn.execute(count_stmt).scalar_one()
+            rows = [dict(r._mapping) for r in conn.execute(data_stmt)]
+
+        return AggregateResult(columns=result_columns, rows=rows, total=total)
+
+    # ------------------------------------------------------------------
+    # Internal: pivot aggregation
+    # ------------------------------------------------------------------
+
+    def _pivot_aggregate(
+        self,
+        group_by_rows: list[str],
+        group_by_cols: list[str],
+        values: list[ValueSpec],
+        *,
+        filter_group: FilterGroup | None = None,
+        sort: list[SortSpec] | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+    ) -> AggregateResult:
+        """Two-pass pivot: discover combos, then aggregate per combo.
+
+        SQLAlchemy Core doesn't have built-in PIVOT support, so we:
+        1. Query distinct pivot-column combinations.
+        2. Build one ``CASE WHEN … END`` per (combo × measure) to simulate
+           a pivot in a single grouped query.
+        """
+        where_clause: ColumnElement[bool] | None = None
+        if filter_group:
+            where_clause = compile_filter_group(
+                filter_group, self._column_lookup
+            )
+
+        # --- pass 1: discover distinct pivot combos ---
+        pivot_sa_cols = [self._column_lookup[c] for c in group_by_cols]
+        combo_stmt = (
+            sa.select(*pivot_sa_cols)
+            .select_from(self._selectable)
+            .distinct()
+        )
+        if where_clause is not None:
+            combo_stmt = combo_stmt.where(where_clause)
+        # Deterministic ordering of combos.
+        combo_stmt = combo_stmt.order_by(*pivot_sa_cols)
+
+        with self._engine.connect() as conn:
+            combos = [tuple(r._mapping[c] for c in group_by_cols) for r in conn.execute(combo_stmt)]
+
+        # --- build result column metadata + CASE expressions ---
+        group_row_cols = [self._column_lookup[c] for c in group_by_rows]
+
+        result_columns: list[AggregateColumn] = []
+        for col_name in group_by_rows:
+            result_columns.append(
+                AggregateColumn(key=col_name, header=col_name)
+            )
+
+        case_exprs: list[tuple[str, ColumnElement[Any]]] = []
+
+        for combo in combos:
+            # Build the CASE WHEN condition for this combo.
+            combo_cond = sa.and_(
+                *(
+                    self._column_lookup[group_by_cols[i]] == combo[i]
+                    for i in range(len(group_by_cols))
+                )
+            )
+            for vs in values:
+                pivot_key_parts = [str(v) for v in combo]
+                col_key = "_".join(pivot_key_parts + [vs.agg, vs.column])
+                result_columns.append(
+                    AggregateColumn(
+                        key=col_key,
+                        header=col_key,
+                        pivot_keys=pivot_key_parts,
+                        measure=vs.column,
+                        agg=vs.agg,
+                    )
+                )
+                # CASE WHEN <combo_cond> THEN <measure_col> END → wrapped in agg
+                measure_col = self._column_lookup[vs.column]
+                case_expr = sa.case((combo_cond, measure_col))
+                agg_expr = self._wrap_agg(vs.agg, case_expr)
+                case_exprs.append((col_key, agg_expr))
+
+        # --- pass 2: grouped query with CASE expressions ---
+        select_cols = [
+            *[c.label(c.name) for c in group_row_cols],
+            *[expr.label(key) for key, expr in case_exprs],
+        ]
+
+        # count total groups
+        count_sub = (
+            sa.select(*[c.label(c.name) for c in group_row_cols])
+            .select_from(self._selectable)
+            .group_by(*group_row_cols)
+        )
+        if where_clause is not None:
+            count_sub = count_sub.where(where_clause)
+        count_stmt = sa.select(sa.func.count()).select_from(count_sub.subquery())
+
+        data_stmt = (
+            sa.select(*select_cols)
+            .select_from(self._selectable)
+            .group_by(*group_row_cols)
+        )
+        if where_clause is not None:
+            data_stmt = data_stmt.where(where_clause)
+        data_stmt = self._apply_sort(data_stmt, sort)
+        if limit is not None:
+            data_stmt = data_stmt.limit(limit)
+        data_stmt = data_stmt.offset(offset)
+
+        with self._engine.connect() as conn:
+            total = conn.execute(count_stmt).scalar_one()
+            rows = [dict(r._mapping) for r in conn.execute(data_stmt)]
+
+        return AggregateResult(columns=result_columns, rows=rows, total=total)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _apply_sort(
+        self,
+        stmt: sa.Select[Any],
+        sort: list[SortSpec] | None,
+    ) -> sa.Select[Any]:
+        """Append ORDER BY clauses to *stmt*."""
+        if not sort:
+            return stmt
+        clauses = []
+        for spec in sort:
+            col = self._column_lookup[spec.column]
+            clauses.append(
+                col.desc() if spec.direction == SortDirection.DESC else col.asc()
+            )
+        return stmt.order_by(*clauses)
+
+    def _agg_expression(self, vs: ValueSpec) -> ColumnElement[Any]:
+        """Build a SQLAlchemy aggregate expression for a :class:`ValueSpec`."""
+        col = self._column_lookup[vs.column]
+        return self._wrap_agg(vs.agg, col)
+
+    @staticmethod
+    def _wrap_agg(agg: AggFunc, expr: ColumnElement[Any]) -> ColumnElement[Any]:
+        """Wrap *expr* in the SQL aggregate function for *agg*."""
+        match agg:
+            case AggFunc.SUM:
+                return sa.func.sum(expr)
+            case AggFunc.AVG:
+                return sa.func.avg(expr)
+            case AggFunc.MIN:
+                return sa.func.min(expr)
+            case AggFunc.MAX:
+                return sa.func.max(expr)
+            case AggFunc.COUNT:
+                return sa.func.count(expr)
+            case AggFunc.DISTINCT_COUNT:
+                return sa.func.count(sa.distinct(expr))
+            case AggFunc.FIRST:
+                return sa.func.min(expr)  # approximation — no SQL FIRST
+            case AggFunc.LAST:
+                return sa.func.max(expr)  # approximation — no SQL LAST
+            case _:
+                return sa.func.count(expr)

sanjaya_sqlalchemy-0.1.0/tests/conftest.py

@@ -0,0 +1,97 @@
+"""Shared fixtures for sanjaya-sqlalchemy tests.
+
+Uses an in-memory SQLite database with a ``trades`` table pre-populated
+with deterministic sample data.  The schema and data are designed to
+exercise flat queries, simple aggregation, and pivot aggregation.
+"""
+
+from __future__ import annotations
+
+import pytest
+import sqlalchemy as sa
+
+from sanjaya_core.enums import AggFunc, ColumnType
+from sanjaya_core.types import (
+    ColumnMeta,
+    ColumnPivotOptions,
+    DatasetCapabilities,
+    PivotAggOption,
+)
+
+from sanjaya_sqlalchemy import SQLAlchemyProvider
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(scope="session")
+def engine() -> sa.engine.Engine:
+    return sa.create_engine("sqlite:///:memory:")
+
+
+@pytest.fixture(scope="session")
+def trades_table(engine: sa.engine.Engine) -> sa.Table:
+    metadata = sa.MetaData()
+    table = sa.Table(
+        "trades",
+        metadata,
+        sa.Column("id", sa.Integer, primary_key=True),
+        sa.Column("desk", sa.String(50)),
+        sa.Column("region", sa.String(50)),
+        sa.Column("instrument", sa.String(50)),
+        sa.Column("amount", sa.Float),
+        sa.Column("quantity", sa.Integer),
+    )
+    metadata.create_all(engine)
+
+    rows = [
+        {"id": 1, "desk": "FX",    "region": "US",   "instrument": "EURUSD", "amount": 1000.0, "quantity": 10},
+        {"id": 2, "desk": "FX",    "region": "US",   "instrument": "GBPUSD", "amount": 2000.0, "quantity": 20},
+        {"id": 3, "desk": "FX",    "region": "EU",   "instrument": "EURUSD", "amount": 1500.0, "quantity": 15},
+        {"id": 4, "desk": "Rates", "region": "US",   "instrument": "T-Note", "amount": 5000.0, "quantity": 50},
+        {"id": 5, "desk": "Rates", "region": "EU",   "instrument": "Bund",   "amount": 3000.0, "quantity": 30},
+        {"id": 6, "desk": "Rates", "region": "APAC", "instrument": "JGB",    "amount": 4000.0, "quantity": 40},
+        {"id": 7, "desk": "FX",    "region": "APAC", "instrument": "USDJPY", "amount":  500.0, "quantity":  5},
+    ]
+    with engine.begin() as conn:
+        conn.execute(table.insert(), rows)
+
+    return table
+
+
+COLUMN_DEFS = [
+    ColumnMeta(name="id",         label="ID",         type=ColumnType.NUMBER),
+    ColumnMeta(name="desk",       label="Desk",       type=ColumnType.STRING),
+    ColumnMeta(name="region",     label="Region",     type=ColumnType.STRING),
+    ColumnMeta(name="instrument", label="Instrument", type=ColumnType.STRING),
+    ColumnMeta(
+        name="amount",
+        label="Amount",
+        type=ColumnType.CURRENCY,
+        pivot=ColumnPivotOptions(
+            role="measure",
+            allowed_aggs=[
+                PivotAggOption(agg=AggFunc.SUM, label="Sum"),
+                PivotAggOption(agg=AggFunc.AVG, label="Avg"),
+            ],
+        ),
+    ),
+    ColumnMeta(name="quantity",   label="Quantity",   type=ColumnType.NUMBER),
+]
+
+
+@pytest.fixture(scope="session")
+def provider(
+    engine: sa.engine.Engine,
+    trades_table: sa.Table,
+) -> SQLAlchemyProvider:
+    return SQLAlchemyProvider(
+        key="trades",
+        label="Trades",
+        engine=engine,
+        selectable=trades_table,
+        columns=COLUMN_DEFS,
+        capabilities=DatasetCapabilities(pivot=True),
+    )

sanjaya_sqlalchemy-0.1.0/tests/test_filters.py

@@ -0,0 +1,159 @@
+"""Tests for the SQLAlchemy filter compiler."""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from sqlalchemy.engine import Engine
+
+from sanjaya_core.enums import FilterCombinator, FilterOperator
+from sanjaya_core.filters import FilterCondition, FilterGroup
+
+from sanjaya_sqlalchemy.filters import compile_filter_group
+
+
+class TestFilterCompiler:
+    """Compile filter trees and verify by actually running SQL."""
+
+    def test_eq(self, engine: Engine, trades_table: sa.Table) -> None:
+        fg = FilterGroup(conditions=[
+            FilterCondition(column="desk", operator=FilterOperator.EQ, value="FX"),
+        ])
+        expr = compile_filter_group(fg, {c.name: c for c in trades_table.columns})
+        stmt = sa.select(trades_table).where(expr)
+        with engine.connect() as conn:
+            rows = conn.execute(stmt).fetchall()
+        assert len(rows) == 4
+        assert all(r._mapping["desk"] == "FX" for r in rows)
+
+    def test_neq(self, engine: Engine, trades_table: sa.Table) -> None:
+        fg = FilterGroup(conditions=[
+            FilterCondition(column="desk", operator=FilterOperator.NEQ, value="FX"),
+        ])
+        expr = compile_filter_group(fg, {c.name: c for c in trades_table.columns})
+        stmt = sa.select(trades_table).where(expr)
+        with engine.connect() as conn:
+            rows = conn.execute(stmt).fetchall()
+        assert len(rows) == 3
+
+    def test_gt_lt(self, engine: Engine, trades_table: sa.Table) -> None:
+        fg = FilterGroup(conditions=[
+            FilterCondition(column="amount", operator=FilterOperator.GT, value=1500),
+            FilterCondition(column="amount", operator=FilterOperator.LT, value=5000),
+        ])
+        expr = compile_filter_group(fg, {c.name: c for c in trades_table.columns})
+        stmt = sa.select(trades_table).where(expr)
+        with engine.connect() as conn:
+            rows = conn.execute(stmt).fetchall()
+        # amount > 1500 AND < 5000 → 2000, 3000, 4000 = 3 rows
+        assert len(rows) == 3
+
+    def test_between(self, engine: Engine, trades_table: sa.Table) -> None:
+        fg = FilterGroup(conditions=[
+            FilterCondition(column="amount", operator=FilterOperator.BETWEEN, value=[1000, 3000]),
+        ])
+        expr = compile_filter_group(fg, {c.name: c for c in trades_table.columns})
+        stmt = sa.select(trades_table).where(expr)
+        with engine.connect() as conn:
+            rows = conn.execute(stmt).fetchall()
+        # 1000, 2000, 1500, 3000 = 4 rows
+        assert len(rows) == 4
+
+    def test_in(self, engine: Engine, trades_table: sa.Table) -> None:
+        fg = FilterGroup(conditions=[
+            FilterCondition(column="region", operator=FilterOperator.IN, value=["US", "EU"]),
+        ])
+        expr = compile_filter_group(fg, {c.name: c for c in trades_table.columns})
+        stmt = sa.select(trades_table).where(expr)
+        with engine.connect() as conn:
+            rows = conn.execute(stmt).fetchall()
+        assert len(rows) == 5
+
+    def test_contains(self, engine: Engine, trades_table: sa.Table) -> None:
+        fg = FilterGroup(conditions=[
+            FilterCondition(column="instrument", operator=FilterOperator.CONTAINS, value="USD"),
+        ])
+        expr = compile_filter_group(fg, {c.name: c for c in trades_table.columns})
+        stmt = sa.select(trades_table).where(expr)
+        with engine.connect() as conn:
+            rows = conn.execute(stmt).fetchall()
+        # EURUSD (×2), GBPUSD, USDJPY = 4
+        assert len(rows) == 4
+
+    def test_startswith(self, engine: Engine, trades_table: sa.Table) -> None:
+        fg = FilterGroup(conditions=[
+            FilterCondition(column="instrument", operator=FilterOperator.STARTSWITH, value="EUR"),
+        ])
+        expr = compile_filter_group(fg, {c.name: c for c in trades_table.columns})
+        stmt = sa.select(trades_table).where(expr)
+        with engine.connect() as conn:
+            rows = conn.execute(stmt).fetchall()
+        assert len(rows) == 2
+
+    def test_or_combinator(self, engine: Engine, trades_table: sa.Table) -> None:
+        fg = FilterGroup(
+            combinator=FilterCombinator.OR,
+            conditions=[
+                FilterCondition(column="desk", operator=FilterOperator.EQ, value="FX"),
+                FilterCondition(column="region", operator=FilterOperator.EQ, value="APAC"),
+            ],
+        )
+        expr = compile_filter_group(fg, {c.name: c for c in trades_table.columns})
+        stmt = sa.select(trades_table).where(expr)
+        with engine.connect() as conn:
+            rows = conn.execute(stmt).fetchall()
+        # FX: 1,2,3,7; APAC: 6,7 → union = 1,2,3,6,7 = 5
+        assert len(rows) == 5
+
+    def test_negate_condition(self, engine: Engine, trades_table: sa.Table) -> None:
+        fg = FilterGroup(conditions=[
+            FilterCondition(column="desk", operator=FilterOperator.EQ, value="FX", negate=True),
+        ])
+        expr = compile_filter_group(fg, {c.name: c for c in trades_table.columns})
+        stmt = sa.select(trades_table).where(expr)
+        with engine.connect() as conn:
+            rows = conn.execute(stmt).fetchall()
+        assert len(rows) == 3  # NOT FX → Rates rows
+
+    def test_negate_group(self, engine: Engine, trades_table: sa.Table) -> None:
+        fg = FilterGroup(
+            negate=True,
+            conditions=[
+                FilterCondition(column="desk", operator=FilterOperator.EQ, value="FX"),
+            ],
+        )
+        expr = compile_filter_group(fg, {c.name: c for c in trades_table.columns})
+        stmt = sa.select(trades_table).where(expr)
+        with engine.connect() as conn:
+            rows = conn.execute(stmt).fetchall()
+        assert len(rows) == 3
+
+    def test_nested_groups(self, engine: Engine, trades_table: sa.Table) -> None:
+        """(desk = 'FX') AND (region = 'US' OR region = 'EU')."""
+        fg = FilterGroup(
+            conditions=[
+                FilterCondition(column="desk", operator=FilterOperator.EQ, value="FX"),
+            ],
+            groups=[
+                FilterGroup(
+                    combinator=FilterCombinator.OR,
+                    conditions=[
+                        FilterCondition(column="region", operator=FilterOperator.EQ, value="US"),
+                        FilterCondition(column="region", operator=FilterOperator.EQ, value="EU"),
+                    ],
+                ),
+            ],
+        )
+        expr = compile_filter_group(fg, {c.name: c for c in trades_table.columns})
+        stmt = sa.select(trades_table).where(expr)
+        with engine.connect() as conn:
+            rows = conn.execute(stmt).fetchall()
+        # FX + (US or EU) → ids 1, 2, 3
+        assert len(rows) == 3
+
+    def test_empty_group_matches_all(self, engine: Engine, trades_table: sa.Table) -> None:
+        fg = FilterGroup()
+        expr = compile_filter_group(fg, {c.name: c for c in trades_table.columns})
+        stmt = sa.select(trades_table).where(expr)
+        with engine.connect() as conn:
+            rows = conn.execute(stmt).fetchall()
+        assert len(rows) == 7

sanjaya_sqlalchemy-0.1.0/tests/test_provider.py

@@ -0,0 +1,240 @@
+"""Tests for SQLAlchemyProvider — flat queries, aggregation, and pivot."""
+
+from __future__ import annotations
+
+from sanjaya_core.enums import AggFunc, FilterOperator, SortDirection
+from sanjaya_core.filters import FilterCondition, FilterGroup
+from sanjaya_core.types import SortSpec, ValueSpec
+
+from sanjaya_sqlalchemy import SQLAlchemyProvider
+
+
+# ---------------------------------------------------------------------------
+# Flat query
+# ---------------------------------------------------------------------------
+
+
+class TestQuery:
+    def test_select_all(self, provider: SQLAlchemyProvider) -> None:
+        result = provider.query(["id", "desk", "amount"])
+        assert result.total == 7
+        assert len(result.rows) == 7
+        assert result.columns == ["id", "desk", "amount"]
+        # Every row should have exactly the requested keys.
+        for row in result.rows:
+            assert set(row.keys()) == {"id", "desk", "amount"}
+
+    def test_limit_offset(self, provider: SQLAlchemyProvider) -> None:
+        r1 = provider.query(["id"], sort=[SortSpec(column="id")], limit=3, offset=0)
+        r2 = provider.query(["id"], sort=[SortSpec(column="id")], limit=3, offset=3)
+        assert r1.total == 7
+        ids_1 = [r["id"] for r in r1.rows]
+        ids_2 = [r["id"] for r in r2.rows]
+        assert ids_1 == [1, 2, 3]
+        assert ids_2 == [4, 5, 6]
+
+    def test_filter(self, provider: SQLAlchemyProvider) -> None:
+        fg = FilterGroup(conditions=[
+            FilterCondition(column="desk", operator=FilterOperator.EQ, value="FX"),
+        ])
+        result = provider.query(["id", "desk"], filter_group=fg)
+        assert result.total == 4
+        assert all(r["desk"] == "FX" for r in result.rows)
+
+    def test_sort_asc(self, provider: SQLAlchemyProvider) -> None:
+        result = provider.query(
+            ["id", "amount"],
+            sort=[SortSpec(column="amount", direction=SortDirection.ASC)],
+        )
+        amounts = [r["amount"] for r in result.rows]
+        assert amounts == sorted(amounts)
+
+    def test_sort_desc(self, provider: SQLAlchemyProvider) -> None:
+        result = provider.query(
+            ["id", "amount"],
+            sort=[SortSpec(column="amount", direction=SortDirection.DESC)],
+        )
+        amounts = [r["amount"] for r in result.rows]
+        assert amounts == sorted(amounts, reverse=True)
+
+    def test_empty_result(self, provider: SQLAlchemyProvider) -> None:
+        fg = FilterGroup(conditions=[
+            FilterCondition(column="desk", operator=FilterOperator.EQ, value="Nonexistent"),
+        ])
+        result = provider.query(["id"], filter_group=fg)
+        assert result.total == 0
+        assert result.rows == []
+
+
+# ---------------------------------------------------------------------------
+# Simple aggregation (no pivot)
+# ---------------------------------------------------------------------------
+
+
+class TestSimpleAggregate:
+    def test_group_by_single_column(self, provider: SQLAlchemyProvider) -> None:
+        result = provider.aggregate(
+            group_by_rows=["desk"],
+            group_by_cols=[],
+            values=[ValueSpec(column="amount", agg=AggFunc.SUM)],
+        )
+        assert result.total == 2  # FX, Rates
+        sums = {r["desk"]: r["sum_amount"] for r in result.rows}
+        assert sums["FX"] == 1000 + 2000 + 1500 + 500  # 5000
+        assert sums["Rates"] == 5000 + 3000 + 4000  # 12000
+
+    def test_group_by_multiple_columns(self, provider: SQLAlchemyProvider) -> None:
+        result = provider.aggregate(
+            group_by_rows=["desk", "region"],
+            group_by_cols=[],
+            values=[ValueSpec(column="amount", agg=AggFunc.SUM)],
+        )
+        # FX-US, FX-EU, FX-APAC, Rates-US, Rates-EU, Rates-APAC
+        assert result.total == 6
+
+    def test_multiple_agg_funcs(self, provider: SQLAlchemyProvider) -> None:
+        result = provider.aggregate(
+            group_by_rows=["desk"],
+            group_by_cols=[],
+            values=[
+                ValueSpec(column="amount", agg=AggFunc.SUM),
+                ValueSpec(column="amount", agg=AggFunc.COUNT),
+            ],
+        )
+        fx_row = next(r for r in result.rows if r["desk"] == "FX")
+        assert fx_row["sum_amount"] == 5000.0
+        assert fx_row["count_amount"] == 4  # 4 FX trades
+
+    def test_aggregate_with_filter(self, provider: SQLAlchemyProvider) -> None:
+        fg = FilterGroup(conditions=[
+            FilterCondition(column="region", operator=FilterOperator.EQ, value="US"),
+        ])
+        result = provider.aggregate(
+            group_by_rows=["desk"],
+            group_by_cols=[],
+            values=[ValueSpec(column="amount", agg=AggFunc.SUM)],
+            filter_group=fg,
+        )
+        assert result.total == 2
+        sums = {r["desk"]: r["sum_amount"] for r in result.rows}
+        assert sums["FX"] == 3000.0
+        assert sums["Rates"] == 5000.0
+
+    def test_aggregate_with_limit_offset(self, provider: SQLAlchemyProvider) -> None:
+        result = provider.aggregate(
+            group_by_rows=["desk"],
+            group_by_cols=[],
+            values=[ValueSpec(column="amount", agg=AggFunc.SUM)],
+            sort=[SortSpec(column="desk")],
+            limit=1,
+            offset=0,
+        )
+        assert result.total == 2
+        assert len(result.rows) == 1
+        assert result.rows[0]["desk"] == "FX"
+
+    def test_distinct_count(self, provider: SQLAlchemyProvider) -> None:
+        result = provider.aggregate(
+            group_by_rows=["desk"],
+            group_by_cols=[],
+            values=[ValueSpec(column="region", agg=AggFunc.DISTINCT_COUNT)],
+        )
+        dc = {r["desk"]: r["distinctCount_region"] for r in result.rows}
+        assert dc["FX"] == 3        # US, EU, APAC
+        assert dc["Rates"] == 3     # US, EU, APAC
+
+
+# ---------------------------------------------------------------------------
+# Pivot aggregation
+# ---------------------------------------------------------------------------
+
+
+class TestPivotAggregate:
+    def test_basic_pivot(self, provider: SQLAlchemyProvider) -> None:
+        """Pivot by region: desk × region → sum(amount)."""
+        result = provider.aggregate(
+            group_by_rows=["desk"],
+            group_by_cols=["region"],
+            values=[ValueSpec(column="amount", agg=AggFunc.SUM)],
+        )
+        assert result.total == 2  # FX, Rates
+        # There should be row-dim columns + one per (region × measure)
+        col_keys = [c.key for c in result.columns]
+        assert "desk" in col_keys
+        # Verify a few pivot columns exist
+        assert any("US_sum_amount" in k for k in col_keys)
+        assert any("EU_sum_amount" in k for k in col_keys)
+
+        fx_row = next(r for r in result.rows if r["desk"] == "FX")
+        assert fx_row["US_sum_amount"] == 3000.0   # 1000 + 2000
+        assert fx_row["EU_sum_amount"] == 1500.0
+        assert fx_row["APAC_sum_amount"] == 500.0
+
+    def test_pivot_column_keys_are_strings(self, provider: SQLAlchemyProvider) -> None:
+        result = provider.aggregate(
+            group_by_rows=["desk"],
+            group_by_cols=["region"],
+            values=[ValueSpec(column="amount", agg=AggFunc.SUM)],
+        )
+        for col in result.columns:
+            if col.pivot_keys:
+                assert all(isinstance(k, str) for k in col.pivot_keys)
+
+    def test_multi_dim_pivot(self, provider: SQLAlchemyProvider) -> None:
+        """Pivot by (region, instrument)."""
+        result = provider.aggregate(
+            group_by_rows=["desk"],
+            group_by_cols=["region", "instrument"],
+            values=[ValueSpec(column="amount", agg=AggFunc.SUM)],
+        )
+        assert result.total == 2
+        # Find the FX-US-EURUSD cell
+        fx_row = next(r for r in result.rows if r["desk"] == "FX")
+        assert fx_row.get("US_EURUSD_sum_amount") == 1000.0
+
+    def test_pivot_with_multiple_measures(self, provider: SQLAlchemyProvider) -> None:
+        result = provider.aggregate(
+            group_by_rows=["desk"],
+            group_by_cols=["region"],
+            values=[
+                ValueSpec(column="amount", agg=AggFunc.SUM),
+                ValueSpec(column="quantity", agg=AggFunc.SUM),
+            ],
+        )
+        fx_row = next(r for r in result.rows if r["desk"] == "FX")
+        assert fx_row["US_sum_amount"] == 3000.0
+        assert fx_row["US_sum_quantity"] == 30  # 10 + 20
+
+    def test_pivot_with_filter(self, provider: SQLAlchemyProvider) -> None:
+        fg = FilterGroup(conditions=[
+            FilterCondition(column="desk", operator=FilterOperator.EQ, value="FX"),
+        ])
+        result = provider.aggregate(
+            group_by_rows=["desk"],
+            group_by_cols=["region"],
+            values=[ValueSpec(column="amount", agg=AggFunc.SUM)],
+            filter_group=fg,
+        )
+        assert result.total == 1
+        assert result.rows[0]["desk"] == "FX"
+
+
+# ---------------------------------------------------------------------------
+# Provider metadata
+# ---------------------------------------------------------------------------
+
+
+class TestProviderMeta:
+    def test_get_columns(self, provider: SQLAlchemyProvider) -> None:
+        cols = provider.get_columns()
+        assert len(cols) == 6
+        names = [c.name for c in cols]
+        assert "id" in names
+        assert "desk" in names
+
+    def test_capabilities(self, provider: SQLAlchemyProvider) -> None:
+        assert provider.capabilities.pivot is True
+
+    def test_identity(self, provider: SQLAlchemyProvider) -> None:
+        assert provider.key == "trades"
+        assert provider.label == "Trades"