plugantic 0.1.0__py3-none-any.whl

plugantic/__init__.py

@@ -0,0 +1,3 @@
+"""Plugantic: Simplify extendable composition with Pydantic."""
+from ._consts import version as __version__
+from .plugin import PluginModel, PluginDowncastHandler

plugantic/_consts.py

@@ -0,0 +1,2 @@
+# Single source of truth for information needed at runtime and compile-time (i.e. version)
+version = "0.1.0"

plugantic/_helpers.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing_extensions import TypeVar, Iterable, TypeGuard, TypeAliasType, Callable
+from itertools import combinations, product
+
+T = TypeVar("T")
+RecursiveList = TypeAliasType("RecursiveList", Iterable["RecursiveListItem[T]"], type_params=(T,))
+RecursiveListItem = TypeAliasType("RecursiveListItem", T | RecursiveList[T], type_params=(T,))
+
+def recursive_linear(items: RecursiveList[T], typeguard: Callable[[RecursiveListItem[T]], TypeGuard[T]], join: Callable[[Iterable[T]], T]) -> Iterable[T]:
+    result = []
+    for item in items:
+        if typeguard(item):
+            result.append(item)
+        else:
+            result.extend(recursive_powerset(item, typeguard, join))
+    return result
+
+def recursive_powerset(items: RecursiveList[T], typeguard: Callable[[RecursiveListItem[T]], TypeGuard[T]], join: Callable[[Iterable[T]], T]) -> Iterable[T]:
+    arbitrary_subset = []
+    subsets = []
+    for downcast in items:
+        if typeguard(downcast):
+            arbitrary_subset.append(downcast)
+        else:
+            linear_subset = recursive_linear(downcast, typeguard, join)
+            linear_subset = ((), *((d,) for d in linear_subset))
+            subsets.append(linear_subset)
+
+    arbitrary_powerset = [()]
+    for l in range(1, len(arbitrary_subset) + 1):
+        arbitrary_powerset.extend(combinations(arbitrary_subset, l))
+    subsets.append(arbitrary_powerset)
+
+    powerset = []
+    for subset in product(*subsets):
+        callbacks = [c for s in subset for c in s]
+        if not callbacks:
+            continue
+        powerset.append(join(callbacks))
+
+    return powerset

plugantic/_types.py

@@ -0,0 +1,6 @@
+class _InjectBase:
+    def __init__(self, *bases: type):
+        self._bases = bases
+    def __mro_entries__(self, bases):
+        return tuple(base for base in self._bases if base not in bases)
+_VanishBase = _InjectBase()

plugantic/plugin.py

@@ -0,0 +1,409 @@
+from __future__ import annotations
+
+from typing_extensions import ClassVar, Iterable, Type, Union, Self, Literal, Any, Callable, Generic, TypeVar, TypeVarTuple, Unpack, TypeAliasType, TypedDict, get_origin, get_args, TYPE_CHECKING
+from pydantic import BaseModel, GetCoreSchemaHandler, model_validator
+from pydantic_core.core_schema import tagged_union_schema
+
+from ._helpers import recursive_powerset, recursive_linear, RecursiveList
+from ._types import _VanishBase
+
+Ts = TypeVarTuple("Ts")
+
+if TYPE_CHECKING:
+    _plugin_base = Generic[Unpack[Ts]]
+else:
+    _plugin_base = _VanishBase
+
+class PluganticConfig(TypedDict):
+    varname_type: str|None = None
+    value: str|None = None
+    supported_features: set[Any]|tuple[Any, ...]=()
+    required_features: _RequiresFeatureSpec|None=None
+    auto_downcasts: PluginDowncastCallbacks|None=None
+
+class PluginModel(BaseModel, _plugin_base):
+    __plugantic_varname_type__: ClassVar[str] = "type"
+    __plugantic_supported_features__: ClassVar[set[Any]] = set()
+    __plugantic_required_features__: ClassVar[_RequiresFeatureSpec|None] = None
+    __plugantic_inherit_features__: ClassVar[bool] = True
+    __plugantic_generic_supertype__: ClassVar[type|None] = None
+    __plugantic_auto_downcasts__: ClassVar[set[Self]|None] = None
+    __plugantic_auto_downcast_callbacks__: ClassVar[PluginDowncastCallbacks|None] = None
+    __plugantic_was_schema_created__: ClassVar[bool] = False
+    __plugantic_check_schema_usage__: ClassVar[bool] = True
+
+    plugantic_config: ClassVar[PluganticConfig|None] = None
+
+    def __init__(self, *args, **kwargs):
+        declared_type = self._get_declared_type()
+        if declared_type:
+            kwargs = {
+                self.__plugantic_varname_type__: declared_type,
+                **kwargs
+            }
+        super().__init__(*args, **kwargs)
+
+    def __class_getitem__(cls, args):
+        if not isinstance(args, tuple):
+            args = (args,)
+        requires_features, supports_features = cls._unpack_features(*args)
+        return type(cls.__name__, (cls,), {}, supported_features=supports_features, required_features=requires_features, _plugantic_generic_supertype=cls)
+
+    def __init_subclass__(cls, *,
+        varname_type: str|None=None,
+        value: str|None=None,
+        supported_features: set[Any]|tuple[Any, ...]=(),
+        required_features: _RequiresFeatureSpec|None=None,
+        auto_downcasts: PluginDowncastCallbacks|None=None,
+        _plugantic_generic_supertype: type|None=None,
+        _plugantic_downcast_callback: SimplePluginDowncastCallback|None=None,
+    **kwargs):
+        if cls._check_plugantic_schema_usage():
+            raise ValueError(f"Schema of {cls.__name__} has already been created. Creating new subclasses after the schema has been created will lead to undefined behaviour.")
+
+        super().__init_subclass__(**kwargs)
+
+        if cls.plugantic_config:
+            varname_type = cls.plugantic_config.get("varname_type", None) or varname_type
+            value = cls.plugantic_config.get("value", None) or value
+            supported_features = cls.plugantic_config.get("supported_features", ()) or supported_features
+            required_features = cls.plugantic_config.get("required_features", None) or required_features
+            auto_downcasts = cls.plugantic_config.get("auto_downcasts", None) or auto_downcasts
+
+        cls.__plugantic_was_schema_created__ = False
+
+        cls.__plugantic_generic_supertype__ = _plugantic_generic_supertype
+        cls.__plugantic_required_features__ = required_features
+        cls.__plugantic_auto_downcasts__ = None
+
+        supported_features = set(supported_features)
+        if cls.__plugantic_inherit_features__:
+            supported_features = cls.__plugantic_supported_features__ | supported_features
+
+        cls.__plugantic_supported_features__ = supported_features
+
+        if varname_type is not None:
+            cls.__plugantic_varname_type__ = varname_type
+
+        if value is not None:
+            cls._create_annotation(cls.__plugantic_varname_type__, Literal[value])
+        
+        cls._ensure_varname_default()
+
+        if _plugantic_downcast_callback:
+            _plugantic_downcast_callback(PluginDowncastHandler(cls))
+
+        cls.__plugantic_auto_downcast_callbacks__ = auto_downcasts
+
+    @classmethod
+    def _ensure_downcasts(cls):
+        if not cls.__plugantic_auto_downcast_callbacks__:
+            return
+
+        callbacks = cls.__plugantic_auto_downcast_callbacks__
+        cls.__plugantic_auto_downcast_callbacks__ = None
+
+        cls.__plugantic_auto_downcasts__ = cls._create_downcasts(callbacks)
+
+    @classmethod
+    def _create_downcasts(cls, downcast_callbacks: PluginDowncastCallbacks):
+        downcasts = set()
+        for callback in cls._create_powerset_downcast_callbacks(downcast_callbacks):
+            subcls = type(cls.__name__, (cls,), {}, _plugantic_downcast_callback=callback)
+            downcasts.add(subcls)
+        return downcasts
+
+    @classmethod
+    def _create_linear_downcast_callbacks(cls, downcasts: PluginDowncastCallbacks):
+        return recursive_linear(downcasts, callable, cls._create_joined_downcast_callback)
+
+    @classmethod
+    def _create_powerset_downcast_callbacks(cls, downcasts: PluginDowncastCallbacks):
+        return recursive_powerset(downcasts, callable, cls._create_joined_downcast_callback)
+
+    @classmethod
+    def _create_joined_downcast_callback(cls, downcasts: PluginDowncastCallbacks) -> SimplePluginDowncastCallback:
+        def callback(handler: PluginDowncastHandler):
+            for downcast in downcasts:
+                downcast(handler)
+
+        return callback
+
+    @classmethod
+    def _unpack_features(cls, *features: Any) -> tuple[_RequiresFeatureSpec, set[Any]]:
+        requires_all_features = set()
+        supports_features = set()
+
+        for feature in features:
+            if isinstance(feature, _RequiresFeatureSpec):
+                requires_all_features.add(feature)
+                continue
+            
+            _any_features = set()
+            if get_origin(feature) is Union:
+                for sub_feature in get_args(feature):
+                    _any_features.update(cls._unwrap_feature(sub_feature))
+            if get_origin(feature) is Literal:
+                _any_features.update(get_args(feature))
+            
+            if len(_any_features) == 1:
+                feature = _any_features.pop()
+
+            if _any_features:
+                requires_all_features.add(_RequiresAnyFeature(any_of=_any_features))
+                supports_features.update(_any_features)
+                continue
+
+            requires_all_features.add(feature)
+            supports_features.add(feature)
+
+        return _RequiresAllFeatures(all_of=requires_all_features), supports_features
+
+    @classmethod
+    def _unwrap_feature(cls, feature: Any) -> tuple[Any]:
+        if get_origin(feature) is Literal:
+            return get_args(feature)
+        return (feature,)
+
+    @classmethod
+    def _create_subclass(cls):
+        return type(cls.__name__, (cls,), {})
+
+    @classmethod
+    def _create_annotation(cls, name: str, value: Any):
+        """
+        Create an annotation of value for the given name as a member variable of the class
+        e.g. name="type" value=Literal["test"] -> `type: Literal["test"]`
+        """
+        if not hasattr(cls, "__annotations__"):
+            cls.__annotations__ = {}
+        if not cls.__annotations__.get(name, None):
+            cls.__annotations__[name] = value
+
+    _NoValue = object()
+    @classmethod
+    def _create_field_default(cls, name: str, value: Any):
+        actual_value = getattr(cls, name, cls._NoValue)
+        if actual_value == value:
+            return
+        setattr(cls, name, value)
+
+    @classmethod
+    def _ensure_varname_default(cls):
+        """
+        Ensure that the discriminator name is associated with a value so that creating a direct instance does not require passing the value again
+        e.g.:
+        class SomeConfig(PluginModel):
+            type: Literal["something"] # will be transformed to the equivalent of `type: Literal["something"] = "something"`
+
+        SomeConfig() # works, because there is a default value set
+        SomeConfig(type="something") # works
+        SomeConfig(type="else") # fails
+        """
+        declared_type = cls._get_declared_type()
+        if not declared_type:
+            return
+        cls._create_field_default(cls.__plugantic_varname_type__, declared_type)
+
+    @classmethod
+    def _get_declared_type(cls) -> str|None:
+        """Get the value declared for the discriminator name (e.g. `type: Literal["something"]` -> "something")"""
+        field = getattr(cls, "__annotations__", {}).get(cls.__plugantic_varname_type__, None)
+
+        if (not field) and hasattr(cls, "model_fields"):
+            field = cls.model_fields.get(cls.__plugantic_varname_type__, None)
+            if field:
+                field = field.annotation
+
+        if get_origin(field) is Literal:
+            return get_args(field)[0]
+
+        return None
+
+    @classmethod
+    def _supports_features(cls, features: _RequiresFeatureSpec|None) -> bool:
+        if features is None:
+            return True
+
+        return features.applies_to(cls.__plugantic_supported_features__)
+
+    @classmethod
+    def _is_valid_subclass(cls, filter: _PluginFeatureFilter) -> bool:
+        if cls.__plugantic_generic_supertype__:
+            return False
+
+        if not cls._supports_features(filter.required_features):
+            return False
+
+        if cls._get_declared_type():
+            return True
+
+        return False
+
+    @classmethod
+    def _select_optimal_subclass(cls, subclasses: Iterable[Self], filter: _PluginFeatureFilter) -> Self|None:
+        """
+        Select the optimal subclass from a list of subclasses given a feature filter
+
+        This is primarily used to select the least restrictive subclass for automatic downcasting
+        We assume that the subclass with the fewest changes (i.e. with the fewest added features) is the least restrictive.
+        Thus, the optimal subclass is the one that has the fewest overall features. 
+        In the future this might be changed to the subclass with the fewest differences between the subclass and the base class.
+        """
+        optimal = None
+        for subcls in subclasses:
+            if optimal is None:
+                optimal = subcls
+            
+            if len(subcls.__plugantic_supported_features__) < len(optimal.__plugantic_supported_features__):
+                optimal = subcls
+
+        return optimal
+
+    @classmethod
+    def _get_all_subclasses(cls):
+        cls._ensure_downcasts()
+        if not cls.__plugantic_auto_downcasts__:
+            return cls.__subclasses__()
+
+        return [subcls for subcls in cls.__subclasses__() if not subcls in cls.__plugantic_auto_downcasts__]
+
+    @classmethod
+    def _get_valid_self_class(cls, filter: _PluginFeatureFilter) -> Type[Self]|None:
+        if cls._is_valid_subclass(filter):
+            return cls
+
+        cls._ensure_downcasts()
+        if not cls.__plugantic_auto_downcasts__:
+            return None
+
+        return cls._select_optimal_subclass(cls._get_valid_downcast_subclasses(filter), filter)
+
+    @classmethod
+    def _get_valid_downcast_subclasses(cls, filter: _PluginFeatureFilter) -> Iterable[Type[Self]]:
+        return [subcls for subcls in cls.__plugantic_auto_downcasts__ if subcls._is_valid_subclass(filter)]
+
+    @classmethod
+    def _get_valid_subclasses(cls, filter: _PluginFeatureFilter) -> Iterable[Type[Self]]:
+        valid = []
+
+        valid_self_class = cls._get_valid_self_class(filter)
+        if valid_self_class:
+            valid.append(valid_self_class)
+
+        for subcls in cls._get_all_subclasses():
+            valid.extend(subcls._get_valid_subclasses(filter))
+
+        return valid
+
+    @classmethod
+    def _as_tagged_union(cls, handler: GetCoreSchemaHandler, filter: _PluginFeatureFilter):
+        subclasses = set(cls._get_valid_subclasses(filter))
+        if len(subclasses) == 1:
+            return handler(subclasses.pop())
+
+        choices = {subcls._get_declared_type(): handler(subcls) for subcls in subclasses}
+        return tagged_union_schema(choices, discriminator=cls.__plugantic_varname_type__)
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source, handler: GetCoreSchemaHandler):
+        _required_features = None
+        _base = cls
+
+        if cls.__plugantic_generic_supertype__:
+            _required_features = cls.__plugantic_required_features__
+            _base = cls.__plugantic_generic_supertype__
+
+        _filter = _PluginFeatureFilter(required_features=_required_features)
+
+        cls.__plugantic_was_schema_created__ = True
+
+        return _base._as_tagged_union(handler, _filter)
+
+    @classmethod
+    def _check_plugantic_schema_usage(cls) -> bool:
+        """
+        Return True if the schema of this class or any of its superclasses has been created
+        This check can be circumvented by setting __plugantic_check_schema_usage__ to False
+        """
+        if not cls.__plugantic_check_schema_usage__:
+            return False
+        for supcls in cls.mro():
+            if not issubclass(supcls, PluginModel):
+                continue
+            if supcls.__plugantic_was_schema_created__:
+                return True
+        return False
+
+    @model_validator(mode="wrap")
+    def _try_downcast(cls, data, handler):
+        if isinstance(data, cls):
+            pass
+        elif cls.__plugantic_generic_supertype__ and isinstance(data, cls.__plugantic_generic_supertype__):
+            try:
+                data = cls(**data.model_dump())
+            except Exception as e:
+                raise ValueError(f"Failed to downcast given {repr(data)} to required {cls.__name__}; please provide the required config directly") from e
+        return handler(data)
+    
+    model_config = {"defer_build": True}
+
+class _RequiresFeatureSpec:
+    def applies_to(self, supported_features: set[Any]) -> bool:
+        ...
+
+    def _split_features(self, features: set[Any]) -> tuple[set[Any], set[Self]]:
+        feats, specs = set(), set()
+        for feature in features:
+            if isinstance(feature, _RequiresFeatureSpec):
+                specs.add(feature)
+            else:
+                feats.add(feature)
+        return feats, specs
+
+class _RequiresAnyFeature(_RequiresFeatureSpec):
+    def __init__(self, *, any_of: set[Any]):
+        self.any_of_features, self.any_of_specs = self._split_features(any_of)
+    
+    def applies_to(self, supported_features) -> bool:
+        return (not self.any_of_features.isdisjoint(supported_features)) or any(spec.applies_to(supported_features) for spec in self.any_of_specs)
+
+class _RequiresAllFeatures(_RequiresFeatureSpec):
+    def __init__(self, *, all_of: set[Any]):
+        self.all_of_features, self.all_of_specs = self._split_features(all_of)
+    
+    def applies_to(self, supported_features) -> bool:
+        return self.all_of_features.issubset(supported_features) and all(spec.applies_to(supported_features) for spec in self.all_of_specs)
+
+class _PluginFeatureFilter:
+    def __init__(self, *, required_features: _RequiresFeatureSpec|None=None):
+        self.required_features = required_features
+
+T = TypeVar("T", bound=PluginModel)
+
+class PluginDowncastHandler(Generic[T]):
+    def __init__(self, wraps: Type[T]):
+        self.wraps = wraps
+
+    def get_raw_type(self) -> Type[T]:
+        return self.wraps
+
+    def enable_feature(self, feature: Any):
+        features = self.wraps._unwrap_feature(feature)
+        self.wraps.__plugantic_supported_features__.update(features)
+    
+    def disable_feature(self, feature: Any):
+        for item in self.wraps._unwrap_feature(feature):
+            self.wraps.__plugantic_supported_features__.discard(item)
+
+    def set_field_annotation(self, name: str, annotation: Type):
+        self.wraps._create_annotation(name, annotation)
+
+    def set_field_default(self, name: str, value: Any):
+        self.wraps._create_field_default(name, value)
+
+    def remove_field_default(self, name: str):
+        self.set_field_default(name, ...)
+
+SimplePluginDowncastCallback = TypeAliasType("SimplePluginDowncastCallback", Callable[[PluginDowncastHandler[T]], None], type_params=(T,))
+PluginDowncastCallbacks = TypeAliasType("PluginDowncastCallbacks", RecursiveList[SimplePluginDowncastCallback[T]], type_params=(T,))

plugantic-0.1.0.dist-info/METADATA

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: plugantic
+Version: 0.1.0
+Summary: Simplified extendable composition with pydantic
+Author-email: Martin Kunze <martin@martinkunze.com>
+Project-URL: Homepage, https://github.com/martinkunze/plugantic
+Project-URL: Documentation, https://github.com/martinkunze/plugantic/blob/main/README.md
+Project-URL: Source, https://github.com/martinkunze/plugantic
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic
+Requires-Dist: propert
+Requires-Dist: typing-extensions
+Dynamic: license-file
+
+# 🧩 Plugantic - Simplified extendable composition with pydantic
+
+## 🤔 Why use `plugantic`?
+
+You may have learned that you should avoid inheritance in favor of composition. When using pydantic you can achieve that by using something like the following:
+
+```python
+# Declare a base config
+class OutputConfig(BaseModel):
+    mode: str
+    def print(self): ...
+
+# Declare all implementations of the base config
+class TextConfig(OutputConfig):
+    mode: Literal["text"] = "text"
+    text: str
+    def print(self):
+        print(self.text)
+
+class NumberConfig(OutputConfig):
+    mode: Literal["number"] = "number"
+    number: float
+    precision: int = 2
+    def print(self):
+        print(f"{self.number:.{self.precision}f}")
+
+# Define a union type of all implementations
+AllOutputConfigs = Annotated[Union[
+    TextConfig,
+    NumberConfig,
+], Field(discriminator="mode")]
+
+# Use the union type in your model
+class CommonConfig(BaseModel):
+    output: AllOutputConfigs
+
+...
+
+CommonConfig.model_validate({"output": {
+    "mode": "text",
+    "text": "Hello World"
+}})
+```
+
+Whilst this works, there are multiple issues and annoyances with that approach:
+ - **Hard to maintain**: you need to declare a type union and update it with every change
+ - **Not extensible**: adding a different config afterwards would required to update the `AllOutputConfigs` type and all of the objects using it
+ - **Redundant definition** of the discriminator field (i.e. `Literal[<x>] = <x>`)
+
+This library solves all of these issues (and more), so you can just write
+
+```python
+from plugantic import PluginModel
+
+class OutputConfig(PluginModel):
+    mode: str
+    def print(self): ...
+
+class TextConfig(OutputConfig):
+    # No redundant "text" definition here!
+    mode: Literal["text"]
+    text: str
+    def print(self):
+        print(self.text)
+
+class NumberConfig(OutputConfig):
+    # No redundant definition here either!
+    mode: Literal["number"]
+    number: float
+    precision: int = 2
+    def print(self):
+        print(f"{self.number:.{self.precision}f}")
+
+# No need to define a union type or a discriminator field!
+# You can just use the base type as a field type!
+class CommonConfig(BaseModel):
+    output: OutputConfig
+
+# You can even add new configs after the fact!
+class BytesConfig(OutputConfig):
+    mode: Literal["bytes"]
+    content: bytes
+    def print(self):
+        print(self.content.decode("utf-8"))
+
+...
+
+# The actual type is only evaluated when it is actually needed!
+CommonConfig.model_validate({"output": {
+    "mode": "text",
+    "text": "Hello World"
+}})
+```
+
+## ✨ Features
+
+### 🌀 Automatic Downcasts
+
+Let's say you have the following logger:
+
+```python
+FeatureNewPage = Literal["newline"]
+
+class LoggerBase(PluginModel):
+    def log_line(self, line: str, new_page: bool=False): ...
+
+class LoggerStdout(LoggerBase, value="stdout"):
+    new_page_token: str|None = None
+    def log_line(self, line: str, new_page: bool=False):
+        if new_page:
+            if not self.new_page_token:
+                raise ValueError("new_page_token is not set")
+            print(self.new_page_token)
+        print(line)
+
+class Component1(BaseModel):
+    logger: LoggerBase
+
+class Component2(BaseModel):
+    logger: LoggerBase[FeatureNewPage]
+```
+
+then users could not use `Component2` with `LoggerStdout` as it does not support the `FeatureNewPage` feature, even thoudh `LoggerStdout` would support it, if `new_page_token: str` was enforced.
+
+Conventionally, this would require the developer to create two classes (i.e. `LoggerStdout` and `LoggerStdoutNewPage`) and then include either one in the final annotated union depending on if the component requires the new page functionality.
+
+With `plugantic`, you can automatically create subtypes that are more strict than the base type and they will be automatically validated and downcast when using the model:
+
+```python
+def ensure_new_page_feature(handler: PluginDowncastHandler):
+    handler.enable_feature(FeatureNewPage)
+    handler.set_field_annotation("new_page_token", str)
+    handler.remove_field_default("new_page_token")
+
+class LoggerBase(PluginModel, value="stdout", auto_downcasts=(ensure_new_page_feature,)):
+    new_page_token: str|None = None
+    def log_line(self, line: str, new_page: bool=False):
+        if new_page:
+            if not self.new_page_token:
+                raise ValueError("new_page_token is not set")
+            print(self.new_page_token)
+        print(line)
+```
+
+By declaring multiple callbacks in `auto_downcasts`, you can create a superset of all possible downcasts and `plugantic` will automatically select the least strict depending on which features you require.
+
+
+### 🔌 Extensibility
+
+You can add new plugins after the fact!
+
+To do so, you will have to ensure one of the following prerequisites:
+
+**1. Use `ForwardRef`s**
+
+```python
+from __future__ import annotations # either by importing annotations from the __future__ package
+
+class BaseConfig(PluginModel):
+    ...
+
+...
+
+class CommonConfig1(BaseModel):
+    config: BaseConfig
+
+class CommonConfig2(BaseModel):
+    config: "BaseConfig" # or by using a string as the type annotation
+
+
+class NumberConfig(BaseConfig): # now you can declare new types after the fact (but before using/validating the models)!
+    ...
+```
+
+**2. Enable `defer_build`**
+
+```python
+class BaseConfig(PluginModel):
+    ...
+
+class CommonConfig(BaseModel):
+    config: BaseConfig
+
+    model_config = {"defer_build": True}
+```
+
+### 📝 Type Checker Friendliness
+
+The type checker can infer the type of the plugin model, so you don't need to define a union type or a discriminator field!
+Everything except for the annotated union is based on pydantic and as such can be used like before as type checkers are already familiar with pydantic.
+
+## 🏛️ Leading Principles
+
+### Composition over Inheritance
+
+Composition is preferred over inheritance.
+
+### Dont repeat yourself (DRY)
+
+Having to inherit from a base class just to then declare an annotated union or having to declare a discriminator field both as an annotation and with a default being the same as the annotation is a violation of the DRY principle. This library tackles all of these issues at once.
+
+### Be conservative in what you send and liberal in what you accept
+
+Using automatic downcasts, this library allows developers to accept every possible value when validating a model.
+
+
+## 💻 Development
+
+### 📁 Code structure
+
+The code is structured as follows:
+
+- `src/plugantic/` contains the source code
+- `tests/` contains the tests
+
+Most of the actual logic is in the `src/plugantic/plugin.py` file.
+
+### 📦 Distribution
+
+To build the package, you can do the following:
+
+```bash
+uv run build
+```
+    
+<details>
+<summary>Publishing</summary>
+
+> 💡 This section is primarily relevant for the maintainers of this package (me), as it requires permission to push a package to the `plugantic` repository on PyPI.
+
+```bash
+uv run publish --token <token>
+```
+
+</details>
+
+### 🎯 Tests
+
+To run all tests, you can do the following:
+
+```bash
+uv run pytest
+```

plugantic-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+plugantic/__init__.py,sha256=MTKfwiTeL6NXzc5BFXzOW-9h1g3JdMvtv-fWjvar82g,163
+plugantic/_consts.py,sha256=j2iVE7WWaZT7gutn9Fe2HNKSOjXI-X-bpvhvoZaoi4w,109
+plugantic/_helpers.py,sha256=YQVGLjpQ-WhIFKt_sCKIyo1LOOqeZYj9TNy5y6xwkHE,1636
+plugantic/_types.py,sha256=a16kLslWFNrVUpON_GVG4iJA-Mr_GeCQre1TAlvKiqM,223
+plugantic/plugin.py,sha256=6ZM5zK2FMqHjREcgcETC3Cx_ep1sFR1SLzYpZwBmn70,16461
+plugantic-0.1.0.dist-info/licenses/LICENSE,sha256=5E8cRbGFBw4uIbIkiaxH_LFrI-_4nsn_YElk0LMkiL8,1060
+plugantic-0.1.0.dist-info/METADATA,sha256=RPkxeT0JzDlAOQDM8tUehPIYAlT-AQTU0RjIsw_kBp0,7614
+plugantic-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+plugantic-0.1.0.dist-info/top_level.txt,sha256=xiHgfBTODu2aghczK5ZLmAvc1ZPLqIWXx0H0NU4Rr7A,10
+plugantic-0.1.0.dist-info/RECORD,,

plugantic-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

plugantic-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Martin Kunze
+
+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.

plugantic-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+plugantic