python-corekit 0.1.0__py3-none-any.whl → 0.2.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:
@@ -339,20 +361,20 @@ class DropIndex(Operation):
 
 
 @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 +386,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,7 +404,7 @@ class RenameColumn(Operation):
 
 
 @dataclass
-class DataOperation(Operation):
+class DataMigrationOperation(MigrationOperation):
     """
     Executes a Python function for data migrations (seeding, transformations).
 
@@ -391,12 +413,12 @@ class DataOperation(Operation):
     invalidate the checksum, so choose a stable, descriptive name.
 
     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 +432,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,102 @@
+"""
+Statement primitives: the shapes a database operation can take.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+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}
+
+    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 write against rows: insert, update or delete.
+    """
+
+
+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,150 @@
+"""
+The statements an application runs: select, insert, update and delete.
+"""
+
+from typing import Any
+
+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 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)
+    """
+
+    order_by_field: Any = None
+    order_by_desc: bool = False
+    limit_count: int = -1
+
+    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. A non-positive value means no limit.
+        """
+        self.limit_count = limit
+        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.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.
+
+        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``.
+    """
+
+    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)

corekit/connections/sql/query.py

@@ -1,68 +1,10 @@
 """
-A chainable query builder over SQLModel's select().
+The read operation, under its original name.
 """
 
-from typing import Any
-
-from pydantic import BaseModel, Field
-from sqlmodel import desc as _desc
-from sqlmodel import select
-
-from corekit.connections.sql.table import NamedTable
+from corekit.connections.sql.operations.statements import Select
 
 __all__ = ["Query"]
 
-
-class Query(BaseModel):
-    """
-    Accumulates filters, ordering and a limit, then builds a select statement.
-
-        Query(table=User).where(User.age >= 18).order_by(User.name).limit(10)
-    """
-
-    table: type[NamedTable]
-    queries: list[Any] = Field(default_factory=list)
-    order_by_field: Any = None
-    order_by_desc: bool = False
-    limit_count: int = -1
-
-    def where(self, query: Any) -> "Query":
-        """
-        Add a filter clause.
-        """
-        self.queries.append(query)
-        return self
-
-    def order_by(self, field: Any, desc: bool = False) -> "Query":
-        """
-        Order results by a field.
-        """
-        self.order_by_field = field
-        self.order_by_desc = desc
-        return self
-
-    def limit(self, limit: int) -> "Query":
-        """
-        Cap the number of rows returned. A non-positive value means no limit.
-        """
-        self.limit_count = limit
-        return self
-
-    def build(self) -> Any:
-        """
-        Produce the select statement.
-        """
-        statement = select(self.table)
-        for query in self.queries:
-            statement = statement.where(query)
-
-        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.limit_count > 0:
-            statement = statement.limit(self.limit_count)
-
-        return statement
+#: ``Select`` names the statement it builds; ``Query`` is its original name.
+Query = Select