ddd-value-objects 0.1.2__tar.gz → 0.1.4__tar.gz

ddd_value_objects-0.1.4/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: ddd-value-objects
+Version: 0.1.4
+Summary: A collection of base classes for Domain-Driven Design (DDD) value objects and entities in Python
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# DDD Value Objects for Python
+
+A comprehensive collection of base classes and specialized types for implementing **Domain-Driven Design (DDD)** patterns in Python. This library provides a robust foundation for building maintainable, type-safe, and self-validating domain models using Value Objects and Entities.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/josedejesuschavez/ddd-value-objects)
+
+## Key Features
+
+- **Base Classes**: Robust base classes for both Primitive and Composite Value Objects.
+- **Immutability**: Designed to be immutable, ensuring domain integrity.
+- **Structural Equality**: Value Objects are compared by their attributes, not by identity.
+- **Self-Validation**: Built-in validation for common domain types (Emails, UUIDs, URLs, etc.).
+- **Strong Typing**: Leverages Python generics for type safety and better IDE support.
+- **Entity Support**: Base class for Entities with identity-based equality.
+
+## Installation
+
+Install using `pip`:
+
+```bash
+pip install ddd-value-objects
+```
+
+Or using `uv`:
+
+```bash
+uv add ddd-value-objects
+```
+
+## Core Concepts
+
+### Value Objects
+In DDD, a **Value Object** is an object that represents a descriptive aspect of the domain with no conceptual identity. They are defined by their attributes and are immutable. Two value objects are considered equal if all their attributes are equal.
+
+### Primitive Value Objects
+Wrap single primitive types (`str`, `int`, `float`, `bool`) to give them domain meaning.
+
+### Composite Value Objects
+Combine multiple values into a single domain concept (e.g., `Money` which consists of an `amount` and a `currency`).
+
+### Entities
+**Entities** have a unique identity that persists over time, regardless of changes to their attributes.
+
+---
+
+## Usage Examples
+
+### 1. Primitive Value Objects
+
+You can extend base classes to create domain-specific types:
+
+```python
+from ddd_value_objects import StringValueObject, PositiveIntValueObject, InvalidArgumentError
+
+class UserName(StringValueObject):
+    pass
+
+class UserAge(PositiveIntValueObject):
+    def __init__(self, value: int):
+        super().__init__(value)
+        if value > 150:
+            raise InvalidArgumentError(f"Age {value} is out of valid range (max 150)")
+
+# Usage
+name1 = UserName("Alice")
+name2 = UserName("Alice")
+age = UserAge(30)
+
+print(name1 == name2)  # True (Structural equality)
+print(name1.value)     # "Alice"
+```
+
+### 2. Specialized Value Objects
+
+The library includes many pre-built, self-validating types:
+
+```python
+from ddd_value_objects import (
+    EmailValueObject, 
+    UuidValueObject, 
+    UrlValueObject, 
+    PhoneNumberValueObject,
+    CurrencyValueObject
+)
+
+email = EmailValueObject("user@example.com")
+user_id = UuidValueObject("550e8400-e29b-41d4-a716-446655440000")
+website = UrlValueObject("https://github.com")
+currency = CurrencyValueObject("USD") # Validates ISO 4217 code
+```
+
+### 3. Composite Value Objects (e.g., Money)
+
+Handle complex types that group multiple values:
+
+```python
+from ddd_value_objects import MoneyValueObject
+
+price = MoneyValueObject(99.99, "USD")
+tax = MoneyValueObject(10.00, "USD")
+
+# Arithmetic operations (if supported by implementation)
+total = price.add(tax)
+
+print(total.amount)   # 109.99
+print(total.currency) # "USD"
+```
+
+### 4. Enum Value Objects
+
+Restrict values to a specific set using an `Enum`:
+
+```python
+from enum import Enum
+from ddd_value_objects import EnumValueObject, StringValueObject, InvalidArgumentError
+
+class UserRole(Enum):
+    ADMIN = "admin"
+    USER = "user"
+
+class RoleValueObject(EnumValueObject):
+    def __init__(self, value: str):
+        # Define the valid options
+        valid_roles = [StringValueObject(r.value) for r in UserRole]
+        
+        # Pass the current value as a ValueObject and the list of valid options
+        super().__init__(
+            StringValueObject(value), 
+            valid_roles
+        )
+
+# Usage
+try:
+    role = RoleValueObject("admin")
+    print(role.value)  # "admin"
+    
+    invalid_role = RoleValueObject("guest") # Raises InvalidArgumentError
+except InvalidArgumentError as e:
+    print(e)
+```
+
+### 5. Entities
+
+Use the `Entity` base class for objects with identity:
+
+```python
+from ddd_value_objects import Entity, UuidValueObject
+
+class Product(Entity):
+    def __init__(self, product_id: str, name: str):
+        # Entity expects a string ID which it wraps in a UuidValueObject
+        super().__init__(product_id)
+        self.name = name
+
+product1 = Product("550e8400-e29b-41d4-a716-446655440000", "Laptop")
+product2 = Product("550e8400-e29b-41d4-a716-446655440000", "Updated Laptop Name")
+
+print(product1 == product2) # True (Same identity/ID)
+```
+
+---
+
+## Available Value Objects
+
+| Category | Classes |
+| :--- | :--- |
+| **Primitives** | `StringValueObject`, `IntValueObject`, `FloatValueObject`, `BoolValueObject` |
+| **Numeric** | `PositiveIntValueObject`, `PositiveFloatValueObject` |
+| **Identity** | `UuidValueObject` |
+| **Network** | `EmailValueObject`, `UrlValueObject`, `IpAddressValueObject` |
+| **Communication** | `PhoneNumberValueObject`, `CountryCodeValueObject` (ISO 3166-1 alpha-2) |
+| **Temporal** | `DateTimeValueObject`, `DateValueObject` (Unix timestamps) |
+| **Financial** | `CurrencyValueObject` (ISO 4217), `MoneyValueObject` |
+| **Others** | `EnumValueObject`, `CompositeValueObject` |
+
+---
+
+## Development and Testing
+
+We use `uv` for dependency management and `pytest` for testing.
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/youruser/ddd-value-objects.git
+cd ddd-value-objects
+
+# Install dependencies
+uv sync
+```
+
+### Running Tests
+
+```bash
+uv run pytest
+```
+
+### Coverage Threshold
+
+This project maintains a minimum coverage threshold of **90%**. The CI workflow will automatically fail if coverage falls below this level.
+
+## License
+
+This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.

ddd_value_objects-0.1.4/README.md

@@ -0,0 +1,207 @@
+# DDD Value Objects for Python
+
+A comprehensive collection of base classes and specialized types for implementing **Domain-Driven Design (DDD)** patterns in Python. This library provides a robust foundation for building maintainable, type-safe, and self-validating domain models using Value Objects and Entities.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/josedejesuschavez/ddd-value-objects)
+
+## Key Features
+
+- **Base Classes**: Robust base classes for both Primitive and Composite Value Objects.
+- **Immutability**: Designed to be immutable, ensuring domain integrity.
+- **Structural Equality**: Value Objects are compared by their attributes, not by identity.
+- **Self-Validation**: Built-in validation for common domain types (Emails, UUIDs, URLs, etc.).
+- **Strong Typing**: Leverages Python generics for type safety and better IDE support.
+- **Entity Support**: Base class for Entities with identity-based equality.
+
+## Installation
+
+Install using `pip`:
+
+```bash
+pip install ddd-value-objects
+```
+
+Or using `uv`:
+
+```bash
+uv add ddd-value-objects
+```
+
+## Core Concepts
+
+### Value Objects
+In DDD, a **Value Object** is an object that represents a descriptive aspect of the domain with no conceptual identity. They are defined by their attributes and are immutable. Two value objects are considered equal if all their attributes are equal.
+
+### Primitive Value Objects
+Wrap single primitive types (`str`, `int`, `float`, `bool`) to give them domain meaning.
+
+### Composite Value Objects
+Combine multiple values into a single domain concept (e.g., `Money` which consists of an `amount` and a `currency`).
+
+### Entities
+**Entities** have a unique identity that persists over time, regardless of changes to their attributes.
+
+---
+
+## Usage Examples
+
+### 1. Primitive Value Objects
+
+You can extend base classes to create domain-specific types:
+
+```python
+from ddd_value_objects import StringValueObject, PositiveIntValueObject, InvalidArgumentError
+
+class UserName(StringValueObject):
+    pass
+
+class UserAge(PositiveIntValueObject):
+    def __init__(self, value: int):
+        super().__init__(value)
+        if value > 150:
+            raise InvalidArgumentError(f"Age {value} is out of valid range (max 150)")
+
+# Usage
+name1 = UserName("Alice")
+name2 = UserName("Alice")
+age = UserAge(30)
+
+print(name1 == name2)  # True (Structural equality)
+print(name1.value)     # "Alice"
+```
+
+### 2. Specialized Value Objects
+
+The library includes many pre-built, self-validating types:
+
+```python
+from ddd_value_objects import (
+    EmailValueObject, 
+    UuidValueObject, 
+    UrlValueObject, 
+    PhoneNumberValueObject,
+    CurrencyValueObject
+)
+
+email = EmailValueObject("user@example.com")
+user_id = UuidValueObject("550e8400-e29b-41d4-a716-446655440000")
+website = UrlValueObject("https://github.com")
+currency = CurrencyValueObject("USD") # Validates ISO 4217 code
+```
+
+### 3. Composite Value Objects (e.g., Money)
+
+Handle complex types that group multiple values:
+
+```python
+from ddd_value_objects import MoneyValueObject
+
+price = MoneyValueObject(99.99, "USD")
+tax = MoneyValueObject(10.00, "USD")
+
+# Arithmetic operations (if supported by implementation)
+total = price.add(tax)
+
+print(total.amount)   # 109.99
+print(total.currency) # "USD"
+```
+
+### 4. Enum Value Objects
+
+Restrict values to a specific set using an `Enum`:
+
+```python
+from enum import Enum
+from ddd_value_objects import EnumValueObject, StringValueObject, InvalidArgumentError
+
+class UserRole(Enum):
+    ADMIN = "admin"
+    USER = "user"
+
+class RoleValueObject(EnumValueObject):
+    def __init__(self, value: str):
+        # Define the valid options
+        valid_roles = [StringValueObject(r.value) for r in UserRole]
+        
+        # Pass the current value as a ValueObject and the list of valid options
+        super().__init__(
+            StringValueObject(value), 
+            valid_roles
+        )
+
+# Usage
+try:
+    role = RoleValueObject("admin")
+    print(role.value)  # "admin"
+    
+    invalid_role = RoleValueObject("guest") # Raises InvalidArgumentError
+except InvalidArgumentError as e:
+    print(e)
+```
+
+### 5. Entities
+
+Use the `Entity` base class for objects with identity:
+
+```python
+from ddd_value_objects import Entity, UuidValueObject
+
+class Product(Entity):
+    def __init__(self, product_id: str, name: str):
+        # Entity expects a string ID which it wraps in a UuidValueObject
+        super().__init__(product_id)
+        self.name = name
+
+product1 = Product("550e8400-e29b-41d4-a716-446655440000", "Laptop")
+product2 = Product("550e8400-e29b-41d4-a716-446655440000", "Updated Laptop Name")
+
+print(product1 == product2) # True (Same identity/ID)
+```
+
+---
+
+## Available Value Objects
+
+| Category | Classes |
+| :--- | :--- |
+| **Primitives** | `StringValueObject`, `IntValueObject`, `FloatValueObject`, `BoolValueObject` |
+| **Numeric** | `PositiveIntValueObject`, `PositiveFloatValueObject` |
+| **Identity** | `UuidValueObject` |
+| **Network** | `EmailValueObject`, `UrlValueObject`, `IpAddressValueObject` |
+| **Communication** | `PhoneNumberValueObject`, `CountryCodeValueObject` (ISO 3166-1 alpha-2) |
+| **Temporal** | `DateTimeValueObject`, `DateValueObject` (Unix timestamps) |
+| **Financial** | `CurrencyValueObject` (ISO 4217), `MoneyValueObject` |
+| **Others** | `EnumValueObject`, `CompositeValueObject` |
+
+---
+
+## Development and Testing
+
+We use `uv` for dependency management and `pytest` for testing.
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/youruser/ddd-value-objects.git
+cd ddd-value-objects
+
+# Install dependencies
+uv sync
+```
+
+### Running Tests
+
+```bash
+uv run pytest
+```
+
+### Coverage Threshold
+
+This project maintains a minimum coverage threshold of **90%**. The CI workflow will automatically fail if coverage falls below this level.
+
+## License
+
+This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.

{ddd_value_objects-0.1.2 → ddd_value_objects-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ddd-value-objects"
-version = "0.1.2"
+version = "0.1.4"
 description = "A collection of base classes for Domain-Driven Design (DDD) value objects and entities in Python"
 readme = "README.md"
 license = {text = "MIT"}
@@ -20,4 +20,8 @@ where = ["src"]
 [dependency-groups]
 dev = [
     "pytest==9.0.2",
+    "pytest-cov",
 ]
+
+[tool.pytest.ini_options]
+addopts = "--cov=src --cov-report=term-missing --cov-fail-under=90"

ddd_value_objects-0.1.4/src/ddd_value_objects/__init__.py

@@ -0,0 +1,45 @@
+from .value_object import ValueObject
+from .composite_value_object import CompositeValueObject
+from .string_value_object import StringValueObject
+from .int_value_object import IntValueObject
+from .float_value_object import FloatValueObject
+from .bool_value_object import BoolValueObject
+from .uuid_value_object import UuidValueObject
+from .date_time_value_object import DateTimeValueObject
+from .date_value_object import DateValueObject
+from .positive_int_value_object import PositiveIntValueObject
+from .positive_float_value_object import PositiveFloatValueObject
+from .email_value_object import EmailValueObject
+from .phone_number_value_object import PhoneNumberValueObject
+from .currency_value_object import CurrencyValueObject
+from .country_code_value_object import CountryCodeValueObject
+from .url_value_object import UrlValueObject
+from .ip_address_value_object import IpAddressValueObject
+from .enum_value_object import EnumValueObject
+from .money_value_object import MoneyValueObject
+from .entity import Entity
+from .invalid_argument_error import InvalidArgumentError
+
+__all__ = [
+    "ValueObject",
+    "CompositeValueObject",
+    "StringValueObject",
+    "IntValueObject",
+    "FloatValueObject",
+    "BoolValueObject",
+    "UuidValueObject",
+    "DateTimeValueObject",
+    "DateValueObject",
+    "PositiveIntValueObject",
+    "PositiveFloatValueObject",
+    "EmailValueObject",
+    "PhoneNumberValueObject",
+    "CurrencyValueObject",
+    "CountryCodeValueObject",
+    "UrlValueObject",
+    "IpAddressValueObject",
+    "EnumValueObject",
+    "MoneyValueObject",
+    "Entity",
+    "InvalidArgumentError",
+]

ddd_value_objects-0.1.4/src/ddd_value_objects/composite_value_object.py

@@ -0,0 +1,35 @@
+from abc import ABC, abstractmethod
+from typing import Generic, TypeVar, Optional, Any
+
+from .invalid_argument_error import InvalidArgumentError
+
+T = TypeVar('T', bound=dict)
+
+class CompositeValueObject(ABC, Generic[T]):
+    def __init__(self, value: T):
+        self._value = value
+        self._ensure_value_is_defined(value)
+
+    def equals(self, other: 'CompositeValueObject[T]') -> bool:
+        return other.__class__ == self.__class__ and other.value == self._value
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, CompositeValueObject):
+            return False
+        return self.equals(other)
+
+    def __hash__(self) -> int:
+        # Los diccionarios no son hasheables, así que convertimos a items ordenados si es posible
+        # o usamos una representación inmutable para el hash.
+        return hash((self.__class__, tuple(sorted(self._value.items()))))
+
+    def __str__(self) -> str:
+        return str(self._value)
+
+    def _ensure_value_is_defined(self, value: Optional[T]) -> None:
+        if value is None:
+            raise InvalidArgumentError("Value must be defined")
+
+    @property
+    def value(self) -> T:
+        return self._value

ddd_value_objects-0.1.4/src/ddd_value_objects/country_code_value_object.py

@@ -0,0 +1,23 @@
+import re
+
+from .invalid_argument_error import InvalidArgumentError
+from .string_value_object import StringValueObject
+
+
+class CountryCodeValueObject(StringValueObject):
+    """
+    Value Object for ISO 3166-1 alpha-2 country codes.
+    """
+
+    def __init__(self, value: str):
+        super().__init__(value)
+        self._ensure_is_valid_country_code(value)
+
+    def _ensure_is_valid_country_code(self, value: str) -> None:
+        if not re.match(r"^[A-Z]{2}$", value):
+            raise InvalidArgumentError(
+                f"'{value}' is not a valid ISO 3166-1 alpha-2 country code"
+            )
+
+    def __repr__(self):
+        return f"CountryCodeValueObject(value='{self.value}')"

ddd_value_objects-0.1.4/src/ddd_value_objects/currency_value_object.py

@@ -0,0 +1,19 @@
+import re
+from .string_value_object import StringValueObject
+from .invalid_argument_error import InvalidArgumentError
+
+
+class CurrencyValueObject(StringValueObject):
+    # Código ISO 4217: 3 letras mayúsculas
+    CURRENCY_REGEX = re.compile(r"^[A-Z]{3}$")
+
+    def __init__(self, value: str):
+        super().__init__(value)
+        self._ensure_is_valid_currency(value)
+
+    def _ensure_is_valid_currency(self, value: str) -> None:
+        if not self.CURRENCY_REGEX.match(value):
+            raise InvalidArgumentError(f"'{value}' is not a valid ISO 4217 currency code")
+
+    def __repr__(self):
+        return f"CurrencyValueObject(value='{self.value}')"

ddd_value_objects-0.1.4/src/ddd_value_objects/date_time_value_object.py

@@ -0,0 +1,24 @@
+from datetime import datetime
+from .value_object import ValueObject
+from .invalid_argument_error import InvalidArgumentError
+
+
+class DateTimeValueObject(ValueObject[int]):
+
+    def __init__(self, value: int):
+        super().__init__(value)
+        self._ensure_is_valid_timestamp(value)
+
+    def _ensure_is_valid_timestamp(self, value: int) -> None:
+        try:
+            datetime.fromtimestamp(value)
+        except (ValueError, OSError, OverflowError):
+            raise InvalidArgumentError(f"'{value}' is not a valid Unix timestamp")
+
+    def equals(self, other: 'ValueObject') -> bool:
+        if not isinstance(other, DateTimeValueObject):
+            return False
+        return self.value == other.value
+
+    def __repr__(self):
+        return f"DateTimeValueObject(value={self.value})"

ddd_value_objects-0.1.4/src/ddd_value_objects/date_value_object.py

@@ -0,0 +1,24 @@
+from datetime import date, datetime
+from .value_object import ValueObject
+from .invalid_argument_error import InvalidArgumentError
+
+
+class DateValueObject(ValueObject[int]):
+
+    def __init__(self, value: int):
+        super().__init__(value)
+        self._ensure_is_valid_timestamp(value)
+
+    def _ensure_is_valid_timestamp(self, value: int) -> None:
+        try:
+            datetime.fromtimestamp(value)
+        except (ValueError, OSError, OverflowError):
+            raise InvalidArgumentError(f"'{value}' is not a valid Unix timestamp")
+
+    def equals(self, other: 'ValueObject') -> bool:
+        if not isinstance(other, DateValueObject):
+            return False
+        return self.value == other.value
+
+    def __repr__(self):
+        return f"DateValueObject(value={self.value})"

ddd_value_objects-0.1.4/src/ddd_value_objects/email_value_object.py

@@ -0,0 +1,19 @@
+import re
+
+from .string_value_object import StringValueObject
+from .invalid_argument_error import InvalidArgumentError
+
+
+class EmailValueObject(StringValueObject):
+    EMAIL_REGEX = re.compile(r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$")
+
+    def __init__(self, value: str):
+        super().__init__(value)
+        self._ensure_is_valid_email(value)
+
+    def _ensure_is_valid_email(self, value: str) -> None:
+        if not self.EMAIL_REGEX.match(value):
+            raise InvalidArgumentError(f"'{value}' is not a valid email address")
+
+    def __repr__(self):
+        return f"EmailValueObject(value='{self.value}')"

ddd_value_objects-0.1.4/src/ddd_value_objects/enum_value_object.py

@@ -0,0 +1,24 @@
+from typing import List
+
+from .value_object import ValueObject, Primitives
+from .invalid_argument_error import InvalidArgumentError
+
+
+class EnumValueObject(ValueObject):
+    def __init__(self, value: Primitives, valid_values: List[Primitives]):
+        super().__init__(value)
+        self._ensure_value_is_valid(value, valid_values)
+
+    def _ensure_value_is_valid(self, value: ValueObject, valid_values: List[ValueObject]) -> None:
+        if value not in valid_values:
+            raise InvalidArgumentError(
+                f"'{value}' is not a valid value. Allowed values are: {valid_values}"
+            )
+
+    def equals(self, other: 'Primitives') -> bool:
+        if not isinstance(other, EnumValueObject):
+            return False
+        return self.value == other.value
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}(value={repr(self.value)})"

ddd_value_objects-0.1.4/src/ddd_value_objects/ip_address_value_object.py

@@ -0,0 +1,25 @@
+import ipaddress
+
+from .invalid_argument_error import InvalidArgumentError
+from .string_value_object import StringValueObject
+
+
+class IpAddressValueObject(StringValueObject):
+
+    def __init__(self, value: str):
+        super().__init__(value)
+        self._ensure_is_valid_ip(value)
+
+    def _ensure_is_valid_ip(self, value: str) -> None:
+        try:
+            ipaddress.ip_address(value)
+        except ValueError:
+            raise InvalidArgumentError(f"'{value}' is not a valid IP address")
+
+    def equals(self, other: 'ValueObject') -> bool:
+        if not isinstance(other, IpAddressValueObject):
+            return False
+        return self.value == other.value
+
+    def __repr__(self):
+        return f"IpAddressValueObject(value='{self.value}')"