loom-kernel 4.0.0__tar.gz → 5.0.0__tar.gz

{loom_kernel-4.0.0 → loom_kernel-5.0.0}/CHANGELOG.md

@@ -589,6 +589,36 @@
   it. A `@cache_query` argument that is a pydantic instance now contributes
   its builtins rendering to the cache key rather than the instance's own
   `repr`, a one-time key change.
+- **core:** a model field annotated with an enum and no declared column type
+  takes the column type of the scalar the enum is mixed with, the first class
+  of its MRO with a column rule, as that class itself would: a `StrEnum` (any
+  `str` enum) becomes `String`, honouring `length=`, an `IntEnum` or `IntFlag`
+  becomes `Integer`, a `float` enum `Float`, a `Decimal` enum `Numeric`,
+  instead of `JSON`. The value is stored as a plain string or integer, not
+  JSON-encoded, so the column can be filtered by equality; `Optional` of such
+  an enum behaves the same. An existing table with such a column needs a
+  migration that converts the data with a `USING` clause, which Alembic's
+  autogenerate does not write: on Postgres,
+  `ALTER TABLE t ALTER COLUMN c TYPE varchar USING c #>> '{}'` and
+  `ALTER TABLE t ALTER COLUMN c TYPE integer USING (c #>> '{}')::integer`. On
+  SQLAlchemy models, a plain `Enum` (mixed with no scalar) or a `Literal[...]`
+  field with no declared column type now fails model compilation with a
+  `ValueError` naming the model and the field, instead of becoming a `JSON`
+  column; loom does not infer a type from the values. Declare the column, for
+  example `colour: Colour = ColumnField(String(20))`. Mongo and DynamoDB
+  models keep such fields as they are. Declared column types are unchanged,
+  and an `Annotated[...]` column type or `Field` is now read also when the
+  `Annotated` sits inside `Optional` (`Annotated[T, String(1)] | None`), and
+  is used when a `ColumnField(...)` on the field declares no column type.
+  `ColumnFieldInfo` gains `needs_declared_type`.
+- **core:** an `Optional` inside `Annotated` whose metadata carries no column
+  type, such as `Annotated[int | None, msgspec.Meta(ge=0)]`, now takes the
+  column of its scalar type (`Integer` here) instead of `JSON`; an existing
+  table needs the same `USING` migration as above. A `Field(...)` inside
+  `Annotated` with no column type is now read instead of being dropped, so its
+  settings take effect: `primary_key=True` adds the column to the primary key,
+  which can turn a model's key composite, and `nullable=True` makes the column
+  nullable. Review such fields before upgrading.
 
 ### ai
 
@@ -704,8 +734,8 @@
   the route at startup. Only scalar columns of the use case's own model
   (`UseCase[Model, ...]`) qualify. A related model's column (`warehouse.code`)
   is refused, and so are JSON, array and text-search columns; lists, dicts
-  and structs, and an `Enum` or `Literal` declared without a column type, are
-  JSON. `InterfaceCompilationError` names the route and the field. It is also
+  and structs are JSON. A `StrEnum` or `IntEnum` column is scalar; a plain
+  `Enum` or a `Literal` needs a declared column type. `InterfaceCompilationError` names the route and the field. It is also
   raised for a declaration on a use case with no model, and for a route-level
   declaration on a route without a `QuerySpec`; an inherited one is ignored.
   `exists` and `not_exists` answer `400 unsupported_query`, and so do `like`

{loom_kernel-4.0.0 → loom_kernel-5.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 4.0.0
+Version: 5.0.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3

{loom_kernel-4.0.0 → loom_kernel-5.0.0}/src/loom/core/backend/sqlalchemy.py

@@ -234,6 +234,7 @@ def _compile_model(
 
     table_name = get_table_name(struct_cls)
     column_fields = get_column_fields(struct_cls)
+    _refuse_undeclared_column_types(struct_cls, column_fields)
     scopes = scope_columns(struct_cls)
     boundary = next((scope for scope in scopes if scope.is_boundary), None)
     constraints, composite_columns = _foreign_key_constraints(
@@ -284,6 +285,21 @@ def _compile_model(
     return sa_cls
 
 
+def _refuse_undeclared_column_types(
+    struct_cls: type, column_fields: Mapping[str, ColumnFieldInfo]
+) -> None:
+    """Refuse a plain enum or ``Literal`` field whose column type is not declared.
+
+    loom does not infer a SQL type from the values of such a field.
+    """
+    for name, info in column_fields.items():
+        if info.needs_declared_type:
+            raise ValueError(
+                f"{struct_cls.__name__}.{name}: no column type can be inferred from a plain "
+                "Enum or Literal annotation; declare it, e.g. `ColumnField(String(20))`"
+            )
+
+
 def _declared_constraints(struct_cls: type, table_name: str) -> list[Constraint | Index]:
     """Keys, indexes and checks declared on the model, in declaration order.
 

{loom_kernel-4.0.0 → loom_kernel-5.0.0}/src/loom/core/model/introspection.py

@@ -5,8 +5,19 @@ from collections.abc import Callable, Mapping
 from dataclasses import dataclass, replace
 from datetime import date, datetime, time
 from decimal import Decimal
+from enum import Enum
 from types import UnionType
-from typing import Any, ClassVar, Union, cast, get_args, get_origin, get_type_hints
+from typing import (
+    Annotated,
+    Any,
+    ClassVar,
+    Literal,
+    Union,
+    cast,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
 
 import msgspec
 
@@ -40,12 +51,18 @@ class PartialUnique:
 
 @dataclass(frozen=True, slots=True)
 class ColumnFieldInfo:
-    """Resolved metadata for a single column field."""
+    """Resolved metadata for a single column field.
+
+    ``needs_declared_type`` marks a field whose column type was not declared
+    and cannot be inferred, a plain enum or a ``Literal``: ``column_type`` is
+    then a JSON placeholder.
+    """
 
     name: str
     python_type: type
     column_type: ColumnType
     field: Field
+    needs_declared_type: bool = False
 
 
 def _collect_inherited_dict_metadata(cls: type, attr: str) -> dict[str, Any]:
@@ -86,40 +103,31 @@ def _resolve_column_field(
     struct_default: Any,
     declared: ColumnFieldSpec | None,
 ) -> ColumnFieldInfo:
-    """Build the column metadata for one field, declared or inferred."""
-    python_type = _extract_origin_type(annotation)
-    if declared is not None:
-        return ColumnFieldInfo(
-            name=name,
-            python_type=python_type,
-            column_type=declared.column_type
-            or _infer_column_type(annotation, field=declared.field),
-            field=_with_struct_default(declared.field, struct_default),
-        )
-
-    annotated_type, annotated_field = _extract_annotated_column(annotation)
-    if annotated_type is not None:
-        return ColumnFieldInfo(
-            name=name,
-            python_type=python_type,
-            column_type=annotated_type,
-            field=_with_struct_default(annotated_field, struct_default),
-        )
+    """Build the column metadata for one field, declared or inferred.
 
-    inferred_field = _with_struct_default(Field(), struct_default)
+    A ``ColumnField`` supplies the ``Field``; its column type, else the one in
+    ``Annotated``, else the inferred one is used.
+    """
+    annotated_type, field = _extract_annotated_column(annotation)
+    if declared is not None:
+        annotated_type, field = declared.column_type or annotated_type, declared.field
+    field = _with_struct_default(field, struct_default)
+    column_type = annotated_type or _infer_column_type(annotation, field=field)
     return ColumnFieldInfo(
         name=name,
-        python_type=python_type,
-        column_type=_infer_column_type(annotation, field=inferred_field),
-        field=inferred_field,
+        python_type=_extract_origin_type(annotation),
+        column_type=column_type or JSON,
+        field=field,
+        needs_declared_type=column_type is None,
     )
 
 
 def _extract_annotated_column(annotation: Any) -> tuple[ColumnType | None, Field]:
-    """Read the ``ColumnType`` and ``Field`` carried by ``Annotated[T, ...]``."""
+    """Read the ``ColumnType`` and ``Field`` carried by ``Annotated[T, ...]``, optional or not."""
     column_type: ColumnType | None = None
     field = Field()
-    for entry in _extract_metadata(annotation):
+    _, metadata = _column_base(annotation)
+    for entry in metadata:
         if isinstance(entry, ColumnType):
             column_type = entry
         elif isinstance(entry, Field):
@@ -170,11 +178,6 @@ def get_table_name(cls: type) -> str:
     return table
 
 
-def _extract_metadata(annotation: Any) -> tuple[Any, ...]:
-    """Pull metadata entries from ``Annotated[T, ...]``."""
-    return getattr(annotation, "__metadata__", ())
-
-
 def resolve_type_hints(obj: Any, *, include_extras: bool = False) -> dict[str, Any]:
     """Return the resolved annotations of *obj*, or ``{}`` when they cannot be resolved.
 
@@ -325,8 +328,10 @@ def scalar_column_annotations(model: type) -> dict[str, Any]:
     """Return the annotation of each scalar column of *model*, ``Annotated`` metadata removed.
 
     A JSON, array or text-search column is not scalar; lists, dicts and
-    structs, and an ``Enum`` or ``Literal`` declared without a column type,
-    are inferred as JSON.
+    structs are inferred as JSON. An enum mixed with a scalar type, such as a
+    ``StrEnum`` or ``IntEnum``, takes that type's column and is scalar. No
+    column type can be inferred for a plain ``Enum`` or a ``Literal`` declared
+    without one; its ``column_type`` is a JSON placeholder and it is not listed.
 
     Args:
         model: Model whose columns are read.
@@ -373,6 +378,23 @@ def _unwrap_optional(annotation: Any) -> Any:
     return annotation
 
 
+def _column_base(annotation: Any) -> tuple[Any, tuple[Any, ...]]:
+    """Strip ``Optional`` and ``Annotated`` layers, in either order.
+
+    Returns:
+        The inner annotation and the metadata of the ``Annotated`` layers.
+    """
+    metadata: tuple[Any, ...] = ()
+    while True:
+        unwrapped = _unwrap_optional(annotation)
+        if get_origin(unwrapped) is Annotated:
+            metadata += unwrapped.__metadata__
+            unwrapped = get_args(unwrapped)[0]
+        if unwrapped is annotation:
+            return annotation, metadata
+        annotation = unwrapped
+
+
 def _is_classvar(annotation: Any) -> bool:
     return get_origin(annotation) is ClassVar
 
@@ -383,20 +405,46 @@ _SCALAR_TYPE_MAP: dict[type, ColumnType] = {
     bool: Boolean,
     bytes: Bytes,
     datetime: DateTime(tz=True),
+    date: String(None),
+    time: String(None),
     Decimal: Numeric(),
 }
 
 
-def _infer_column_type(annotation: Any, *, field: Field) -> ColumnType:
-    base = _unwrap_optional(annotation)
-    if get_origin(base) in (list, tuple, set, dict):
+_COLUMN_RULE_TYPES = frozenset({str, *_SCALAR_TYPE_MAP})
+
+
+def _column_rule_type(annotation: Any) -> type:
+    """The class whose column rule the annotation follows.
+
+    An enum follows the first class of its MRO that has a rule, the scalar it is
+    mixed with; a plain enum has none and is returned as it is.
+    """
+    python_type = _extract_origin_type(annotation)
+    if not issubclass(python_type, Enum):
+        return python_type
+    return next((t for t in python_type.__mro__ if t in _COLUMN_RULE_TYPES), python_type)
+
+
+def _infer_column_type(annotation: Any, *, field: Field) -> ColumnType | None:
+    """Infer the column type from the annotation; an enum follows its scalar mixin.
+
+    Returns:
+        The column type, or ``None`` for a plain enum or a ``Literal``, which
+        have no scalar type to follow.
+    """
+    base, _ = _column_base(annotation)
+    origin = get_origin(base)
+    if origin is Literal:
+        return None
+    if origin in (list, tuple, set, dict):
         return JSON
-    python_type = _extract_origin_type(base)
-    if python_type is str:
+    rule_type = _column_rule_type(base)
+    if rule_type is str:
         return String(field.length)
-    if python_type in (date, time):
-        return String(None)
-    return _SCALAR_TYPE_MAP.get(python_type, JSON)
+    if issubclass(rule_type, Enum):
+        return None
+    return _SCALAR_TYPE_MAP.get(rule_type, JSON)
 
 
 _SCOPE_NAME = re.compile(r"^[a-z_][a-z0-9_]*$")