value-object-pattern 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

value_object_pattern/__init__.py

@@ -1,9 +1,10 @@
-__version__ = '0.2.0'
+__version__ = '0.4.0'
 
 from .decorators import process, validation
-from .models import ValueObject
+from .models import EnumerationValueObject, ValueObject
 
 __all__ = (
+    'EnumerationValueObject',
     'ValueObject',
     'process',
     'validation',

value_object_pattern/models/__init__.py

@@ -1,3 +1,7 @@
+from .enumeration_value_object import EnumerationValueObject
 from .value_object import ValueObject
 
-__all__ = ('ValueObject',)
+__all__ = (
+    'EnumerationValueObject',
+    'ValueObject',
+)

value_object_pattern/models/enumeration_value_object.py

@@ -0,0 +1,169 @@
+"""
+EnumerationValueObject module.
+"""
+
+from enum import Enum
+from inspect import isclass
+from sys import version_info
+from typing import Any, Generic, TypeVar, get_args, get_origin
+
+if version_info >= (3, 12):
+    from typing import override  # pragma: no cover
+else:
+    from typing_extensions import override  # pragma: no cover
+
+from value_object_pattern.decorators import process, validation
+from value_object_pattern.models.value_object import ValueObject
+
+E = TypeVar('E', bound=Enum)
+
+
+class EnumerationValueObject(ValueObject[str | E], Generic[E]):  # noqa: UP046
+    """
+    EnumerationValueObject is a value object that ensures the provided value is from an enumeration.
+
+    Example:
+    ```python
+    from enum import Enum, unique
+
+    from value_object_pattern import EnumerationValueObject
+
+
+    @unique
+    class ColorEnumeration(Enum):
+        RED = 1
+        GREEN = 2
+        BLUE = 3
+
+
+    class ColorValueObject(EnumerationValueObject[ColorEnumeration]):
+        pass
+
+
+    red = ColorValueObject(value=ColorEnumeration.RED)
+    green = ColorValueObject(value='GREEN')
+    print(repr(red), repr(green))
+    # >>> ColorValueObject(value=ColorEnumeration.RED) ColorValueObject(value=ColorEnumeration.GREEN)
+    ```
+    """
+
+    _enumeration: type[E]
+
+    @override
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """
+        Initializes the class.
+
+        Args:
+            **kwargs (Any): Keyword arguments.
+
+        Raises:
+            TypeError: If the class parameter is not an Enum subclass.
+            TypeError: If the class is not parameterized.
+        """
+        super().__init_subclass__(**kwargs)
+
+        for base in getattr(cls, '__orig_bases__', ()):
+            if get_origin(tp=base) is EnumerationValueObject:
+                enumeration, *_ = get_args(tp=base)
+
+                if not (isclass(object=enumeration) and issubclass(enumeration, Enum)):
+                    raise TypeError(f'EnumerationValueObject[...] <<<{enumeration}>>> must be an Enum subclass. Got <<<{type(enumeration).__name__}>>> type.')  # noqa: E501  # fmt: skip
+
+                cls._enumeration = enumeration
+                return
+
+        raise TypeError('EnumerationValueObject must be parameterized, e.g. "class ColorValueObject(EnumerationValueObject[ColorEnumeration])".')  # noqa: E501  # fmt: skip
+
+    @override
+    def __repr__(self) -> str:
+        """
+        Returns a detailed string representation of the value object.
+
+        Returns:
+            str: A string representation of the value object in the format 'ClassName(value=value)'.
+
+        Example:
+        ```python
+        from enum import Enum, unique
+
+        from value_object_pattern import EnumerationValueObject
+
+
+        @unique
+        class ColorEnumeration(Enum):
+            RED = 1
+            GREEN = 2
+            BLUE = 3
+
+
+        class ColorValueObject(EnumerationValueObject[ColorEnumeration]):
+            pass
+
+
+        red = ColorValueObject(value=ColorEnumeration.RED)
+        print(repr(red))
+        # >>> ColorValueObject(value=ColorEnumeration.RED)
+        ```
+        """
+        return f'{self.__class__.__name__}(value={self.value.__class__.__name__}.{self.value.name})'
+
+    @process(order=0)
+    def _ensure_value_is_stored_as_enumeration(self, value: str | E) -> E:
+        """
+        Ensures the value object `value` is stored as an enumeration.
+
+        Args:
+            value (str | E): The provided value. It can be the name of the member or the member itself.
+
+        Returns:
+            E: The processed value.
+        """
+        if isinstance(value, str):
+            return self._enumeration[value.upper()]
+
+        return value
+
+    @validation(order=0)
+    def _ensure_value_is_from_enumeration(self, value: str | E) -> None:
+        """
+        Ensures the value object `value` is from the enumeration.
+
+        Args:
+            value (str | E): The provided value. It can be the name of the member or the member itself.
+
+        Raises:
+            TypeError: If the `value` is not from the enumeration.
+        """
+        if isinstance(value, self._enumeration):
+            return
+
+        if isinstance(value, str) and value in self._enumeration.__members__:
+            return
+
+        raise TypeError(f'EnumerationValueObject value <<<{value}>>> must be from the enumeration <<<{self._title}>>>.')  # noqa: E501  # fmt: skip
+
+    @override
+    @property
+    def value(self) -> E:
+        """
+        Returns the value object value.
+
+        Returns:
+            E: The value object value.
+
+        Example:
+        ```python
+        from value_object_pattern import ValueObject
+
+
+        class IntegerValueObject(ValueObject[int]):
+            pass
+
+
+        integer = IntegerValueObject(value=10)
+        print(integer.value)
+        # >>> 10
+        ```
+        """
+        return self._value  # type: ignore[return-value]

value_object_pattern/models/value_object.py

@@ -15,7 +15,7 @@ else:
 T = TypeVar('T')
 
 
-class ValueObject(ABC, Generic[T]):
+class ValueObject(ABC, Generic[T]):  # noqa: UP046
     """
     ValueObject generic type.
 
@@ -34,13 +34,14 @@ class ValueObject(ABC, Generic[T]):
     ```
     """
 
-    __slots__ = ('_title', '_value')
-    __match_args__ = ('_title', '_value')
+    __slots__ = ('_parameter', '_title', '_value')
+    __match_args__ = ('_parameter', '_title', '_value')
 
     _value: T
     _title: str
+    _parameter: str
 
-    def __init__(self, *, value: T, title: str | None = None) -> None:
+    def __init__(self, *, value: T, title: str | None = None, parameter: str | None = None) -> None:
         """
         ValueObject value object constructor.
 
@@ -48,10 +49,16 @@ class ValueObject(ABC, Generic[T]):
             value (T): The value to store in the value object.
             title (str | None, optional): The title of the value object when raising exceptions, if title is None, the
             class name is used instead. Defaults to None.
+            parameter (str | None, optional): The parameter name of the value object when raising exceptions, if
+            parameter is None, the string "value" is used instead. Defaults to None.
 
         Raises:
             TypeError: If the title is not a string.
+            ValueError: If the title is an empty string.
             ValueError: If the title contains leading or trailing whitespaces.
+            TypeError: If the parameter is not a string.
+            ValueError: If the parameter is an empty string.
+            ValueError: If the parameter contains leading or trailing whitespaces.
 
         Example:
         ```python
@@ -71,12 +78,28 @@ class ValueObject(ABC, Generic[T]):
             title = self.__class__.__name__
 
         if type(title) is not str:
-            raise TypeError(f'ValueObject value <<<{title}>>> must be a string. Got <<<{type(title).__name__}>>> instead.')  # noqa: E501  # fmt: skip
+            raise TypeError(f'ValueObject title <<<{title}>>> must be a string. Got <<<{type(title).__name__}>>> instead.')  # noqa: E501  # fmt: skip
+
+        if title == '':
+            raise ValueError(f'ValueObject title <<<{title}>>> must not be an empty string.')  # noqa: E501  # fmt: skip
 
         if title.strip() != title:
             raise ValueError(f'ValueObject title <<<{title}>>> contains leading or trailing whitespaces. Only trimmed values are allowed.')  # noqa: E501  # fmt: skip
 
+        if parameter is None:
+            parameter = 'value'
+
+        if type(parameter) is not str:
+            raise TypeError(f'ValueObject parameter <<<{parameter}>>> must be a string. Got <<<{type(parameter).__name__}>>> instead.')  # noqa: E501  # fmt: skip
+
+        if parameter == '':
+            raise ValueError(f'ValueObject parameter <<<{parameter}>>> must not be an empty string.')  # noqa: E501  # fmt: skip
+
+        if parameter.strip() != parameter:
+            raise ValueError(f'ValueObject parameter <<<{parameter}>>> contains leading or trailing whitespaces. Only trimmed values are allowed.')  # noqa: E501  # fmt: skip
+
         object.__setattr__(self, '_title', title)
+        object.__setattr__(self, '_parameter', parameter)
 
         self._validate(value=value)
         value = self._process(value=value)
@@ -247,6 +270,8 @@ class ValueObject(ABC, Generic[T]):
             for class_name in {cls.__name__ for cls in classes}:
                 error.args = (str(object=error.args[0]).replace(class_name, self.title),)
 
+            error.args = (str(object=error.args[0]).replace('value', self.parameter, 1),)
+
             raise error
 
     def _post_order_dfs_mro(self, cls: type, visited: set[type] | None = None, cut_off: type = object) -> list[type]:
@@ -381,3 +406,27 @@ class ValueObject(ABC, Generic[T]):
         ```
         """
         return self._title
+
+    @property
+    def parameter(self) -> str:
+        """
+        Returns the value object parameter name.
+
+        Returns:
+            str: The value object parameter name.
+
+        Example:
+        ```python
+        from value_object_pattern import ValueObject
+
+
+        class IntegerValueObject(ValueObject[int]):
+            pass
+
+
+        integer = IntegerValueObject(value=10)
+        print(integer.parameter)
+        # >>> value
+        ```
+        """
+        return self._parameter

{value_object_pattern-0.2.0.dist-info → value_object_pattern-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: value-object-pattern
-Version: 0.2.0
+Version: 0.4.0
 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

{value_object_pattern-0.2.0.dist-info → value_object_pattern-0.4.0.dist-info}/RECORD

@@ -1,10 +1,11 @@
-value_object_pattern/__init__.py,sha256=FkXjACU6R9F9vyZv_sMVMi3nK4uYNbSGaFormGodXFw,166
+value_object_pattern/__init__.py,sha256=12VKCLbhT9Cz8m58ucw8UJ4NhO2G0YY6TZjcEWF7MWA,220
 value_object_pattern/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 value_object_pattern/decorators/__init__.py,sha256=Ze0c0z3x5sdmV-KB7nljPsybpoTXAgjJDGfR8FCIxUQ,138
 value_object_pattern/decorators/value_object_process.py,sha256=Q_0w26XolcfZOE6avveA5OGs1yIMNAVC_AxsBV8F5D0,2621
 value_object_pattern/decorators/value_object_validation.py,sha256=ENAQuOLalc-dDzVEpRolbBg8Y0g7--4DRimHTPDD12U,2793
-value_object_pattern/models/__init__.py,sha256=Dx-VEvvCNyKmso8xWM69kz2pfTYuGxgZYD08VQPw1io,66
-value_object_pattern/models/value_object.py,sha256=nnMNv34An6nDMc215oDEAbhtDhkNoerbIJ9WAapwOuQ,11647
+value_object_pattern/models/__init__.py,sha256=1BsXKFnX_0EufuHurfgdpbMUvnrjF8HLz46saTcmNr4,163
+value_object_pattern/models/enumeration_value_object.py,sha256=6ih7GlohDcA3Lknk6SaIsve2Udaco8iHTPkRCrhvYJo,4886
+value_object_pattern/models/value_object.py,sha256=-xXCk_qwCj_VBIzNJfUflM4vD7M0bicJdlprFYh2_Uw,13627
 value_object_pattern/usables/__init__.py,sha256=LsHh5uSECizrDXPogZC3zRMzcBIBPyiWXpqSrG2qHrg,1483
 value_object_pattern/usables/dates/__init__.py,sha256=x4MafCtJ1S9WN36cVGOfPdXeKgfptlg4QkcH9fPV4tA,253
 value_object_pattern/usables/dates/date/__init__.py,sha256=rSifr41n8gmqW80e0Ygzoj221dpVsZy7m4TecC_VJus,174
@@ -61,7 +62,7 @@ value_object_pattern/usables/primitives/string/printable_string_value_object.py,
 value_object_pattern/usables/primitives/string/string_value_object.py,sha256=6u98oMzz5qsVNEWna-UpziDmzFhaLFW7J5NBoJnbKWk,1370
 value_object_pattern/usables/primitives/string/trimmed_string_value_object.py,sha256=WMp4IBA74cEli-N_9Q7qU_oMszHtk5tgCr6o2y99HMs,1435
 value_object_pattern/usables/primitives/string/uppercase_string_value_object.py,sha256=yZajkdq09zb56_UHs4nc0sIeTV4K74ek26JcoHYhM64,1457
-value_object_pattern-0.2.0.dist-info/METADATA,sha256=KmRPYmvh3yDemfj1L2fykaJIwHHCwF8TYt1Bo7UfmPM,4018
-value_object_pattern-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-value_object_pattern-0.2.0.dist-info/licenses/LICENSE.md,sha256=6E0wpVdiB-k3oJ9cvVG9BPZ07yIevD3IuOECHKveFkM,1076
-value_object_pattern-0.2.0.dist-info/RECORD,,
+value_object_pattern-0.4.0.dist-info/METADATA,sha256=4wEChHY3T0DNwarqKoc9_gGhl4hsomvd86r1bN7W1sI,4018
+value_object_pattern-0.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+value_object_pattern-0.4.0.dist-info/licenses/LICENSE.md,sha256=6E0wpVdiB-k3oJ9cvVG9BPZ07yIevD3IuOECHKveFkM,1076
+value_object_pattern-0.4.0.dist-info/RECORD,,