value-object-pattern 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

value_object_pattern/__init__.py

@@ -1,9 +1,10 @@
-__version__ = '0.1.0'
+__version__ = '0.3.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]):
+    """
+    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/usables/identifiers/{country_ids → countries}/spain/dni_value_object.py

@@ -3,6 +3,7 @@ DniValueObject value object.
 """
 
 from re import Pattern, compile as re_compile
+from typing import NoReturn
 
 from value_object_pattern.decorators import process, validation
 from value_object_pattern.usables import NotEmptyStringValueObject, TrimmedStringValueObject
@@ -16,7 +17,7 @@ class DniValueObject(NotEmptyStringValueObject, TrimmedStringValueObject):
 
     Example:
     ```python
-    from value_object_pattern.usables.identifiers.country_ids import DniValueObject
+    from value_object_pattern.usables.identifiers.countries.spain import DniValueObject
 
     dni = DniValueObject(value='87654321X')
 
@@ -54,10 +55,22 @@ class DniValueObject(NotEmptyStringValueObject, TrimmedStringValueObject):
         """
         match = self.__DNI_VALUE_OBJECT_REGEX.fullmatch(string=value)
         if not match:
-            raise ValueError(f'DniValueObject value <<<{value}>>> is not a valid Spanish DNI.')
+            self._raise_value_is_not_dni(value=value)
 
         number, letter = match.groups()
 
         expected_letter = self.__DNI_VALUE_OBJECT_LETTERS[int(number) % 23]
         if letter.upper() != expected_letter:
-            raise ValueError(f'DniValueObject value <<<{value}>>> is not a valid Spanish DNI.')
+            self._raise_value_is_not_dni(value=value)
+
+    def _raise_value_is_not_dni(self, value: str) -> NoReturn:
+        """
+        Raises a ValueError if the value object `value` is not a Spanish DNI.
+
+        Args:
+            value (str): The provided value.
+
+        Raises:
+            ValueError: If the `value` is not a Spanish DNI.
+        """
+        raise ValueError(f'DniValueObject value <<<{value}>>> is not a valid Spanish DNI.')

value_object_pattern/usables/identifiers/string_uuid_value_object.py

@@ -2,8 +2,7 @@
 StringUuidValueObject value object.
 """
 
-from __future__ import annotations
-
+from typing import NoReturn
 from uuid import UUID
 
 from value_object_pattern.decorators import process, validation
@@ -52,5 +51,17 @@ class StringUuidValueObject(NotEmptyStringValueObject, TrimmedStringValueObject)
         try:
             UUID(hex=value)
 
-        except ValueError as error:
-            raise ValueError(f'StringUuidValueObject value <<<{value}>>> is not a valid UUID.') from error
+        except ValueError:
+            self._raise_value_is_not_uuid(value=value)
+
+    def _raise_value_is_not_uuid(self, value: str) -> NoReturn:
+        """
+        Raises a ValueError if the value object `value` is not a UUID.
+
+        Args:
+            value (str): The provided value.
+
+        Raises:
+            ValueError: If the `value` is not a UUID.
+        """
+        raise ValueError(f'StringUuidValueObject value <<<{value}>>> is not a valid UUID.')

value_object_pattern/usables/identifiers/uuid_value_object.py

@@ -2,6 +2,7 @@
 UuidValueObject value object.
 """
 
+from typing import Any, NoReturn
 from uuid import UUID
 
 from value_object_pattern.decorators import validation
@@ -37,4 +38,16 @@ class UuidValueObject(ValueObject[UUID]):
             TypeError: If the `value` is not a UUID.
         """
         if type(value) is not UUID:
-            raise TypeError(f'UuidValueObject value <<<{value}>>> must be a UUID. Got <<<{type(value).__name__}>>> type.')  # noqa: E501  # fmt: skip
+            self._raise_value_is_not_uuid(value=value)
+
+    def _raise_value_is_not_uuid(self, value: Any) -> NoReturn:
+        """
+        Raises a TypeError if the value object `value` is not a UUID.
+
+        Args:
+            value (Any): The provided value.
+
+        Raises:
+            TypeError: If the `value` is not a UUID.
+        """
+        raise TypeError(f'UuidValueObject value <<<{value}>>> must be a UUID. Got <<<{type(value).__name__}>>> type.')

value_object_pattern/usables/internet/__init__.py

@@ -1,10 +1,3 @@
-from .api_keys import (
-    AwsAccessKeyValueObject,
-    AwsSecretAccessKeyValueObject,
-    GitHubPersonalAccessTokenValueObject,
-    OpenaiApiKeyValueObject,
-    ResendApiKeyValueObject,
-)
 from .aws_cloud_region_value_object import AwsCloudRegionValueObject
 from .domain_value_object import DomainValueObject
 from .host_value_object import HostValueObject
@@ -17,11 +10,8 @@ from .port_value_object import PortValueObject
 from .uri import HttpHttpsUrlValueObject, HttpUrlValueObject, HttpsUrlValueObject, UrlValueObject
 
 __all__ = (
-    'AwsAccessKeyValueObject',
     'AwsCloudRegionValueObject',
-    'AwsSecretAccessKeyValueObject',
     'DomainValueObject',
-    'GitHubPersonalAccessTokenValueObject',
     'HostValueObject',
     'HttpHttpsUrlValueObject',
     'HttpUrlValueObject',
@@ -31,8 +21,6 @@ __all__ = (
     'Ipv6AddressValueObject',
     'Ipv6NetworkValueObject',
     'MacAddressValueObject',
-    'OpenaiApiKeyValueObject',
     'PortValueObject',
-    'ResendApiKeyValueObject',
     'UrlValueObject',
 )

value_object_pattern/usables/primitives/boolean/boolean_value_object.py

@@ -2,6 +2,8 @@
 BooleanValueObject value object.
 """
 
+from typing import Any, NoReturn
+
 from value_object_pattern.decorators import validation
 from value_object_pattern.models import ValueObject
 
@@ -33,4 +35,16 @@ class BooleanValueObject(ValueObject[bool]):
             TypeError: If the `value` is not a boolean.
         """
         if type(value) is not bool:
-            raise TypeError(f'BooleanValueObject value <<<{value}>>> must be a boolean. Got <<<{type(value).__name__}>>> type.')  # noqa: E501  # fmt: skip
+            self._raise_value_is_not_boolean(value=value)
+
+    def _raise_value_is_not_boolean(self, value: Any) -> NoReturn:
+        """
+        Raises a TypeError if the value object `value` is not a boolean.
+
+        Args:
+            value (Any): The provided value.
+
+        Raises:
+            TypeError: If the `value` is not a boolean.
+        """
+        raise TypeError(f'BooleanValueObject value <<<{value}>>> must be a boolean. Got <<<{type(value).__name__}>>> type.')  # noqa: E501  # fmt: skip

value_object_pattern/usables/primitives/boolean/false_value_object.py

@@ -2,6 +2,8 @@
 FalseValueObject value object.
 """
 
+from typing import NoReturn
+
 from value_object_pattern.decorators import validation
 
 from .boolean_value_object import BooleanValueObject
@@ -34,4 +36,16 @@ class FalseValueObject(BooleanValueObject):
             ValueError: If the `value` is not false.
         """
         if value:
-            raise ValueError(f'FalseValueObject value <<<{value}>>> must be false.')
+            self._raise_value_is_not_false(value=value)
+
+    def _raise_value_is_not_false(self, value: bool) -> NoReturn:
+        """
+        Raises a ValueError if the value object `value` is not false.
+
+        Args:
+            value (bool): The provided value.
+
+        Raises:
+            ValueError: If the `value` is not false.
+        """
+        raise ValueError(f'FalseValueObject value <<<{value}>>> must be false.')

value_object_pattern/usables/primitives/boolean/true_value_object.py

@@ -2,6 +2,8 @@
 TrueValueObject value object.
 """
 
+from typing import NoReturn
+
 from value_object_pattern.decorators import validation
 
 from .boolean_value_object import BooleanValueObject
@@ -34,4 +36,16 @@ class TrueValueObject(BooleanValueObject):
             ValueError: If the `value` is not true.
         """
         if not value:
-            raise ValueError(f'TrueValueObject value <<<{value}>>> must be true.')
+            self._raise_value_is_not_true(value=value)
+
+    def _raise_value_is_not_true(self, value: bool) -> NoReturn:
+        """
+        Raises a ValueError if the value object `value` is not true.
+
+        Args:
+            value (bool): The provided value.
+
+        Raises:
+            ValueError: If the `value` is not true.
+        """
+        raise ValueError(f'TrueValueObject value <<<{value}>>> must be true.')

value_object_pattern/usables/primitives/bytes/bytes_value_object.py

@@ -2,6 +2,8 @@
 BytesValueObject value object.
 """
 
+from typing import Any, NoReturn
+
 from value_object_pattern.decorators import validation
 from value_object_pattern.models import ValueObject
 
@@ -33,4 +35,16 @@ class BytesValueObject(ValueObject[bytes]):
             TypeError: If the `value` is not bytes.
         """
         if type(value) is not bytes:
-            raise TypeError(f'BytesValueObject value <<<{str(object=value)}>>> must be bytes. Got <<<{type(value).__name__}>>> type.')  # noqa: E501  # fmt: skip
+            self._raise_value_is_not_bytes(value=value)
+
+    def _raise_value_is_not_bytes(self, value: Any) -> NoReturn:
+        """
+        Raises a TypeError if the value object `value` is not bytes.
+
+        Args:
+            value (Any): The provided value.
+
+        Raises:
+            TypeError: If the `value` is not bytes.
+        """
+        raise TypeError(f'BytesValueObject value <<<{str(object=value)}>>> must be bytes. Got <<<{type(value).__name__}>>> type.')  # noqa: E501  # fmt: skip

value_object_pattern/usables/primitives/float/float_value_object.py

@@ -2,6 +2,8 @@
 FloatValueObject value object.
 """
 
+from typing import Any, NoReturn
+
 from value_object_pattern.decorators import validation
 from value_object_pattern.models import ValueObject
 
@@ -33,4 +35,16 @@ class FloatValueObject(ValueObject[float]):
             TypeError: If the `value` is not a float.
         """
         if type(value) is not float:
-            raise TypeError(f'FloatValueObject value <<<{value}>>> must be a float. Got <<<{type(value).__name__}>>> type.')  # noqa: E501  # fmt: skip
+            self._raise_value_is_not_float(value=value)
+
+    def _raise_value_is_not_float(self, value: Any) -> NoReturn:
+        """
+        Raises a TypeError if the value object `value` is not a float.
+
+        Args:
+            value (Any): The provided value.
+
+        Raises:
+            TypeError: If the `value` is not a float.
+        """
+        raise TypeError(f'FloatValueObject value <<<{value}>>> must be a float. Got <<<{type(value).__name__}>>> type.')  # noqa: E501  # fmt: skip

value_object_pattern/usables/primitives/float/negative_float_value_object.py

@@ -2,6 +2,8 @@
 NegativeFloatValueObject value object.
 """
 
+from typing import NoReturn
+
 from value_object_pattern.decorators import validation
 
 from .float_value_object import FloatValueObject
@@ -34,4 +36,16 @@ class NegativeFloatValueObject(FloatValueObject):
             ValueError: If the `value` is not a negative float.
         """
         if value >= 0:
-            raise ValueError(f'NegativeFloatValueObject value <<<{value}>>> must be a negative float.')
+            self._raise_value_is_not_negative_float(value=value)
+
+    def _raise_value_is_not_negative_float(self, value: float) -> NoReturn:
+        """
+        Raises a ValueError if the value object `value` is not a negative float.
+
+        Args:
+            value (float): The provided value.
+
+        Raises:
+            ValueError: If the `value` is not a negative float.
+        """
+        raise ValueError(f'NegativeFloatValueObject value <<<{value}>>> must be a negative float.')

value_object_pattern/usables/primitives/float/positive_float_value_object.py

@@ -2,6 +2,8 @@
 PositiveFloatValueObject value object.
 """
 
+from typing import NoReturn
+
 from value_object_pattern.decorators import validation
 
 from .float_value_object import FloatValueObject
@@ -34,4 +36,16 @@ class PositiveFloatValueObject(FloatValueObject):
             ValueError: If the `value` is not a positive float.
         """
         if value <= 0:
-            raise ValueError(f'PositiveFloatValueObject value <<<{value}>>> must be a positive float.')
+            self._raise_value_is_not_positive_float(value=value)
+
+    def _raise_value_is_not_positive_float(self, value: float) -> NoReturn:
+        """
+        Raises a ValueError if the value object `value` is not a positive float.
+
+        Args:
+            value (float): The provided value.
+
+        Raises:
+            ValueError: If the `value` is not a positive float.
+        """
+        raise ValueError(f'PositiveFloatValueObject value <<<{value}>>> must be a positive float.')

value_object_pattern/usables/primitives/integer/even_integer_value_object.py

@@ -2,6 +2,8 @@
 EvenIntegerValueObject value object.
 """
 
+from typing import NoReturn
+
 from value_object_pattern.decorators import validation
 
 from .integer_value_object import IntegerValueObject
@@ -34,4 +36,16 @@ class EvenIntegerValueObject(IntegerValueObject):
             ValueError: If the `value` is not an even number.
         """
         if value % 2 != 0:
-            raise ValueError(f'EvenIntegerValueObject value <<<{value}>>> must be an even number.')
+            self._raise_value_is_not_even_number(value=value)
+
+    def _raise_value_is_not_even_number(self, value: int) -> NoReturn:
+        """
+        Raises a ValueError if the value object `value` is not an even number.
+
+        Args:
+            value (int): The provided value.
+
+        Raises:
+            ValueError: If the `value` is not an even number.
+        """
+        raise ValueError(f'EvenIntegerValueObject value <<<{value}>>> must be an even number.')

value_object_pattern/usables/primitives/integer/integer_value_object.py

@@ -2,6 +2,8 @@
 IntegerValueObject value object.
 """
 
+from typing import Any, NoReturn
+
 from value_object_pattern.decorators import validation
 from value_object_pattern.models import ValueObject
 
@@ -33,4 +35,16 @@ class IntegerValueObject(ValueObject[int]):
             TypeError: If the `value` is not an integer.
         """
         if type(value) is not int:
-            raise TypeError(f'IntegerValueObject value <<<{value}>>> must be an integer. Got <<<{type(value).__name__}>>> type.')  # noqa: E501  # fmt: skip
+            self._raise_value_is_not_integer(value=value)
+
+    def _raise_value_is_not_integer(self, value: Any) -> NoReturn:
+        """
+        Raises a TypeError if the value object `value` is not an integer.
+
+        Args:
+            value (Any): The provided value.
+
+        Raises:
+            TypeError: If the `value` is not an integer.
+        """
+        raise TypeError(f'IntegerValueObject value <<<{value}>>> must be an integer. Got <<<{type(value).__name__}>>> type.')  # noqa: E501  # fmt: skip

value_object_pattern/usables/primitives/integer/negative_integer_value_object.py

@@ -2,6 +2,8 @@
 NegativeIntegerValueObject value object.
 """
 
+from typing import NoReturn
+
 from value_object_pattern.decorators import validation
 
 from .integer_value_object import IntegerValueObject
@@ -34,4 +36,16 @@ class NegativeIntegerValueObject(IntegerValueObject):
             ValueError: If the `value` is not a negative integer.
         """
         if value >= 0:
-            raise ValueError(f'NegativeIntegerValueObject value <<<{value}>>> must be a negative integer.')
+            self._raise_value_is_not_negative_integer(value=value)
+
+    def _raise_value_is_not_negative_integer(self, value: int) -> NoReturn:
+        """
+        Raises a ValueError if the value object `value` is not a negative integer.
+
+        Args:
+            value (int): The provided value.
+
+        Raises:
+            ValueError: If the `value` is not a negative integer.
+        """
+        raise ValueError(f'NegativeIntegerValueObject value <<<{value}>>> must be a negative integer.')

value_object_pattern/usables/primitives/integer/odd_integer_value_object.py

@@ -2,6 +2,8 @@
 OddIntegerValueObject value object.
 """
 
+from typing import NoReturn
+
 from value_object_pattern.decorators import validation
 
 from .integer_value_object import IntegerValueObject
@@ -34,4 +36,16 @@ class OddIntegerValueObject(IntegerValueObject):
             ValueError: If the `value` is not an odd number.
         """
         if value % 2 == 0:
-            raise ValueError(f'OddIntegerValueObject value <<<{value}>>> must be an odd number.')
+            self._raise_value_is_not_odd_number(value=value)
+
+    def _raise_value_is_not_odd_number(self, value: int) -> NoReturn:
+        """
+        Raises a ValueError if the value object `value` is not an odd number.
+
+        Args:
+            value (int): The provided value.
+
+        Raises:
+            ValueError: If the `value` is not an odd number.
+        """
+        raise ValueError(f'OddIntegerValueObject value <<<{value}>>> must be an odd number.')

value_object_pattern/usables/primitives/integer/positive_integer_value_object.py

@@ -2,6 +2,8 @@
 PositiveIntegerValueObject value object.
 """
 
+from typing import NoReturn
+
 from value_object_pattern.decorators import validation
 
 from .integer_value_object import IntegerValueObject
@@ -34,4 +36,16 @@ class PositiveIntegerValueObject(IntegerValueObject):
             ValueError: If the `value` is not a positive integer.
         """
         if value <= 0:
-            raise ValueError(f'PositiveIntegerValueObject value <<<{value}>>> must be a positive integer.')
+            self._raise_value_is_not_positive_integer(value=value)
+
+    def _raise_value_is_not_positive_integer(self, value: int) -> NoReturn:
+        """
+        Raises a ValueError if the value object `value` is not a positive integer.
+
+        Args:
+            value (int): The provided value.
+
+        Raises:
+            ValueError: If the `value` is not a positive integer.
+        """
+        raise ValueError(f'PositiveIntegerValueObject value <<<{value}>>> must be a positive integer.')