value-object-pattern 1.30.0__tar.gz → 1.31.1__tar.gz

{value_object_pattern-1.30.0 → value_object_pattern-1.31.1}/.gitignore

@@ -12,3 +12,4 @@ htmlcov/
 
 # environment folders
 **.venv**
+**.agents/skills**

{value_object_pattern-1.30.0 → value_object_pattern-1.31.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: value-object-pattern
-Version: 1.30.0
+Version: 1.31.1
 Summary: The Value Object Pattern is a Python package that streamlines the creation and management of value objects in your projects.
 Project-URL: Homepage, https://github.com/adriamontoto/value-object-pattern
 Project-URL: Repository, https://github.com/adriamontoto/value-object-pattern
@@ -262,10 +262,10 @@ low-level operations, and boundary examples.
 | --- | --- |
 | `ValueObject[T]` | Base class for immutable validated single-value wrappers. |
 | `EnumerationValueObject[E]` | Stores enum members while accepting enum members or raw enum values. |
-| `UnionValueObject[T]` | Accepts and converts values that match a union annotation. |
+| `UnionValueObject[T]` | Accepts and converts values that match a union annotation; supports subclass and inline construction. |
 | `BaseModel` | Adds representation, equality, copying, and primitive conversion for aggregate-like models. |
-| `ListValueObject[T]` | Immutable typed list wrapper with helper methods that return new instances. |
-| `DictValueObject[K, V]` | Immutable typed dictionary wrapper with helper methods that return new instances. |
+| `ListValueObject[T]` | Immutable typed list wrapper; supports subclass and inline construction. |
+| `DictValueObject[K, V]` | Immutable typed dictionary wrapper; supports subclass and inline construction. |
 
 See [`docs/usage/README.md`](docs/usage/README.md) for examples of each model.
 

{value_object_pattern-1.30.0 → value_object_pattern-1.31.1}/README.md

@@ -237,10 +237,10 @@ low-level operations, and boundary examples.
 | --- | --- |
 | `ValueObject[T]` | Base class for immutable validated single-value wrappers. |
 | `EnumerationValueObject[E]` | Stores enum members while accepting enum members or raw enum values. |
-| `UnionValueObject[T]` | Accepts and converts values that match a union annotation. |
+| `UnionValueObject[T]` | Accepts and converts values that match a union annotation; supports subclass and inline construction. |
 | `BaseModel` | Adds representation, equality, copying, and primitive conversion for aggregate-like models. |
-| `ListValueObject[T]` | Immutable typed list wrapper with helper methods that return new instances. |
-| `DictValueObject[K, V]` | Immutable typed dictionary wrapper with helper methods that return new instances. |
+| `ListValueObject[T]` | Immutable typed list wrapper; supports subclass and inline construction. |
+| `DictValueObject[K, V]` | Immutable typed dictionary wrapper; supports subclass and inline construction. |
 
 See [`docs/usage/README.md`](docs/usage/README.md) for examples of each model.
 

{value_object_pattern-1.30.0 → value_object_pattern-1.31.1}/value_object_pattern/__init__.py

@@ -1,4 +1,4 @@
-__version__ = '1.30.0'
+__version__ = '1.31.1'
 
 from .decorators import process, validation
 from .models import BaseModel, EnumerationValueObject, UnionValueObject, ValueObject

{value_object_pattern-1.30.0 → value_object_pattern-1.31.1}/value_object_pattern/models/collections/dict_value_object.py

@@ -14,7 +14,21 @@ else:
 from collections.abc import Iterator
 from inspect import isclass
 from types import UnionType
-from typing import Any, Generic, ItemsView, KeysView, NoReturn, Self, TypeVar, Union, ValuesView, get_args, get_origin
+from typing import (
+    Any,
+    ClassVar,
+    Generic,
+    ItemsView,
+    KeysView,
+    NoReturn,
+    Self,
+    TypeVar,
+    Union,
+    ValuesView,
+    cast,
+    get_args,
+    get_origin,
+)
 
 from value_object_pattern.decorators import validation
 from value_object_pattern.models import ValueObject
@@ -25,6 +39,154 @@ K = TypeVar('K', bound=Any)
 V = TypeVar('V', bound=Any)
 
 
+def _validate_dict_type_argument(*, type_argument: Any) -> None:
+    """
+    Validate a type argument used by DictValueObject.
+
+    Args:
+        type_argument: The type argument to validate.
+
+    Raises:
+        TypeError: If the type argument is not a type-like annotation.
+    """
+    if isinstance(type_argument, TypeVar):
+        return
+
+    if type(type_argument) is not type and not isclass(object=type_argument) and get_origin(tp=type_argument) is None:
+        raise TypeError(f'DictValueObject[...] <<<{type_argument}>>> must be a type. Got <<<{type(type_argument).__name__}>>> type.')  # noqa: E501  # fmt: skip
+
+
+def _parse_dict_type_arguments(*, type_arguments: Any) -> tuple[Any, Any]:
+    """
+    Return key and value type arguments from `DictValueObject[K, V]` input.
+
+    Args:
+        type_arguments: The raw type arguments passed to `DictValueObject[...]`.
+
+    Raises:
+        TypeError: If exactly two type arguments are not provided.
+
+    Returns:
+        tuple[Any, Any]: The key and value type arguments.
+    """
+    if not isinstance(type_arguments, tuple):
+        raise TypeError('DictValueObject must be parameterised, e.g. `class StrIntDict(DictValueObject[str, int])`.')
+
+    if len(type_arguments) != 2:
+        raise TypeError('DictValueObject must be parameterised, e.g. `class StrIntDict(DictValueObject[str, int])`.')
+
+    key_type, value_type = type_arguments
+
+    return key_type, value_type
+
+
+class _DictValueObjectAlias:
+    """
+    Runtime alias returned by `DictValueObject[K, V]`.
+
+    Key and value types must be available before `ValueObject.__init__` validates the dictionary. This alias keeps
+    subclass declarations working through `__mro_entries__` and supports direct inline construction by creating a
+    parameterized runtime subclass before validation starts.
+    """
+
+    _runtime_classes: ClassVar[dict[Any, type[DictValueObject[Any, Any]]]] = {}
+
+    def __init__(self, *, origin: type[DictValueObject[Any, Any]], key_type: Any, value_type: Any) -> None:
+        """
+        Create a runtime alias for a parameterized DictValueObject.
+
+        Args:
+            origin: The original DictValueObject class.
+            key_type: The key type argument used in `DictValueObject[K, V]`.
+            value_type: The value type argument used in `DictValueObject[K, V]`.
+        """
+        self.__origin__ = origin
+        self.__args__ = (key_type, value_type)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """
+        Construct an inline parameterized DictValueObject instance.
+
+        Args:
+            *args: Positional arguments passed to the generated value object subclass.
+            **kwargs: Keyword arguments passed to the generated value object subclass.
+
+        Returns:
+            Any: The constructed value object.
+        """
+        return self._runtime_class()(*args, **kwargs)
+
+    def __getattr__(self, name: str) -> Any:
+        """
+        Delegate class attribute access to the generated runtime subclass.
+
+        Args:
+            name: The attribute name to retrieve.
+
+        Returns:
+            Any: The resolved attribute.
+        """
+        return getattr(self._runtime_class(), name)
+
+    def __mro_entries__(self, bases: tuple[type, ...]) -> tuple[type[DictValueObject[Any, Any]], ...]:
+        """
+        Return the origin class when the alias is used as a base class.
+
+        Args:
+            bases: The original class bases supplied by Python.
+
+        Returns:
+            tuple[type[DictValueObject[Any, Any]], ...]: The base classes to use for MRO construction.
+        """
+        _ = bases
+
+        return (self.__origin__,)
+
+    def _runtime_class(self) -> type[DictValueObject[Any, Any]]:
+        """
+        Return the generated runtime subclass for this alias.
+
+        Returns:
+            type[DictValueObject[Any, Any]]: The runtime subclass.
+        """
+        key_type, value_type = self.__args__
+        _validate_dict_type_argument(type_argument=key_type)
+        _validate_dict_type_argument(type_argument=value_type)
+        key = (self.__origin__, key_type, value_type)
+        if key not in self._runtime_classes:
+            self._runtime_classes[key] = type(
+                f'{self.__origin__.__name__}[{self._format_type_argument(type=key_type)}, {self._format_type_argument(type=value_type)}]',  # noqa: E501
+                (self.__origin__,),
+                {
+                    '_is_inline_parameterized_dict_value_object': True,
+                    '_key_type': key_type,
+                    '_value_type': value_type,
+                },
+            )
+
+        return self._runtime_classes[key]
+
+    @staticmethod
+    def _format_type_argument(*, type: Any) -> str:
+        """
+        Return a compact type-argument label for generated runtime class names.
+
+        Args:
+            type: The type argument to format.
+
+        Returns:
+            str: A readable type label.
+        """
+        origin = get_origin(tp=type)
+        if origin in (Union, UnionType):
+            return ' | '.join(_DictValueObjectAlias._format_type_argument(type=allowed) for allowed in get_args(type))
+
+        if hasattr(type, '__name__'):
+            return type.__name__  # type: ignore[no-any-return]
+
+        return str(type).replace('typing.', '')
+
+
 class DictValueObject(ValueObject[dict[K, V]], Generic[K, V]):  # noqa: UP046
     """
     Validate dictionary values, keys, and items against declared key and value types.
@@ -54,6 +216,21 @@ class DictValueObject(ValueObject[dict[K, V]], Generic[K, V]):  # noqa: UP046
     _key_type: K
     _value_type: V
 
+    @classmethod
+    def __class_getitem__(cls, item: Any) -> Any:
+        """
+        Return a runtime alias that supports subclassing and inline construction.
+
+        Args:
+            item: The type arguments used in `DictValueObject[item]`.
+
+        Returns:
+            Any: A runtime alias for the parameterized DictValueObject.
+        """
+        key_type, value_type = _parse_dict_type_arguments(type_arguments=item)
+
+        return _DictValueObjectAlias(origin=cls, key_type=key_type, value_type=value_type)
+
     @override
     def __init_subclass__(cls, **kwargs: Any) -> None:
         """
@@ -69,25 +246,17 @@ class DictValueObject(ValueObject[dict[K, V]], Generic[K, V]):  # noqa: UP046
         """
         super().__init_subclass__(**kwargs)
 
-        for base in getattr(cls, '__orig_bases__', ()):
-            if get_origin(base) is DictValueObject:
-                key_type, val_type, *_ = get_args(base)
-
-                if isinstance(key_type, TypeVar):
-                    cls._key_type = key_type  # type: ignore[assignment]
-                else:
-                    if type(key_type) is not type and not isclass(key_type) and get_origin(key_type) is None:
-                        raise TypeError(f'DictValueObject[...] <<<{key_type}>>> must be a type. Got <<<{type(key_type).__name__}>>> type.')  # noqa: E501  # fmt: skip
-
-                    cls._key_type = key_type
+        if getattr(cls, '_is_inline_parameterized_dict_value_object', False):
+            return
 
-                if isinstance(val_type, TypeVar):
-                    cls._value_type = val_type  # type: ignore[assignment]
-                else:
-                    if type(val_type) is not type and not isclass(val_type) and get_origin(val_type) is None:
-                        raise TypeError(f'DictValueObject[...] <<<{val_type}>>> must be a type. Got <<<{type(val_type).__name__}>>> type.')  # noqa: E501  # fmt: skip
+        for base in getattr(cls, '__orig_bases__', ()):
+            if get_origin(base) is DictValueObject or getattr(base, '__origin__', None) is DictValueObject:
+                key_type, val_type = get_args(base) or base.__args__
 
-                    cls._value_type = val_type
+                _validate_dict_type_argument(type_argument=key_type)
+                cls._key_type = key_type
+                _validate_dict_type_argument(type_argument=val_type)
+                cls._value_type = val_type
 
                 return
 
@@ -476,6 +645,9 @@ class DictValueObject(ValueObject[dict[K, V]], Generic[K, V]):  # noqa: UP046
         Returns:
             Self: The created DictValueObject.
 
+        Raises:
+            TypeError: If the `value` is not a dict.
+
         Example:
         ```python
         from value_object_pattern.models import ValueObject
@@ -495,6 +667,9 @@ class DictValueObject(ValueObject[dict[K, V]], Generic[K, V]):  # noqa: UP046
         # >>> {'john': 30, 'jane': 25}
         ```
         """
+        if not isinstance(cast(Any, value), dict):
+            return cls(value=value)
+
         dictionary: dict[Any, Any] = {}
 
         for key, item in value.items():

{value_object_pattern-1.30.0 → value_object_pattern-1.31.1}/value_object_pattern/models/collections/list_value_object.py

@@ -15,7 +15,7 @@ from collections.abc import Iterator
 from enum import Enum
 from inspect import isclass
 from types import UnionType
-from typing import Any, Generic, NoReturn, Self, TypeVar, Union, get_args, get_origin
+from typing import Any, ClassVar, Generic, NoReturn, Self, TypeVar, Union, cast, get_args, get_origin
 
 from value_object_pattern.decorators import validation
 from value_object_pattern.models import BaseModel, ValueObject
@@ -25,6 +25,127 @@ from value_object_pattern.models.type_matching import matches_expected_type
 T = TypeVar('T', bound=Any)
 
 
+def _validate_list_type_argument(*, type_argument: Any) -> None:
+    """
+    Validate a type argument used by ListValueObject.
+
+    Args:
+        type_argument: The type argument to validate.
+
+    Raises:
+        TypeError: If the type argument is not a type-like annotation.
+    """
+    if isinstance(type_argument, TypeVar):
+        return
+
+    if type(type_argument) is not type and not isclass(object=type_argument) and get_origin(tp=type_argument) is None:
+        raise TypeError(f'ListValueObject[...] <<<{type_argument}>>> must be a type. Got <<<{type(type_argument).__name__}>>> type.')  # noqa: E501  # fmt: skip
+
+
+class _ListValueObjectAlias:
+    """
+    Runtime alias returned by `ListValueObject[T]`.
+
+    The item type must be available before `ValueObject.__init__` validates the list. This alias keeps subclass
+    declarations working through `__mro_entries__` and supports direct inline construction by creating a parameterized
+    runtime subclass before validation starts.
+    """
+
+    _runtime_classes: ClassVar[dict[Any, type[ListValueObject[Any]]]] = {}
+
+    def __init__(self, *, origin: type[ListValueObject[Any]], type_argument: Any) -> None:
+        """
+        Create a runtime alias for a parameterized ListValueObject.
+
+        Args:
+            origin: The original ListValueObject class.
+            type_argument: The type argument used in `ListValueObject[T]`.
+        """
+        self.__origin__ = origin
+        self.__args__ = (type_argument,)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """
+        Construct an inline parameterized ListValueObject instance.
+
+        Args:
+            *args: Positional arguments passed to the generated value object subclass.
+            **kwargs: Keyword arguments passed to the generated value object subclass.
+
+        Returns:
+            Any: The constructed value object.
+        """
+        return self._runtime_class()(*args, **kwargs)
+
+    def __getattr__(self, name: str) -> Any:
+        """
+        Delegate class attribute access to the generated runtime subclass.
+
+        Args:
+            name: The attribute name to retrieve.
+
+        Returns:
+            Any: The resolved attribute.
+        """
+        return getattr(self._runtime_class(), name)
+
+    def __mro_entries__(self, bases: tuple[type, ...]) -> tuple[type[ListValueObject[Any]], ...]:
+        """
+        Return the origin class when the alias is used as a base class.
+
+        Args:
+            bases: The original class bases supplied by Python.
+
+        Returns:
+            tuple[type[ListValueObject[Any]], ...]: The base classes to use for MRO construction.
+        """
+        _ = bases
+
+        return (self.__origin__,)
+
+    def _runtime_class(self) -> type[ListValueObject[Any]]:
+        """
+        Return the generated runtime subclass for this alias.
+
+        Returns:
+            type[ListValueObject[Any]]: The runtime subclass.
+        """
+        type_argument, *_ = self.__args__
+        _validate_list_type_argument(type_argument=type_argument)
+        key = (self.__origin__, type_argument)
+        if key not in self._runtime_classes:
+            self._runtime_classes[key] = type(
+                f'{self.__origin__.__name__}[{self._format_type_argument(type=type_argument)}]',
+                (self.__origin__,),
+                {
+                    '_is_inline_parameterized_list_value_object': True,
+                    '_type': type_argument,
+                },
+            )
+
+        return self._runtime_classes[key]
+
+    @staticmethod
+    def _format_type_argument(*, type: Any) -> str:
+        """
+        Return a compact type-argument label for generated runtime class names.
+
+        Args:
+            type: The type argument to format.
+
+        Returns:
+            str: A readable type label.
+        """
+        origin = get_origin(tp=type)
+        if origin in (Union, UnionType):
+            return ' | '.join(_ListValueObjectAlias._format_type_argument(type=allowed) for allowed in get_args(type))
+
+        if hasattr(type, '__name__'):
+            return type.__name__  # type: ignore[no-any-return]
+
+        return str(type).replace('typing.', '')
+
+
 class ListValueObject(ValueObject[list[T]], Generic[T]):  # noqa: UP046
     """
     Validate list values and every item against the declared item type.
@@ -50,6 +171,19 @@ class ListValueObject(ValueObject[list[T]], Generic[T]):  # noqa: UP046
 
     _type: T
 
+    @classmethod
+    def __class_getitem__(cls, item: Any) -> Any:
+        """
+        Return a runtime alias that supports subclassing and inline construction.
+
+        Args:
+            item: The type argument used in `ListValueObject[item]`.
+
+        Returns:
+            Any: A runtime alias for the parameterized ListValueObject.
+        """
+        return _ListValueObjectAlias(origin=cls, type_argument=item)
+
     @override
     def __init_subclass__(cls, **kwargs: Any) -> None:
         """
@@ -64,17 +198,14 @@ class ListValueObject(ValueObject[list[T]], Generic[T]):  # noqa: UP046
         """
         super().__init_subclass__(**kwargs)
 
-        for base in getattr(cls, '__orig_bases__', ()):
-            if get_origin(tp=base) is ListValueObject:
-                _type, *_ = get_args(tp=base)
-
-                if isinstance(_type, TypeVar):
-                    cls._type = _type  # type: ignore[assignment]
-                    return
+        if getattr(cls, '_is_inline_parameterized_list_value_object', False):
+            return
 
-                if type(_type) is not type and not isclass(object=_type) and get_origin(tp=_type) is None:
-                    raise TypeError(f'ListValueObject[...] <<<{_type}>>> must be a type. Got <<<{type(_type).__name__}>>> type.')  # noqa: E501  # fmt: skip
+        for base in getattr(cls, '__orig_bases__', ()):
+            if get_origin(tp=base) is ListValueObject or getattr(base, '__origin__', None) is ListValueObject:
+                _type, *_ = get_args(tp=base) or base.__args__
 
+                _validate_list_type_argument(type_argument=_type)
                 cls._type = _type
                 return
 
@@ -747,6 +878,9 @@ class ListValueObject(ValueObject[list[T]], Generic[T]):  # noqa: UP046
         # >>> [10, 20, 30]
         ```
         """
+        if not isinstance(cast(Any, value), list):
+            return cls(value=value)
+
         return cls(value=[from_primitive(value=item, expected_type=cls._type) for item in value])
 
     def to_primitives(self) -> list[Any]: