Sergey Vanyushkin
ca4e8877a5
- Add AI code generation requirements to AGENTS.md - Add module-level docstrings to all 46 Python modules - Add detailed Google-style docstrings to all classes and functions - Remove all inline comments following self-documenting code principle - Include Args, Returns, Raises sections in function docstrings - Add Attributes and Examples sections to class docstrings
92 lines
2.4 KiB
Python
92 lines
2.4 KiB
Python
"""Base value object for DDD domain layer.
|
|
|
|
This module provides the foundational ValueObject class that all domain
|
|
value objects must inherit from. Implements equality, hashing, and
|
|
validation patterns for immutable value objects.
|
|
"""
|
|
|
|
from abc import ABC, abstractmethod
|
|
from dataclasses import dataclass
|
|
from typing import Any, Generic, TypeVar
|
|
|
|
T = TypeVar("T")
|
|
|
|
|
|
@dataclass(frozen=True, slots=True)
|
|
class ValueObject(ABC, Generic[T]):
|
|
"""Base class for all value objects.
|
|
|
|
Value objects are immutable objects defined by their attributes rather
|
|
than identity. They are validated on creation and provide type safety.
|
|
|
|
Attributes:
|
|
value: The underlying value wrapped by the value object.
|
|
|
|
Type Parameters:
|
|
T: Type of the wrapped value.
|
|
|
|
Example:
|
|
>>> class Email(ValueObject[str]):
|
|
... def _validate(self) -> None:
|
|
... if "@" not in self.value:
|
|
... raise ValueError("Invalid email")
|
|
"""
|
|
|
|
value: T
|
|
|
|
def __post_init__(self) -> None:
|
|
"""Validate value object after initialization.
|
|
|
|
Automatically called by dataclass after __init__. Triggers
|
|
the validation method to ensure value integrity.
|
|
"""
|
|
self._validate()
|
|
|
|
@abstractmethod
|
|
def _validate(self) -> None:
|
|
"""Validate the value object.
|
|
|
|
Must be implemented by subclasses to enforce value constraints.
|
|
|
|
Raises:
|
|
ValueError: If the value does not meet validation criteria.
|
|
"""
|
|
...
|
|
|
|
def __eq__(self, other: object) -> bool:
|
|
"""Compare value objects by value.
|
|
|
|
Args:
|
|
other: Another object to compare with.
|
|
|
|
Returns:
|
|
True if both are ValueObjects with equal values.
|
|
"""
|
|
if not isinstance(other, ValueObject):
|
|
return False
|
|
return bool(self.value == other.value)
|
|
|
|
def __hash__(self) -> int:
|
|
"""Get hash based on wrapped value.
|
|
|
|
Returns:
|
|
Hash of the underlying value.
|
|
"""
|
|
return hash(self.value)
|
|
|
|
def __str__(self) -> str:
|
|
"""Convert value object to string.
|
|
|
|
Returns:
|
|
String representation of the wrapped value.
|
|
"""
|
|
return str(self.value)
|
|
|
|
def to_primitive(self) -> Any:
|
|
"""Convert value object to primitive type.
|
|
|
|
Returns:
|
|
The underlying primitive value.
|
|
"""
|
|
return self.value
|