dynapydantic 0.1.0__py3-none-any.whl

dynapydantic/__init__.py

@@ -0,0 +1,19 @@
+"""dynapydantic - dynamic tracking of pydantic models"""
+
+from .exceptions import (
+    AmbiguousDiscriminatorValueError,
+    ConfigurationError,
+    Error,
+    RegistrationError,
+)
+from .subclass_tracking_model import SubclassTrackingModel
+from .tracking_group import TrackingGroup
+
+__all__ = [
+    "AmbiguousDiscriminatorValueError",
+    "ConfigurationError",
+    "Error",
+    "RegistrationError",
+    "SubclassTrackingModel",
+    "TrackingGroup",
+]

dynapydantic/exceptions.py

@@ -0,0 +1,17 @@
+"""Custom exception types"""
+
+
+class Error(Exception):
+    """Base class for all dynapydanitc errors"""
+
+
+class RegistrationError(Error):
+    """Occurs when a model cannot be registered"""
+
+
+class AmbiguousDiscriminatorValueError(Error):
+    """Occurs when the discriminator value is ambiguous"""
+
+
+class ConfigurationError(Error):
+    """Occurs when the user misconfigured a tracking setup"""

dynapydantic/subclass_tracking_model.py

@@ -0,0 +1,119 @@
+"""Base class for dynamic pydantic models"""
+
+import typing as ty
+
+import pydantic
+
+from .exceptions import ConfigurationError
+from .tracking_group import TrackingGroup
+
+
+def direct_children_of_base_in_mro(derived: type, base: type) -> list[type]:
+    """Find all classes in derived's MRO that are direct subclasses of base.
+
+    Parameters
+    ----------
+    derived
+        The class whose MRO is being examined.
+    base
+        The base class to find direct subclasses of.
+
+    Returns
+    -------
+    Classes in derived's MRO that are direct subclasses of base.
+    """
+    return [cls for cls in derived.__mro__ if cls is not base and base in cls.__bases__]
+
+
+class SubclassTrackingModel(pydantic.BaseModel):
+    """Subclass-tracking BaseModel"""
+
+    def __init_subclass__(
+        cls,
+        *args,
+        exclude_from_union: bool | None = None,
+        **kwargs,
+    ) -> None:
+        """Subclass hook"""
+        # Intercept any kwargs that are intended for TrackingGroup
+        super().__pydantic_init_subclass__(
+            *args,
+            **{k: v for k, v in kwargs.items() if k not in TrackingGroup.model_fields},
+        )
+
+    @classmethod
+    def __pydantic_init_subclass__(
+        cls,
+        *args,
+        exclude_from_union: bool | None = None,
+        **kwargs,
+    ) -> None:
+        """Pydantic subclass hook"""
+        if SubclassTrackingModel in cls.__bases__:
+            # Intercept any kwargs that are intended for TrackingGroup
+            super().__pydantic_init_subclass__(
+                *args,
+                **{
+                    k: v
+                    for k, v in kwargs.items()
+                    if k not in TrackingGroup.model_fields
+                },
+            )
+
+            if isinstance(getattr(cls, "tracking_config", None), TrackingGroup):
+                cls.__DYNAPYDANTIC__ = cls.tracking_config
+            else:
+                try:
+                    cls.__DYNAPYDANTIC__: TrackingGroup = TrackingGroup.model_validate(
+                        {"name": f"{cls.__name__}-subclasses"} | kwargs,
+                    )
+                except pydantic.ValidationError as e:
+                    msg = (
+                        "SubclassTrackingModel subclasses must either have a "
+                        "tracking_config: ClassVar[dynapydantic.TrackingGroup] "
+                        "member or pass kwargs sufficient to construct a "
+                        "dynapydantic.TrackingGroup in the class declaration. "
+                        "The latter approach produced the following "
+                        f"ValidationError:\n{e}"
+                    )
+                    raise ConfigurationError(msg) from e
+
+            # Promote the tracking group's methods to the parent class
+            if cls.__DYNAPYDANTIC__.plugin_entry_point is not None:
+
+                def _load_plugins() -> None:
+                    """Load plugins to register more models"""
+                    cls.__DYNAPYDANTIC__.load_plugins()
+
+                cls.load_plugins = staticmethod(_load_plugins)
+
+            def _union(*, annotated: bool = True) -> ty.GenericAlias:
+                """Get the union of all tracked subclasses
+
+                Parameters
+                ----------
+                annotated
+                    Whether this should be an annotated union for usage as a
+                    pydantic field annotation, or a plain typing.Union for a
+                    regular type annotation.
+                """
+                return cls.__DYNAPYDANTIC__.union(annotated=annotated)
+
+            cls.union = staticmethod(_union)
+
+            def _subclasses() -> dict[str, type[cls]]:
+                """Return a mapping of discriminator values to registered model"""
+                return cls.__DYNAPYDANTIC__.models
+
+            cls.registered_subclasses = staticmethod(_subclasses)
+
+            return
+
+        super().__pydantic_init_subclass__(*args, **kwargs)
+
+        if exclude_from_union:
+            return
+
+        supers = direct_children_of_base_in_mro(cls, SubclassTrackingModel)
+        for base in supers:
+            base.__DYNAPYDANTIC__.register_model(cls)

dynapydantic/tracking_group.py

@@ -0,0 +1,203 @@
+"""Base class for dynamic pydantic models"""
+
+import typing as ty
+
+import pydantic
+import pydantic.fields
+import pydantic_core
+
+from .exceptions import AmbiguousDiscriminatorValueError, RegistrationError
+
+
+def _inject_discriminator_field(
+    cls: type[pydantic.BaseModel],
+    disc_field: str,
+    value: str,
+) -> pydantic.fields.FieldInfo:
+    """Injects the discriminator field into the given model
+
+    Parameters
+    ----------
+    cls
+        The BaseModel subclass
+    disc_field
+        Name of the discriminator field
+    value
+        Value of the discriminator field
+    """
+    cls.model_fields[disc_field] = pydantic.fields.FieldInfo(
+        default=value,
+        annotation=ty.Literal[value],
+        frozen=True,
+    )
+    cls.model_rebuild(force=True)
+    return cls.model_fields[disc_field]
+
+
+class TrackingGroup(pydantic.BaseModel):
+    """Tracker for pydantic models"""
+
+    name: str = pydantic.Field(
+        description=(
+            "Name of the tracking group. This is for human display, so it "
+            "doesn't technically need to be globally unique, but it should be "
+            "meaningfully named, as it will be used in error messages."
+        ),
+    )
+    discriminator_field: str = pydantic.Field(
+        description="Name of the discriminator field",
+    )
+    plugin_entry_point: str | None = pydantic.Field(
+        None,
+        description=(
+            "If given, then plugins packages will be supported through this "
+            "Python entrypoint. The entrypoint can either be a function, "
+            "which will be called, or simply a module, which will be "
+            "imported. In either case, models found along the import path of "
+            "the entrypoint will be registered. If the entrypoint is a "
+            "function, additional models may be declared in the function."
+        ),
+    )
+    discriminator_value_generator: ty.Callable[[type], str] | None = pydantic.Field(
+        None,
+        description=(
+            "A callable that produces default values for the discriminator field"
+        ),
+    )
+    models: dict[str, type[pydantic.BaseModel]] = pydantic.Field(
+        {},
+        description="The tracked models",
+    )
+
+    def load_plugins(self) -> None:
+        """Load plugins to discover/register additional models"""
+        if self.plugin_entry_point is None:
+            return
+
+        from importlib.metadata import entry_points  # noqa: PLC0415
+
+        for ep in entry_points().select(group=self.plugin_entry_point):
+            plugin = ep.load()
+            if callable(plugin):
+                plugin()
+
+    def register(
+        self,
+        discriminator_value: str | None = None,
+    ) -> ty.Callable[[type], type]:
+        """Register a model into this group (decorator)
+
+        Parameters
+        ----------
+        discriminator_value
+            Value for the discriminator field. If not given, then
+            discriminator_value_generator must be non-None or the
+            discriminator field must be declared by hand.
+        """
+
+        def _wrapper(cls: type[pydantic.BaseModel]) -> None:
+            disc = self.discriminator_field
+            field = cls.model_fields.get(self.discriminator_field)
+            if field is None:
+                if discriminator_value is not None:
+                    _inject_discriminator_field(cls, disc, discriminator_value)
+                elif self.discriminator_value_generator is not None:
+                    _inject_discriminator_field(
+                        cls,
+                        disc,
+                        self.discriminator_value_generator(cls),
+                    )
+                else:
+                    msg = (
+                        f"unable to determine a discriminator value for "
+                        f'{cls.__name__} in tracking group "{self.name}". No '
+                        "value was passed to register(), "
+                        "discriminator_value_generator was None and the "
+                        f'"{disc}" field was not defined.'
+                    )
+                    raise RegistrationError(msg)
+            elif (
+                discriminator_value is not None and field.default != discriminator_value
+            ):
+                msg = (
+                    f"the discriminator value for {cls.__name__} was "
+                    f'ambiguous, it was set to "{discriminator_value}" via '
+                    f'register() and "{field.default}" via the discriminator '
+                    f"field ({self.discriminator_field})."
+                )
+                raise AmbiguousDiscriminatorValueError(msg)
+
+            self._register_with_discriminator_field(cls)
+            return cls
+
+        return _wrapper
+
+    def register_model(self, cls: type[pydantic.BaseModel]) -> None:
+        """Register the given model into this group
+
+        Parameters
+        ----------
+        cls
+            The model to register
+        """
+        disc = self.discriminator_field
+        if cls.model_fields.get(self.discriminator_field) is None:
+            if self.discriminator_value_generator is not None:
+                _inject_discriminator_field(
+                    cls,
+                    disc,
+                    self.discriminator_value_generator(cls),
+                )
+            else:
+                msg = (
+                    f"unable to determine a discriminator value for "
+                    f'{cls.__name__} in tracking group "{self.name}", '
+                    "discriminator_value_generator was None and the "
+                    f'"{disc}" field was not defined.'
+                )
+                raise RegistrationError(msg)
+
+        self._register_with_discriminator_field(cls)
+
+    def _register_with_discriminator_field(self, cls: type[pydantic.BaseModel]) -> None:
+        """Register the model with the default of the discriminator field
+
+        Parameters
+        ----------
+        cls
+            The class to register, must have the disciminator field set with a
+            unique default value in the group.
+        """
+        disc = self.discriminator_field
+        field = cls.model_fields.get(disc)
+        value = field.default
+        if value == pydantic_core.PydanticUndefined:
+            msg = (
+                f"{cls.__name__}.{disc} had no default value, it must "
+                "have one which is unique among all tracked models."
+            )
+            raise RegistrationError(msg)
+
+        if (other := self.models.get(value)) is not None and other is not cls:
+            msg = (
+                f'Cannot register {cls.__name__} under the "{value}" '
+                f"identifier, which is already in use by {other.__name__}."
+            )
+            raise RegistrationError(msg)
+
+        self.models[value] = cls
+
+    def union(self, *, annotated: bool = True) -> ty.GenericAlias:
+        """Return the union of all registered models"""
+        return (
+            ty.Annotated[
+                ty.Union[  # noqa: UP007
+                    tuple(
+                        ty.Annotated[x, pydantic.Tag(v)] for v, x in self.models.items()
+                    )
+                ],
+                pydantic.Field(discriminator=self.discriminator_field),
+            ]
+            if annotated
+            else ty.Union[tuple(self.models.values())]  # noqa: UP007
+        )

dynapydantic-0.1.0.dist-info/METADATA

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,9 @@
+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,,

dynapydantic-0.1.0.dist-info/WHEEL

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

dynapydantic-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Philip Salvaggio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.