value-object-pattern 1.15.1__tar.gz → 1.17.0__tar.gz

{value_object_pattern-1.15.1 → value_object_pattern-1.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: value-object-pattern
-Version: 1.15.1
+Version: 1.17.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-1.15.1 → value_object_pattern-1.17.0}/value_object_pattern/__init__.py

@@ -1,4 +1,4 @@
-__version__ = '1.15.1'
+__version__ = '1.17.0'
 
 from .decorators import process, validation
 from .models import BaseModel, EnumerationValueObject, ValueObject

{value_object_pattern-1.15.1 → value_object_pattern-1.17.0}/value_object_pattern/models/base_model.py

@@ -15,7 +15,7 @@ from abc import ABC, abstractmethod
 from copy import deepcopy
 from enum import Enum
 from inspect import Parameter, _empty, signature
-from typing import Any, NoReturn, Self
+from typing import Any, NoReturn
 
 from .value_object import ValueObject
 
@@ -307,7 +307,7 @@ class BaseModel(ABC):
         return dictionary
 
     @classmethod
-    def from_primitives(cls, primitives: dict[str, Any]) -> Self:
+    def from_primitives(cls, primitives: dict[str, Any]) -> BaseModel:
         """
         Create an instance of the class with a dictionary of its primitives.
 
@@ -319,7 +319,7 @@ class BaseModel(ABC):
             ValueError: If the `primitives` does not have all the required attributes.
 
         Returns:
-            Self: Instance of the class.
+            BaseModel: Instance of the class.
 
         Example:
         ```python

{value_object_pattern-1.15.1 → value_object_pattern-1.17.0}/value_object_pattern/models/collections/list_value_object.py

@@ -2,6 +2,8 @@
 ListValueObject module.
 """
 
+from __future__ import annotations
+
 from sys import version_info
 
 if version_info >= (3, 12):
@@ -12,7 +14,7 @@ else:
 from collections.abc import Iterator
 from enum import Enum
 from inspect import isclass
-from typing import Any, Generic, NoReturn, Self, TypeVar, get_args, get_origin
+from typing import Any, Generic, NoReturn, TypeVar, get_args, get_origin
 
 from value_object_pattern.decorators import validation
 from value_object_pattern.models import BaseModel, ValueObject
@@ -350,8 +352,324 @@ class ListValueObject(ValueObject[list[T]], Generic[T]):  # noqa: UP046
         """
         return not self._value
 
+    def add(self, *, item: T) -> ListValueObject[T]:
+        """
+        Returns a new ListValueObject with the item added to the end.
+
+        Args:
+            item (T): The item to add.
+
+        Returns:
+            ListValueObject[T]: A new ListValueObject with the item added.
+
+        Example:
+        ```python
+        from value_object_pattern.models.collections import ListValueObject
+
+
+        class IntListValueObject(ListValueObject[int]):
+            pass
+
+
+        sequence = IntListValueObject(value=[1, 2, 3])
+        new_sequence = sequence.add(item=4)
+        print(new_sequence)
+        print(id(sequence) == id(new_sequence))
+        # >>> [1, 2, 3, 4]
+        # >>> False
+        ```
+        """
+        return self.__class__(value=[*self._value, item])
+
+    def add_from_primitives(self, *, item: Any) -> ListValueObject[T]:
+        """
+        Returns a new ListValueObject with the item created from a primitives added to the end.
+
+        Args:
+            item (Any): The primitives item to convert and add.
+
+        Returns:
+            ListValueObject[T]: A new ListValueObject with the item added.
+
+        Example:
+        ```python
+        from value_object_pattern.models import ValueObject
+        from value_object_pattern.models.collections import ListValueObject
+
+
+        class Age(ValueObject[int]):
+            pass
+
+
+        class AgeListValueObject(ListValueObject[Age]):
+            pass
+
+
+        sequence = AgeListValueObject(value=[Age(value=10), Age(value=20)])
+        new_sequence = sequence.add_from_primitives(item=30)
+        print(new_sequence)
+        print(id(sequence) == id(new_sequence))
+        # >>> [10, 20, 30]
+        # >>> False
+        ```
+        """
+        item = self._convert_from_primitives(value=item)
+
+        return self.add(item=item)
+
+    def extend(self, *, items: list[T]) -> ListValueObject[T]:
+        """
+        Returns a new ListValueObject with multiple items added to the end.
+
+        Args:
+            items (list[T]): The items to add.
+
+        Returns:
+            ListValueObject[T]: A new ListValueObject with the items added.
+
+        Example:
+        ```python
+        from value_object_pattern.models.collections import ListValueObject
+
+
+        class IntListValueObject(ListValueObject[int]):
+            pass
+
+
+        sequence = IntListValueObject(value=[1, 2, 3])
+        new_sequence = sequence.extend(items=[4, 5, 6])
+        print(new_sequence)
+        print(id(sequence) == id(new_sequence))
+        # >>> [1, 2, 3, 4, 5, 6]
+        # >>> False
+        ```
+        """
+        return self.__class__(value=self._value + items)
+
+    def extend_from_primitives(self, *, items: list[Any]) -> ListValueObject[T]:
+        """
+        Returns a new ListValueObject with multiple items created from primitives added to the end.
+
+        Args:
+            items (list[Any]): The primitive items to convert and add.
+
+        Returns:
+            ListValueObject[T]: A new ListValueObject with the items added.
+
+        Example:
+        ```python
+        from value_object_pattern.models import ValueObject
+        from value_object_pattern.models.collections import ListValueObject
+
+
+        class Age(ValueObject[int]):
+            pass
+
+
+        class AgeListValueObject(ListValueObject[Age]):
+            pass
+
+
+        sequence = AgeListValueObject(value=[Age(value=10)])
+        new_sequence = sequence.extend_from_primitives(items=[20, 30])
+        print(new_sequence)
+        print(id(sequence) == id(new_sequence))
+        # >>> [10, 20, 30]
+        # >>> False
+        ```
+        """
+        items = [self._convert_from_primitives(value=item) for item in items]
+
+        return self.extend(items=items)
+
+    def delete(self, *, item: T) -> ListValueObject[T]:
+        """
+        Returns a new ListValueObject with the first occurrence of the item deleted.
+
+        Args:
+            item (T): The item to delete.
+
+        Raises:
+            ValueError: If the item is not in the list.
+
+        Returns:
+            ListValueObject[T]: A new ListValueObject with the item deleted.
+
+        Example:
+        ```python
+        from value_object_pattern.models.collections import ListValueObject
+
+
+        class IntListValueObject(ListValueObject[int]):
+            pass
+
+
+        sequence = IntListValueObject(value=[1, 2, 3, 2])
+        new_sequence = sequence.delete(item=2)
+        print(new_sequence)
+        print(id(sequence) == id(new_sequence))
+        # >>> [1, 3, 2]
+        # >>> False
+        ```
+        """
+        items = self._value.copy()
+
+        try:
+            items.remove(item)
+
+        except ValueError:
+            self._raise_value_not_found_when_deleting(value=item)
+
+        return self.__class__(value=items)
+
+    def _raise_value_not_found_when_deleting(self, value: Any) -> NoReturn:
+        """
+        Raises a ValueError if the item to be deleted is not found.
+
+        Args:
+            value (Any): The item to be deleted.
+
+        Raises:
+            ValueError: If the item is not found.
+        """
+        raise ValueError(f'ListValueObject item <<<{value}>>> not found in thelist when attempting to delete it.')
+
+    def delete_from_primitives(self, *, item: Any) -> ListValueObject[T]:
+        """
+        Returns a new ListValueObject with the first occurrence of an item matching the primitive deleted.
+
+        Args:
+            item (Any): The primitive value to convert and delete.
+
+        Raises:
+            ValueError: If the item is not in the list.
+
+        Returns:
+            ListValueObject[T]: A new ListValueObject with the item deleted.
+
+        Example:
+        ```python
+        from value_object_pattern.models import ValueObject
+        from value_object_pattern.models.collections import ListValueObject
+
+
+        class Age(ValueObject[int]):
+            pass
+
+
+        class AgeListValueObject(ListValueObject[Age]):
+            pass
+
+
+        sequence = AgeListValueObject(value=[Age(value=10), Age(value=20)])
+        new_sequence = sequence.delete_from_primitives(item=10)
+        print(new_sequence)
+        print(id(sequence) == id(new_sequence))
+        # >>> [20]
+        # >>> False
+        ```
+        """
+        item = self._convert_from_primitives(value=item)
+
+        return self.delete(item=item)
+
+    def delete_all(self, *, items: list[T]) -> ListValueObject[T]:
+        """
+        Returns a new ListValueObject with all occurrences of the specified items deleted.
+
+        Args:
+            items (list[T]): The items to delete.
+
+        Raises:
+            ValueError: If any item is not in the list.
+
+        Returns:
+            ListValueObject[T]: A new ListValueObject with the items deleted.
+
+        Example:
+        ```python
+        from value_object_pattern.models.collections import ListValueObject
+
+
+        class IntListValueObject(ListValueObject[int]):
+            pass
+
+
+        sequence = IntListValueObject(value=[1, 2, 3, 2, 4])
+        new_sequence = sequence.delete_all(items=[2, 4])
+        print(new_sequence)
+        print(id(sequence) == id(new_sequence))
+        # >>> [1, 3]
+        # >>> False
+        ```
+        """
+        new_list = [item for item in self._value if item not in items]
+
+        for item in items:
+            if item not in self._value:
+                self._raise_value_not_found_when_deleting(value=item)
+
+        return self.__class__(value=new_list)
+
+    def delete_all_from_primitives(self, *, items: list[Any]) -> ListValueObject[T]:
+        """
+        Returns a new ListValueObject with all occurrences of items matching the primitives deleted.
+
+        Args:
+            items (list[Any]): The primitive values to convert and delete.
+
+        Raises:
+            ValueError: If any item is not in the list.
+
+        Returns:
+            ListValueObject[T]: A new ListValueObject with the items deleted.
+
+        Example:
+        ```python
+        from value_object_pattern.models.collections import ListValueObject
+        from value_object_pattern.models import ValueObject
+
+
+        class Age(ValueObject[int]):
+            pass
+
+
+        class AgeListValueObject(ListValueObject[Age]):
+            pass
+
+
+        sequence = AgeListValueObject(value=[Age(value=10), Age(value=20), Age(value=30)])
+        new_sequence = sequence.delete_all_from_primitives(items=[10, 30])
+        print(new_sequence)
+        print(id(sequence) == id(new_sequence))
+        # >>> [20]
+        # >>> False
+        ```
+        """
+        items = [self._convert_from_primitives(value=item) for item in items]
+
+        return self.delete_all(items=items)
+
+    def _convert_from_primitives(self, *, value: Any) -> T:
+        """
+        Converts a primitive value to the appropriate type T.
+
+        Args:
+            value (Any): The primitive value to convert.
+
+        Returns:
+            T: The converted value.
+        """
+        if hasattr(self._type, 'from_primitives'):
+            return self._type.from_primitives(value)  # type: ignore[no-any-return]
+
+        if hasattr(self._type, 'value'):
+            return self._type(value=value)  # type: ignore[no-any-return]
+
+        return value  # type: ignore[no-any-return]
+
     @classmethod
-    def from_primitives(cls, value: list[Any]) -> Self:
+    def from_primitives(cls, value: list[Any]) -> ListValueObject[T]:
         """
         Creates a ListValueObject from a list of primitives.
 
@@ -359,18 +677,18 @@ class ListValueObject(ValueObject[list[T]], Generic[T]):  # noqa: UP046
             value (list[Any]): The list of primitives.
 
         Returns:
-            Self: The created ListValueObject.
+            ListValueObject[T]: The created ListValueObject.
         """
         items: list[Any] = []
 
-        for primitive in value:
+        for item in value:
             if hasattr(cls._type, 'from_primitives'):
-                items.append(cls._type.from_primitives(primitive))  # BaseModel
+                items.append(cls._type.from_primitives(item))  # BaseModel
 
             elif hasattr(cls._type, 'value'):
-                items.append(cls._type(value=primitive))  # ValueObject
+                items.append(cls._type(value=item))  # ValueObject
 
             else:
-                items.append(primitive)
+                items.append(item)
 
         return cls(value=items)

value_object_pattern-1.17.0/value_object_pattern/usables/identifiers/__init__.py

@@ -0,0 +1,37 @@
+from .uuid import (
+    StringUuidV1ValueObject,
+    StringUuidV3ValueObject,
+    StringUuidV4ValueObject,
+    StringUuidV5ValueObject,
+    StringUuidV6ValueObject,
+    StringUuidV7ValueObject,
+    StringUuidV8ValueObject,
+    StringUuidValueObject,
+    UuidV1ValueObject,
+    UuidV3ValueObject,
+    UuidV4ValueObject,
+    UuidV5ValueObject,
+    UuidV6ValueObject,
+    UuidV7ValueObject,
+    UuidV8ValueObject,
+    UuidValueObject,
+)
+
+__all__ = (
+    'StringUuidV1ValueObject',
+    'StringUuidV3ValueObject',
+    'StringUuidV4ValueObject',
+    'StringUuidV5ValueObject',
+    'StringUuidV6ValueObject',
+    'StringUuidV7ValueObject',
+    'StringUuidV8ValueObject',
+    'StringUuidValueObject',
+    'UuidV1ValueObject',
+    'UuidV3ValueObject',
+    'UuidV4ValueObject',
+    'UuidV5ValueObject',
+    'UuidV6ValueObject',
+    'UuidV7ValueObject',
+    'UuidV8ValueObject',
+    'UuidValueObject',
+)

value_object_pattern-1.17.0/value_object_pattern/usables/identifiers/uuid/__init__.py

@@ -0,0 +1,35 @@
+from .string_uuid_v1_value_object import StringUuidV1ValueObject
+from .string_uuid_v3_value_object import StringUuidV3ValueObject
+from .string_uuid_v4_value_object import StringUuidV4ValueObject
+from .string_uuid_v5_value_object import StringUuidV5ValueObject
+from .string_uuid_v6_value_object import StringUuidV6ValueObject
+from .string_uuid_v7_value_object import StringUuidV7ValueObject
+from .string_uuid_v8_value_object import StringUuidV8ValueObject
+from .string_uuid_value_object import StringUuidValueObject
+from .uuid_v1_value_object import UuidV1ValueObject
+from .uuid_v3_value_object import UuidV3ValueObject
+from .uuid_v4_value_object import UuidV4ValueObject
+from .uuid_v5_value_object import UuidV5ValueObject
+from .uuid_v6_value_object import UuidV6ValueObject
+from .uuid_v7_value_object import UuidV7ValueObject
+from .uuid_v8_value_object import UuidV8ValueObject
+from .uuid_value_object import UuidValueObject
+
+__all__ = (
+    'StringUuidV1ValueObject',
+    'StringUuidV3ValueObject',
+    'StringUuidV4ValueObject',
+    'StringUuidV5ValueObject',
+    'StringUuidV6ValueObject',
+    'StringUuidV7ValueObject',
+    'StringUuidV8ValueObject',
+    'StringUuidValueObject',
+    'UuidV1ValueObject',
+    'UuidV3ValueObject',
+    'UuidV4ValueObject',
+    'UuidV5ValueObject',
+    'UuidV6ValueObject',
+    'UuidV7ValueObject',
+    'UuidV8ValueObject',
+    'UuidValueObject',
+)

value_object_pattern-1.17.0/value_object_pattern/usables/identifiers/uuid/string_uuid_v1_value_object.py

@@ -0,0 +1,52 @@
+"""
+StringUuidV1ValueObject value object.
+"""
+
+from typing import NoReturn
+from uuid import UUID
+
+from value_object_pattern.decorators import validation
+
+from .string_uuid_value_object import StringUuidValueObject
+
+
+class StringUuidV1ValueObject(StringUuidValueObject):
+    """
+    StringUuidV1ValueObject value object ensures the provided value is a valid UUID version 1.
+
+    Example:
+    ```python
+    from value_object_pattern.usables.identifiers import StringUuidV1ValueObject
+
+    uuid = StringUuidV1ValueObject(value='53734b8c-d517-11f0-a57a-452bbcae0235')
+    print(repr(uuid))
+    # >>> StringUuidV1ValueObject(value=53734b8c-d517-11f0-a57a-452bbcae0235)
+    ```
+    """
+
+    @validation(order=1)
+    def _ensure_value_is_uuid1(self, value: str) -> None:
+        """
+        Ensures the value object `value` is a UUID version 1.
+
+        Args:
+            value (str): The provided value.
+
+        Raises:
+            ValueError: If the `value` is not a UUID version 1.
+        """
+        uuid_object = UUID(value)
+        if uuid_object.version != 1:
+            self._raise_value_is_not_uuid1(value=value)
+
+    def _raise_value_is_not_uuid1(self, value: str) -> NoReturn:
+        """
+        Raises a ValueError if the value object `value` is not a UUID version 1.
+
+        Args:
+            value (str): The provided value.
+
+        Raises:
+            ValueError: If the `value` is not a UUID version 1.
+        """
+        raise ValueError(f'StringUuidV1ValueObject value <<<{value}>>> must be a UUID version 1. Got version <<<{UUID(value).version}>>>.')  # noqa: E501  # fmt: skip

value_object_pattern-1.17.0/value_object_pattern/usables/identifiers/uuid/string_uuid_v3_value_object.py

@@ -0,0 +1,52 @@
+"""
+StringUuidV3ValueObject value object.
+"""
+
+from typing import NoReturn
+from uuid import UUID
+
+from value_object_pattern.decorators import validation
+
+from .string_uuid_value_object import StringUuidValueObject
+
+
+class StringUuidV3ValueObject(StringUuidValueObject):
+    """
+    StringUuidV3ValueObject value object ensures the provided value is a valid UUID version 3.
+
+    Example:
+    ```python
+    from value_object_pattern.usables.identifiers import StringUuidV3ValueObject
+
+    uuid = StringUuidV3ValueObject(value='9073926b-929f-31c2-abc9-fad77ae3e8eb')
+    print(repr(uuid))
+    # >>> StringUuidV3ValueObject(value=9073926b-929f-31c2-abc9-fad77ae3e8eb)
+    ```
+    """
+
+    @validation(order=1)
+    def _ensure_value_is_uuid3(self, value: str) -> None:
+        """
+        Ensures the value object `value` is a UUID version 3.
+
+        Args:
+            value (str): The provided value.
+
+        Raises:
+            ValueError: If the `value` is not a UUID version 3.
+        """
+        uuid_object = UUID(value)
+        if uuid_object.version != 3:
+            self._raise_value_is_not_uuid3(value=value)
+
+    def _raise_value_is_not_uuid3(self, value: str) -> NoReturn:
+        """
+        Raises a ValueError if the value object `value` is not a UUID version 3.
+
+        Args:
+            value (str): The provided value.
+
+        Raises:
+            ValueError: If the `value` is not a UUID version 3.
+        """
+        raise ValueError(f'StringUuidV3ValueObject value <<<{value}>>> must be a UUID version 3. Got version <<<{UUID(value).version}>>>.')  # noqa: E501  # fmt: skip

{value_object_pattern-1.15.1 → value_object_pattern-1.17.0}/value_object_pattern/usables/identifiers/uuid/string_uuid_v4_value_object.py

@@ -18,10 +18,9 @@ class StringUuidV4ValueObject(StringUuidValueObject):
     ```python
     from value_object_pattern.usables.identifiers import StringUuidV4ValueObject
 
-    uuid = StringUuidV4ValueObject(value='9908bb2d-54b4-426f-bef0-b09aa978ed21')
-
+    uuid = StringUuidV4ValueObject(value='3e9e0f3a-64a3-474f-9127-368e723f389f')
     print(repr(uuid))
-    # >>> StringUuidV4ValueObject(value=9908bb2d-54b4-426f-bef0-b09aa978ed21)
+    # >>> StringUuidV4ValueObject(value=3e9e0f3a-64a3-474f-9127-368e723f389f)
     ```
     """
 
@@ -36,7 +35,7 @@ class StringUuidV4ValueObject(StringUuidValueObject):
         Raises:
             ValueError: If the `value` is not a UUID version 4.
         """
-        uuid_object = UUID(hex=value)
+        uuid_object = UUID(value)
         if uuid_object.version != 4:
             self._raise_value_is_not_uuid4(value=value)
 
@@ -50,4 +49,4 @@ class StringUuidV4ValueObject(StringUuidValueObject):
         Raises:
             ValueError: If the `value` is not a UUID version 4.
         """
-        raise ValueError(f'StringUuidV4ValueObject value <<<{value}>>> must be a UUID version 4. Got version <<<{UUID(hex=value).version}>>>.')  # noqa: E501  # fmt: skip
+        raise ValueError(f'StringUuidV4ValueObject value <<<{value}>>> must be a UUID version 4. Got version <<<{UUID(value).version}>>>.')  # noqa: E501  # fmt: skip

value_object_pattern-1.17.0/value_object_pattern/usables/identifiers/uuid/string_uuid_v5_value_object.py

@@ -0,0 +1,52 @@
+"""
+StringUuidV5ValueObject value object.
+"""
+
+from typing import NoReturn
+from uuid import UUID
+
+from value_object_pattern.decorators import validation
+
+from .string_uuid_value_object import StringUuidValueObject
+
+
+class StringUuidV5ValueObject(StringUuidValueObject):
+    """
+    StringUuidV5ValueObject value object ensures the provided value is a valid UUID version 5.
+
+    Example:
+    ```python
+    from value_object_pattern.usables.identifiers import StringUuidV5ValueObject
+
+    uuid = StringUuidV5ValueObject(value='cfbff0d1-9375-5685-968c-48ce8b15ae17')
+    print(repr(uuid))
+    # >>> StringUuidV5ValueObject(value=cfbff0d1-9375-5685-968c-48ce8b15ae17)
+    ```
+    """
+
+    @validation(order=1)
+    def _ensure_value_is_uuid5(self, value: str) -> None:
+        """
+        Ensures the value object `value` is a UUID version 5.
+
+        Args:
+            value (str): The provided value.
+
+        Raises:
+            ValueError: If the `value` is not a UUID version 5.
+        """
+        uuid_object = UUID(value)
+        if uuid_object.version != 5:
+            self._raise_value_is_not_uuid5(value=value)
+
+    def _raise_value_is_not_uuid5(self, value: str) -> NoReturn:
+        """
+        Raises a ValueError if the value object `value` is not a UUID version 5.
+
+        Args:
+            value (str): The provided value.
+
+        Raises:
+            ValueError: If the `value` is not a UUID version 5.
+        """
+        raise ValueError(f'StringUuidV5ValueObject value <<<{value}>>> must be a UUID version 5. Got version <<<{UUID(value).version}>>>.')  # noqa: E501  # fmt: skip