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

corekit/connections/sql/__init__.py

@@ -3,7 +3,7 @@ SQL building blocks: a Connectable session, statement primitives and a base tabl
 """
 
 from corekit.connections.sql.connection import PaginatedResult, SQLConnection
-from corekit.connections.sql.fields import JSONBField, PydanticJSON
+from corekit.connections.sql.fields import JSONBField, JsonModelField, PydanticJSON
 from corekit.connections.sql.operations import (
     Conditional,
     DdlOperation,
@@ -25,6 +25,7 @@ __all__ = [
     "DmlOperation",
     "DqlOperation",
     "Insert",
+    "JsonModelField",
     "JSONBField",
     "NamedTable",
     "Operation",

corekit/connections/sql/connection.py

@@ -24,7 +24,7 @@ from sqlmodel import Session, SQLModel, create_engine, select
 
 from corekit.config import get_settings
 from corekit.connections import Connectable
-from corekit.connections.sql.operations import DmlOperation, DqlOperation, Operation
+from corekit.connections.sql.operations import DqlOperation, Operation, Select
 from corekit.connections.sql.query import Query
 from corekit.connections.sql.table import NamedTable
 
@@ -204,12 +204,14 @@ class SQLConnection(Connectable):
         """
         Create any tables present in SQLModel metadata but missing from the database.
         """
+        self.require_writable()
         SQLModel.metadata.create_all(_get_engine(self._connection_url))
 
     def exec_ddl(self, sql: str) -> None:
         """
         Run a raw DDL statement. Intended for migrations, not application code.
         """
+        self.require_writable()
         self._start_session()
         self.session.exec(text(sql))
         self.session.commit()
@@ -222,6 +224,7 @@ class SQLConnection(Connectable):
         """
         Insert new rows.
         """
+        self.require_writable()
         self._start_session()
         self.session.add_all(items)
         self.session.commit()
@@ -230,6 +233,7 @@ class SQLConnection(Connectable):
         """
         Insert or update rows. Slower than insert, but tolerates existing ids.
         """
+        self.require_writable()
         self._start_session()
         for item in items:
             self.session.merge(item)
@@ -239,6 +243,7 @@ class SQLConnection(Connectable):
         """
         Delete a row by id.
         """
+        self.require_writable()
         item = self.fetch_one_by_id(table, identifier)
         if item is None:
             return
@@ -296,8 +301,12 @@ class SQLConnection(Connectable):
     def fetch_one_by_condition(self, table: type[NamedTable], key: Any, value: Any) -> NamedTable | None:
         """
         The first row where a column equals a value.
+
+        ``key`` may be a column attribute (``Person.city``) or a column name
+        string resolved against ``table``.
         """
-        return self.first(select(table).where(key == value))
+        column = getattr(table, key) if isinstance(key, str) else key
+        return self.first(select(table).where(column == value))
 
     def exists(self, table: type[NamedTable], identifier: str) -> bool:
         """
@@ -321,6 +330,16 @@ class SQLConnection(Connectable):
         """
         return list(self._exec(query.build()))
 
+    def delete_many_by_query(self, query: Query) -> None:
+        """
+        Delete every row matching a Query.
+        """
+        self.require_writable()
+        self._start_session()
+        for item in self.fetch_many_by_query(query):
+            self.session.delete(item)
+        self.session.commit()
+
     def execute(self, operation: Operation) -> Any:
         """
         Run an operation, committing if it writes.
@@ -328,8 +347,10 @@ class SQLConnection(Connectable):
         A read returns its rows; a write returns the result, whose
         ``rowcount`` reports how many rows it touched.
         """
+        if operation.writes:
+            self.require_writable()
         result = self._exec(operation.build())
-        if isinstance(operation, DmlOperation):
+        if operation.writes:
             self.session.commit()
         return result
 
@@ -352,10 +373,23 @@ class SQLConnection(Connectable):
         self._start_session()
         return self.session.exec(select(func.count()).select_from(table)).one()
 
-    def paginate(self, table: type[NamedTable], offset: int = 0, limit: int = 50) -> PaginatedResult:
+    def paginate(
+        self,
+        table: type[NamedTable],
+        offset: int = 0,
+        limit: int = 50,
+        *,
+        order_by: Any = None,
+        desc: bool = False,
+    ) -> PaginatedResult:
         """
         A page of rows, together with the total row count.
+
+        Pages are ordered: pass ``order_by`` for a column, or omit it to order
+        by ``table.id`` so offsets are stable.
         """
         total = self.count(table)
-        rows = list(self._exec(select(table).offset(offset).limit(limit)))
+        query = Select(table=table).offset(offset).limit(limit)
+        query.order_by(order_by if order_by is not None else table.id, desc=desc)
+        rows = self.fetch(query)
         return PaginatedResult(rows=rows, total=total)

corekit/connections/sql/fields/__init__.py

@@ -2,6 +2,6 @@
 Custom SQL column types.
 """
 
-from corekit.connections.sql.fields.jsonb import JSONBField, PydanticJSON
+from corekit.connections.sql.fields.jsonb import JSONBField, JsonModelField, PydanticJSON
 
-__all__ = ["JSONBField", "PydanticJSON"]
+__all__ = ["JsonModelField", "JSONBField", "PydanticJSON"]

corekit/connections/sql/fields/jsonb.py

@@ -1,18 +1,21 @@
 """
 Columns that store a Pydantic model as JSON.
 
-``JSONBField`` round-trips a model through a JSON column, so a table can hold
-structured data without a separate table and without hand-written encoding at
-every call site::
+``JsonModelField`` round-trips a model through a JSON column, so a table can
+hold structured data without a separate table and without hand-written encoding
+at every call site::
 
     class Profile(BaseModel):
         theme: str = "dark"
 
     class User(NamedTable, table=True):
         id: str = Field(primary_key=True)
-        profile: Profile = JSONBField(Profile)
+        profile: Profile = JsonModelField(Profile)
 
 Reading ``user.profile`` gives a ``Profile``, not a dict.
+
+The SQLAlchemy ``impl`` is ``JSON``, not PostgreSQL ``JSONB``. The historical
+``JSONBField`` name is kept as an alias.
 """
 
 from typing import Any
@@ -22,7 +25,7 @@ from sqlalchemy import Column
 from sqlalchemy.types import JSON, TypeDecorator
 from sqlmodel import Field
 
-__all__ = ["JSONBField", "PydanticJSON"]
+__all__ = ["JsonModelField", "JSONBField", "PydanticJSON"]
 
 
 class PydanticJSON(TypeDecorator):
@@ -60,8 +63,12 @@ class PydanticJSON(TypeDecorator):
         return self.pydantic_model(**value)
 
 
-def JSONBField(pydantic_model: type[BaseModel], **kwargs: Any) -> Any:  # noqa: N802 - reads as a field constructor
+def JsonModelField(pydantic_model: type[BaseModel], **kwargs: Any) -> Any:  # noqa: N802 - reads as a field constructor
     """
     Declare a column holding ``pydantic_model`` as JSON.
     """
     return Field(sa_column=Column(PydanticJSON(pydantic_model)), **kwargs)
+
+
+#: Historical name. The column type is SQLAlchemy ``JSON``, not PostgreSQL JSONB.
+JSONBField = JsonModelField

corekit/connections/sql/migration/__init__.py

@@ -24,7 +24,9 @@ from corekit.connections.sql.migration.base import Migration
 from corekit.connections.sql.migration.operations import (
     AddColumn,
     AlterColumnType,
+    ColumnSpec,
     CreateIndex,
+    CreateTable,
     DataMigrationOperation,
     DropColumn,
     DropColumnDefault,
@@ -41,7 +43,9 @@ from corekit.connections.sql.migration.table import SchemaMigration
 __all__ = [
     "AddColumn",
     "AlterColumnType",
+    "ColumnSpec",
     "CreateIndex",
+    "CreateTable",
     "DataMigrationOperation",
     "DropColumn",
     "DropColumnDefault",

corekit/connections/sql/migration/operations.py

@@ -360,6 +360,72 @@ class DropIndex(MigrationOperation):
 # ---------------------------------------------------------------------------
 
 
+@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(MigrationOperation):
     table: type[NamedTable] | str
@@ -409,8 +475,9 @@ 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:
         DataMigrationOperation(

corekit/connections/sql/operations/base.py

@@ -3,7 +3,7 @@ Statement primitives: the shapes a database operation can take.
 """
 
 from abc import ABC, abstractmethod
-from typing import Any
+from typing import Any, ClassVar
 
 from pydantic import BaseModel, Field
 
@@ -24,6 +24,10 @@ class Operation(BaseModel, ABC):
 
     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
@@ -79,9 +83,14 @@ class DqlOperation(Conditional, ABC):
 
 class DmlOperation(Conditional, ABC):
     """
-    A write against rows: insert, update or delete.
+    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):
     """

corekit/connections/sql/operations/statements.py

@@ -2,7 +2,7 @@
 The statements an application runs: select, insert, update and delete.
 """
 
-from typing import Any
+from typing import Any, ClassVar
 
 from pydantic import Field
 from sqlmodel import delete as _delete
@@ -18,7 +18,7 @@ __all__ = ["Delete", "Insert", "Select", "Update"]
 
 class Select(DqlOperation):
     """
-    Read rows, optionally ordered and capped.
+    Read rows, optionally ordered, offset and capped.
 
         Select(table=User).where(User.age >= 18).order_by(User.name).limit(10)
 
@@ -26,11 +26,14 @@ class Select(DqlOperation):
     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":
         """
@@ -42,11 +45,20 @@ class Select(DqlOperation):
 
     def limit(self, limit: int) -> "Select":
         """
-        Cap the number of rows returned. A non-positive value means no limit.
+        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.
@@ -59,7 +71,10 @@ class Select(DqlOperation):
                 order_by_field = _desc(order_by_field)
             statement = statement.order_by(order_by_field)
 
-        if self.limit_count > 0:
+        if self.offset_count > 0:
+            statement = statement.offset(self.offset_count)
+
+        if self.limit_count >= 0:
             statement = statement.limit(self.limit_count)
 
         return statement
@@ -121,7 +136,10 @@ class Update(DmlOperation):
 
 class Insert(Operation):
     """
-    Add rows.
+    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"}])
 
@@ -129,6 +147,8 @@ class Insert(Operation):
     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":

corekit/connections/sql/table.py

@@ -2,7 +2,6 @@
 Base table type.
 """
 
-import json
 import logging
 from typing import Any, ClassVar
 
@@ -33,6 +32,10 @@ class NamedTable(SQLModel):
     Subclasses register themselves by name, so a table class can be resolved
     from a string -- useful for imports, exports and admin tooling that work
     with table names rather than imported classes.
+
+    ``table_name`` is the database table name (``__tablename__``). Use
+    ``get_display_name`` for a human-readable label. Structured JSON columns
+    belong on ``JsonModelField`` / ``PydanticJSON``, not ad-hoc encode helpers.
     """
 
     __registry__: SmartRegistry = SmartRegistry()
@@ -65,9 +68,9 @@ class NamedTable(SQLModel):
     @property
     def table_name(self) -> str:
         """
-        The name of the table this record belongs to.
+        The database table name for this row (``__tablename__``).
         """
-        return type(self).__name__
+        return type(self).__tablename__
 
     @classmethod
     def get_display_name(cls) -> str:
@@ -92,31 +95,6 @@ class NamedTable(SQLModel):
 
     def export(self) -> TableExportItem:
         """
-        This row as a portable record, tagged with its table.
+        This row as a portable record, tagged with its database table name.
         """
         return TableExportItem(table_name=self.table_name, data=self.model_dump())
-
-    @staticmethod
-    def _serialize(value: Any) -> str:
-        return json.dumps(value)
-
-    @staticmethod
-    def _deserialize(value: str) -> Any:
-        try:
-            return json.loads(value)
-        except (TypeError, ValueError):
-            logger.error(f"Unable to deserialize value: {value!r}")
-            raise
-
-    def serialize(self, values: dict[str, Any], key: str) -> dict[str, Any]:
-        """
-        Replace ``values[key]`` with its JSON encoding.
-        """
-        values[key] = self._serialize(values.get(key))
-        return values
-
-    def deserialize(self, key: str) -> Any:
-        """
-        Decode the JSON stored in the named field.
-        """
-        return self._deserialize(getattr(self, key))

corekit/crypto/__init__.py

@@ -1 +1,3 @@
-from .hasher import Hasher
+from .hasher import Hasher, MissingSaltError
+
+__all__ = ["Hasher", "MissingSaltError"]

corekit/crypto/constants.py

@@ -3,5 +3,5 @@ EMPTY_HASH = ""
 
 # There is deliberately no default salt. A salt shipped with a library is shared
 # by every install, which defeats the purpose of salting. Supply one through
-# configuration -- see `corekit.config.CorekitSettings.crypto_salt` and
-# `corekit.crypto.hasher.Hasher`.
+# configuration -- COREKIT_CRYPTO__SALT, or [crypto] salt in a config file --
+# or pass salt= to Hasher.

corekit/crypto/hasher.py

@@ -4,22 +4,27 @@ from typing import Any
 from corekit.config import get_settings
 from corekit.crypto.constants import EMPTY_HASH, HASH_JOINER
 from corekit.crypto.enum import SaltMethod
+from corekit.exceptions import InternalCoreException, Retryability
 from corekit.observability.loggable import Loggable
 
 
-class MissingSaltError(RuntimeError):
+class MissingSaltError(InternalCoreException):
     """
     Raised when hashing is attempted without a configured salt.
     """
 
+    def __init__(self, message: str, *, error: str | None = None) -> None:
+        super().__init__(message, retryable=Retryability.NON_RETRYABLE, error=error)
+
 
 class Hasher(Loggable):
     """
     Salted SHA-256 hashing.
 
     The salt has no default. Supply it explicitly, or configure it via
-    ``COREKIT_CRYPTO_SALT`` / ``crypto_salt`` in a corekit config file. Resolution
-    is deferred until first use so that importing this module never fails.
+    ``COREKIT_CRYPTO__SALT`` or ``[crypto] salt`` in a corekit config file.
+    Resolution is deferred until first use so that importing this module
+    never fails.
     """
 
     def __init__(
@@ -41,7 +46,7 @@ class Hasher(Loggable):
         if not salt:
             raise MissingSaltError(
                 "No crypto salt configured. Pass salt=... to Hasher, set "
-                "COREKIT_CRYPTO_SALT, or add crypto_salt to your corekit config. "
+                "COREKIT_CRYPTO__SALT, or add salt under [crypto] in your corekit config. "
                 'Generate one with: python -c "import secrets; print(secrets.token_hex(32))"'
             )
         return salt

corekit/data/dataset.py

@@ -268,8 +268,14 @@ class Dataset:
     def at(self, idx: int) -> Any:
         return self._records[idx]
 
-    def get_record(self, record_id: Any) -> Any:
-        return self._id_index[record_id]
+    def get_record(self, record_id: Any) -> Any | None:
+        """
+        Look up a record by id, or ``None`` if it is missing.
+
+        Matches SQL ``fetch_one_by_id``: identity lookup returns absence as
+        ``None`` rather than raising.
+        """
+        return self._id_index.get(record_id)
 
     # -- removing whole records ----------------------------------------------
 

corekit/data/expressions/__init__.py

@@ -8,9 +8,9 @@ values or against each other::
     Field("first_name") == Field("nickname")
     (Field("age") > 20) & ~Field("name").contains("test")
 
-Every node can also emit a backend query: ``to_mongo``, ``to_elasticsearch`` or
-``to_sqlalchemy``. ``Target`` names the context an operand is resolved for, so a
-new backend needs one more translation method and no changes to the tree.
+A node evaluates against a record in Python. ``to_sqlalchemy`` is the other
+implementation of the same predicate. Operators SQL cannot mean the same way
+are refused there rather than compiled into a different query.
 """
 
 from corekit.data.expressions.comparison import (