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

value_object_pattern/__init__.py

@@ -0,0 +1,10 @@
+__version__ = '0.1.0'
+
+from .decorators import process, validation
+from .models import ValueObject
+
+__all__ = (
+    'ValueObject',
+    'process',
+    'validation',
+)

value_object_pattern/decorators/__init__.py

@@ -0,0 +1,7 @@
+from .value_object_process import process
+from .value_object_validation import validation
+
+__all__ = (
+    'process',
+    'validation',
+)

value_object_pattern/decorators/value_object_process.py

@@ -0,0 +1,83 @@
+"""
+Process decorator for value object pattern.
+"""
+
+from functools import wraps
+from typing import Any, Callable, TypeVar
+
+T = TypeVar('T')
+
+
+def process(order: int | None = None) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """
+    Decorator for process the value after the value is validated.
+
+    Args:
+        order (int | None, optional): The order of the process that will be executed, if None the functions will be
+        executed alphabetically. Defaults to None.
+
+    Raises:
+        TypeError: If the order is not an integer.
+        ValueError: If the order is not equal or greater than 0.
+
+    Returns:
+        Callable[[Callable[..., T]], Callable[..., T]]: Wrapper function for the process.
+
+    Example:
+    ```python
+    from value_object_pattern import ValueObject, process
+
+
+    class UpperStringValueObject(ValueObject[str]):
+        @process()
+        def ensure_value_is_upper(self, value: str) -> str:
+            return value.upper()
+
+
+    string = UpperStringValueObject(value='hello world')
+    print(string)
+    # >>> HELLO WORLD
+    ```
+    """
+
+    def decorator(function: Callable[..., T]) -> Callable[..., T]:
+        """
+        Decorator for process the value after the value is validated.
+
+        Args:
+            function (Callable[..., T]): Function to be execution after the value object is validated.
+
+        Raises:
+            TypeError: If the order is not an integer.
+            ValueError: If the order is not equal or greater than 0.
+
+        Returns:
+            Callable[..., T]: Wrapper function for the process.
+        """
+        if order is not None:
+            if type(order) is not int:
+                raise TypeError(f'Process order <<<{order}>>> must be an integer. Got <<<{type(order).__name__}>>> type.')  # noqa: E501  # fmt: skip
+
+            if order < 0:
+                raise ValueError(f'Process order <<<{order}>>> must be equal or greater than 0.')
+
+        function._is_process = True  # type: ignore[attr-defined]
+        function._order = function.__name__ if order is None else str(order)  # type: ignore[attr-defined]
+
+        @wraps(wrapped=function)
+        def wrapper(*args: tuple[Any, ...], **kwargs: dict[str, Any]) -> T:
+            """
+            Wrapper for process.
+
+            Args:
+                *args (tuple[Any, ...]): The arguments for the function.
+                **kwargs (dict[str, Any]): The keyword arguments for the function.
+
+            Returns:
+                T: The return value of the function.
+            """
+            return function(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

value_object_pattern/decorators/value_object_validation.py

@@ -0,0 +1,78 @@
+"""
+Validation decorator for value object pattern.
+"""
+
+from functools import wraps
+from typing import Any, Callable
+
+
+def validation(order: int | None = None) -> Callable[[Callable[..., None]], Callable[..., None]]:
+    """
+    Decorator for validation the value before the value is created.
+
+    Args:
+        order (int | None, optional): The order of the validation that will be executed, if None the functions will be
+        executed alphabetically. Defaults to None.
+
+    Raises:
+        TypeError: If the order is not an integer.
+        ValueError: If the order is not equal or greater than 0.
+
+    Returns:
+        Callable[[Callable[..., None]], Callable[..., None]]: Wrapper function for the validation.
+
+    Example:
+    ```python
+    from value_object_pattern import ValueObject, validation
+
+
+    class IntegerValueObject(ValueObject[int]):
+        @validation()
+        def ensure_value_is_integer(self, value: int) -> None:
+            if type(value) is not int:
+                raise TypeError(f'IntegerValueObject value <<<{value}>>> must be an integer. Got <<<{type(value).__name__}>>> type.')
+
+
+    integer = IntegerValueObject(value='invalid')
+    # >>> TypeError: IntegerValueObject value <<<invalid>>> must be an integer. Got <<<str>>> type.
+    ```
+    """  # noqa: E501 # fmt: skip
+
+    def decorator(function: Callable[..., None]) -> Callable[..., None]:
+        """
+        Decorator for validation the value before the value is created.
+
+        Args:
+            function (Callable[..., None]): Function to be execution before the value object is created.
+
+        Raises:
+            TypeError: If the order is not an integer.
+            ValueError: If the order is not equal or greater than 0.
+
+        Returns:
+            Callable[..., None]: Wrapper function for the validation.
+        """
+        if order is not None:
+            if type(order) is not int:
+                raise TypeError(f'Validation order <<<{order}>>> must be an integer. Got <<<{type(order).__name__}>>> type.')  # noqa: E501  # fmt: skip
+
+            if order < 0:
+                raise ValueError(f'Validation order <<<{order}>>> must be equal or greater than 0.')
+
+        function._is_validation = True  # type: ignore[attr-defined]
+        function._order = function.__name__ if order is None else str(order)  # type: ignore[attr-defined]
+
+        @wraps(wrapped=function)
+        def wrapper(*args: tuple[Any, ...], **kwargs: dict[str, Any]) -> None:
+            """
+            Wrapper for validation.
+
+            Args:
+                *args (tuple[Any, ...]): The arguments for the function.
+                **kwargs (dict[str, Any]): The keyword arguments for the function.
+            """
+            function(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

value_object_pattern/models/__init__.py

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

value_object_pattern/models/value_object.py

@@ -0,0 +1,383 @@
+"""
+Value object generic type.
+"""
+
+from abc import ABC
+from collections import deque
+from sys import version_info
+from typing import Any, Callable, Generic, NoReturn, TypeVar
+
+if version_info >= (3, 12):
+    from typing import override  # pragma: no cover
+else:
+    from typing_extensions import override  # pragma: no cover
+
+T = TypeVar('T')
+
+
+class ValueObject(ABC, Generic[T]):
+    """
+    ValueObject generic type.
+
+    Example:
+    ```python
+    from value_object_pattern import ValueObject
+
+
+    class IntegerValueObject(ValueObject[int]):
+        pass
+
+
+    integer = IntegerValueObject(value=10)
+    print(repr(integer))
+    # >>> IntegerValueObject(value=10)
+    ```
+    """
+
+    __slots__ = ('_title', '_value')
+    __match_args__ = ('_title', '_value')
+
+    _value: T
+    _title: str
+
+    def __init__(self, *, value: T, title: str | None = None) -> None:
+        """
+        ValueObject value object constructor.
+
+        Args:
+            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.
+
+        Raises:
+            TypeError: If the title is not a string.
+            ValueError: If the title contains leading or trailing whitespaces.
+
+        Example:
+        ```python
+        from value_object_pattern import ValueObject
+
+
+        class IntegerValueObject(ValueObject[int]):
+            pass
+
+
+        integer = IntegerValueObject(value=10)
+        print(repr(integer))
+        # >>> IntegerValueObject(value=10)
+        ```
+        """
+        if title is None:
+            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
+
+        if title.strip() != title:
+            raise ValueError(f'ValueObject title <<<{title}>>> contains leading or trailing whitespaces. Only trimmed values are allowed.')  # noqa: E501  # fmt: skip
+
+        object.__setattr__(self, '_title', title)
+
+        self._validate(value=value)
+        value = self._process(value=value)
+
+        object.__setattr__(self, '_value', value)
+
+    @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 value_object_pattern import ValueObject
+
+
+        class IntegerValueObject(ValueObject[int]):
+            pass
+
+
+        integer = IntegerValueObject(value=10)
+        print(repr(integer))
+        # >>> IntegerValueObject(value=10)
+        ```
+        """
+        return f'{self.__class__.__name__}(value={self._value!s})'
+
+    @override
+    def __str__(self) -> str:
+        """
+        Returns a simple string representation of the value object.
+
+        Returns:
+            str: The string representation of the value object value.
+
+        Example:
+        ```python
+        from value_object_pattern import ValueObject
+
+
+        class IntegerValueObject(ValueObject[int]):
+            pass
+
+
+        integer = IntegerValueObject(value=10)
+        print(integer)
+        # >>> 10
+        ```
+        """
+        return str(object=self._value)
+
+    @override
+    def __hash__(self) -> int:
+        """
+        Returns the hash of the value object.
+
+        Returns:
+            int: Hash of the value object.
+
+        Example:
+        ```python
+        from value_object_pattern import ValueObject
+
+
+        class IntegerValueObject(ValueObject[int]):
+            pass
+
+
+        integer = IntegerValueObject(value=10)
+        print(hash(integer))
+        # >>> 10
+        ```
+        """
+        return hash(self._value)
+
+    @override
+    def __eq__(self, other: object) -> bool:
+        """
+        Check if the value object is equal to another value object.
+
+        Args:
+            other (object): Object to compare.
+
+        Returns:
+            bool: True if both objects are equal, otherwise False.
+
+        Example:
+        ```python
+        from value_object_pattern import ValueObject
+
+
+        class IntegerValueObject(ValueObject[int]):
+            pass
+
+
+        integer_a = IntegerValueObject(value=10)
+        integer_b = IntegerValueObject(value=16)
+        print(integer_a == integer_b)
+        # >>> False
+        ```
+        """
+        if not isinstance(other, self.__class__):
+            return NotImplemented
+
+        return self._value == other.value
+
+    @override
+    def __setattr__(self, key: str, value: T) -> NoReturn:
+        """
+        Prevents modification or addition of attributes in the value object.
+
+        Args:
+            key (str): The name of the attribute.
+            value (T): The value to be assigned to the attribute.
+
+        Raises:
+            AttributeError: If there is an attempt to modify an existing attribute.
+            AttributeError: If there is an attempt to add a new attribute.
+        """
+        public_key = key.replace('_', '')
+        public_slots1 = [slot.replace('_', '') for slot in self.__slots__]
+
+        if key in self.__slots__:
+            raise AttributeError(f'Cannot modify attribute "{key}" of immutable instance.')
+
+        if public_key in public_slots1:
+            raise AttributeError(f'Cannot modify attribute "{public_key}" of immutable instance.')
+
+        raise AttributeError(f'{self.__class__.__name__} object has no attribute "{key}".')
+
+    def _process(self, value: T) -> T:
+        """
+        This method processes the value object value after validation. It ensure that the value object is stored in the
+        correct format, by executing all methods with the `@process` decorator.
+
+        Args:
+            value (T): The value object value.
+
+        Returns:
+            T: The processed value object value.
+        """
+        methods = self._gather_decorated_methods(instance=self, attribute_name='_is_process')
+        while methods:
+            method: Callable[..., T] = methods.popleft().__get__(self, self.__class__)
+            value = method(value=value)
+
+        return value
+
+    def _validate(self, value: T) -> None:
+        """
+        This method validates that the value follows the domain rules, by executing all methods with the `@validation`
+        decorator.
+
+        Args:
+            value (T): The value object value.
+        """
+        try:
+            methods = self._gather_decorated_methods(instance=self, attribute_name='_is_validation')
+            while methods:
+                method: Callable[..., T] = methods.popleft().__get__(self, self.__class__)
+                method(value=value)
+
+        except Exception as error:
+            classes = self._post_order_dfs_mro(cls=self.__class__, cut_off=ValueObject)
+            for class_name in {cls.__name__ for cls in classes}:
+                error.args = (str(object=error.args[0]).replace(class_name, self.title),)
+
+            raise error
+
+    def _post_order_dfs_mro(self, cls: type, visited: set[type] | None = None, cut_off: type = object) -> list[type]:
+        """
+        Computes the Post-Order Depth-First Search (DFS) Method Resolution Order (MRO) of a class.
+
+        Args:
+            cls (type): The class to process.
+            visited (set[type] | None, optional): A set of already visited classes (to prevent duplicates). Defaults
+            to None.
+            cut_off (type, optional): The class to stop the search. Defaults to object.
+
+        Returns:
+            list[type]: A list of classes type sorted by post-order DFS MRO.
+
+        References:
+            DFS: https://en.wikipedia.org/wiki/Depth-first_search
+            MRO: https://docs.python.org/3/howto/mro.html
+        """
+        if cls is cut_off:
+            return []
+
+        if visited is None:
+            visited = set()
+
+        result = []
+        for parent in cls.__bases__:
+            if parent not in visited and parent is not object:  # pragma: no cover
+                result.extend(self._post_order_dfs_mro(cls=parent, visited=visited, cut_off=cut_off))
+
+        if cls not in visited:  # pragma: no cover
+            visited.add(cls)
+            result.append(cls)
+
+        return result
+
+    def _gather_decorated_methods(self, instance: object, attribute_name: str) -> deque[Callable[..., Any]]:
+        """
+        Gathers decorated methods from instance.__class__ and its parent classes following the post-order DFS MRO,
+        returning them in a deque with the methods sorted by class hierarchy, method order, and method name.
+
+        Args:
+            instance (object): The object instance whose class hierarchy is inspected.
+            attribute_name (str): The attribute name used to identify the methods.
+
+        Returns
+            deque[Callable[..., Any]]: A deque of methods sorted by class hierarchy, method order, and method name.
+
+        References:
+            DFS: https://en.wikipedia.org/wiki/Depth-first_search
+            MRO: https://docs.python.org/3/howto/mro.html
+        """
+
+        def sort_key(item: tuple[str, str, Callable[..., Any]]) -> tuple[int, str, str]:
+            """
+            Sorts the methods by class hierarchy, method order attribute, and method name.
+            The only global variable used is classes_names.
+
+            Args:
+                item (tuple[str, str, Callable[..., Any]]): The item to sort.
+
+            Returns:
+                tuple[int, str, str]: A tuple with the class index, method order, and method name.
+            """
+            class_name, method_name, method = item
+            class_index = classes_names.get(class_name, 999)
+            order = getattr(method, '_order', method_name)
+
+            return int(class_index), order, method_name
+
+        classes = self._post_order_dfs_mro(cls=instance.__class__, cut_off=ValueObject)
+        classes_names = {cls.__name__: index for index, cls in enumerate(iterable=classes)}
+
+        classes_methods: deque[tuple[str, str, Callable[..., Any]]] = deque()
+        for cls in classes:
+            for method_name, method in cls.__dict__.items():
+                if not callable(method):
+                    continue
+
+                if not getattr(method, attribute_name, False):
+                    continue  # only methods with the attribute
+
+                classes_methods.append((method.__qualname__.split('.')[0], method_name, method))
+
+        # sort by class hierarchy, method order attribute, and method name
+        return deque([method for _, _, method in sorted(classes_methods, key=sort_key)])
+
+    @property
+    def value(self) -> T:
+        """
+        Returns the value object value.
+
+        Returns:
+            T: 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
+
+    @property
+    def title(self) -> str:
+        """
+        Returns the value object title.
+
+        Returns:
+            str: The value object title.
+
+        Example:
+        ```python
+        from value_object_pattern import ValueObject
+
+
+        class IntegerValueObject(ValueObject[int]):
+            pass
+
+
+        integer = IntegerValueObject(value=10)
+        print(integer.title)
+        # >>> IntegerValueObject
+        ```
+        """
+        return self._title

value_object_pattern/usables/__init__.py

@@ -0,0 +1,54 @@
+from .primitives import (
+    AlphaStringValueObject,
+    AlphanumericStringValueObject,
+    BooleanValueObject,
+    BytesValueObject,
+    DigitStringValueObject,
+    EvenIntegerValueObject,
+    FalseValueObject,
+    FloatValueObject,
+    IntegerValueObject,
+    LowercaseStringValueObject,
+    NegativeFloatValueObject,
+    NegativeIntegerValueObject,
+    NotEmptyStringValueObject,
+    OddIntegerValueObject,
+    PositiveFloatValueObject,
+    PositiveIntegerValueObject,
+    PrintableStringValueObject,
+    StringValueObject,
+    TrimmedStringValueObject,
+    TrueValueObject,
+    UppercaseStringValueObject,
+)
+
+__all__ = (
+    'AlphaStringValueObject',
+    'AlphanumericStringValueObject',
+    'BooleanValueObject',
+    'BytesValueObject',
+    'DigitStringValueObject',
+    'EvenIntegerValueObject',
+    'FalseValueObject',
+    'FloatValueObject',
+    'HexadecimalStringValueObject',
+    'IntegerValueObject',
+    'LowercaseStringValueObject',
+    'LowercaseStringValueObject',
+    'NegativeFloatValueObject',
+    'NegativeIntegerValueObject',
+    'NotEmptyStringValueObject',
+    'NotEmptyStringValueObject',
+    'OddIntegerValueObject',
+    'PositiveFloatValueObject',
+    'PositiveIntegerValueObject',
+    'PrintableStringValueObject',
+    'PrintableStringValueObject',
+    'StringValueObject',
+    'StringValueObject',
+    'TrimmedStringValueObject',
+    'TrimmedStringValueObject',
+    'TrueValueObject',
+    'UppercaseStringValueObject',
+    'UppercaseStringValueObject',
+)

value_object_pattern/usables/dates/__init__.py

@@ -0,0 +1,9 @@
+from .date import DateValueObject, StringDateValueObject
+from .datetime import DatetimeValueObject, StringDatetimeValueObject
+
+__all__ = (
+    'DateValueObject',
+    'DatetimeValueObject',
+    'StringDateValueObject',
+    'StringDatetimeValueObject',
+)

value_object_pattern/usables/dates/date/__init__.py

@@ -0,0 +1,7 @@
+from .date_value_object import DateValueObject
+from .string_date_value_object import StringDateValueObject
+
+__all__ = (
+    'DateValueObject',
+    'StringDateValueObject',
+)