typebind 0.1.0a1__tar.gz → 0.1.0a2__tar.gz

{typebind-0.1.0a1 → typebind-0.1.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typebind
-Version: 0.1.0a1
+Version: 0.1.0a2
 Summary: Typed Pydantic model families, plugin discovery, and scoped behavior adapters.
 Keywords: pydantic,discriminator,generics,plugins,adapters
 License-Expression: MIT

{typebind-0.1.0a1 → typebind-0.1.0a2}/docs/behaviors.md

@@ -50,6 +50,10 @@ family interface. One implementation can implement multiple interfaces, even
 when those interfaces bind to different ancestor families. Native generic
 forwarding through intermediate implementation bases is supported; there must
 ultimately be one concrete model target. Models do not inherit these interfaces.
+This includes forwarding a tag parameter inside a model: a base such as
+`Shared[K: str](Implementation[Message[K]])` specialized as
+`Shared[Literal["query"]]` targets `Message[Literal["query"]]`. Assembly uses
+Pydantic's native model specialization; the target retains its exact class identity.
 
 Assembly resolves the `model` property's return annotation with `get_type_hints`.
 With `from __future__ import annotations`, a family defined only inside a function

{typebind-0.1.0a1 → typebind-0.1.0a2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "typebind"
-version = "0.1.0a1"
+version = "0.1.0a2"
 description = "Typed Pydantic model families, plugin discovery, and scoped behavior adapters."
 readme = "README.md"
 requires-python = ">=3.12"

{typebind-0.1.0a1 → typebind-0.1.0a2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "typebind"
-version = "0.1.0a1"
+version = "0.1.0a2"
 description = "Typed Pydantic model families, plugin discovery, and scoped behavior adapters."
 readme = "README.md"
 requires-python = ">=3.12"

{typebind-0.1.0a1 → typebind-0.1.0a2}/src/typebind/_behavior.py

@@ -45,6 +45,20 @@ def _implementation_class(value: object) -> type[Implementation[Any]]:
     return cast(type[Implementation[Any]], value)
 
 
+def _substitute_argument(argument: object, substitutions: dict[TypeVar, object]) -> object:
+    """Bind model parameters through native Pydantic specialization at assembly time."""
+    if isinstance(argument, TypeVar):
+        return substitutions.get(argument, argument)
+    if isinstance(argument, type) and issubclass(argument, DiscriminatedModel):
+        parameters = argument.__pydantic_generic_metadata__["parameters"]
+        resolved = tuple(substitutions.get(parameter, parameter) for parameter in parameters)
+        if resolved != parameters:
+            # Pydantic models are classes, not typing aliases. Let their native
+            # specialization substitute fields and preserve cached class identity.
+            return cast(Any, argument)[resolved]
+    return cast(object, argument)
+
+
 def _implementation_model(implementation: type[Implementation[Any]]) -> type[DiscriminatedModel]:
     """Resolve native generic bases, including type-variable forwarding through mixins."""
     targets: set[type[DiscriminatedModel]] = set()
@@ -54,10 +68,7 @@ def _implementation_model(implementation: type[Implementation[Any]]) -> type[Dis
             origin: object = get_origin(base) or base
             if not isinstance(origin, type):
                 continue
-            arguments = tuple(
-                substitutions.get(arg, arg) if isinstance(arg, TypeVar) else arg
-                for arg in get_args(base)
-            )
+            arguments = tuple(_substitute_argument(arg, substitutions) for arg in get_args(base))
             if origin is Implementation:
                 if len(arguments) != 1:
                     raise TypeError(
@@ -68,6 +79,11 @@ def _implementation_model(implementation: type[Implementation[Any]]) -> type[Dis
             elif issubclass(origin, Implementation):
                 parent = cast(type[Implementation[Any]], origin)
                 parameters = cast(tuple[TypeVar, ...], getattr(parent, "__parameters__", ()))
+                if len(arguments) != len(parameters):
+                    raise TypeError(
+                        f"{_name(implementation)}: expected explicit type arguments "
+                        f"for {_name(parent)}"
+                    )
                 visit(parent, dict(zip(parameters, arguments, strict=True)))
 
     visit(implementation, {})

{typebind-0.1.0a1 → typebind-0.1.0a2}/src/typebind/_models.py

@@ -230,6 +230,7 @@ class DiscriminatedModel(BaseModel):
             annotation = cls.model_fields[field_name].annotation
             if not _is_open_tag(annotation):
                 _literal_tag(cls, field_name)
+            cls._check_tag_field(field_name)
             return
         parent_discriminator = _open_discriminator(parent)
         if parent_discriminator is not None and not _decorated_field(
@@ -450,7 +451,7 @@ def _branches(
     Unspecialized ancestors identify the family boundaries. All tag values come
     from the supplied leaf's resolved Pydantic fields, not generic arguments or
     stored paths. Repeated classes are harmless; conflicting parent/tag claims
-    raise ValueError. Open families and untagged models raise TypeError.
+    raise ValueError. Abstract models, open families and untagged models raise TypeError.
     """
     branches: dict[type[DiscriminatedModel], dict[str, type[DiscriminatedModel]]] = {}
     seen: set[type[DiscriminatedModel]] = set()
@@ -460,7 +461,11 @@ def _branches(
         if variant in seen:
             continue
         seen.add(variant)
-        if _open_discriminator(variant) is not None or not _tag_fields(variant):
+        if (
+            isabstract(variant)
+            or _open_discriminator(variant) is not None
+            or not _tag_fields(variant)
+        ):
             raise TypeError(f"{_model_name(variant)} must be a tagged leaf model")
         families = [
             base

{typebind-0.1.0a1 → typebind-0.1.0a2}/tests/test_behavior.py

@@ -1,8 +1,9 @@
 """Behavior assembly validates declarations once and binds ordinary objects."""
 
+import sys
 from abc import abstractmethod
 from importlib import metadata
-from typing import Annotated, Any, Literal, Protocol, cast
+from typing import Annotated, Any, Literal, Protocol, assert_type, cast
 
 import pytest
 from pydantic import BaseModel, TypeAdapter
@@ -159,6 +160,69 @@ def test_generic_forwarding_and_inherited_implementation() -> None:
     )
 
 
+@pytest.mark.parametrize("through_middle", [False, True])
+def test_nested_model_type_argument_forwarding(through_middle: bool) -> None:
+    class Shared[K: str](Implementation[Message[K]], Describable):
+        def describe(self) -> str:
+            return self.model.identifier
+
+    class Direct(Shared[Literal["nested"]]):
+        pass
+
+    class Middle[K: str](Shared[K]):
+        pass
+
+    class Forwarded(Middle[Literal["nested"]]):
+        pass
+
+    class Inherited(Forwarded):
+        pass
+
+    leaf = Message[Literal["nested"]]
+    sample = leaf(identifier="nested")
+    assert_type(Direct(sample).model, Message[Literal["nested"]])
+    assert_type(Inherited(sample).model, Message[Literal["nested"]])
+    implementation = Inherited if through_middle else Direct
+    runtime = assemble(
+        variants=[leaf], implementations=[implementation], required_interfaces=[Describable]
+    )
+    view = runtime.adapt(sample, Describable)
+    assert type(view) is implementation
+    assert view.model is sample
+    assert view.describe() == "nested"
+
+
+def test_nested_model_argument_through_whole_model_forwarding() -> None:
+    class Whole[T: DiscriminatedModel](Implementation[T]):
+        pass
+
+    class Shared[K: str](Whole[Request[K]], Describable):
+        def describe(self) -> str:
+            return f"{self.model.kind}/{self.model.method}"
+
+    class Concrete(Shared[Literal["nested"]]):
+        pass
+
+    leaf = Request[Literal["nested"]]
+    sample = leaf(identifier="q")
+    assert_type(Concrete(sample).model, Request[Literal["nested"]])
+    runtime = assemble(
+        variants=[leaf], implementations=[Concrete], required_interfaces=[Describable]
+    )
+    view = runtime.adapt(sample, Describable)
+    assert view.model is sample
+    assert view.describe() == "request/nested"
+
+    class Open(Shared[str]):
+        pass
+
+    with pytest.raises(TypeError, match="expected a concrete model"):
+        assemble(variants=[leaf], implementations=[Open])
+
+    with pytest.raises(TypeError, match="expected a concrete model"):
+        assemble(variants=[leaf], implementations=[Shared])
+
+
 def test_no_reflection_discovery_or_validation_in_hot_path(monkeypatch: pytest.MonkeyPatch) -> None:
     runtime = assemble(
         variants=[Query], implementations=[QueryObject], required_interfaces=[Describable]
@@ -220,6 +284,56 @@ def test_unspecialized_implementation_is_rejected(bare: type[object]) -> None:
     assert f"{bare.__module__}.{bare.__qualname__}" in str(error.value)
 
 
+def test_unspecialized_intermediate_implementation_is_rejected() -> None:
+    class Shared[T: DiscriminatedModel](Implementation[T]):
+        pass
+
+    # Deliberately omit the generic arguments, as an unchecked plugin may do.
+    bare = type("Unparameterized", (Shared,), {})
+    with pytest.raises(TypeError, match="expected explicit type arguments for .*Shared") as error:
+        assemble(variants=[Query], implementations=[bare])
+    assert "Unparameterized" in str(error.value)
+    assert (
+        f"Behavior implementation: {bare.__module__}.{bare.__qualname__}" in error.value.__notes__
+    )
+
+
+@pytest.mark.skipif(
+    sys.version_info < (3, 13), reason="Native type parameter defaults require 3.13"
+)
+def test_implementation_type_parameter_defaults() -> None:
+    namespace: dict[str, Any] = {
+        "__name__": __name__,
+        "DiscriminatedModel": DiscriminatedModel,
+        "Implementation": Implementation,
+        "Query": Query,
+        "Describable": Describable,
+    }
+    # Keep the test module importable on Python 3.12.
+    exec(
+        """
+class Shared[T: DiscriminatedModel = Query](Implementation[T]):
+    pass
+class Bare(Shared):
+    pass
+class Explicit(Shared[()], Describable):
+    def describe(self) -> str:
+        return self.model.expression
+""",
+        namespace,
+    )
+    with pytest.raises(TypeError, match="Bare.*expected explicit type arguments for .*Shared"):
+        assemble(variants=[Query], implementations=[namespace["Bare"]])
+
+    runtime = assemble(
+        variants=[Query], implementations=[namespace["Explicit"]], required_interfaces=[Describable]
+    )
+    query = Query(identifier="q", expression="default")
+    view = runtime.adapt(query, Describable)
+    assert view.model is query
+    assert view.describe() == "default"
+
+
 def test_abstract_and_invalid_declarations() -> None:
     class Missing(Implementation[Query], Describable):
         pass

{typebind-0.1.0a1 → typebind-0.1.0a2}/tests/test_models.py

@@ -1,5 +1,6 @@
 """Exercise declarations, dispatch, isolation, and serialization boundaries."""
 
+from abc import ABC, abstractmethod
 from datetime import UTC, datetime
 from types import SimpleNamespace
 from typing import Annotated, Any, Literal, Self, assert_type, cast, get_type_hints
@@ -292,6 +293,35 @@ def test_invalid_variant_inputs_report_the_value(value: object) -> None:
     assert repr(value) in str(error.value)
 
 
+@pytest.mark.parametrize("binding", [False, True], ids=["adapter", "binding"])
+def test_abstract_tagged_variants_are_rejected(binding: bool) -> None:
+    class AbstractQuery(Request[Literal["abstract"]], ABC):
+        @abstractmethod
+        def execute(self) -> str: ...
+
+    with pytest.raises(TypeError, match="AbstractQuery.*tagged leaf model"):
+        if binding:
+            bind_variants([AbstractQuery])
+        else:
+            build_adapter(Message[Any], variants=[AbstractQuery])
+
+    class ConcreteQuery(AbstractQuery):
+        def execute(self) -> str:
+            return self.identifier
+
+    annotation = Annotated[Message[Any], bind_variants([ConcreteQuery])]
+    adapter = (
+        TypeAdapter[Message[Any]](annotation)
+        if binding
+        else build_adapter(Message[Any], variants=[ConcreteQuery])
+    )
+    result = adapter.validate_python(
+        {"kind": "request", "method": "abstract", "identifier": "q", "sequence": 1}
+    )
+    assert isinstance(result, ConcreteQuery)
+    assert result.execute() == "q"
+
+
 def test_variant_bindings_are_explicit_independent_snapshots() -> None:
     before = Message.model_json_schema()
     variants: list[type[DiscriminatedModel]] = [Query]
@@ -551,6 +581,42 @@ def test_conditional_tag_exclusion_is_rejected_at_declaration() -> None:
     assert "Unsupported settings: exclude_if" in str(error.value)
 
 
+@pytest.mark.parametrize(
+    "setting, value",
+    [
+        ("alias", "k"),
+        ("validation_alias", "k"),
+        ("serialization_alias", "k"),
+        ("exclude", True),
+        pytest.param(
+            "exclude_if",
+            bool,
+            marks=pytest.mark.skipif(
+                not hasattr(Field(), "exclude_if"), reason="Requires Pydantic's exclude_if"
+            ),
+        ),
+    ],
+)
+def test_specialization_preserves_tag_field_restrictions(setting: str, value: Any) -> None:
+    options = {setting: value}
+
+    class Native[Tag: str](BaseModel):
+        kind: Tag
+
+    native = Native[Annotated[Literal["hidden"], Field(**options)]]
+    if getattr(native.model_fields["kind"], setting) is None:
+        # Older Pydantic releases ignore these settings in generic type arguments.
+        # They remain safe only if tags are still exported and routable.
+        leaf = Message[Annotated[Literal["hidden"], Field(**options)]]
+        sample = leaf(identifier="q")
+        adapter = build_adapter(Message[Any], variants=[leaf])
+        assert sample.model_dump(by_alias=True) == {"kind": "hidden", "identifier": "q"}
+        assert adapter.validate_json(adapter.dump_json(sample, by_alias=True)) == sample
+        return
+    with pytest.raises(TypeError, match=f"Unsupported settings: .*{setting}"):
+        Message[Annotated[Literal["hidden"], Field(**options)]]
+
+
 def test_tag_field_is_the_single_source_of_the_discriminator() -> None:
     class Packet[Tag: str](DiscriminatedModel, extra="forbid"):
         operation: Annotated[Tag, Field(description="Wire operation")] = tag_field()

{typebind-0.1.0a1 → typebind-0.1.0a2}/uv.lock

@@ -1250,7 +1250,7 @@ wheels = [
 
 [[package]]
 name = "typebind"
-version = "0.1.0a1"
+version = "0.1.0a2"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic" },