sqlcrucible 0.3.5__tar.gz → 0.3.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlcrucible
-Version: 0.3.5
+Version: 0.3.6
 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.5 → sqlcrucible-0.3.6}/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.5'
-__version_tuple__ = version_tuple = (0, 3, 5)
+__version__ = version = '0.3.6'
+__version_tuple__ = version_tuple = (0, 3, 6)
 
 __commit_id__ = commit_id = None

{sqlcrucible-0.3.5 → sqlcrucible-0.3.6}/src/sqlcrucible/conversion/__init__.py

@@ -5,8 +5,10 @@ from sqlcrucible.conversion.noop import NoOpConverterFactory
 from sqlcrucible.conversion.registry import ConverterRegistry
 from sqlcrucible.conversion.sequences import SequenceConverterFactory
 from sqlcrucible.conversion.unions import UnionConverterFactory
+from sqlcrucible.conversion.unwrap import AnnotatedUnwrappingFactory
 
 default_registry = ConverterRegistry(
+    CachingConverterFactory(AnnotatedUnwrappingFactory()),
     CachingConverterFactory(NoOpConverterFactory()),
     CachingConverterFactory(LiteralConverterFactory()),
     CachingConverterFactory(DictConverterFactory()),

sqlcrucible-0.3.6/src/sqlcrucible/conversion/unwrap.py

@@ -0,0 +1,36 @@
+"""Converter factory for unwrapping transparent type wrappers."""
+
+from typing import Annotated, Any, get_args, get_origin
+
+from sqlalchemy.orm import Mapped
+
+from sqlcrucible.conversion.registry import Converter, ConverterFactory, ConverterRegistry
+
+_WRAPPER_ORIGINS = (Annotated, Mapped)
+
+
+def _unwrap(tp: Any) -> Any:
+    """Strip a single Annotated[T, ...] or Mapped[T] wrapper, returning the inner type."""
+    if get_origin(tp) in _WRAPPER_ORIGINS:
+        return get_args(tp)[0]
+    return tp
+
+
+class AnnotatedUnwrappingFactory(ConverterFactory):
+    """Factory that strips Annotated[T, ...] and Mapped[T] wrappers before converter lookup.
+
+    Non-SQLCrucible annotations (e.g. access-control markers) and SQLAlchemy's
+    Mapped wrapper should be transparent to the conversion registry. This factory
+    unwraps them and delegates to the registry for the inner type pair.
+    """
+
+    def matches(self, source_tp: Any, target_tp: Any) -> bool:
+        return _unwrap(source_tp) is not source_tp or _unwrap(target_tp) is not target_tp
+
+    def converter(
+        self,
+        source_tp: Any,
+        target_tp: Any,
+        registry: ConverterRegistry,
+    ) -> Converter | None:
+        return registry.resolve(_unwrap(source_tp), _unwrap(target_tp))

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

@@ -7,6 +7,7 @@ from typing import Any, get_args, get_origin
 
 import sqlalchemy.orm
 from sqlalchemy.orm.attributes import Mapped
+from typing import Annotated
 
 from sqlcrucible.entity.core import SQLAlchemyBase, SQLCrucibleEntity
 from sqlcrucible.entity.field_definitions import SQLCrucibleField
@@ -158,6 +159,13 @@ def _transform_field_type(
     # Resolve any forward references in the source type first
     resolved_tp = resolve_forward_refs(field_def.source_tp, owner)
 
+    # Strip Annotated wrappers — non-SA metadata (access-control markers, Pydantic
+    # validators, etc.) belongs on the entity side only. Leaving it in the SA model
+    # annotation prevents SQLAlchemy from correctly inferring relationship config
+    # such as uselist (e.g. Mapped[Annotated[list[X], meta]] yields uselist=False).
+    while get_origin(resolved_tp) is Annotated:
+        resolved_tp = get_args(resolved_tp)[0]
+
     match (get_origin(resolved_tp), get_args(resolved_tp)):
         case (sqlalchemy.orm.Mapped, _):
             return TypeTransformerResult(result=resolved_tp)

{sqlcrucible-0.3.5 → sqlcrucible-0.3.6}/src/sqlcrucible/entity/sa_type.py

@@ -1,15 +1,21 @@
 """SAType utility for type-safe access to entity SQLAlchemy types."""
 
-from typing import Protocol, TypeVar, Any, TYPE_CHECKING
+from typing import Any, Protocol, TYPE_CHECKING, TypeVar
 
-_S = TypeVar("_S", covariant=True)
+_S = TypeVar("_S")
 
 
 class HasSAType(Protocol[_S]):
-    """Protocol for types that have a __sqlalchemy_type__ property."""
+    """Protocol for entity classes that expose ``__sqlalchemy_type__``.
 
-    @property
-    def __sqlalchemy_type__(self) -> _S: ...
+    The attribute is declared as ``ClassVar`` so that pyright accepts
+    matching against entity classes whose own declarations use the
+    same form (which SQLCrucibleBaseModel does). The metaclass
+    accessor takes the class itself (``type[HasSAType[_S]]``) and reads
+    the SA-type out at the class level.
+    """
+
+    __sqlalchemy_type__: _S
 
 
 class SATypeMeta(type):

{sqlcrucible-0.3.5 → sqlcrucible-0.3.6}/src/sqlcrucible/stubs/codegen.py

@@ -139,6 +139,9 @@ def construct_sa_type_stub(entities: list[type[SQLCrucibleEntity]]) -> str:
 
     return (
         f"{import_block}\n\n"
+        f"_S = typing.TypeVar('_S')\n\n"
+        f"class HasSAType(typing.Protocol[_S]):\n"
+        f"    __sqlalchemy_type__: _S\n\n"
         f"class SATypeMeta(type):\n"
         f"{overload_block}\n"
         f"    @typing.overload\n"

sqlcrucible-0.3.6/tests/conversion/test_unwrap.py

@@ -0,0 +1,81 @@
+"""Tests for AnnotatedUnwrappingFactory."""
+
+from typing import Annotated, Any
+
+import pytest
+from sqlalchemy.orm import Mapped
+
+from sqlcrucible.conversion.registry import ConverterRegistry
+from sqlcrucible.conversion.unwrap import AnnotatedUnwrappingFactory
+from tests.conversion.conftest import SourceItem, TargetItem
+
+
+@pytest.mark.parametrize(
+    ("source_tp", "target_tp"),
+    [
+        (Annotated[int, "meta"], str),
+        (int, Annotated[str, "meta"]),
+        (Annotated[int, "meta"], Annotated[str, "other"]),
+        (Mapped[int], str),
+        (int, Mapped[str]),
+    ],
+    ids=[
+        "annotated_source",
+        "annotated_target",
+        "both_annotated",
+        "mapped_source",
+        "mapped_target",
+    ],
+)
+def test_matches_when_either_side_is_wrapped(source_tp: Any, target_tp: Any):
+    factory = AnnotatedUnwrappingFactory()
+    assert factory.matches(source_tp, target_tp)
+
+
+@pytest.mark.parametrize(
+    ("source_tp", "target_tp"),
+    [
+        (int, str),
+        (list[int], set[str]),
+    ],
+    ids=["plain_types", "generic_types"],
+)
+def test_does_not_match_unwrapped_types(source_tp: Any, target_tp: Any):
+    factory = AnnotatedUnwrappingFactory()
+    assert not factory.matches(source_tp, target_tp)
+
+
+def test_delegates_to_registry_with_unwrapped_types(registry: ConverterRegistry):
+    factory = AnnotatedUnwrappingFactory()
+    converter = factory.converter(
+        Annotated[SourceItem, "some_marker"],
+        TargetItem,
+        registry,
+    )
+    assert converter is not None
+    result = converter.convert(SourceItem(1))
+    assert result == TargetItem(2)
+
+
+def test_registry_resolves_annotated_source_via_unwrapping(registry: ConverterRegistry):
+    unwrapping_registry = ConverterRegistry(AnnotatedUnwrappingFactory(), *registry)
+    conv = unwrapping_registry.resolve(Annotated[SourceItem, "marker"], TargetItem)
+    assert conv is not None
+    assert conv.convert(SourceItem(3)) == TargetItem(6)
+
+
+def test_registry_resolves_annotated_list_via_unwrapping(registry: ConverterRegistry):
+    unwrapping_registry = ConverterRegistry(AnnotatedUnwrappingFactory(), *registry)
+    conv = unwrapping_registry.resolve(
+        Annotated[list[SourceItem], "marker"],
+        list[TargetItem],
+    )
+    assert conv is not None
+    assert conv.convert([SourceItem(1), SourceItem(2)]) == [TargetItem(2), TargetItem(4)]
+
+
+def test_registry_resolves_mapped_source_via_unwrapping(registry: ConverterRegistry):
+    unwrapping_registry = ConverterRegistry(AnnotatedUnwrappingFactory(), *registry)
+    conv = unwrapping_registry.resolve(Mapped[SourceItem], TargetItem)
+    assert conv is not None
+    assert conv.convert(SourceItem(5)) == TargetItem(10)

sqlcrucible-0.3.6/tests/entity/test_relationships_annotated_metadata.py

@@ -0,0 +1,75 @@
+"""Tests for relationship fields annotated with non-SA metadata.
+
+Pattern: A parent entity has a relationship field whose annotation includes
+non-SQLAlchemy metadata (e.g. access-control markers) alongside the
+relationship() descriptor.
+"""
+
+from uuid import uuid4, UUID
+from typing import Annotated
+
+from pydantic import Field
+from sqlalchemy import MetaData, ForeignKey
+from sqlalchemy.orm import mapped_column, relationship
+
+from sqlcrucible.entity.core import SQLCrucibleBaseModel
+from sqlcrucible.entity.sa_type import SAType
+
+
+metadata = MetaData()
+
+
+class AnnotatedMetaBase(SQLCrucibleBaseModel):
+    __sqlalchemy_params__ = {"__abstract__": True, "metadata": metadata}
+
+
+class _ReadOnly:
+    """Marker annotation that is not a SQLAlchemy or SQLCrucible type."""
+
+
+READ_ONLY = _ReadOnly()
+
+
+class TagAnnotated(AnnotatedMetaBase):
+    __sqlalchemy_params__ = {"__tablename__": "annotated_tag"}
+
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    post_id: Annotated[UUID, mapped_column(ForeignKey("annotated_post.id"))]
+    label: str
+
+
+class PostAnnotated(AnnotatedMetaBase):
+    __sqlalchemy_params__ = {"__tablename__": "annotated_post"}
+
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    title: str
+
+    tags: Annotated[
+        list[TagAnnotated],
+        READ_ONLY,
+        relationship(
+            lambda: SAType[TagAnnotated],
+            foreign_keys=lambda: [SAType[TagAnnotated].post_id],
+        ),
+    ] = Field(default_factory=list)
+
+
+def test_relationship_field_with_non_sa_annotated_metadata_roundtrips():
+    """A relationship field with non-SA Annotated metadata round-trips correctly."""
+    post_id = uuid4()
+    tag = TagAnnotated(post_id=post_id, label="python")
+    post = PostAnnotated(id=post_id, title="Hello", tags=[tag])
+
+    restored = PostAnnotated.from_sa_model(post.to_sa_model())
+
+    assert len(restored.tags) == 1
+    assert restored.tags[0].label == "python"
+
+
+def test_sa_model_annotation_for_relationship_with_annotated_metadata_uses_list():
+    """The SA model annotation for an Annotated relationship field should be Mapped[list[...]]."""
+    from sqlalchemy import inspect
+
+    mapper = inspect(SAType[PostAnnotated])
+    rel = next(r for r in mapper.relationships if r.key == "tags")
+    assert rel.uselist is True