sqlpiston 0.1.0__py3-none-any.whl

sqlpiston/__init__.py

@@ -0,0 +1,27 @@
+from sqlpiston._types import ColumnValue, SQLValue
+from sqlpiston.builder.ddl import (
+    AlterTable, ColumnDef, CreateIndex, CreateTable, CreateView,
+    DropIndex, DropTable, DropView, Truncate,
+)
+from sqlpiston.builder.dml import Delete, Insert, Update, Upsert
+from sqlpiston.builder.nodes import CaseNode, Field, SQLFunction
+from sqlpiston.builder.selectable import CTE, CompoundSelect, Select
+from sqlpiston.compiler.base import Dialect
+from sqlpiston.core.engine import DBType
+from sqlpiston.core.engine.base import DBEngine
+from sqlpiston.core.pool import ConnectionPool
+from sqlpiston.core.session import Session
+from sqlpiston.orm.mapper import ResultSet
+
+__all__ = [
+    'SQLValue', 'ColumnValue',
+    'AlterTable', 'ColumnDef', 'CreateIndex', 'CreateTable', 'CreateView',
+    'DropIndex', 'DropTable', 'DropView', 'Truncate',
+    'Delete', 'Insert', 'Update', 'Upsert',
+    'CaseNode', 'Field', 'SQLFunction',
+    'CTE', 'CompoundSelect', 'Select',
+    'Dialect',
+    'DBType', 'DBEngine',
+    'ConnectionPool', 'Session',
+    'ResultSet',
+]

sqlpiston/_types.py

@@ -0,0 +1,5 @@
+from typing import TypeAlias, Union
+
+
+SQLValue: TypeAlias = Union[str, int, float, bool, None, bytes]
+ColumnValue = SQLValue

sqlpiston/builder/ddl.py

@@ -0,0 +1,228 @@
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, List, Optional, Tuple
+
+from sqlpiston.builder.nodes import ASTNode
+from sqlpiston._types import SQLValue
+
+if TYPE_CHECKING:
+    from sqlpiston.builder.selectable import Select
+
+
+class AlterAction(Enum):
+    ADD = 1
+    DROP = 2
+    MODIFY = 3
+
+
+@dataclass
+class ColumnDef:
+    """Column definition for CREATE TABLE."""
+    name: str
+    type_: str
+    nullable: bool = True
+    primary_key: bool = False
+    default: Optional[SQLValue] = None
+    unique: bool = False
+
+
+class CreateTable(ASTNode):
+    """CREATE TABLE name (col1 TYPE, col2 TYPE, ...)"""
+
+    def __init__(self) -> None:
+        self._table: Optional[str] = None
+        self._if_not_exists: bool = False
+        self._columns: List[ColumnDef] = []
+
+    def table(self, name: str) -> 'CreateTable':
+        self._table = name
+        return self
+
+    def if_not_exists(self) -> 'CreateTable':
+        self._if_not_exists = True
+        return self
+
+    def column(self, name: str, type_: str, *,
+               nullable: bool = True,
+               primary_key: bool = False,
+               default: Optional[SQLValue] = None,
+               unique: bool = False) -> 'CreateTable':
+        self._columns.append(ColumnDef(
+            name=name, type_=type_, nullable=nullable,
+            primary_key=primary_key, default=default, unique=unique,
+        ))
+        return self
+
+    def columns(self, *col_defs: ColumnDef) -> 'CreateTable':
+        self._columns.extend(col_defs)
+        return self
+
+    def __repr__(self) -> str:
+        return f"CreateTable(table={self._table!r}, columns={len(self._columns)})"
+
+
+class AlterTable(ASTNode):
+    """ALTER TABLE name ADD/DROP/MODIFY COLUMN ..."""
+
+    def __init__(self) -> None:
+        self._table: Optional[str] = None
+        self._actions: List[Tuple[AlterAction, str, Optional[str], Optional[ColumnDef]]] = []
+
+    def table(self, name: str) -> 'AlterTable':
+        self._table = name
+        return self
+
+    def add_column(self, name: str, type_: str, *,
+                   nullable: bool = True,
+                   default: Optional[SQLValue] = None) -> 'AlterTable':
+        col_def = ColumnDef(name=name, type_=type_, nullable=nullable, default=default)
+        self._actions.append((AlterAction.ADD, name, type_, col_def))
+        return self
+
+    def drop_column(self, name: str) -> 'AlterTable':
+        self._actions.append((AlterAction.DROP, name, None, None))
+        return self
+
+    def modify_column(self, name: str, type_: str, *,
+                      nullable: bool = True,
+                      default: Optional[SQLValue] = None) -> 'AlterTable':
+        col_def = ColumnDef(name=name, type_=type_, nullable=nullable, default=default)
+        self._actions.append((AlterAction.MODIFY, name, type_, col_def))
+        return self
+
+    def __repr__(self) -> str:
+        return f"AlterTable(table={self._table!r}, actions={len(self._actions)})"
+
+
+class DropTable(ASTNode):
+    """DROP TABLE [IF EXISTS] name"""
+
+    def __init__(self) -> None:
+        self._table: Optional[str] = None
+        self._if_exists: bool = False
+
+    def table(self, name: str) -> 'DropTable':
+        self._table = name
+        return self
+
+    def if_exists(self) -> 'DropTable':
+        self._if_exists = True
+        return self
+
+    def __repr__(self) -> str:
+        return f"DropTable(table={self._table!r}, if_exists={self._if_exists})"
+
+
+class CreateIndex(ASTNode):
+    """CREATE [UNIQUE] INDEX [IF NOT EXISTS] name ON table (col1, col2, ...)"""
+
+    def __init__(self) -> None:
+        self._name: Optional[str] = None
+        self._table: Optional[str] = None
+        self._columns: Tuple[str, ...] = ()
+        self._unique: bool = False
+        self._if_not_exists: bool = False
+
+    def name(self, idx_name: str) -> 'CreateIndex':
+        self._name = idx_name
+        return self
+
+    def on(self, table: str) -> 'CreateIndex':
+        self._table = table
+        return self
+
+    def columns(self, *cols: str) -> 'CreateIndex':
+        self._columns = cols
+        return self
+
+    def unique(self) -> 'CreateIndex':
+        self._unique = True
+        return self
+
+    def if_not_exists(self) -> 'CreateIndex':
+        self._if_not_exists = True
+        return self
+
+    def __repr__(self) -> str:
+        return f"CreateIndex(name={self._name!r}, table={self._table!r})"
+
+
+class DropIndex(ASTNode):
+    """DROP INDEX [IF EXISTS] name ON table"""
+
+    def __init__(self) -> None:
+        self._name: Optional[str] = None
+        self._table: Optional[str] = None
+        self._if_exists: bool = False
+
+    def name(self, idx_name: str) -> 'DropIndex':
+        self._name = idx_name
+        return self
+
+    def on(self, table: str) -> 'DropIndex':
+        self._table = table
+        return self
+
+    def if_exists(self) -> 'DropIndex':
+        self._if_exists = True
+        return self
+
+    def __repr__(self) -> str:
+        return f"DropIndex(name={self._name!r}, table={self._table!r})"
+
+
+class CreateView(ASTNode):
+    """CREATE VIEW [IF NOT EXISTS] name AS SELECT ..."""
+
+    def __init__(self) -> None:
+        self._name: Optional[str] = None
+        self._select: Optional['Select'] = None
+        self._if_not_exists: bool = False
+
+    def name(self, view_name: str) -> 'CreateView':
+        self._name = view_name
+        return self
+
+    def as_(self, select: 'Select') -> 'CreateView':
+        self._select = select
+        return self
+
+    def if_not_exists(self) -> 'CreateView':
+        self._if_not_exists = True
+        return self
+
+    def __repr__(self) -> str:
+        return f"CreateView(name={self._name!r})"
+
+
+class DropView(ASTNode):
+    """DROP VIEW [IF EXISTS] name"""
+
+    def __init__(self) -> None:
+        self._name: Optional[str] = None
+        self._if_exists: bool = False
+
+    def name(self, view_name: str) -> 'DropView':
+        self._name = view_name
+        return self
+
+    def if_exists(self) -> 'DropView':
+        self._if_exists = True
+        return self
+
+    def __repr__(self) -> str:
+        return f"DropView(name={self._name!r})"
+
+
+class Truncate(ASTNode):
+    """TRUNCATE TABLE name"""
+
+    def __init__(self) -> None:
+        self._table: Optional[str] = None
+
+    def table(self, name: str) -> 'Truncate':
+        self._table = name
+        return self
+
+    def __repr__(self) -> str:
+        return f"Truncate(table={self._table!r})"

sqlpiston/builder/dml.py

@@ -0,0 +1,124 @@
+from typing import TYPE_CHECKING, Dict, Optional, Tuple
+
+from sqlpiston.builder.nodes import ASTNode
+from sqlpiston._types import ColumnValue
+
+if TYPE_CHECKING:
+    from sqlpiston.builder.selectable import Select
+
+
+class Insert(ASTNode):
+    """INSERT INTO table (col1, col2) VALUES (v1, v2)
+       INSERT INTO table (col1, col2) SELECT ...
+    """
+
+    def __init__(self) -> None:
+        self._table: Optional[str] = None
+        self._data: Optional[Dict[str, ColumnValue]] = None
+        self._select: Optional['Select'] = None
+
+    def into(self, table: str) -> 'Insert':
+        self._table = table
+        return self
+
+    def values(self, data: Dict[str, ColumnValue]) -> 'Insert':
+        self._data = data
+        self._select = None
+        return self
+
+    def select(self, select: 'Select') -> 'Insert':
+        self._select = select
+        self._data = None
+        return self
+
+    def __repr__(self) -> str:
+        return f"Insert(into={self._table!r})"
+
+
+class Update(ASTNode):
+    """UPDATE table SET col1=v1, col2=v2 WHERE condition"""
+
+    def __init__(self) -> None:
+        self._table: Optional[str] = None
+        self._data: Optional[Dict[str, ColumnValue]] = None
+        self._where: Optional[ASTNode] = None
+
+    def table(self, name: str) -> 'Update':
+        self._table = name
+        return self
+
+    def set(self, data: Dict[str, ColumnValue]) -> 'Update':
+        self._data = data
+        return self
+
+    def where(self, condition: ASTNode) -> 'Update':
+        self._where = condition
+        return self
+
+    def __repr__(self) -> str:
+        return f"Update(table={self._table!r})"
+
+
+class Delete(ASTNode):
+    """DELETE FROM table WHERE condition"""
+
+    def __init__(self) -> None:
+        self._table: Optional[str] = None
+        self._where: Optional[ASTNode] = None
+
+    def from_table(self, table: str) -> 'Delete':
+        self._table = table
+        return self
+
+    def where(self, condition: ASTNode) -> 'Delete':
+        self._where = condition
+        return self
+
+    def __repr__(self) -> str:
+        return f"Delete(from={self._table!r})"
+
+
+class Upsert(ASTNode):
+    """Standard UPSERT — AST stores intent; dialect compilers translate per DB.
+
+    MySQL compiler  → INSERT INTO ... VALUES (...) ON DUPLICATE KEY UPDATE ...
+    SQLite compiler → INSERT INTO ... VALUES (...) ON CONFLICT (...) DO UPDATE SET ...
+
+    Usage:
+        Upsert()
+            .into("users")
+            .values({"id": 1, "name": "X"})
+            .on_conflict("id")
+            .do_update({"name": "X"})
+    """
+
+    def __init__(self) -> None:
+        self._table: Optional[str] = None
+        self._data: Optional[Dict[str, ColumnValue]] = None
+        self._conflict_columns: Optional[Tuple[str, ...]] = None
+        self._update_data: Optional[Dict[str, ColumnValue]] = None
+        self._do_nothing: bool = False
+
+    def into(self, table: str) -> 'Upsert':
+        self._table = table
+        return self
+
+    def values(self, data: Dict[str, ColumnValue]) -> 'Upsert':
+        self._data = data
+        return self
+
+    def on_conflict(self, *columns: str) -> 'Upsert':
+        self._conflict_columns = columns
+        return self
+
+    def do_update(self, data: Dict[str, ColumnValue]) -> 'Upsert':
+        self._update_data = data
+        self._do_nothing = False
+        return self
+
+    def do_nothing(self) -> 'Upsert':
+        self._do_nothing = True
+        return self
+
+    def __repr__(self) -> str:
+        return f"Upsert(into={self._table!r}, conflict={self._conflict_columns!r})"

sqlpiston/builder/nodes.py

@@ -0,0 +1,248 @@
+from abc import ABC
+from typing import (
+    TYPE_CHECKING, List, Literal, Optional, Sequence, Tuple, Union, cast, overload,
+)
+
+from sqlpiston._types import SQLValue
+
+if TYPE_CHECKING:
+    from sqlpiston.builder.selectable import Select
+    from sqlpiston.compiler.base import Dialect
+
+# ExprValue: a value that can appear in an AST expression.
+# Can be a scalar literal, another Field reference, a Select subquery, or a function call.
+# 'Select' is a string forward-reference to avoid circular imports with selectable.py.
+ExprValue = Union[SQLValue, 'Field', 'Select', 'SQLFunction']
+
+
+class Field:
+    """Column reference. Operator overloading returns AST nodes, not values.
+
+    Usage:
+        Field("age") >= 18          → ComparisonNode
+        Field("id", "users")        → qualified column
+        Field("name").alias("n")    → name AS n
+    """
+
+    def __init__(self, name: str, table: Optional[str] = None) -> None:
+        self._name = name
+        self._table = table
+        self._alias: Optional[str] = None
+
+    def __repr__(self) -> str:
+        parts: List[str] = []
+        if self._table:
+            parts.append(self._table)
+        parts.append(self._name)
+        base = ".".join(parts)
+        if self._alias:
+            return f"Field({base} AS {self._alias})"
+        return f"Field({base})"
+
+    def __eq__(self, value: object) -> 'ComparisonNode':  # type: ignore[override]  # intentional: return AST node, not bool
+        return ComparisonNode(self, '=', cast(ExprValue, value))
+
+    def __ne__(self, value: object) -> 'ComparisonNode':  # type: ignore[override]  # intentional: return AST node, not bool
+        return ComparisonNode(self, '!=', cast(ExprValue, value))
+
+    def __lt__(self, value: ExprValue) -> 'ComparisonNode':
+        return ComparisonNode(self, '<', value)
+
+    def __le__(self, value: ExprValue) -> 'ComparisonNode':
+        return ComparisonNode(self, '<=', value)
+
+    def __gt__(self, value: ExprValue) -> 'ComparisonNode':
+        return ComparisonNode(self, '>', value)
+
+    def __ge__(self, value: ExprValue) -> 'ComparisonNode':
+        return ComparisonNode(self, '>=', value)
+
+    def __hash__(self) -> int:
+        return hash((self._name, self._table, self._alias))
+
+    @overload
+    def is_in(self, values: Sequence[SQLValue]) -> 'InNode': ...
+
+    @overload
+    def is_in(self, values: 'Select') -> 'InNode': ...
+
+    def is_in(self, values: Union[Sequence[SQLValue], 'Select']) -> 'InNode':
+        return InNode(self, values)
+
+    def between(self, low: ExprValue, high: ExprValue) -> 'BetweenNode':
+        return BetweenNode(self, low, high)
+
+    def is_null(self) -> 'ComparisonNode':
+        return ComparisonNode(self, 'IS NULL', None)
+
+    def is_not_null(self) -> 'ComparisonNode':
+        return ComparisonNode(self, 'IS NOT NULL', None)
+
+    def alias(self, name: str) -> 'Field':
+        f = Field(self._name, self._table)
+        f._alias = name
+        return f
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def table(self) -> Optional[str]:
+        return self._table
+
+    @property
+    def _alias_prop(self) -> Optional[str]:
+        return self._alias
+
+
+class ASTNode(ABC):
+    """Base for all expression/statement nodes.
+
+    compile() delegates to a dialect-specific compiler via the visitor pattern.
+    """
+
+    def __and__(self, other: 'ASTNode') -> 'LogicalNode':
+        return LogicalNode('AND', [self, other])
+
+    def __or__(self, other: 'ASTNode') -> 'LogicalNode':
+        return LogicalNode('OR', [self, other])
+
+    def __invert__(self) -> 'LogicalNode':
+        return LogicalNode('NOT', [self])
+
+    def compile(self, dialect: Optional['Dialect'] = None) -> Tuple[str, Tuple[ExprValue, ...]]:
+        if dialect is None:
+            from sqlpiston.compiler.base import Compiler, GenericCompiler
+            compiler: Compiler = GenericCompiler()
+        else:
+            compiler = dialect.get_compiler()
+        return compiler.process(self)
+
+
+class ComparisonNode(ASTNode):
+    """leaf: field OP value
+
+    value can be:
+    - SQL literal  → field OP %s    (parameterized)
+    - Field        → field OP other_field   (table-qualified comparison)
+    - Select       → field OP (SELECT ...)  (scalar subquery)
+    - SQLFunction  → field OP func(...)
+    """
+
+    def __init__(self, field: Field, operator: str, value: ExprValue) -> None:
+        self.field = field
+        self.operator = operator
+        self.value: ExprValue = value
+
+    def __repr__(self) -> str:
+        return f"ComparisonNode({self.field} {self.operator} {self.value!r})"
+
+
+class InNode(ASTNode):
+    """leaf: field IN (...literals...)  or  field IN (SELECT ...)"""
+
+    def __init__(self, field: Field, values: Union[Sequence[SQLValue], 'Select']) -> None:
+        self.field = field
+        self.values: Union[Sequence[SQLValue], 'Select'] = values
+
+    def __repr__(self) -> str:
+        return f"InNode({self.field} IN {self.values!r})"
+
+
+class BetweenNode(ASTNode):
+    """leaf: field BETWEEN low AND high"""
+
+    def __init__(self, field: Field, low: ExprValue, high: ExprValue) -> None:
+        self.field = field
+        self.low: ExprValue = low
+        self.high: ExprValue = high
+
+    def __repr__(self) -> str:
+        return f"BetweenNode({self.field} BETWEEN {self.low!r} AND {self.high!r})"
+
+
+class LogicalNode(ASTNode):
+    """composite: AND / OR / NOT.
+
+    Same-operator flattening: A & B & C → one LogicalNode('AND', [A,B,C]),
+    not nested.
+    """
+
+    def __init__(self, operator: Literal['AND', 'OR', 'NOT'], children: List[ASTNode]) -> None:
+        self.operator = operator
+        self.children = children
+
+    def __and__(self, other: ASTNode) -> 'LogicalNode':
+        if self.operator == 'AND':
+            return LogicalNode('AND', self.children + [other])
+        return LogicalNode('AND', [self, other])
+
+    def __or__(self, other: ASTNode) -> 'LogicalNode':
+        if self.operator == 'OR':
+            return LogicalNode('OR', self.children + [other])
+        return LogicalNode('OR', [self, other])
+
+    def __repr__(self) -> str:
+        return f"LogicalNode({self.operator}, children={len(self.children)})"
+
+
+class ExistsNode(ASTNode):
+    """EXISTS (SELECT ...)  or  NOT EXISTS (SELECT ...)"""
+
+    def __init__(self, select: 'Select', negated: bool = False) -> None:
+        self.select = select
+        self.negated = negated
+
+    def __repr__(self) -> str:
+        prefix = "NOT EXISTS" if self.negated else "EXISTS"
+        return f"ExistsNode({prefix} {self.select!r})"
+
+
+class CaseNode(ASTNode):
+    """CASE WHEN cond1 THEN val1 WHEN cond2 THEN val2 ... [ELSE default] END
+
+    Usage:
+        CaseNode()
+            .when(Field("score") >= 90, "A")
+            .when(Field("score") >= 80, "B")
+            .else_("C")
+    """
+
+    def __init__(self) -> None:
+        self._whens: List[Tuple[ASTNode, ExprValue]] = []
+        self._else: Optional[ExprValue] = None
+
+    def when(self, condition: ASTNode, result: ExprValue) -> 'CaseNode':
+        self._whens.append((condition, result))
+        return self
+
+    def else_(self, default: ExprValue) -> 'CaseNode':
+        self._else = default
+        return self
+
+    def __repr__(self) -> str:
+        return f"CaseNode(whens={len(self._whens)}, has_else={self._else is not None})"
+
+
+class SQLFunction(ASTNode):
+    """SQL function call: COUNT(*), SUM(col), COALESCE(a, b), etc.
+
+    Usage:
+        SQLFunction("count", "*")
+        SQLFunction("coalesce", Field("name"), "N/A")
+        SQLFunction("sum", Field("amount"))
+    """
+
+    def __init__(self, name: str, *args: Union[str, Field, 'SQLFunction']) -> None:
+        self.name = name
+        self.args: Tuple[Union[str, Field, 'SQLFunction'], ...] = args
+        self._alias: Optional[str] = None
+
+    def alias(self, name: str) -> 'SQLFunction':
+        self._alias = name
+        return self
+
+    def __repr__(self) -> str:
+        alias_str = f" AS {self._alias}" if self._alias else ""
+        return f"SQLFunction({self.name}({', '.join(repr(a) for a in self.args)}){alias_str})"