dynapydantic 0.1.1__py3-none-any.whl → 0.2.0__py3-none-any.whl

dynapydantic/__init__.py

@@ -6,6 +6,7 @@ from .exceptions import (
     Error,
     RegistrationError,
 )
+from .polymorphic import Polymorphic
 from .subclass_tracking_model import SubclassTrackingModel
 from .tracking_group import TrackingGroup
 
@@ -13,6 +14,7 @@ __all__ = [
     "AmbiguousDiscriminatorValueError",
     "ConfigurationError",
     "Error",
+    "Polymorphic",
     "RegistrationError",
     "SubclassTrackingModel",
     "TrackingGroup",

dynapydantic/polymorphic.py

@@ -0,0 +1,29 @@
+"""Definition for Polymorphic"""
+
+import typing as ty
+
+from .subclass_tracking_model import SubclassTrackingModel
+
+ModelT = ty.TypeVar("ModelT", bound=SubclassTrackingModel)
+
+if ty.TYPE_CHECKING:  # pragma: no cover
+    Polymorphic = ty.Annotated[ModelT, ...]
+else:
+
+    class Polymorphic:
+        """Annotation used to mark a type as having duck-typing behavior
+
+        This annotation is only valid for SubclassTrackingModel's.
+
+        Similar to SerializeAsAny, a field annotated with this shall serialize as
+        according to its actual type, not the field annotation type. In addition,
+        parsing will function as if the field annotation type were the union of
+        all tracked subclasses.
+        """
+
+        def __class_getitem__(cls, item: ModelT) -> ty.Any:  # noqa: ANN401
+            """Get the annotation for the pydantic field"""
+            if not isinstance(item, type):
+                msg = f"dynapydantic.Polymorphic must be given a type, not {item}"
+                raise TypeError(msg)
+            return ty.Annotated[item, SubclassTrackingModel.PydanticAdaptor]

dynapydantic/subclass_tracking_model.py

@@ -1,8 +1,12 @@
 """Base class for dynamic pydantic models"""
 
+import inspect
 import typing as ty
 
 import pydantic
+from pydantic import GetCoreSchemaHandler
+from pydantic.errors import PydanticSchemaGenerationError
+from pydantic_core import core_schema
 
 from .exceptions import ConfigurationError
 from .tracking_group import TrackingGroup
@@ -45,17 +49,18 @@ class SubclassTrackingModel(pydantic.BaseModel):
         TrackingGroup.load_plugins for more details.
     """
 
-    def __init_subclass__(
-        cls,
-        *args,
-        exclude_from_union: bool | None = None,
-        **kwargs,
-    ) -> None:
+    def __init_subclass__(cls, *args, **kwargs) -> None:
         """Subclass hook"""
-        # Intercept any kwargs that are intended for TrackingGroup
-        super().__pydantic_init_subclass__(
+        # Intercept any kwargs that are intended for TrackingGroup or
+        # __pydantic_init_subclass__
+        sig = inspect.signature(SubclassTrackingModel.__pydantic_init_subclass__)
+        super().__init_subclass__(
             *args,
-            **{k: v for k, v in kwargs.items() if k not in TrackingGroup.model_fields},
+            **{
+                k: v
+                for k, v in kwargs.items()
+                if k not in TrackingGroup.model_fields and k not in sig.parameters
+            },
         )
 
     @classmethod
@@ -77,8 +82,8 @@ class SubclassTrackingModel(pydantic.BaseModel):
                 },
             )
 
-            if isinstance(getattr(cls, "tracking_config", None), TrackingGroup):
-                cls.__DYNAPYDANTIC__ = cls.tracking_config
+            if isinstance((tc := getattr(cls, "tracking_config", None)), TrackingGroup):
+                cls.__DYNAPYDANTIC__ = tc
             else:
                 try:
                     cls.__DYNAPYDANTIC__: TrackingGroup = TrackingGroup.model_validate(
@@ -118,7 +123,7 @@ class SubclassTrackingModel(pydantic.BaseModel):
 
             cls.union = staticmethod(_union)
 
-            def _subclasses() -> dict[str, type[cls]]:
+            def _subclasses() -> dict[str, type[pydantic.BaseModel]]:
                 """Return a mapping of discriminator values to registered model"""
                 return cls.__DYNAPYDANTIC__.models
 
@@ -134,3 +139,23 @@ class SubclassTrackingModel(pydantic.BaseModel):
         supers = direct_children_of_base_in_mro(cls, SubclassTrackingModel)
         for base in supers:
             base.__DYNAPYDANTIC__.register_model(cls)
+
+    class PydanticAdaptor:
+        """Pydantic type adaptor for SubclassTrackingModel"""
+
+        @staticmethod
+        def __get_pydantic_core_schema__(
+            source_type: ty.Any,  # noqa: ANN401
+            handler: GetCoreSchemaHandler,
+        ) -> core_schema.CoreSchema:
+            """Get the pydantic schema for this type"""
+            if not isinstance(source_type, type) or not issubclass(
+                source_type,
+                SubclassTrackingModel,
+            ):
+                msg = (
+                    f"{source_type} was not a SubclassTrackingModel, "
+                    "so it is incompatible with dynapydantic.Polymorphic"
+                )
+                raise PydanticSchemaGenerationError(msg)
+            return handler(source_type.union())

dynapydantic/tracking_group.py

@@ -1,5 +1,6 @@
 """Base class for dynamic pydantic models"""
 
+import contextlib
 import typing as ty
 
 import pydantic
@@ -27,10 +28,11 @@ def _inject_discriminator_field(
     """
     cls.model_fields[disc_field] = pydantic.fields.FieldInfo(
         default=value,
-        annotation=ty.Literal[value],
+        annotation=ty.Literal[value],  # type: ignore[not-a-type]
         frozen=True,
     )
-    cls.model_rebuild(force=True)
+    with contextlib.suppress(pydantic.errors.PydanticUndefinedAnnotation):
+        cls.model_rebuild(force=True)
     return cls.model_fields[disc_field]
 
 
@@ -95,7 +97,7 @@ class TrackingGroup(pydantic.BaseModel):
             discriminator field must be declared by hand.
         """
 
-        def _wrapper(cls: type[pydantic.BaseModel]) -> None:
+        def _wrapper(cls: type[pydantic.BaseModel]) -> type[pydantic.BaseModel]:
             disc = self.discriminator_field
             field = cls.model_fields.get(self.discriminator_field)
             if field is None:
@@ -169,8 +171,7 @@ class TrackingGroup(pydantic.BaseModel):
             unique default value in the group.
         """
         disc = self.discriminator_field
-        field = cls.model_fields.get(disc)
-        value = field.default
+        value = cls.model_fields[disc].default
         if value == pydantic_core.PydanticUndefined:
             msg = (
                 f"{cls.__name__}.{disc} had no default value, it must "
@@ -187,17 +188,20 @@ class TrackingGroup(pydantic.BaseModel):
 
         self.models[value] = cls
 
-    def union(self, *, annotated: bool = True) -> ty.GenericAlias:
+    def union(self, *, annotated: bool = True) -> ty.Any:  # noqa: ANN401
         """Return the union of all registered models"""
         return (
             ty.Annotated[
                 ty.Union[  # noqa: UP007
-                    tuple(
+                    # This is fundamentally incompatible with static type
+                    # checking, as this is resolved at runtime.
+                    tuple(  # type: ignore[not-a-type]
                         ty.Annotated[x, pydantic.Tag(v)] for v, x in self.models.items()
                     )
                 ],
                 pydantic.Field(discriminator=self.discriminator_field),
             ]
             if annotated
+            # type: ignore[not-a-type]
             else ty.Union[tuple(self.models.values())]  # noqa: UP007
         )

{dynapydantic-0.1.1.dist-info → dynapydantic-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dynapydantic
-Version: 0.1.1
+Version: 0.2.0
 Summary: Dyanmic pydantic models
 Author-email: Philip Salvaggio <salvaggio.philip@gmail.com>
 License-File: LICENSE
@@ -13,23 +13,101 @@ Description-Content-Type: text/markdown
 [![CI](https://github.com/psalvaggio/dynapydantic/actions/workflows/ci.yml/badge.svg)](https://github.com/psalvaggio/dynapydantic/actions/workflows/ci.yml)
 [![Pre-commit](https://github.com/psalvaggio/dynapydantic/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/psalvaggio/dynapydantic/actions/workflows/pre-commit.yml)
 [![Docs](https://img.shields.io/badge/docs-Docs-blue?style=flat-square&logo=github&logoColor=white&link=https://psalvaggio.github.io/dynapydantic/dev/)](https://psalvaggio.github.io/dynapydantic/dev/)
+[![PyPI - Version](https://img.shields.io/pypi/v/dynapydantic)](https://pypi.org/project/dynapydantic/)
+[![Coverage Status](https://coveralls.io/repos/github/psalvaggio/dynapydantic/badge.svg?branch=main)](https://coveralls.io/github/psalvaggio/dynapydantic?branch=main)
+[![Conda Version](https://img.shields.io/conda/v/conda-forge/dynapydantic)](https://anaconda.org/conda-forge/dynapydantic)
 
 
 `dynapydantic` is an extension to the [pydantic](https://pydantic.dev) Python
 package that allow for dynamic tracking of `pydantic.BaseModel` subclasses.
 
-Installation
-==
+## Installation
 This project can be installed via PyPI:
 ```
 pip install dynapydantic
 ```
+or with `conda` via the `conda-forge` channel:
+```
+conda install dynapydantic
+```
+
+
+## Motiviation
+Consider the following simple class setup:
+```python
+import pydantic
+
+class Base(pydantic.BaseModel):
+    pass
+
+class A(Base):
+    field: int
+
+class B(Base):
+    field: str
+
+class Model(pydantic.BaseModel):
+    val: Base
+```
+As expected, we can use `A`'s and `B`'s for `Model.val`:
+```python
+>>> m = Model(val=A(field=1))
+>>> m
+Model(val=A(field=1))
+```
+However, we quickly run into trouble when serializing and validating:
+```python
+>>> m.model_dump()
+{'base': {}}
+>>> m.model_dump(serialize_as_any=True)
+{'val': {'field': 1}}
+>>> Model.model_validate(m.model_dump(serialize_as_any=True))
+Model(val=Base())
+```
+
+Pydantic provides a solution for serialization via `serialize_as_any` (and
+its corresponding field annotation `SerializeAsAny`), but offers no native
+solution for the validation half. Currently, the canonical way of doing this
+is to annotate the field as a discriminated union of all subclasses. Often, a
+single field in the model is chosen as the "discriminator". This library,
+`dynapydantic`, automates this process.
+
+Let's reframe the above problem with `dynapydantic`:
+```python
+import dynapydantic
+import pydantic
+
+class Base(
+    dynapydantic.SubclassTrackingModel,
+    discriminator_field="name",
+    discriminator_value_generator=lambda t: t.__name__,
+):
+    pass
+
+class A(Base):
+    field: int
+
+class B(Base):
+    field: str
+
+class Model(pydantic.BaseModel):
+    val: dynapydantic.Polymorphic[Base]
+```
+Now, the same set of operations works as intended:
+```python
+>>> m = Model(val=A(field=1))
+>>> m
+Model(val=A(field=1, name='A'))
+>>> m.model_dump()
+{'val': {'field': 1, 'name': 'A'}}
+>>> Model.model_validate(m.model_dump())
+Model(val=A(field=1, name='A')
+```
+
 
-Usage
-==
+## How it works
 
-`TrackingGroup`
---
+### `TrackingGroup`
 The core entity in this library is the `dynapydantic.TrackingGroup`:
 ```python
 import typing as ty
@@ -63,26 +141,26 @@ print(Model(field={"name": "B", "a": 5})) # field=B(name='B', a=5)
 
 The `union()` method produces a [discriminated union](https://docs.pydantic.dev/latest/concepts/unions/#discriminated-unions)
 of all registered `pydantic.BaseModel` subclasses. It also accepts an
-`annotated=False` keyword argument to produce a plain `typing.Union` for use in
-type annotations. This union is based on a discriminator field, which was
-configured by the `discriminator_field` argument to `TrackingGroup`. The field
-can be created by hand, as was shown with `B`, or `dynapydantic` will inject it
-for you, as was shown with `A`.
+`annotated=False` keyword argument to produce a plain `typing.Union` for use
+in type annotations, but since this is a runtime-computed union, this will not
+work with static type checkers. This union is based on a discriminator field,
+which was configured by the `discriminator_field` argument to `TrackingGroup`.
+The field can be created by hand, as was shown with `B`, or `dynapydantic`
+will inject it for you, as was shown with `A`.
 
 `TrackingGroup` has a few opt-in features to make it more powerful and easier to use:
 1. `discriminator_value_generator`: This parameter is a optional callback
   function that is called with each class that gets registered and produces a
   default value for the discriminator field. This allows the user to call
-  `register()` without a value for the discriminator. The most common value to
-  pass here would be `lambda cls: cls.__name__`, to use the name of the class as
-  the discriminator value.
+  `register()` without a value for the discriminator. For example, passing:
+  `lambda cls: cls.__name__` would use the name of the class as the
+   discriminator value.
 2. `plugin_entry_point`: This parameter indicates to `dynapydantic` that there
-  might be models to be discovered in other packages. Packages are discovered by
-  the Python entrypoint mechanism. See the `tests/example` directory for an
+  might be models to be discovered in other packages. Packages are discovered
+  by the Python entrypoint mechanism. See the `tests/example` directory for an
   example of how this works.
 
-`SubclassTrackingModel`
---
+### `SubclassTrackingModel`
 The most common use case of this pattern is to automatically register subclasses
 of a given `pydantic.BaseModel`. This is supported via the use of
 `dynapydantic.SubclassTrackingModel`. For example:
@@ -102,7 +180,7 @@ class Base(
     # The TrackingGroup can be specified here like model_config, or passed in
     # kwargs of the class declaration, just like how model_config works with
     # pydantic.BaseModel. If you do it like this, you have to give the tracking
-    # group a name
+    # group a name, whereas using kwargs will generate the name for you.
     # tracking_config: ty.ClassVar[dynapydantic.TrackingGroup] = dynapydantic.TrackingGroup(
     #     name="BaseSubclasses",
     #     discriminator_field="name",
@@ -130,10 +208,15 @@ print(Base.registered_subclasses())
 
 class Model(pydantic.BaseModel):
     """A model that can have any registered Base subclass"""
-    field: Base.union()  # call after all subclasses have been registered
+    field: dynapydantic.Polymorphic[Base]
 
 print(Model(field={"name": "Derived1", "a": 4}))
 # field=Derived1(a=4, name='Derived1')
 print(Model(field={"name": "Custom", "a": 5}))
 # field=Derived2(name='Custom', a=5)
 ```
+It is important to note that the subclasses that are supported are those that
+were defined *prior* to defining the model that uses `dynapydantic.Polymorphic`
+(`Model` in the above example). If you declare additional subclasses afterwards,
+you must call `.model_rebuild(force=True)` on the model that uses the subclass
+union.

dynapydantic-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+dynapydantic/__init__.py,sha256=5i1hbdkJO6fUwO1Sal9CfMv-htg_9MibQemwJH0gFGY,508
+dynapydantic/exceptions.py,sha256=R1wJj-FmKv2JdYSG5HVMkZ0zLyFRKJRuUsBxXGnEjsQ,394
+dynapydantic/polymorphic.py,sha256=qt7m2LBZH5jJzV0Uv8ipO-LUvWDXXPk7rRbAyJ7ghcg,1097
+dynapydantic/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dynapydantic/subclass_tracking_model.py,sha256=-dVA7eAOlzPDLg75S2PNZ5nuVpZmgbwA3drxclKRNyc,5980
+dynapydantic/tracking_group.py,sha256=EdY9REjM_bhW7MAbFuKtm52ZZvQhBDVb_sght12KxAo,7673
+dynapydantic-0.2.0.dist-info/METADATA,sha256=BHEgxpPBCak2VsCIDgYfkij1OJWYxgtEKaMX47mHqUc,7653
+dynapydantic-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+dynapydantic-0.2.0.dist-info/licenses/LICENSE,sha256=I6pwCRw86q30bFjJohgVzXYgCLNCWN3A4jNGJX2iVM4,1073
+dynapydantic-0.2.0.dist-info/RECORD,,

{dynapydantic-0.1.1.dist-info → dynapydantic-0.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any

dynapydantic-0.1.1.dist-info/RECORD

@@ -1,9 +0,0 @@
-dynapydantic/__init__.py,sha256=vIK1dasCAghxjXaUjw8blTHLFwsHZ9L2txuX_8AB7cQ,452
-dynapydantic/exceptions.py,sha256=R1wJj-FmKv2JdYSG5HVMkZ0zLyFRKJRuUsBxXGnEjsQ,394
-dynapydantic/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-dynapydantic/subclass_tracking_model.py,sha256=MmxQgbIusULSEM04R7Yz5kHCHZCeb-vLHenbNctmZPM,4914
-dynapydantic/tracking_group.py,sha256=-rorYSrjHCCV6yeiulA8lI8e9aVrqG-u57UDgD5gZKA,7342
-dynapydantic-0.1.1.dist-info/METADATA,sha256=4b5kR3ImNfPHo7acEQy3LXRAV4nUDFwLBM4v_OjfEqQ,5048
-dynapydantic-0.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dynapydantic-0.1.1.dist-info/licenses/LICENSE,sha256=I6pwCRw86q30bFjJohgVzXYgCLNCWN3A4jNGJX2iVM4,1073
-dynapydantic-0.1.1.dist-info/RECORD,,