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

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

corekit/connections/sql/table.py

@@ -2,15 +2,25 @@
 Base table type.
 """
 
-import json
 import logging
-from typing import Any
+from typing import Any, ClassVar
 
+from pydantic import BaseModel
 from sqlmodel import SQLModel
 
 from corekit.registry import SmartRegistry
 
-__all__ = ["NamedTable"]
+__all__ = ["NamedTable", "TableExportItem"]
+
+
+class TableExportItem(BaseModel):
+    """
+    One exported row, tagged with the table it came from.
+    """
+
+    table_name: str
+    data: dict[str, Any]
+
 
 logger = logging.getLogger(__name__)
 
@@ -22,10 +32,18 @@ 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()
 
+    #: A human-readable name for the table. Declared as a ClassVar so pydantic
+    #: leaves a subclass's value as a plain string rather than wrapping it.
+    _table_display_name: ClassVar[str | None] = None
+
     def __init_subclass__(cls, **kwargs: Any) -> None:
         """
         Register every subclass under its class name.
@@ -50,16 +68,21 @@ 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:
         """
-        A human-readable name for the table.
+        A human-readable name for the table, falling back to the class name.
         """
-        return getattr(cls, "__display_name__", None) or cls.__name__
+        name = cls._table_display_name
+        if name is not None and not isinstance(name, str):
+            # A subclass declared outside this module's ClassVar annotation
+            # gets its value wrapped, and the wrapper's repr is not a label.
+            name = getattr(name, "default", None) or str(name)
+        return name or cls.__name__
 
     @classmethod
     def create_default(cls, identifier: str, **kwargs: Any) -> "NamedTable":
@@ -70,27 +93,8 @@ class NamedTable(SQLModel):
         logger.info(f"Creating default {cls.__name__} with id {kwargs['id']!r}")
         return cls(**kwargs)
 
-    @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:
+    def export(self) -> TableExportItem:
         """
-        Decode the JSON stored in the named field.
+        This row as a portable record, tagged with its database table name.
         """
-        return self._deserialize(getattr(self, key))
+        return TableExportItem(table_name=self.table_name, data=self.model_dump())

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/__init__.py

@@ -24,6 +24,7 @@ from corekit.data.expressions import (
     And,
     Comparison,
     Contains,
+    Dialect,
     Equals,
     Expression,
     FieldExpression,
@@ -34,7 +35,10 @@ from corekit.data.expressions import (
     LessThanOrEquals,
     Not,
     NotEquals,
+    Operator,
     Or,
+    Target,
+    UnknownFieldError,
     ValueExpression,
 )
 from corekit.data.record import BaseRecord, is_valid_key, resolve_default
@@ -74,6 +78,10 @@ __all__ = [
     "NotEquals",
     "NumericFieldStats",
     "Or",
+    "Dialect",
+    "Operator",
+    "Target",
+    "UnknownFieldError",
     "ValueCounts",
     "ValueExpression",
     "is_valid_key",

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,8 +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 via ``to_sql``, ``to_mongo`` or
-``to_elasticsearch``.
+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 (
@@ -23,9 +24,12 @@ from corekit.data.expressions.comparison import (
     LessThan,
     LessThanOrEquals,
     NotEquals,
+    UnknownFieldError,
     ValueExpression,
 )
 from corekit.data.expressions.expression import And, Expression, Not, Or
+from corekit.data.expressions.operator import Dialect, Operator
+from corekit.data.expressions.target import Target
 
 __all__ = [
     "And",
@@ -41,6 +45,10 @@ __all__ = [
     "LessThanOrEquals",
     "Not",
     "NotEquals",
+    "UnknownFieldError",
     "Or",
+    "Dialect",
+    "Operator",
+    "Target",
     "ValueExpression",
 ]