sqlstratum 0.1.0__py3-none-any.whl

sqlstratum/__init__.py

@@ -0,0 +1,32 @@
+"""sqlstratum: minimal SQL AST + compiler + sqlite runner."""
+from .dsl import SELECT, INSERT, UPDATE, DELETE, OR, AND, NOT
+from .expr import COUNT, SUM, AVG, MIN, MAX
+from .meta import Table, Column, col
+from .compile import compile
+from .runner import Runner
+from .types import Expression, HydrationTarget, Hydrator, Predicate, Source
+
+__all__ = [
+    "SELECT",
+    "INSERT",
+    "UPDATE",
+    "DELETE",
+    "OR",
+    "AND",
+    "NOT",
+    "COUNT",
+    "SUM",
+    "AVG",
+    "MIN",
+    "MAX",
+    "Table",
+    "Column",
+    "col",
+    "compile",
+    "Runner",
+    "Expression",
+    "HydrationTarget",
+    "Hydrator",
+    "Predicate",
+    "Source",
+]

sqlstratum/ast.py

@@ -0,0 +1,96 @@
+"""AST node definitions for sqlstratum."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, Optional, Sequence, Tuple, TypeVar
+
+from .meta import Column
+from .expr import OrderSpec
+from .types import Expression, HydrationTarget, Predicate, Source
+
+
+@dataclass(frozen=True)
+class Compiled:
+    sql: str
+    params: Dict[str, Any]
+
+
+@dataclass(frozen=True)
+class SelectQuery:
+    projections: Tuple[Expression, ...]
+    from_: Optional[Source]
+    joins: Tuple["Join", ...]
+    where: Tuple[Predicate, ...]
+    group_by: Tuple[Expression, ...]
+    having: Tuple[Predicate, ...]
+    order_by: Tuple[OrderSpec, ...]
+    limit: Optional[int]
+    offset: Optional[int]
+    distinct: bool
+    hydrate: HydrationTarget
+
+
+@dataclass(frozen=True)
+class Join:
+    kind: str  # "INNER" or "LEFT"
+    source: Source
+    on: Predicate
+
+
+@dataclass(frozen=True)
+class InsertQuery:
+    table: Any
+    values: Tuple[Tuple[str, Any], ...]
+
+
+@dataclass(frozen=True)
+class UpdateQuery:
+    table: Any
+    values: Tuple[Tuple[str, Any], ...]
+    where: Tuple[Predicate, ...]
+
+
+@dataclass(frozen=True)
+class DeleteQuery:
+    table: Any
+    where: Tuple[Predicate, ...]
+
+
+@dataclass(frozen=True)
+class Subquery:
+    query: SelectQuery
+    alias: str
+    c: Any = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "c", _SubqueryColumnAccessor(self.alias))
+
+    def __getattr__(self, item: str) -> Column:
+        return getattr(self.c, item)
+
+
+@dataclass(frozen=True)
+class _SubqueryTable:
+    name: str
+    alias: Optional[str] = None
+
+
+class _SubqueryColumnAccessor:
+    def __init__(self, alias: str) -> None:
+        self._alias = alias
+
+    def __getattr__(self, item: str) -> Column:
+        return Column(name=item, py_type=object, table=_SubqueryTable(self._alias))
+
+
+@dataclass(frozen=True)
+class ExecutionResult:
+    rowcount: int
+    lastrowid: Optional[int]
+
+
+T = TypeVar("T")
+
+
+def tupled(items: Iterable[T]) -> Tuple[T, ...]:
+    return tuple(items)

sqlstratum/compile.py

@@ -0,0 +1,156 @@
+"""SQLite compiler for sqlstratum AST."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, List
+
+from . import ast
+from .expr import (
+    AliasExpr,
+    BinaryPredicate,
+    Function,
+    Literal,
+    LogicalPredicate,
+    NotPredicate,
+    OrderSpec,
+    UnaryPredicate,
+)
+from .meta import Column, Table
+from .types import Predicate
+
+
+@dataclass(frozen=True)
+class Compiled(ast.Compiled):
+    pass
+
+
+def compile(query: Any, dialect: str = "sqlite") -> Compiled:
+    if dialect != "sqlite":
+        raise ValueError("Only sqlite dialect is supported in v0.1")
+    compiler = _Compiler()
+    sql = compiler.compile_query(query)
+    return Compiled(sql=sql, params=compiler.params)
+
+
+class _Compiler:
+    def __init__(self) -> None:
+        self.params: Dict[str, Any] = {}
+        self._param_index = 0
+
+    def compile_query(self, query: Any) -> str:
+        if isinstance(query, ast.SelectQuery):
+            return self._compile_select(query)
+        if isinstance(query, ast.InsertQuery):
+            return self._compile_insert(query)
+        if isinstance(query, ast.UpdateQuery):
+            return self._compile_update(query)
+        if isinstance(query, ast.DeleteQuery):
+            return self._compile_delete(query)
+        raise TypeError(f"Unsupported query type: {type(query)}")
+
+    def _compile_select(self, query: ast.SelectQuery) -> str:
+        parts: List[str] = []
+        distinct = "DISTINCT " if query.distinct else ""
+        projections = ", ".join(self._compile_projection(p) for p in query.projections)
+        parts.append(f"SELECT {distinct}{projections}")
+        if query.from_ is not None:
+            parts.append("FROM " + self._compile_source(query.from_))
+        for join in query.joins:
+            join_sql = "JOIN" if join.kind == "INNER" else "LEFT JOIN"
+            parts.append(f"{join_sql} {self._compile_source(join.source)} ON {self._compile_predicate(join.on)}")
+        if query.where:
+            parts.append("WHERE " + self._compile_and_list(query.where))
+        if query.group_by:
+            parts.append("GROUP BY " + ", ".join(self._compile_expr(e) for e in query.group_by))
+        if query.having:
+            parts.append("HAVING " + self._compile_and_list(query.having))
+        if query.order_by:
+            parts.append("ORDER BY " + ", ".join(self._compile_order(o) for o in query.order_by))
+        if query.limit is not None:
+            parts.append("LIMIT " + self._bind(query.limit))
+        if query.offset is not None:
+            parts.append("OFFSET " + self._bind(query.offset))
+        return " ".join(parts)
+
+    def _compile_insert(self, query: ast.InsertQuery) -> str:
+        columns = ", ".join(self._quote(k) for k, _ in query.values)
+        values = ", ".join(self._bind(v) for _, v in query.values)
+        return f"INSERT INTO {self._compile_table(query.table)} ({columns}) VALUES ({values})"
+
+    def _compile_update(self, query: ast.UpdateQuery) -> str:
+        sets = ", ".join(f"{self._quote(k)} = {self._bind(v)}" for k, v in query.values)
+        parts = [f"UPDATE {self._compile_table(query.table)} SET {sets}"]
+        if query.where:
+            parts.append("WHERE " + self._compile_and_list(query.where))
+        return " ".join(parts)
+
+    def _compile_delete(self, query: ast.DeleteQuery) -> str:
+        parts = [f"DELETE FROM {self._compile_table(query.table)}"]
+        if query.where:
+            parts.append("WHERE " + self._compile_and_list(query.where))
+        return " ".join(parts)
+
+    def _compile_projection(self, expr: Any) -> str:
+        return self._compile_expr(expr)
+
+    def _compile_source(self, source: Any) -> str:
+        if isinstance(source, Table):
+            return self._compile_table(source)
+        if isinstance(source, ast.Subquery):
+            return f"({self._compile_select(source.query)}) AS {self._quote(source.alias)}"
+        raise TypeError(f"Unsupported source type: {type(source)}")
+
+    def _compile_table(self, table: Table) -> str:
+        if table.alias:
+            return f"{self._quote(table.name)} AS {self._quote(table.alias)}"
+        return self._quote(table.name)
+
+    def _compile_expr(self, expr: Any) -> str:
+        if isinstance(expr, Column):
+            return self._compile_column(expr)
+        if isinstance(expr, AliasExpr):
+            return f"{self._compile_expr(expr.expr)} AS {self._quote(expr.alias)}"
+        if isinstance(expr, Function):
+            args = ", ".join(self._compile_expr(a) for a in expr.args)
+            return f"{expr.name}({args})"
+        if isinstance(expr, OrderSpec):
+            return self._compile_order(expr)
+        if isinstance(expr, Literal):
+            return self._bind(expr.value)
+        if isinstance(expr, ast.Subquery):
+            return f"({self._compile_select(expr.query)})"
+        return self._compile_predicate(expr)
+
+    def _compile_predicate(self, pred: Predicate) -> str:
+        if isinstance(pred, BinaryPredicate):
+            return f"{self._compile_expr(pred.left)} {pred.op} {self._compile_expr(pred.right)}"
+        if isinstance(pred, UnaryPredicate):
+            return f"{self._compile_expr(pred.expr)} {pred.op}"
+        if isinstance(pred, LogicalPredicate):
+            inner = f" {pred.op} ".join(self._compile_predicate(p) for p in pred.predicates)
+            return f"({inner})"
+        if isinstance(pred, NotPredicate):
+            return f"NOT ({self._compile_predicate(pred.predicate)})"
+        raise TypeError(f"Unsupported predicate type: {type(pred)}")
+
+    def _compile_and_list(self, preds: Iterable[Predicate]) -> str:
+        parts = [self._compile_predicate(p) for p in preds]
+        return " AND ".join(parts)
+
+    def _compile_order(self, order: OrderSpec) -> str:
+        return f"{self._compile_expr(order.expr)} {order.direction}"
+
+    def _compile_column(self, col: Column) -> str:
+        if col.table.alias:
+            return f"{self._quote(col.table.alias)}.{self._quote(col.name)}"
+        return f"{self._quote(col.table.name)}.{self._quote(col.name)}"
+
+    def _quote(self, ident: str) -> str:
+        escaped = ident.replace('"', '""')
+        return f'"{escaped}"'
+
+    def _bind(self, value: Any) -> str:
+        name = f"p{self._param_index}"
+        self._param_index += 1
+        self.params[name] = value
+        return f":{name}"

sqlstratum/dsl.py

@@ -0,0 +1,150 @@
+"""Public DSL constructors and query chaining."""
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Any, Tuple
+
+from .ast import DeleteQuery, InsertQuery, Join, SelectQuery, Subquery, UpdateQuery, tupled
+from .expr import LogicalPredicate, NotPredicate, OrderSpec
+from .meta import Table
+from .types import Expression, HydrationTarget, Predicate, Source
+
+
+def SELECT(*projections: Expression) -> SelectQuery:
+    return SelectQuery(
+        projections=tupled(projections),
+        from_=None,
+        joins=tuple(),
+        where=tuple(),
+        group_by=tuple(),
+        having=tuple(),
+        order_by=tuple(),
+        limit=None,
+        offset=None,
+        distinct=False,
+        hydrate=None,
+    )
+
+
+def INSERT(table: Table) -> "InsertBuilder":
+    return InsertBuilder(table)
+
+
+def UPDATE(table: Table) -> "UpdateBuilder":
+    return UpdateBuilder(table)
+
+
+def DELETE(table: Table) -> "DeleteBuilder":
+    return DeleteBuilder(table)
+
+
+def OR(*predicates: Predicate) -> LogicalPredicate:
+    return LogicalPredicate("OR", tupled(predicates))
+
+
+def AND(*predicates: Predicate) -> LogicalPredicate:
+    return LogicalPredicate("AND", tupled(predicates))
+
+
+def NOT(predicate: Predicate) -> NotPredicate:
+    return NotPredicate(predicate)
+
+
+# Query chaining methods added via monkey-patching style functions
+
+def _from(self: SelectQuery, source: Source) -> SelectQuery:
+    return replace(self, from_=source)
+
+
+def _join(self: SelectQuery, source: Source, ON: Predicate) -> SelectQuery:
+    joins = self.joins + (Join("INNER", source, ON),)
+    return replace(self, joins=joins)
+
+
+def _left_join(self: SelectQuery, source: Source, ON: Predicate) -> SelectQuery:
+    joins = self.joins + (Join("LEFT", source, ON),)
+    return replace(self, joins=joins)
+
+
+def _where(self: SelectQuery, *predicates: Predicate) -> SelectQuery:
+    where = self.where + tupled(predicates)
+    return replace(self, where=where)
+
+
+def _group_by(self: SelectQuery, *cols: Expression) -> SelectQuery:
+    return replace(self, group_by=self.group_by + tupled(cols))
+
+
+def _having(self: SelectQuery, *predicates: Predicate) -> SelectQuery:
+    return replace(self, having=self.having + tupled(predicates))
+
+
+def _order_by(self: SelectQuery, *order_specs: OrderSpec) -> SelectQuery:
+    return replace(self, order_by=self.order_by + tupled(order_specs))
+
+
+def _limit(self: SelectQuery, n: int) -> SelectQuery:
+    return replace(self, limit=n)
+
+
+def _offset(self: SelectQuery, n: int) -> SelectQuery:
+    return replace(self, offset=n)
+
+
+def _distinct(self: SelectQuery) -> SelectQuery:
+    return replace(self, distinct=True)
+
+
+def _as(self: SelectQuery, alias: str) -> Subquery:
+    return Subquery(self, alias)
+
+
+def _hydrate(self: SelectQuery, target: HydrationTarget) -> SelectQuery:
+    return replace(self, hydrate=target)
+
+
+SelectQuery.FROM = _from  # type: ignore[attr-defined]
+SelectQuery.JOIN = _join  # type: ignore[attr-defined]
+SelectQuery.LEFT_JOIN = _left_join  # type: ignore[attr-defined]
+SelectQuery.WHERE = _where  # type: ignore[attr-defined]
+SelectQuery.GROUP_BY = _group_by  # type: ignore[attr-defined]
+SelectQuery.HAVING = _having  # type: ignore[attr-defined]
+SelectQuery.ORDER_BY = _order_by  # type: ignore[attr-defined]
+SelectQuery.LIMIT = _limit  # type: ignore[attr-defined]
+SelectQuery.OFFSET = _offset  # type: ignore[attr-defined]
+SelectQuery.DISTINCT = _distinct  # type: ignore[attr-defined]
+SelectQuery.AS = _as  # type: ignore[attr-defined]
+SelectQuery.HYDRATE = _hydrate  # type: ignore[attr-defined]
+
+
+class InsertBuilder:
+    def __init__(self, table: Table):
+        self.table = table
+
+    def VALUES(self, **values: Any) -> InsertQuery:
+        return InsertQuery(self.table, tuple(values.items()))
+
+
+class UpdateBuilder:
+    def __init__(self, table: Table):
+        self.table = table
+
+    def SET(self, **values: Any) -> "UpdateWhereBuilder":
+        return UpdateWhereBuilder(self.table, tuple(values.items()))
+
+
+class UpdateWhereBuilder:
+    def __init__(self, table: Table, values: Tuple[Tuple[str, Any], ...]):
+        self.table = table
+        self.values = values
+
+    def WHERE(self, *predicates: Predicate) -> UpdateQuery:
+        return UpdateQuery(self.table, self.values, tupled(predicates))
+
+
+class DeleteBuilder:
+    def __init__(self, table: Table):
+        self.table = table
+
+    def WHERE(self, *predicates: Predicate) -> DeleteQuery:
+        return DeleteQuery(self.table, tupled(predicates))

sqlstratum/expr.py

@@ -0,0 +1,115 @@
+"""Expression and predicate nodes."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional, Tuple
+
+
+class Expr:
+    def __eq__(self, other: Any) -> "BinaryPredicate":  # type: ignore[override]
+        return BinaryPredicate(self, "=", ensure_expr(other))
+
+    def __ne__(self, other: Any) -> "BinaryPredicate":  # type: ignore[override]
+        return BinaryPredicate(self, "!=", ensure_expr(other))
+
+    def __lt__(self, other: Any) -> "BinaryPredicate":
+        return BinaryPredicate(self, "<", ensure_expr(other))
+
+    def __le__(self, other: Any) -> "BinaryPredicate":
+        return BinaryPredicate(self, "<=", ensure_expr(other))
+
+    def __gt__(self, other: Any) -> "BinaryPredicate":
+        return BinaryPredicate(self, ">", ensure_expr(other))
+
+    def __ge__(self, other: Any) -> "BinaryPredicate":
+        return BinaryPredicate(self, ">=", ensure_expr(other))
+
+    def AS(self, alias: str) -> "AliasExpr":
+        return AliasExpr(self, alias)
+
+    def ASC(self) -> "OrderSpec":
+        return OrderSpec(self, "ASC")
+
+    def DESC(self) -> "OrderSpec":
+        return OrderSpec(self, "DESC")
+
+
+@dataclass(frozen=True)
+class AliasExpr(Expr):
+    expr: Expr
+    alias: str
+
+
+@dataclass(frozen=True)
+class Literal(Expr):
+    value: Any
+
+
+@dataclass(frozen=True)
+class BinaryPredicate:
+    left: Expr
+    op: str
+    right: Expr
+
+
+@dataclass(frozen=True)
+class UnaryPredicate:
+    expr: Expr
+    op: str
+
+
+@dataclass(frozen=True)
+class LogicalPredicate:
+    op: str  # "AND" or "OR"
+    predicates: Tuple["Predicate", ...]
+
+
+@dataclass(frozen=True)
+class NotPredicate:
+    predicate: "Predicate"
+
+
+@dataclass(frozen=True)
+class Function(Expr):
+    name: str
+    args: tuple
+
+
+@dataclass(frozen=True)
+class OrderSpec:
+    expr: Expr
+    direction: str
+
+
+def ensure_expr(value: Any) -> Expr:
+    from .meta import Column
+    if isinstance(value, Expr) or isinstance(value, Column):
+        return value  # type: ignore[return-value]
+    return Literal(value)
+
+
+# Aggregate helpers
+
+def COUNT(expr: Optional[Expr] = None) -> Function:
+    if expr is None:
+        return Function("COUNT", (Literal(1),))
+    return Function("COUNT", (ensure_expr(expr),))
+
+
+def SUM(expr: Expr) -> Function:
+    return Function("SUM", (ensure_expr(expr),))
+
+
+def AVG(expr: Expr) -> Function:
+    return Function("AVG", (ensure_expr(expr),))
+
+
+def MIN(expr: Expr) -> Function:
+    return Function("MIN", (ensure_expr(expr),))
+
+
+def MAX(expr: Expr) -> Function:
+    return Function("MAX", (ensure_expr(expr),))
+
+
+Predicate = BinaryPredicate | UnaryPredicate | LogicalPredicate | NotPredicate

sqlstratum/hydrate.py

@@ -0,0 +1,55 @@
+"""Hydration utilities."""
+from __future__ import annotations
+
+from dataclasses import is_dataclass
+from typing import Any, Dict, Iterable, List, Mapping, Sequence
+
+from .expr import AliasExpr, Function
+from .meta import Column
+from .types import HydrationTarget
+
+
+class HydrationError(ValueError):
+    pass
+
+
+def projection_keys(projections: Sequence[Any]) -> List[str]:
+    keys: List[str] = []
+    for proj in projections:
+        key = _projection_key(proj)
+        if key in keys:
+            raise HydrationError(f"Duplicate projection key '{key}'. Use AS() to disambiguate.")
+        keys.append(key)
+    return keys
+
+
+def _projection_key(proj: Any) -> str:
+    if isinstance(proj, AliasExpr):
+        return proj.alias
+    if isinstance(proj, Column):
+        return proj.name
+    if isinstance(proj, Function):
+        raise HydrationError("Aggregate expressions require AS('alias') for hydration")
+    raise HydrationError("Projection requires AS('alias') for hydration")
+
+
+def hydrate_rows(
+    rows: Iterable[Mapping[str, Any]],
+    projections: Sequence[Any],
+    target: HydrationTarget,
+) -> List[Any]:
+    keys = projection_keys(projections)
+    mapped: List[Dict[str, Any]] = []
+    for row in rows:
+        mapped.append({k: row[k] for k in keys})
+
+    if target is None or target is dict:
+        return mapped
+
+    if is_dataclass(target):
+        return [target(**m) for m in mapped]
+
+    if callable(target):
+        return [target(m) for m in mapped]
+
+    raise HydrationError("Unsupported hydration target")

sqlstratum/meta.py

@@ -0,0 +1,112 @@
+"""Metadata objects: Table and Column."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, List, Optional
+
+from .expr import Expr
+
+@dataclass(frozen=True)
+class Column(Expr):
+    name: str
+    py_type: type
+    table: "Table"
+
+    def __repr__(self) -> str:  # pragma: no cover - debug aid
+        return f"Column({self.table.name}.{self.name})"
+
+    # Comparison operators build predicates (defined in expr.py)
+    def __eq__(self, other: Any) -> "BinaryPredicate":  # type: ignore[override]
+        from .expr import BinaryPredicate, ensure_expr
+        return BinaryPredicate(self, "=", ensure_expr(other))
+
+    def __ne__(self, other: Any) -> "BinaryPredicate":  # type: ignore[override]
+        from .expr import BinaryPredicate, ensure_expr
+        return BinaryPredicate(self, "!=", ensure_expr(other))
+
+    def __lt__(self, other: Any) -> "BinaryPredicate":
+        from .expr import BinaryPredicate, ensure_expr
+        return BinaryPredicate(self, "<", ensure_expr(other))
+
+    def __le__(self, other: Any) -> "BinaryPredicate":
+        from .expr import BinaryPredicate, ensure_expr
+        return BinaryPredicate(self, "<=", ensure_expr(other))
+
+    def __gt__(self, other: Any) -> "BinaryPredicate":
+        from .expr import BinaryPredicate, ensure_expr
+        return BinaryPredicate(self, ">", ensure_expr(other))
+
+    def __ge__(self, other: Any) -> "BinaryPredicate":
+        from .expr import BinaryPredicate, ensure_expr
+        return BinaryPredicate(self, ">=", ensure_expr(other))
+
+    def is_null(self) -> "UnaryPredicate":
+        from .expr import UnaryPredicate
+        return UnaryPredicate(self, "IS NULL")
+
+    def is_not_null(self) -> "UnaryPredicate":
+        from .expr import UnaryPredicate
+        return UnaryPredicate(self, "IS NOT NULL")
+
+    def contains(self, text: str) -> "BinaryPredicate":
+        from .expr import BinaryPredicate, Literal
+        return BinaryPredicate(self, "LIKE", Literal(f"%{text}%"))
+
+    def is_true(self) -> "BinaryPredicate":
+        from .expr import BinaryPredicate, Literal
+        return BinaryPredicate(self, "=", Literal(True))
+
+    def is_false(self) -> "BinaryPredicate":
+        from .expr import BinaryPredicate, Literal
+        return BinaryPredicate(self, "=", Literal(False))
+
+    def ASC(self) -> "OrderSpec":
+        from .expr import OrderSpec
+        return OrderSpec(self, "ASC")
+
+    def DESC(self) -> "OrderSpec":
+        from .expr import OrderSpec
+        return OrderSpec(self, "DESC")
+
+
+class Table:
+    def __init__(self, name: str, *columns: Column, alias: Optional[str] = None, columns_list: Optional[Iterable[Column]] = None):
+        self.name = name
+        self.alias = alias
+        if columns_list is not None:
+            cols = list(columns_list)
+        else:
+            cols = list(columns)
+        self._columns: Dict[str, Column] = {}
+        for col in cols:
+            if col.table is not self:
+                object.__setattr__(col, "table", self)  # type: ignore[misc]
+            self._columns[col.name] = col
+        self.c = _ColumnAccessor(self._columns)
+
+    def __repr__(self) -> str:  # pragma: no cover - debug aid
+        return f"Table({self.name})"
+
+    def AS(self, alias: str) -> "Table":
+        return Table(self.name, columns_list=self._columns.values(), alias=alias)
+
+    @property
+    def columns(self) -> List[Column]:
+        return list(self._columns.values())
+
+
+def col(name: str, py_type: type) -> Column:
+    # Placeholder table; Table will reset table reference on init.
+    dummy = Table("__dummy__")
+    return Column(name=name, py_type=py_type, table=dummy)
+
+
+class _ColumnAccessor:
+    def __init__(self, columns: Dict[str, Column]):
+        self._columns = columns
+
+    def __getattr__(self, item: str) -> Column:
+        try:
+            return self._columns[item]
+        except KeyError as exc:
+            raise AttributeError(item) from exc

sqlstratum/runner.py

@@ -0,0 +1,141 @@
+"""SQLite execution runner."""
+from __future__ import annotations
+
+import logging
+import os
+import sqlite3
+import time
+from contextlib import contextmanager
+from typing import Any, Dict, Iterable, Optional
+
+from . import ast
+from .compile import compile
+from .hydrate import hydrate_rows
+
+
+_LOGGER = logging.getLogger("sqlstratum")
+_DEBUG_TRUE = {"1", "true", "yes"}
+_MAX_PARAM_REPR_LEN = 200
+_MAX_BLOB_PREVIEW = 64
+
+
+def _env_debug_enabled() -> bool:
+    value = os.getenv("SQLSTRATUM_DEBUG", "")
+    return value.lower() in _DEBUG_TRUE
+
+
+def _debug_enabled() -> bool:
+    return _env_debug_enabled() and _LOGGER.isEnabledFor(logging.DEBUG)
+
+
+def _truncate(value: str, limit: int) -> str:
+    if len(value) <= limit:
+        return value
+    return f"{value[:limit]}...<{len(value) - limit} more>"
+
+
+def _safe_param_repr(value: Any) -> str:
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        data = bytes(value)
+        preview = data[:_MAX_BLOB_PREVIEW]
+        rep = repr(preview)
+        if len(data) > _MAX_BLOB_PREVIEW:
+            rep = f"{rep}...<{len(data) - _MAX_BLOB_PREVIEW} more bytes>"
+        return rep
+    rep = repr(value)
+    return _truncate(rep, _MAX_PARAM_REPR_LEN)
+
+
+def _render_params(params: Dict[str, Any]) -> str:
+    if not params:
+        return "{}"
+    items = ", ".join(f"{key}={_safe_param_repr(params[key])}" for key in sorted(params))
+    return "{" + items + "}"
+
+
+def _debug_log(compiled: ast.Compiled, duration_ms: float) -> None:
+    _LOGGER.debug(
+        "SQL: %s | params=%s | duration_ms=%.3f",
+        compiled.sql,
+        _render_params(compiled.params),
+        duration_ms,
+    )
+
+
+class Runner:
+    def __init__(self, connection: sqlite3.Connection):
+        self.connection = connection
+        self.connection.row_factory = sqlite3.Row
+        self._tx_depth = 0
+
+    @classmethod
+    def connect(cls, path: str) -> "Runner":
+        return cls(sqlite3.connect(path))
+
+    def exec_ddl(self, sql: str) -> None:
+        cur = self.connection.cursor()
+        cur.execute(sql)
+        if self._tx_depth == 0:
+            self.connection.commit()
+
+    def fetch_all(self, query: ast.SelectQuery) -> list[Any]:
+        compiled = compile(query)
+        log_enabled = _debug_enabled()
+        start = time.perf_counter() if log_enabled else 0.0
+        cur = self.connection.cursor()
+        cur.execute(compiled.sql, compiled.params)
+        rows = cur.fetchall()
+        if log_enabled:
+            _debug_log(compiled, (time.perf_counter() - start) * 1000)
+        return hydrate_rows(rows, query.projections, query.hydrate or dict)
+
+    def fetch_one(self, query: ast.SelectQuery) -> Optional[Any]:
+        compiled = compile(query)
+        log_enabled = _debug_enabled()
+        start = time.perf_counter() if log_enabled else 0.0
+        cur = self.connection.cursor()
+        cur.execute(compiled.sql, compiled.params)
+        row = cur.fetchone()
+        if log_enabled:
+            _debug_log(compiled, (time.perf_counter() - start) * 1000)
+        if row is None:
+            return None
+        return hydrate_rows([row], query.projections, query.hydrate or dict)[0]
+
+    def scalar(self, query: ast.SelectQuery) -> Optional[Any]:
+        compiled = compile(query)
+        log_enabled = _debug_enabled()
+        start = time.perf_counter() if log_enabled else 0.0
+        cur = self.connection.cursor()
+        cur.execute(compiled.sql, compiled.params)
+        row = cur.fetchone()
+        if log_enabled:
+            _debug_log(compiled, (time.perf_counter() - start) * 1000)
+        if row is None:
+            return None
+        return row[0]
+
+    def execute(self, query: Any) -> ast.ExecutionResult:
+        compiled = compile(query)
+        log_enabled = _debug_enabled()
+        start = time.perf_counter() if log_enabled else 0.0
+        cur = self.connection.cursor()
+        cur.execute(compiled.sql, compiled.params)
+        if self._tx_depth == 0:
+            self.connection.commit()
+        if log_enabled:
+            _debug_log(compiled, (time.perf_counter() - start) * 1000)
+        return ast.ExecutionResult(rowcount=cur.rowcount, lastrowid=cur.lastrowid)
+
+    @contextmanager
+    def transaction(self):
+        self._tx_depth += 1
+        try:
+            yield
+        except Exception:
+            self.connection.rollback()
+            raise
+        else:
+            self.connection.commit()
+        finally:
+            self._tx_depth -= 1

sqlstratum/types.py

@@ -0,0 +1,44 @@
+"""Type-checker-friendly Protocols for sqlstratum DSL."""
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional, Protocol, TYPE_CHECKING, runtime_checkable, TypeVar
+
+if TYPE_CHECKING:
+    from .expr import AliasExpr, BinaryPredicate, LogicalPredicate, NotPredicate, OrderSpec, UnaryPredicate
+
+
+@runtime_checkable
+class Expression(Protocol):
+    def AS(self, alias: str) -> "AliasExpr": ...
+
+    def ASC(self) -> "OrderSpec": ...
+
+    def DESC(self) -> "OrderSpec": ...
+
+    def __eq__(self, other: Any) -> "BinaryPredicate": ...
+
+    def __ne__(self, other: Any) -> "BinaryPredicate": ...
+
+    def __lt__(self, other: Any) -> "BinaryPredicate": ...
+
+    def __le__(self, other: Any) -> "BinaryPredicate": ...
+
+    def __gt__(self, other: Any) -> "BinaryPredicate": ...
+
+    def __ge__(self, other: Any) -> "BinaryPredicate": ...
+
+
+@runtime_checkable
+class Source(Protocol):
+    alias: Optional[str]
+    c: Any
+
+
+RowMapping = Dict[str, Any]
+T = TypeVar("T")
+Hydrator = Callable[[RowMapping], T]
+HydrationTarget = Callable[[RowMapping], Any] | type[Any] | None
+if TYPE_CHECKING:
+    Predicate = BinaryPredicate | UnaryPredicate | LogicalPredicate | NotPredicate
+else:  # pragma: no cover - typing only
+    Predicate = Any

sqlstratum-0.1.0.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: sqlstratum
+Version: 0.1.0
+Summary: Lightweight, source-first SQL AST + compiler + runner.
+Author-email: Antonio Ognio <aognio@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Antonio Ognio <aognio@gmail.com>
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/aognio/sqlstratum
+Project-URL: Repository, https://github.com/aognio/sqlstratum
+Project-URL: Issues, https://github.com/aognio/sqlstratum/issues
+Keywords: sql,query-builder,sqlite,compiler,ast
+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 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# SQLStratum
+
+<p align="center">
+  <img src="assets/images/SQLStratum-Logo-500x500-transparent.png" alt="SQLStratum logo" />
+</p>
+
+SQLStratum is a modern, typed, deterministic SQL query builder and compiler for Python with a 
+SQLite runner and a hydration pipeline. It exists to give applications and ORMs a reliable foundation 
+layer with composable SQL, predictable parameter binding, and explicit execution boundaries.
+
+## Key Features
+- Deterministic compilation: identical AST inputs produce identical SQL + params
+- Typed, composable DSL for SELECT/INSERT/UPDATE/DELETE
+- Safe parameter binding (no raw interpolation)
+- Hydration targets for structured results
+- SQLite-first execution via a small Runner API
+- Testable compiled output and runtime behavior
+
+## Non-Goals
+- Not an ORM (no identity map, relationships, lazy loading)
+- Not a migrations/DDL system
+- Not a full database abstraction layer for every backend yet (SQLite first)
+- Not a SQL string templating engine
+
+SQLStratum focuses on queries. DDL statements such as `CREATE TABLE` or `ALTER TABLE` are intended to
+live in a complementary library with similar design goals that is currently in the works.
+
+## Quickstart
+```python
+import sqlite3
+
+from sqlstratum import SELECT, INSERT, Table, col, Runner
+
+users = Table(
+    "users",
+    col("id", int),
+    col("email", str),
+    col("active", int),
+)
+
+conn = sqlite3.connect(":memory:")
+runner = Runner(conn)
+runner.exec_ddl("CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT, active INTEGER)")
+
+runner.execute(INSERT(users).VALUES(email="a@b.com", active=1))
+runner.execute(INSERT(users).VALUES(email="c@d.com", active=0))
+
+q = (
+    SELECT(users.c.id, users.c.email)
+    .FROM(users)
+    .WHERE(users.c.active.is_true())
+    .HYDRATE(dict)
+)
+
+rows = runner.fetch_all(q)
+print(rows)
+```
+
+## Why `Table` objects?
+SQLStratum’s `Table` objects are the schema anchor for the typed, deterministic query builder. They
+provides column metadata and a stable namespace for column access, which enables predictable SQL
+generation and safe parameter binding. They also support explicit aliasing to avoid ambiguous column
+names in joins.
+
+## Project Structure
+- AST: immutable query nodes in `sqlstratum/ast.py`
+- Compiler: SQL + params generation in `sqlstratum/compile.py`
+- Runner: SQLite execution and transactions in `sqlstratum/runner.py`
+- Hydration: projection rules and targets in `sqlstratum/hydrate.py`
+
+## SQL Debugging
+SQLStratum can log executed SQL statements (compiled SQL + parameters + duration), but logging is
+intentionally gated to avoid noisy output in production. Debug output requires two conditions:
+- Environment variable gate: `SQLSTRATUM_DEBUG` must be truthy (`"1"`, `"true"`, `"yes"`,
+  case-insensitive).
+- Logger gate: the `sqlstratum` logger must be DEBUG-enabled.
+
+Why it does not work by default: Python logging defaults to WARNING level, so even if
+`SQLSTRATUM_DEBUG=1` is set, DEBUG logs will not appear unless logging is configured.
+
+To enable debugging in a development app:
+
+Step 1 - set the environment variable:
+```
+SQLSTRATUM_DEBUG=1
+```
+
+Step 2 - configure logging early in the app:
+```python
+import logging
+
+logging.basicConfig(level=logging.DEBUG)
+# or
+logging.getLogger("sqlstratum").setLevel(logging.DEBUG)
+```
+
+Output looks like:
+```
+SQL: <compiled sql> | params={<sorted params>} | duration_ms=<...>
+```
+
+Architectural intent: logging happens at the Runner boundary (after execution). AST building and
+compilation remain deterministic and side-effect free, preserving separation of concerns.
+
+## Logo Inspiration
+
+Vinicunca (Rainbow Mountain) in Peru’s Cusco Region — a high-altitude day hike from
+Cusco at roughly 5,036 m (16,500 ft). See [Vinicunca](https://en.wikipedia.org/wiki/Vinicunca) for
+background.
+
+## Versioning / Roadmap
+Current version: `0.1.0`.
+Design notes and current limitations are tracked in `NOTES.md`. Roadmap planning is intentionally
+minimal at this stage and will evolve with real usage.
+
+## Authorship
+[Antonio Ognio](https://github.com/aognio/) is the maintainer and author of SQLStratum. ChatGPT is used for brainstorming,
+architectural thinking, documentation drafting, and project management advisory. Codex (CLI/agentic
+coding) is used to implement many code changes under Antonio's direction and review. The maintainer
+reviews and curates changes; AI tools are assistants, not owners, and accountability remains with the
+maintainer.
+
+## License
+MIT License.
+
+## Contributing
+PRs are welcome. Please read `CONTRIBUTING.md` for the workflow and expectations.

sqlstratum-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+sqlstratum/__init__.py,sha256=Qa9boJoOFjo429057MHBm-X0Qf6jHLC28o21JIROaXg,652
+sqlstratum/ast.py,sha256=zbycfm_3zdQCq-g-XCZhS20QTNCUrr1I7hlZ0-4xoeQ,2027
+sqlstratum/compile.py,sha256=_d_q0mGQT7LKrtveTejTqgGCt63TewLGdgc0z4bcTzI,6371
+sqlstratum/dsl.py,sha256=stW_ByQuzGL9tdfm3wIQ8nhAsI-3G9sjFVNojVc8Tek,4478
+sqlstratum/expr.py,sha256=NfqF1HKgbZyae4fMOq9UU4zDIhbmwVyZLVx8HGT2e5c,2629
+sqlstratum/hydrate.py,sha256=giaeAk6otaXIKvDLHZ7oht4MF8OAX9UgijAW2gzpG_Q,1532
+sqlstratum/meta.py,sha256=ZjM_mO-nQgPvChSIByTiyab1pgWmgVJ1Y2jafvKisc8,3953
+sqlstratum/runner.py,sha256=6djSwHntK7T87jI_tkLVDzkfBRa1f-3mjRvIwVPJnuU,4439
+sqlstratum/types.py,sha256=QRfLxf2awVtAAf8aZk8DFasBJTfNKzuE4Gfb3RjUnEc,1251
+sqlstratum-0.1.0.dist-info/licenses/LICENSE,sha256=fbtpXCPZdyN1PZtmPY6pQGqQ6uK7ceT_xcAuHvLVeNw,1089
+sqlstratum-0.1.0.dist-info/METADATA,sha256=Xzk70uyjsg_LONlP37XN0Hyau5QWkhtimz9o9wYhyuI,7074
+sqlstratum-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+sqlstratum-0.1.0.dist-info/top_level.txt,sha256=Hi7z6fGPj8r4mv7p8GFS9afMvXJCmcH_crD_yS6lnNg,11
+sqlstratum-0.1.0.dist-info/RECORD,,

sqlstratum-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sqlstratum-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antonio Ognio <aognio@gmail.com>
+
+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.

sqlstratum-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sqlstratum