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

dynapydantic/subclass_tracking_model.py

@@ -26,7 +26,24 @@ 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,

dynapydantic-0.1.1.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: dynapydantic
+Version: 0.1.1
+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/)
+
+
+`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
+```
+
+Usage
+==
+
+`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. 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.
+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
+    # 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: Base.union()  # call after all subclasses have been registered
+
+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)
+```

{dynapydantic-0.1.0.dist-info → dynapydantic-0.1.1.dist-info}/RECORD

@@ -1,9 +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/subclass_tracking_model.py,sha256=MmxQgbIusULSEM04R7Yz5kHCHZCeb-vLHenbNctmZPM,4914
 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.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,,

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.