python-corekit 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

corekit/connections/sql/migration/operations.py

@@ -1,7 +1,7 @@
 """
 Migration operations.
 
-Each Operation knows how to:
+Each MigrationOperation knows how to:
   - render itself to SQL (for execution) OR execute Python logic
   - render a canonical string (for checksumming)
 
@@ -22,9 +22,16 @@ from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Callable
 
+from sqlalchemy.dialects import postgresql
+
+from corekit.connections.sql.table import NamedTable
+
 if TYPE_CHECKING:
     from corekit.connections.sql.connection import SQLConnection
 
+#: Renders a table's name the way the database expects to read it.
+_PREPARER = postgresql.dialect().identifier_preparer
+
 
 # ---------------------------------------------------------------------------
 # Constants
@@ -151,7 +158,7 @@ class QueryBuilder:
         return self._query.strip()
 
 
-class Operation(ABC):
+class MigrationOperation(ABC):
     """
     Base class for all operations.
     """
@@ -159,6 +166,21 @@ class Operation(ABC):
     def _builder(self) -> QueryBuilder:
         return QueryBuilder()
 
+    @property
+    def table_name(self) -> str:
+        """
+        The table this operation targets, spelled for SQL.
+
+        A model class is rendered by the dialect, which quotes a reserved word
+        such as ``user`` and leaves anything else bare. A plain string is used
+        as given, so a migration can name a table that has no model class --
+        one dropped or renamed since, or not yet defined.
+        """
+        table = getattr(self, "table", None)
+        if isinstance(table, str) or table is None:
+            return table
+        return _PREPARER.format_table(table.__table__)
+
     @abstractmethod
     def to_sql(self) -> str:
         """
@@ -193,7 +215,7 @@ class Operation(ABC):
 
 
 @dataclass
-class AddColumn(Operation):
+class AddColumn(MigrationOperation):
     """
     Add a column to an existing table.
 
@@ -201,7 +223,7 @@ class AddColumn(Operation):
     not. Set it to False when targeting SQLite.
     """
 
-    table: str
+    table: type[NamedTable] | str
     column: str
     dtype: str
     safe: bool = True
@@ -212,7 +234,7 @@ class AddColumn(Operation):
         """
         Example: ALTER TABLE <table_name> ADD COLUMN [IF NOT EXISTS] <column_name> <dtype>
         """
-        builder = self._builder().alter(TABLE, self.table).add(COLUMN)
+        builder = self._builder().alter(TABLE, self.table_name).add(COLUMN)
         if self.safe:
             builder.if_not_exists()
 
@@ -227,29 +249,29 @@ class AddColumn(Operation):
 
     def canonical(self) -> str:
         return (
-            f"AddColumn(table={self.table}, column={self.column}, dtype={self.dtype}, "
+            f"AddColumn(table={self.table_name}, column={self.column}, dtype={self.dtype}, "
             f"nullable={self.nullable}, default={self.default})"
         )
 
 
 @dataclass
-class DropColumn(Operation):
-    table: str
+class DropColumn(MigrationOperation):
+    table: type[NamedTable] | str
     column: str
 
     def to_sql(self) -> str:
         """
         Example: ALTER TABLE <table_name> DROP COLUMN [IF EXISTS] <column_name>
         """
-        return self._builder().alter(TABLE, self.table).drop(COLUMN).if_exists().append(self.column).build()
+        return self._builder().alter(TABLE, self.table_name).drop(COLUMN).if_exists().append(self.column).build()
 
     def canonical(self) -> str:
-        return f"DropColumn(table={self.table}, column={self.column})"
+        return f"DropColumn(table={self.table_name}, column={self.column})"
 
 
 @dataclass
-class AlterColumnType(Operation):
-    table: str
+class AlterColumnType(MigrationOperation):
+    table: type[NamedTable] | str
     column: str
     new_dtype: str
     using: str | None = None
@@ -258,21 +280,19 @@ class AlterColumnType(Operation):
         """
         Example: ALTER TABLE <table_name> ALTER COLUMN <column_name> TYPE <new_dtype> [USING <using>]
         """
-        builder = self._builder().alter(TABLE, self.table).alter(COLUMN, self.column).type(self.new_dtype)
+        builder = self._builder().alter(TABLE, self.table_name).alter(COLUMN, self.column).type(self.new_dtype)
         if self.using:
             builder.using(self.using)
 
         return builder.build()
 
     def canonical(self) -> str:
-        return (
-            f"AlterColumnType(table={self.table}, column={self.column}, new_dtype={self.new_dtype}, using={self.using})"
-        )
+        return f"AlterColumnType(table={self.table_name}, column={self.column}, new_dtype={self.new_dtype}, using={self.using})"
 
 
 @dataclass
-class SetColumnDefault(Operation):
-    table: str
+class SetColumnDefault(MigrationOperation):
+    table: type[NamedTable] | str
     column: str
     default: str
 
@@ -280,25 +300,27 @@ class SetColumnDefault(Operation):
         """
         Example: ALTER TABLE <table_name> ALTER COLUMN <column_name> SET DEFAULT <default>
         """
-        return self._builder().alter(TABLE, self.table).alter(COLUMN, self.column).set_default(self.default).build()
+        return (
+            self._builder().alter(TABLE, self.table_name).alter(COLUMN, self.column).set_default(self.default).build()
+        )
 
     def canonical(self) -> str:
-        return f"SetColumnDefault(table={self.table}, column={self.column}, default={self.default})"
+        return f"SetColumnDefault(table={self.table_name}, column={self.column}, default={self.default})"
 
 
 @dataclass
-class DropColumnDefault(Operation):
-    table: str
+class DropColumnDefault(MigrationOperation):
+    table: type[NamedTable] | str
     column: str
 
     def to_sql(self) -> str:
         """
         Example: ALTER TABLE <table_name> ALTER COLUMN <column_name> DROP DEFAULT
         """
-        return self._builder().alter(TABLE, self.table).alter(COLUMN, self.column).drop_default().build()
+        return self._builder().alter(TABLE, self.table_name).alter(COLUMN, self.column).drop_default().build()
 
     def canonical(self) -> str:
-        return f"DropColumnDefault(table={self.table}, column={self.column})"
+        return f"DropColumnDefault(table={self.table_name}, column={self.column})"
 
 
 # ---------------------------------------------------------------------------
@@ -307,23 +329,23 @@ class DropColumnDefault(Operation):
 
 
 @dataclass
-class CreateIndex(Operation):
+class CreateIndex(MigrationOperation):
     index_name: str
-    table: str
+    table: type[NamedTable] | str
     columns: list[str]
     unique: bool = False
 
     def to_sql(self) -> str:
         unique_clause = "UNIQUE " if self.unique else ""
         cols = ", ".join(self.columns)
-        return f"CREATE {unique_clause}INDEX IF NOT EXISTS {self.index_name} ON {self.table} ({cols})"
+        return f"CREATE {unique_clause}INDEX IF NOT EXISTS {self.index_name} ON {self.table_name} ({cols})"
 
     def canonical(self) -> str:
-        return f"CreateIndex(name={self.index_name}, table={self.table}, columns={self.columns}, unique={self.unique})"
+        return f"CreateIndex(name={self.index_name}, table={self.table_name}, columns={self.columns}, unique={self.unique})"
 
 
 @dataclass
-class DropIndex(Operation):
+class DropIndex(MigrationOperation):
     index_name: str
 
     def to_sql(self) -> str:
@@ -338,21 +360,87 @@ class DropIndex(Operation):
 # ---------------------------------------------------------------------------
 
 
+@dataclass(frozen=True)
+class ColumnSpec:
+    """
+    One column in a ``CreateTable`` statement.
+
+    Types and defaults are SQL text, as on ``AddColumn``, not Python values.
+    Write ``default="FALSE"`` or ``default="'red'"``, not ``False`` or
+    ``"red"``.
+    """
+
+    name: str
+    dtype: str
+    nullable: bool = True
+    primary_key: bool = False
+    default: str | None = None
+
+
+@dataclass
+class CreateTable(MigrationOperation):
+    """
+    Create a table from an explicit column list.
+
+    This is a new operation. It does not change the SQL or checksum of
+    ``AddColumn`` and the other existing operations. Listing the columns here,
+    rather than reading a model at run time, is what keeps an applied
+    migration's checksum stable when that model later gains a field.
+
+    ``if_not_exists`` defaults to True. Both SQLite and Postgres accept
+    ``CREATE TABLE IF NOT EXISTS``.
+    """
+
+    table: type[NamedTable] | str
+    columns: list[ColumnSpec]
+    if_not_exists: bool = True
+
+    def to_sql(self) -> str:
+        """
+        Example: CREATE TABLE [IF NOT EXISTS] <table_name> (<column> <dtype> ...)
+        """
+        if not self.columns:
+            raise ValueError("CreateTable requires at least one column")
+
+        definitions = ", ".join(self._column_sql(column) for column in self.columns)
+        exists = "IF NOT EXISTS " if self.if_not_exists else ""
+        return f"CREATE TABLE {exists}{self.table_name} ({definitions})"
+
+    @staticmethod
+    def _column_sql(column: ColumnSpec) -> str:
+        parts = [column.name, column.dtype]
+        if column.primary_key:
+            parts.append("PRIMARY KEY")
+        if not column.nullable:
+            parts.append("NOT NULL")
+        if column.default is not None:
+            parts.append(f"DEFAULT {column.default}")
+        return " ".join(parts)
+
+    def canonical(self) -> str:
+        rendered = ", ".join(
+            f"{column.name}:{column.dtype}:nullable={column.nullable}:"
+            f"primary_key={column.primary_key}:default={column.default}"
+            for column in self.columns
+        )
+        return f"CreateTable(table={self.table_name}, columns=[{rendered}], if_not_exists={self.if_not_exists})"
+
+
 @dataclass
-class DropTable(Operation):
-    table: str
+class DropTable(MigrationOperation):
+    table: type[NamedTable] | str
     cascade: bool = False
 
     def to_sql(self) -> str:
         cascade_clause = " CASCADE" if self.cascade else ""
-        return f"DROP TABLE IF EXISTS {self.table}{cascade_clause}"
+        return f"DROP TABLE IF EXISTS {self.table_name}{cascade_clause}"
 
     def canonical(self) -> str:
-        return f"DropTable(table={self.table}, cascade={self.cascade})"
+        return f"DropTable(table={self.table_name}, cascade={self.cascade})"
 
 
 @dataclass
-class RenameTable(Operation):
+class RenameTable(MigrationOperation):
     old_name: str
     new_name: str
 
@@ -364,16 +452,16 @@ class RenameTable(Operation):
 
 
 @dataclass
-class RenameColumn(Operation):
-    table: str
+class RenameColumn(MigrationOperation):
+    table: type[NamedTable] | str
     old_name: str
     new_name: str
 
     def to_sql(self) -> str:
-        return f"ALTER TABLE {self.table} RENAME COLUMN {self.old_name} TO {self.new_name}"
+        return f"ALTER TABLE {self.table_name} RENAME COLUMN {self.old_name} TO {self.new_name}"
 
     def canonical(self) -> str:
-        return f"RenameColumn(table={self.table}, old={self.old_name}, new={self.new_name})"
+        return f"RenameColumn(table={self.table_name}, old={self.old_name}, new={self.new_name})"
 
 
 # ---------------------------------------------------------------------------
@@ -382,21 +470,22 @@ class RenameColumn(Operation):
 
 
 @dataclass
-class DataOperation(Operation):
+class DataMigrationOperation(MigrationOperation):
     """
     Executes a Python function for data migrations (seeding, transformations).
 
     The function receives a SQLConnection and should use ORM methods to
-    read/write data. The `name` is used for checksumming - changing it will
-    invalidate the checksum, so choose a stable, descriptive name.
+    read/write data. The checksum is the ``name`` only, not the function.
+    Editing the callable without a new name is invisible to history, so a
+    changed function requires a new name. Choose a stable, descriptive one.
 
     Example:
-        DataOperation(
+        DataMigrationOperation(
             name="seed_user_permissions_v1",
             func=seed_permissions_from_roles,
         )
 
-    IMPORTANT: It is not appropriate to use DataOperation in place of other operations. This is
+    IMPORTANT: It is not appropriate to use DataMigrationOperation in place of other operations. This is
     reserved for the most complex operations that CANNOT be expressed otherwise.
     """
 
@@ -410,7 +499,9 @@ class DataOperation(Operation):
         self.func(conn)
 
     def to_sql(self) -> str:
-        raise NotImplementedError("DataOperation does not produce SQL; use execute() instead")
+        raise NotImplementedError("DataMigrationOperation does not produce SQL; use execute() instead")
 
     def canonical(self) -> str:
+        # This spelling is part of every applied data migration's checksum, so it
+        # is fixed regardless of what this class is called.
         return f"DataOperation(name={self.name})"

corekit/connections/sql/migration/registry.py

@@ -20,7 +20,7 @@ from types import ModuleType
 
 from corekit.connections.sql.connection import SQLConnection
 from corekit.connections.sql.migration.base import Migration
-from corekit.connections.sql.migration.operations import DataOperation
+from corekit.connections.sql.migration.operations import DataMigrationOperation
 from corekit.connections.sql.migration.table import SchemaMigration
 from corekit.observability.benchmarkable import Benchmarkable
 
@@ -120,7 +120,7 @@ class MigrationRegistry(Benchmarkable):
         self.info(f"Applying migration v{migration.version}: {migration.name}")
         for operation in migration.operations():
             self.info(f"  {operation.canonical()}")
-            if isinstance(operation, DataOperation):
+            if isinstance(operation, DataMigrationOperation):
                 operation.execute(conn)
             else:
                 conn.exec_ddl(operation.to_sql())

corekit/connections/sql/operations/__init__.py

@@ -0,0 +1,24 @@
+"""
+Statement primitives, from the shared base to the statements themselves.
+"""
+
+from corekit.connections.sql.operations.base import (
+    Conditional,
+    DdlOperation,
+    DmlOperation,
+    DqlOperation,
+    Operation,
+)
+from corekit.connections.sql.operations.statements import Delete, Insert, Select, Update
+
+__all__ = [
+    "Conditional",
+    "DdlOperation",
+    "Delete",
+    "DmlOperation",
+    "DqlOperation",
+    "Insert",
+    "Operation",
+    "Select",
+    "Update",
+]

corekit/connections/sql/operations/base.py

@@ -0,0 +1,111 @@
+"""
+Statement primitives: the shapes a database operation can take.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, ClassVar
+
+from pydantic import BaseModel, Field
+
+from corekit.connections.sql.table import NamedTable
+from corekit.data.expressions import Expression
+
+__all__ = ["Conditional", "DdlOperation", "DmlOperation", "DqlOperation", "Operation"]
+
+
+class Operation(BaseModel, ABC):
+    """
+    A statement waiting to be executed.
+
+    An operation compiles itself and nothing more: it holds no session and
+    runs no SQL, so building one is free of side effects and a connection
+    stays the only thing that owns a transaction.
+    """
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    #: True when executing this operation changes rows and must be committed.
+    #: Conditional writes (update, delete) and insert both set this; reads do not.
+    writes: ClassVar[bool] = False
+
+    table: type[NamedTable]
+
+    @abstractmethod
+    def build(self) -> Any:
+        """
+        Produce the statement to execute.
+        """
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.table.__name__})"
+
+
+class Conditional(Operation, ABC):
+    """
+    An operation narrowed by conditions, e.g. everything but an insert.
+
+    Conditions accumulate and are combined with AND. Each is either a native
+    SQLModel clause, which names columns so an IDE checks them, or a corekit
+    expression, which names fields as strings and works against any backend.
+    """
+
+    conditions: list[Any] = Field(default_factory=list)
+
+    def where(self, condition: Any) -> "Conditional":
+        """
+        Narrow this operation. Repeated calls combine with AND.
+        """
+        self.conditions.append(condition)
+        return self
+
+    def _as_clause(self, condition: Any) -> Any:
+        """
+        Compile a corekit expression; pass a native SQLModel clause through.
+        """
+        if isinstance(condition, Expression):
+            return condition.to_sqlalchemy(self.table)
+        return condition
+
+    def _apply_conditions(self, statement: Any) -> Any:
+        """
+        Attach every condition to ``statement``.
+        """
+        for condition in self.conditions:
+            statement = statement.where(self._as_clause(condition))
+        return statement
+
+
+class DqlOperation(Conditional, ABC):
+    """
+    A read. Returns rows and changes nothing.
+    """
+
+
+class DmlOperation(Conditional, ABC):
+    """
+    A conditional write against rows: update or delete.
+
+    Insert is also a write, but it has no ``where``, so it is not this class.
+    Both set ``writes`` so a connection commits them.
+    """
+
+    writes: ClassVar[bool] = True
+
+
+class DdlOperation(Operation, ABC):
+    """
+    A change to the schema itself.
+
+    Schema changes are checksummed so a migration that has already run can be
+    recognised, which reads and writes never need. That is what separates
+    this branch from the others.
+    """
+
+    @abstractmethod
+    def canonical(self) -> str:
+        """
+        A deterministic, human-readable rendering of this operation's intent.
+
+        It feeds a checksum, so it must change whenever the intent changes and
+        must not change for anything else -- formatting or field order included.
+        """

corekit/connections/sql/operations/statements.py

@@ -0,0 +1,170 @@
+"""
+The statements an application runs: select, insert, update and delete.
+"""
+
+from typing import Any, ClassVar
+
+from pydantic import Field
+from sqlmodel import delete as _delete
+from sqlmodel import desc as _desc
+from sqlmodel import insert as _insert
+from sqlmodel import select as _select
+from sqlmodel import update as _update
+
+from corekit.connections.sql.operations.base import DmlOperation, DqlOperation, Operation
+
+__all__ = ["Delete", "Insert", "Select", "Update"]
+
+
+class Select(DqlOperation):
+    """
+    Read rows, optionally ordered, offset and capped.
+
+        Select(table=User).where(User.age >= 18).order_by(User.name).limit(10)
+
+    ``where`` also accepts a ``corekit.data`` expression, which is the same
+    predicate language ``Dataset`` filters with::
+
+        Select(table=User).where(Field("age") >= 18)
+
+    ``limit(-1)`` means no cap. ``limit(0)`` returns no rows.
+    """
+
+    order_by_field: Any = None
+    order_by_desc: bool = False
+    limit_count: int = -1
+    offset_count: int = 0
+
+    def order_by(self, field: Any, desc: bool = False) -> "Select":
+        """
+        Order results by a field.
+        """
+        self.order_by_field = field
+        self.order_by_desc = desc
+        return self
+
+    def limit(self, limit: int) -> "Select":
+        """
+        Cap the number of rows returned.
+
+        ``-1`` means no limit. ``0`` means zero rows.
+        """
+        self.limit_count = limit
+        return self
+
+    def offset(self, offset: int) -> "Select":
+        """
+        Skip the first ``offset`` rows.
+        """
+        self.offset_count = offset
+        return self
+
+    def build(self) -> Any:
+        """
+        Produce the select statement.
+        """
+        statement = self._apply_conditions(_select(self.table))
+
+        if self.order_by_field is not None:
+            order_by_field = self.order_by_field
+            if self.order_by_desc:
+                order_by_field = _desc(order_by_field)
+            statement = statement.order_by(order_by_field)
+
+        if self.offset_count > 0:
+            statement = statement.offset(self.offset_count)
+
+        if self.limit_count >= 0:
+            statement = statement.limit(self.limit_count)
+
+        return statement
+
+
+class Delete(DmlOperation):
+    """
+    Delete every row matching the conditions, in one statement.
+
+        Delete(table=Session).where(Session.left_at < cutoff)
+
+    Deleting without a condition would empty the table, so it is refused:
+    a missing ``where`` is far more often a mistake than an intent.
+    """
+
+    def build(self) -> Any:
+        """
+        Produce the delete statement.
+
+        Raises:
+            ValueError: If no condition was given.
+        """
+        if not self.conditions:
+            raise ValueError(f"Delete on {self.table.__name__} needs a condition; use truncate to empty a table")
+        return self._apply_conditions(_delete(self.table))
+
+
+class Update(DmlOperation):
+    """
+    Set columns on every row matching the conditions, in one statement.
+
+        Update(table=User, values={"active": False}).where(User.age < 18)
+
+    Updating without a condition would rewrite the table, so it is refused.
+    """
+
+    values: dict[str, Any] = Field(default_factory=dict)
+
+    def set(self, **values: Any) -> "Update":
+        """
+        Columns to write, as keyword arguments.
+        """
+        self.values.update(values)
+        return self
+
+    def build(self) -> Any:
+        """
+        Produce the update statement.
+
+        Raises:
+            ValueError: If no condition or no value was given.
+        """
+        if not self.conditions:
+            raise ValueError(f"Update on {self.table.__name__} needs a condition")
+        if not self.values:
+            raise ValueError(f"Update on {self.table.__name__} needs values to set")
+        return self._apply_conditions(_update(self.table)).values(**self.values)
+
+
+class Insert(Operation):
+    """
+    Add rows. A write, so ``SQLConnection.execute`` commits it.
+
+    Not a ``DmlOperation``: an insert has no rows to narrow, so it does not
+    take ``where``.
+
+        Insert(table=User, rows=[{"name": "Ada"}, {"name": "Bob"}])
+
+    Rows are dictionaries rather than instances, so this compiles to a single
+    statement. To add model instances, use ``SQLConnection.insert``.
+    """
+
+    writes: ClassVar[bool] = True
+
+    rows: list[dict[str, Any]] = Field(default_factory=list)
+
+    def add(self, **values: Any) -> "Insert":
+        """
+        Append one row.
+        """
+        self.rows.append(values)
+        return self
+
+    def build(self) -> Any:
+        """
+        Produce the insert statement.
+
+        Raises:
+            ValueError: If there is nothing to insert.
+        """
+        if not self.rows:
+            raise ValueError(f"Insert on {self.table.__name__} needs at least one row")
+        return _insert(self.table).values(self.rows)