dynapydantic 0.1.0__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
@@ -26,19 +30,37 @@ def direct_children_of_base_in_mro(derived: type, base: type) -> list[type]:
 
 
 class SubclassTrackingModel(pydantic.BaseModel):
-    """Subclass-tracking BaseModel"""
+    """Subclass-tracking BaseModel
+
+    This will inject a TrackingGroup into your class and automate the
+    registration of subclasses.
+
+    Inheriting from this class will augment your class with the following
+    members functions:
+    1. registered_subclasses() -> dict[str, type[cls]]:
+        This will return a mapping of discriminator value to the corresponding
+        sublcass. See TrackingGroup.models for details.
+    2. union() -> typing.GenericAlias:
+        This will return an (optionally) annotated subclass union. See
+        TrackingGroup.union() for details.
+    3. load_plugins() -> None:
+        If plugin_entry_point was specified, then this method will load plugin
+        packages to discover additional subclasses. See
+        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
@@ -60,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(
@@ -101,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
 
@@ -117,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.2.0.dist-info/METADATA

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: dynapydantic
+Version: 0.2.0
+Summary: Dyanmic pydantic models
+Author-email: Philip Salvaggio <salvaggio.philip@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# dynapydantic
+
+[![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
+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')
+```
+
+
+## How it works
+
+### `TrackingGroup`
+The core entity in this library is the `dynapydantic.TrackingGroup`:
+```python
+import typing as ty
+
+import dynapydantic
+import pydantic
+
+mygroup = dynapydantic.TrackingGroup(
+    name="mygroup",
+    discriminator_field="name"
+)
+
+@mygroup.register("A")
+class A(pydantic.BaseModel):
+    """A class to be tracked, will be tracked as "A"."""
+    a: int
+
+@mygroup.register()
+class B(pydantic.BaseModel):
+    """Another class, will be tracked as "B"."""
+    name: ty.Literal["B"] = "B"
+    a: int
+
+class Model(pydantic.BaseModel):
+    """A model that can have A or B"""
+    field: mygroup.union()  # call after all subclasses have been registered
+
+print(Model(field={"name": "A", "a": 4})) # field=A(a=4, name='A')
+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, 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. 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
+  example of how this works.
+
+### `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:
+```python
+import typing as ty
+
+import dynapydantic
+import pydantic
+
+class Base(
+    dynapydantic.SubclassTrackingModel,
+    discriminator_field="name",
+    discriminator_value_generator=lambda cls: cls.__name__,
+):
+    """Base model, will track its subclasses"""
+
+    # 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, whereas using kwargs will generate the name for you.
+    # tracking_config: ty.ClassVar[dynapydantic.TrackingGroup] = dynapydantic.TrackingGroup(
+    #     name="BaseSubclasses",
+    #     discriminator_field="name",
+    #     discriminator_value_generator=lambda cls: cls.__name__,
+    # )
+
+
+class Intermediate(Base, exclude_from_union=True):
+    """Subclasses can opt out of being tracked"""
+
+class Derived1(Intermediate):
+    """Non-direct descendants are registered"""
+    a: int
+
+class Derived2(Intermediate):
+    """You can override the value generator if desired"""
+    name: ty.Literal["Custom"] = "Custom"
+    a: int
+
+print(Base.registered_subclasses())
+# {'Derived1': <class '__main__.Derived1'>, 'Custom': <class '__main__.Derived2'>}
+
+# if plugin_entry_point was specificed, load plugin packages
+# Base.load_plugins()
+
+class Model(pydantic.BaseModel):
+    """A model that can have any registered Base subclass"""
+    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.0.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.0.dist-info/METADATA

@@ -1,21 +0,0 @@
-Metadata-Version: 2.4
-Name: dynapydantic
-Version: 0.1.0
-Summary: Dyanmic pydantic models
-Author-email: Philip Salvaggio <salvaggio.philip@gmail.com>
-License-File: LICENSE
-Requires-Python: >=3.10
-Requires-Dist: pydantic>=2.0
-Description-Content-Type: text/markdown
-
-# dynapydantic
-
-[![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)
-
-This is a demonstration about how `pydantic` models can track their subclasses
-and round-trip through serialization, both within the package in which they are
-defined and in other packages via `pluggy`.
-
-This package is not intended for public use yet. It's strictly a
-proof-of-concept.

dynapydantic-0.1.0.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=-pE7gEd3ZWmeJ6QW32a4-g-KIK4yEZ-gfvBUPAv0AnM,4145
-dynapydantic/tracking_group.py,sha256=-rorYSrjHCCV6yeiulA8lI8e9aVrqG-u57UDgD5gZKA,7342
-dynapydantic-0.1.0.dist-info/METADATA,sha256=WWZavxdQLdBBtxOZ0li5JTeNCNtu_QCb573_1s2ytZg,905
-dynapydantic-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dynapydantic-0.1.0.dist-info/licenses/LICENSE,sha256=I6pwCRw86q30bFjJohgVzXYgCLNCWN3A4jNGJX2iVM4,1073
-dynapydantic-0.1.0.dist-info/RECORD,,