sqlcrucible 0.3.6__tar.gz → 0.4.0__tar.gz

{sqlcrucible-0.3.6 → sqlcrucible-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlcrucible
-Version: 0.3.6
+Version: 0.4.0
 Summary: Define a single model that works as both Pydantic and SQLAlchemy, with explicit conversion between the two
 Project-URL: Homepage, https://sqlcrucible.rdrj.uk
 Project-URL: Issues, https://github.com/RichardDRJ/sqlcrucible/issues

{sqlcrucible-0.3.6 → sqlcrucible-0.4.0}/docs/guide/type-conversion.md

@@ -2,7 +2,7 @@
 
 ## Custom Type Converters
 
-Use `ConvertToSAWith` and `ConvertFromSAWith` to customize conversion between your entity and the SQLAlchemy model:
+Use `ConvertToSAWith` and `ConvertFromSAWith` to customize conversion between your entity and the SQLAlchemy model. The callable receives `(value, context)` — `context` is a `ConversionContext`, and `context.target_type` is the resolved entity-side field type:
 
 ```python
 from datetime import timedelta
@@ -19,11 +19,51 @@ class Track(SQLCrucibleBaseModel):
         timedelta,
         mapped_column(),
         SQLAlchemyField(name="length_seconds", tp=int),
-        ConvertToSAWith(lambda td: td.total_seconds()),
-        ConvertFromSAWith(lambda s: timedelta(seconds=s)),
+        ConvertToSAWith(lambda td, ctx: td.total_seconds()),
+        ConvertFromSAWith(lambda s, ctx: timedelta(seconds=s)),
     ]
 ```
 
+### `target_type` and generic entities
+
+`context.target_type` is the *resolved* type of the field — for a concrete specialisation of a generic entity it's the specialised type, not the `TypeVar`. So a JSON column holding a per-subclass Pydantic payload can be re-validated against the right model:
+
+```python
+from typing import Annotated, Generic, TypeVar
+from pydantic import BaseModel, TypeAdapter
+from sqlalchemy import JSON
+from sqlalchemy.orm import mapped_column
+from sqlcrucible import ConvertFromSAWith, ConvertToSAWith, ExcludeSAField, SQLCrucibleBaseModel
+
+P = TypeVar("P", bound=BaseModel)
+
+class Event(SQLCrucibleBaseModel, Generic[P]):
+    __sqlalchemy_params__ = {
+        "__tablename__": "event",
+        "__mapper_args__": {"polymorphic_on": "kind", "polymorphic_abstract": True},
+    }
+    payload: Annotated[
+        P | None,
+        mapped_column(JSON, nullable=True),
+        ConvertToSAWith(lambda v, ctx: None if v is None else v.model_dump(mode="json")),
+        ConvertFromSAWith(
+            lambda v, ctx: None if v is None else TypeAdapter(ctx.target_type).validate_python(v)
+        ),
+    ] = None
+
+class ArtistSignedPayload(BaseModel):
+    artist_name: str
+
+class ArtistSigned(Event[ArtistSignedPayload]):
+    __sqlalchemy_params__ = {"__mapper_args__": {"polymorphic_identity": "artist.signed"}}
+    kind: Annotated[str, ExcludeSAField()] = "artist.signed"
+
+# Loading an ArtistSigned row: ctx.target_type is `ArtistSignedPayload | None`,
+# so `payload` comes back as an ArtistSignedPayload, not the raw dict.
+```
+
+Custom `Converter` implementations (registered directly in a `ConverterRegistry`) follow the same shape — `convert(self, source, context)` and `safe_convert(self, source, context)`.
+
 ## How the Conversion System Works
 
 When converting between Pydantic and SQLAlchemy models, SQLCrucible uses a registry of type converters. Understanding how this works helps when dealing with complex nested types.

{sqlcrucible-0.3.6 → sqlcrucible-0.4.0}/docs/reference/api.md

@@ -56,6 +56,12 @@
     options:
       show_bases: false
 
+### ConversionContext
+
+::: sqlcrucible.conversion.context.ConversionContext
+    options:
+      show_bases: false
+
 ## Fields
 
 ### readonly_field

{sqlcrucible-0.3.6 → sqlcrucible-0.4.0}/src/sqlcrucible/__init__.py

@@ -1,3 +1,4 @@
+from sqlcrucible.conversion.context import ConversionContext
 from sqlcrucible.entity.core import SQLCrucibleBaseModel, SQLCrucibleEntity, SQLAlchemyParameters
 from sqlcrucible.entity.sa_type import SAType
 from sqlcrucible.entity.annotations import (
@@ -18,6 +19,7 @@ __all__ = [
     "ExcludeSAField",
     "ConvertFromSAWith",
     "ConvertToSAWith",
+    "ConversionContext",
     "readonly_field",
     "ReadonlyFieldDescriptor",
     "__version__",

{sqlcrucible-0.3.6 → sqlcrucible-0.4.0}/src/sqlcrucible/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.6'
-__version_tuple__ = version_tuple = (0, 3, 6)
+__version__ = version = '0.4.0'
+__version_tuple__ = version_tuple = (0, 4, 0)
 
 __commit_id__ = commit_id = None

{sqlcrucible-0.3.6 → sqlcrucible-0.4.0}/src/sqlcrucible/conversion/caching.py

@@ -4,6 +4,7 @@ from contextlib import contextmanager
 from contextvars import ContextVar
 from typing import Any, Generator, TypeVar, Generic
 
+from sqlcrucible.conversion.context import ConversionContext
 from sqlcrucible.conversion.registry import Converter, ConverterFactory, ConverterRegistry
 
 IdentityMap = dict[int, Any]
@@ -45,16 +46,16 @@ class CachingConverter(Generic[_T, _R], Converter[_T, _R]):
     def matches(self, source_tp: Any, target_tp: Any) -> bool:
         return self._inner.matches(source_tp, target_tp)
 
-    def convert(self, source: _T) -> _R:
+    def convert(self, source: _T, context: ConversionContext) -> _R:
         with _identity_map() as identity_map:
             if id(source) not in identity_map:
-                identity_map[id(source)] = self._inner.convert(source)
+                identity_map[id(source)] = self._inner.convert(source, context)
             return identity_map[id(source)]
 
-    def safe_convert(self, source: _T) -> _R:
+    def safe_convert(self, source: _T, context: ConversionContext) -> _R:
         with _identity_map() as identity_map:
             if id(source) not in identity_map:
-                identity_map[id(source)] = self._inner.safe_convert(source)
+                identity_map[id(source)] = self._inner.safe_convert(source, context)
             return identity_map[id(source)]
 
 

sqlcrucible-0.4.0/src/sqlcrucible/conversion/context.py

@@ -0,0 +1,21 @@
+"""Context handed to value converters."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class ConversionContext:
+    """Context handed to ``ConvertToSAWith`` / ``ConvertFromSAWith`` callables.
+
+    ``target_type`` is the *resolved* entity-side field type — for a concrete
+    specialisation of a generic entity it's the specialised type, not the
+    ``TypeVar`` — so a converter can validate against it (e.g. with
+    ``pydantic.TypeAdapter``) without having to guess. New fields can be added
+    here as more context is needed; the callable signature stays
+    ``Callable[[Any, ConversionContext], Any]``.
+    """
+
+    target_type: Any

{sqlcrucible-0.3.6 → sqlcrucible-0.4.0}/src/sqlcrucible/conversion/dicts.py

@@ -21,6 +21,7 @@ from typing import (
 )
 from typing_extensions import is_typeddict, NoExtraItems
 
+from sqlcrucible.conversion.context import ConversionContext
 from sqlcrucible.conversion.registry import Converter, ConverterFactory, ConverterRegistry
 from sqlcrucible._types.annotations import TypeAnnotation, unwrap
 
@@ -167,18 +168,18 @@ class DictConverter(Converter[dict, dict]):
         if missing:
             raise TypeError(f"Missing required key '{missing}' for {self._target_info.tp}")
 
-    def convert(self, source: dict) -> dict:
+    def convert(self, source: dict, context: ConversionContext) -> dict:
         result = {
-            key: conv.convert(value)
+            key: conv.convert(value, context)
             for key, value in source.items()
             if (conv := self._get_converter(key))
         }
         self._check_required_fields(result)
         return result
 
-    def safe_convert(self, source: dict) -> dict:
+    def safe_convert(self, source: dict, context: ConversionContext) -> dict:
         result = {
-            key: conv.safe_convert(value)
+            key: conv.safe_convert(value, context)
             for key, value in source.items()
             if (conv := self._get_converter(key))
         }

sqlcrucible-0.4.0/src/sqlcrucible/conversion/function.py

@@ -0,0 +1,46 @@
+"""Function-based converter for custom type transformations.
+
+This module provides a converter that wraps a user-supplied function to perform
+type conversion. It's used when fields are annotated with ConvertToSAWith or
+ConvertFromSAWith to specify custom conversion logic. The function is called as
+``fn(value, context)``, where ``context`` is the
+:class:`~sqlcrucible.conversion.context.ConversionContext` for the field being
+converted (it carries the resolved field type).
+
+Example::
+
+    converter = FunctionConverter(lambda x, ctx: x.total_seconds())
+    converter.convert(timedelta(minutes=5), ConversionContext(target_type=float))  # 300.0
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+from sqlcrucible.conversion.context import ConversionContext
+from sqlcrucible.conversion.registry import Converter
+
+
+class FunctionConverter(Converter[Any, Any]):
+    """Converter that applies a custom function to transform values.
+
+    Reports a match for any type pair — the wrapped function decides what's
+    valid; type checking is its responsibility. The function is invoked as
+    ``fn(value, context)`` with the :class:`ConversionContext` supplied by the
+    caller.
+    """
+
+    def __init__(self, fn: Callable[[Any, ConversionContext], Any]) -> None:
+        self._fn = fn
+
+    @property
+    def fn(self) -> Callable[[Any, ConversionContext], Any]:
+        return self._fn
+
+    def matches(self, source_tp: Any, target_tp: Any) -> bool:
+        return True
+
+    def convert(self, source: Any, context: ConversionContext) -> Any:
+        return self._fn(source, context)
+
+    def safe_convert(self, source: Any, context: ConversionContext) -> Any:
+        return self.convert(source, context)

{sqlcrucible-0.3.6 → sqlcrucible-0.4.0}/src/sqlcrucible/conversion/literals.py

@@ -12,6 +12,7 @@ Example:
 
 from typing import Any, Literal, get_args, get_origin
 
+from sqlcrucible.conversion.context import ConversionContext
 from sqlcrucible.conversion.exceptions import TypeMismatchError
 from sqlcrucible.conversion.registry import Converter, ConverterFactory, ConverterRegistry
 from sqlcrucible._types.annotations import unwrap
@@ -62,10 +63,10 @@ class LiteralConverter(Converter[Any, Any]):
         target_values = _get_literal_values(target_tp)
         return source_values <= target_values
 
-    def convert(self, source: Any) -> Any:
+    def convert(self, source: Any, context: ConversionContext) -> Any:
         return source
 
-    def safe_convert(self, source: Any) -> Any:
+    def safe_convert(self, source: Any, context: ConversionContext) -> Any:
         if source not in self._allowed_values:
             raise TypeMismatchError(
                 source,

{sqlcrucible-0.3.6 → sqlcrucible-0.4.0}/src/sqlcrucible/conversion/noop.py

@@ -16,6 +16,7 @@ from sqlcrucible._types.annotations import (
 from typing import Any, get_origin
 
 
+from sqlcrucible.conversion.context import ConversionContext
 from sqlcrucible.conversion.exceptions import TypeMismatchError
 from sqlcrucible.conversion.registry import Converter, ConverterFactory
 from sqlcrucible.conversion.registry import ConverterRegistry
@@ -39,10 +40,10 @@ class NoOpConverter(Converter[Any, Any]):
     def matches(self, source_tp: Any, target_tp: Any) -> bool:
         return types_are_non_parameterised_and_equal(source_tp, target_tp)
 
-    def convert(self, source: Any) -> Any:
+    def convert(self, source: Any, context: ConversionContext) -> Any:
         return source
 
-    def safe_convert(self, source: Any) -> Any:
+    def safe_convert(self, source: Any, context: ConversionContext) -> Any:
         if not (self._target_origin is Any or isinstance(source, self._target_origin)):
             raise TypeMismatchError(source, self._target_tp)
         return source

{sqlcrucible-0.3.6 → sqlcrucible-0.4.0}/src/sqlcrucible/conversion/registry.py

@@ -16,6 +16,8 @@ list[CustomType] needs a converter for CustomType).
 
 from typing import Any, Protocol, TypeVar, runtime_checkable
 
+from sqlcrucible.conversion.context import ConversionContext
+
 _I = TypeVar("_I", contravariant=True)
 _O = TypeVar("_O", covariant=True)
 
@@ -34,7 +36,7 @@ class Converter(Protocol[_I, _O]):
         """
         ...
 
-    def convert(self, source: _I) -> _O:
+    def convert(self, source: _I, context: ConversionContext) -> _O:
         """Convert a value from source type to target type (fast path).
 
         This method assumes the input is valid based on static type resolution.
@@ -43,13 +45,15 @@ class Converter(Protocol[_I, _O]):
 
         Args:
             source: The value to convert.
+            context: The conversion context for the field being converted
+                (carries the resolved field type, for converters that need it).
 
         Returns:
             The converted value.
         """
         ...
 
-    def safe_convert(self, source: _I) -> _O:
+    def safe_convert(self, source: _I, context: ConversionContext) -> _O:
         """Convert a value with runtime type validation.
 
         This method validates the input at runtime and raises ConversionError
@@ -58,6 +62,7 @@ class Converter(Protocol[_I, _O]):
 
         Args:
             source: The value to convert.
+            context: The conversion context for the field being converted.
 
         Returns:
             The converted value.

{sqlcrucible-0.3.6 → sqlcrucible-0.4.0}/src/sqlcrucible/conversion/sequences.py

@@ -16,6 +16,7 @@ Example:
 
 from typing import Any, Sequence, get_args, get_origin
 
+from sqlcrucible.conversion.context import ConversionContext
 from sqlcrucible.conversion.registry import Converter, ConverterFactory, ConverterRegistry
 from sqlcrucible._types.params import get_type_params_for_base
 
@@ -58,11 +59,11 @@ class SequenceConverter(Converter[Sequence, KnownSequenceType]):
     def matches(self, source_tp: Any, target_tp: Any) -> bool:
         return True
 
-    def convert(self, source: Sequence) -> Any:
-        return self._target(self._inner.convert(it) for it in source)
+    def convert(self, source: Sequence, context: ConversionContext) -> Any:
+        return self._target(self._inner.convert(it, context) for it in source)
 
-    def safe_convert(self, source: Sequence) -> Any:
-        return self._target(self._inner.safe_convert(it) for it in source)
+    def safe_convert(self, source: Sequence, context: ConversionContext) -> Any:
+        return self._target(self._inner.safe_convert(it, context) for it in source)
 
 
 class SequenceConverterFactory(ConverterFactory[Sequence, KnownSequenceType]):

{sqlcrucible-0.3.6 → sqlcrucible-0.4.0}/src/sqlcrucible/conversion/unions.py

@@ -19,6 +19,7 @@ from collections.abc import Iterable, Sequence
 from types import UnionType
 from typing import Any, TypeVar, Union, get_args, get_origin
 
+from sqlcrucible.conversion.context import ConversionContext
 from sqlcrucible.conversion.exceptions import ConversionError, NoConverterFoundError
 from sqlcrucible.conversion.noop import NoOpConverter
 from sqlcrucible.conversion.registry import Converter, ConverterFactory, ConverterRegistry
@@ -105,7 +106,7 @@ class UnionConverter(Converter[Any, Any]):
     def matches(self, source_tp: Any, target_tp: Any) -> bool:
         return _is_union(source_tp) or _is_union(target_tp)
 
-    def convert(self, source: Any) -> Any:
+    def convert(self, source: Any, context: ConversionContext) -> Any:
         source_type = type(source)
         candidates = [
             conv
@@ -115,15 +116,15 @@ class UnionConverter(Converter[Any, Any]):
 
         for converter in candidates:
             try:
-                return converter.safe_convert(source)
+                return converter.safe_convert(source, context)
             except ConversionError:
                 continue
 
         raise NoConverterFoundError(source, self._target_tp)
 
-    def safe_convert(self, source: Any) -> Any:
+    def safe_convert(self, source: Any, context: ConversionContext) -> Any:
         # Union conversion always uses safe_convert internally
-        return self.convert(source)
+        return self.convert(source, context)
 
 
 class UnionConverterFactory(ConverterFactory[Any, Any]):

{sqlcrucible-0.3.6 → sqlcrucible-0.4.0}/src/sqlcrucible/entity/annotations.py

@@ -8,8 +8,15 @@ from typing import Any
 
 from sqlalchemy.orm import ORMDescriptor
 
-from sqlcrucible.conversion.function import FunctionConverter
-from sqlcrucible.conversion.registry import Converter
+from sqlcrucible.conversion.context import ConversionContext
+
+__all__ = [
+    "SQLAlchemyField",
+    "ExcludeSAField",
+    "ConvertFromSAWith",
+    "ConvertToSAWith",
+    "ConversionContext",
+]
 
 
 @dataclass(frozen=True, slots=True)
@@ -49,39 +56,48 @@ class ExcludeSAField:
     value: bool = True
 
 
-@dataclass(slots=True)
+@dataclass(slots=True, frozen=True)
 class ConvertFromSAWith:
-    """Annotation specifying custom converter from SQLAlchemy to entity.
+    """Annotation specifying a custom converter from SQLAlchemy to entity.
 
-    Use this annotation to provide a custom conversion function when loading
-    values from SQLAlchemy models into entity instances.
+    The callable receives ``(value, context)``. ``context.target_type`` is the
+    resolved entity-side field type — for a concrete specialisation of a generic
+    entity it's the specialised type on the subclass, not the ``TypeVar`` — so a
+    converter can validate against it without having to guess.
 
     Example:
         ```python
         from typing import Annotated
+        from pydantic import TypeAdapter
 
 
         class MyEntity(SQLCrucibleEntity):
             created_at: Annotated[
-                datetime, mapped_column(), ConvertFromSAWith(lambda dt: dt.astimezone(timezone.utc))
+                datetime,
+                mapped_column(),
+                ConvertFromSAWith(lambda dt, ctx: dt.astimezone(timezone.utc)),
+            ]
+            payload: Annotated[
+                SomeModel | None,
+                mapped_column(JSON),
+                ConvertFromSAWith(
+                    lambda v, ctx: (
+                        None if v is None else TypeAdapter(ctx.target_type).validate_python(v)
+                    )
+                ),
             ]
         ```
     """
 
-    fn: Callable[[Any], Any]
+    fn: Callable[[Any, ConversionContext], Any]
 
-    @property
-    def converter(self) -> Converter:
-        """Get the Converter instance for this function."""
-        return FunctionConverter(self.fn)
 
-
-@dataclass(slots=True)
+@dataclass(slots=True, frozen=True)
 class ConvertToSAWith:
-    """Annotation specifying custom converter from entity to SQLAlchemy.
+    """Annotation specifying a custom converter from entity to SQLAlchemy.
 
-    Use this annotation to provide a custom conversion function when saving
-    entity values into SQLAlchemy models.
+    The callable receives ``(value, context)``. ``context.target_type`` is the
+    resolved entity-side field type of the value being converted.
 
     Example:
         ```python
@@ -90,14 +106,11 @@ class ConvertToSAWith:
 
         class MyEntity(SQLCrucibleEntity):
             created_at: Annotated[
-                datetime, mapped_column(), ConvertToSAWith(lambda dt: dt.astimezone(timezone.utc))
+                datetime,
+                mapped_column(),
+                ConvertToSAWith(lambda dt, ctx: dt.astimezone(timezone.utc)),
             ]
         ```
     """
 
-    fn: Callable[[Any], Any]
-
-    @property
-    def converter(self) -> Converter:
-        """Get the Converter instance for this function."""
-        return FunctionConverter(self.fn)
+    fn: Callable[[Any, ConversionContext], Any]

{sqlcrucible-0.3.6 → sqlcrucible-0.4.0}/src/sqlcrucible/entity/automodel.py

@@ -67,6 +67,40 @@ def _public_fields(it: dict[str, Any]) -> dict[str, Any]:
     return {name: it[name] for name in names}
 
 
+def _transparent_parameterisation_origin(
+    source: type[SQLCrucibleEntity],
+) -> type[SQLCrucibleEntity] | None:
+    """If ``source`` is a Pydantic generic parameterisation (``Origin[Args...]``)
+    that adds no SQLAlchemy configuration of its own, return ``Origin``.
+
+    Such a class is transparent at the SQLAlchemy layer — same table, same
+    columns, same mapper — because the type parameters only constrain the
+    entity-side (Pydantic) field types, which the parameterised class already
+    carries in its own ``model_fields`` / converters. So it should reuse the
+    origin's automodel rather than mint a fresh one. Minting a fresh one is
+    not just wasteful: in single-table inheritance it lands as an identity-less
+    polymorphic intermediate (SQLAlchemy warns), and its ``__name__`` contains
+    ``[`` ``]`` which the stub generator can't emit as a valid identifier.
+
+    Returns ``None`` (build a fresh automodel as usual) when ``source`` adds
+    its own ``__sqlalchemy_params__``, ``__sqlalchemy_base__``, or registered
+    fields — e.g. a concrete subclass of a parameterised generic that supplies
+    its own ``polymorphic_identity``.
+    """
+    pydantic_meta = getattr(source, "__pydantic_generic_metadata__", None)
+    origin = pydantic_meta.get("origin") if pydantic_meta else None
+    is_parameterisation = origin is not None and origin is not source
+
+    own = vars(source)
+    adds_own_sa_config = bool(
+        own.get("__sqlalchemy_params__")
+        or own.get("__sqlalchemy_base__")
+        or own.get("__own_sqlcrucible_fields__")
+    )
+
+    return origin if is_parameterisation and not adds_own_sa_config else None
+
+
 def _create_automodel(source: type[SQLCrucibleEntity]) -> type[Any]:
     """Create a SQLAlchemy automodel class for an entity.
 
@@ -75,10 +109,15 @@ def _create_automodel(source: type[SQLCrucibleEntity]) -> type[Any]:
     mapper configuration, except when a cycle is detected (in which case string
     forward refs are used to break the cycle).
     """
+    if (origin := _transparent_parameterisation_origin(source)) is not None:
+        return origin.__sqlalchemy_type__
+
     params = vars(source).get("__sqlalchemy_params__", {})
     base = _get_sa_base(source)
 
-    own_fields: dict[str, SQLCrucibleField] = source.__dict__.get("__sqlcrucible_fields__") or {}
+    own_fields: dict[str, SQLCrucibleField] = (
+        source.__dict__.get("__own_sqlcrucible_fields__") or {}
+    )
     field_defs = [decl for decl in own_fields.values() if not decl.excluded]
 
     # Determine which fields need type annotations based on SQLAlchemy's Mapped type.