value-object-pattern 1.33.0__tar.gz → 1.34.0__tar.gz

{value_object_pattern-1.33.0 → value_object_pattern-1.34.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: value-object-pattern
-Version: 1.33.0
+Version: 1.34.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
@@ -261,6 +261,7 @@ low-level operations, and boundary examples.
 | Model | Purpose |
 | --- | --- |
 | `ValueObject[T]` | Base class for immutable validated single-value wrappers. |
+| `SecretValueObject` | Composition marker that redacts any value object's display in either inheritance order. |
 | `EnumerationValueObject[E]` | Stores enum members while accepting enum members or raw enum values. |
 | `UnionValueObject[T]` | Accepts and converts values that match a union annotation; supports subclass and inline construction. |
 | `BaseModel` | Adds representation, equality, copying, and primitive conversion for aggregate-like models. |
@@ -269,6 +270,32 @@ low-level operations, and boundary examples.
 
 See [`docs/usage/README.md`](docs/usage/README.md) for examples of each model.
 
+Compose `SecretValueObject` with the typed value object that owns validation. The marker does not need a type argument and may appear before or after the value-object base:
+
+```python
+from value_object_pattern import SecretValueObject
+from value_object_pattern.usables import IntegerValueObject, StringValueObject
+
+
+class SecretToken(SecretValueObject, StringValueObject):
+    pass
+
+
+class SecretPin(IntegerValueObject, SecretValueObject):
+    pass
+
+
+token = SecretToken(value='hidden-token')
+pin = SecretPin(value=1234)
+
+assert str(token) == '********'
+assert str(pin) == '********'
+assert token.value == 'hidden-token'
+assert pin.value == 1234
+```
+
+Display redaction is not encryption: `.value` and primitive conversion still expose the raw stored value.
+
 <p align="right">
     <a href="#readme-top">🔼 Back to top</a>
 </p><br><br>
@@ -282,7 +309,8 @@ The package includes reusable validators for common shapes:
 | Category | Examples |
 | --- | --- |
 | Primitives | strings, bytes, booleans, integers, floats, `None` / not-`None` |
-| String formats | non-empty, trimmed, alpha, alphanumeric, lower/upper case, snake case, kebab case, secret strings |
+| String formats | non-empty, trimmed, alpha, alphanumeric, lower/upper case, snake case, kebab case |
+| Encoded strings | hexadecimal/Base16, Base32, Base36, ambiguity-free Base56, Bitcoin Base58, standard Base64 |
 | Dates | `date`, `datetime`, date strings, datetime strings, timezone objects, timezone names |
 | Identifiers | UUIDs and UUID strings, world codes, Spanish identifiers and vehicle plates |
 | Internet | URLs, hosts, domains, ports, emails, IP addresses, networks, MAC addresses, slugs, keys |

{value_object_pattern-1.33.0 → value_object_pattern-1.34.0}/README.md

@@ -236,6 +236,7 @@ low-level operations, and boundary examples.
 | Model | Purpose |
 | --- | --- |
 | `ValueObject[T]` | Base class for immutable validated single-value wrappers. |
+| `SecretValueObject` | Composition marker that redacts any value object's display in either inheritance order. |
 | `EnumerationValueObject[E]` | Stores enum members while accepting enum members or raw enum values. |
 | `UnionValueObject[T]` | Accepts and converts values that match a union annotation; supports subclass and inline construction. |
 | `BaseModel` | Adds representation, equality, copying, and primitive conversion for aggregate-like models. |
@@ -244,6 +245,32 @@ low-level operations, and boundary examples.
 
 See [`docs/usage/README.md`](docs/usage/README.md) for examples of each model.
 
+Compose `SecretValueObject` with the typed value object that owns validation. The marker does not need a type argument and may appear before or after the value-object base:
+
+```python
+from value_object_pattern import SecretValueObject
+from value_object_pattern.usables import IntegerValueObject, StringValueObject
+
+
+class SecretToken(SecretValueObject, StringValueObject):
+    pass
+
+
+class SecretPin(IntegerValueObject, SecretValueObject):
+    pass
+
+
+token = SecretToken(value='hidden-token')
+pin = SecretPin(value=1234)
+
+assert str(token) == '********'
+assert str(pin) == '********'
+assert token.value == 'hidden-token'
+assert pin.value == 1234
+```
+
+Display redaction is not encryption: `.value` and primitive conversion still expose the raw stored value.
+
 <p align="right">
     <a href="#readme-top">🔼 Back to top</a>
 </p><br><br>
@@ -257,7 +284,8 @@ The package includes reusable validators for common shapes:
 | Category | Examples |
 | --- | --- |
 | Primitives | strings, bytes, booleans, integers, floats, `None` / not-`None` |
-| String formats | non-empty, trimmed, alpha, alphanumeric, lower/upper case, snake case, kebab case, secret strings |
+| String formats | non-empty, trimmed, alpha, alphanumeric, lower/upper case, snake case, kebab case |
+| Encoded strings | hexadecimal/Base16, Base32, Base36, ambiguity-free Base56, Bitcoin Base58, standard Base64 |
 | Dates | `date`, `datetime`, date strings, datetime strings, timezone objects, timezone names |
 | Identifiers | UUIDs and UUID strings, world codes, Spanish identifiers and vehicle plates |
 | Internet | URLs, hosts, domains, ports, emails, IP addresses, networks, MAC addresses, slugs, keys |

{value_object_pattern-1.33.0 → value_object_pattern-1.34.0}/pyproject.toml

@@ -63,7 +63,7 @@ release = ['build>=1.2.2', 'python-semantic-release>=10.0.2']
 test = [
     'pytest>=8.0.0',
     'pytest-randomly>=3.0.0',
-    'object-mother-pattern>=3.2.0',
+    'object-mother-pattern>=3.16.0',
     { include-group = 'coverage' },
 ]
 types = ['types-python-dateutil>=2.9.0.20241206']

{value_object_pattern-1.33.0 → value_object_pattern-1.34.0}/value_object_pattern/__init__.py

@@ -1,11 +1,12 @@
-__version__ = '1.33.0'
+__version__ = '1.34.0'
 
 from .decorators import process, validation
-from .models import BaseModel, EnumerationValueObject, UnionValueObject, ValueObject
+from .models import BaseModel, EnumerationValueObject, SecretValueObject, UnionValueObject, ValueObject
 
 __all__ = (
     'BaseModel',
     'EnumerationValueObject',
+    'SecretValueObject',
     'UnionValueObject',
     'ValueObject',
     'process',

{value_object_pattern-1.33.0 → value_object_pattern-1.34.0}/value_object_pattern/models/__init__.py

@@ -1,11 +1,13 @@
 from .base_model import BaseModel
 from .enumeration_value_object import EnumerationValueObject
+from .secret_value_object import SecretValueObject
 from .union_value_object import UnionValueObject
 from .value_object import ValueObject
 
 __all__ = (
     'BaseModel',
     'EnumerationValueObject',
+    'SecretValueObject',
     'UnionValueObject',
     'ValueObject',
 )

{value_object_pattern-1.33.0 → value_object_pattern-1.34.0}/value_object_pattern/models/base_model.py

@@ -17,7 +17,7 @@ from inspect import Parameter, _empty, signature
 from types import UnionType
 from typing import Any, NoReturn, Self, Union, get_args, get_origin, get_type_hints
 
-from .primitive_conversion import from_primitive, to_primitive
+from .primitive_conversion import from_primitive, to_display_primitive, to_primitive
 from .type_matching import matches_expected_type
 
 
@@ -158,8 +158,8 @@ class BaseModel(ABC):
         ```
         """
         attributes = []
-        for key, value in sorted(self.to_primitives().items()):
-            attributes.append(f'{key}={value}')
+        for key, value in sorted(self._to_dict(ignore_private=True).items()):
+            attributes.append(f'{key}={to_display_primitive(value=value)}')
 
         return f'{self.__class__.__name__}({", ".join(attributes)})'
 

{value_object_pattern-1.33.0 → value_object_pattern-1.34.0}/value_object_pattern/models/collections/list_value_object.py

@@ -18,7 +18,7 @@ from types import UnionType
 from typing import Any, ClassVar, Generic, NoReturn, Self, TypeVar, Union, cast, get_args, get_origin
 
 from value_object_pattern.decorators import validation
-from value_object_pattern.models import BaseModel, ValueObject
+from value_object_pattern.models import ValueObject
 from value_object_pattern.models.primitive_conversion import from_primitive, to_primitive
 from value_object_pattern.models.type_matching import matches_expected_type
 
@@ -328,19 +328,19 @@ class ListValueObject(ValueObject[list[T]], Generic[T]):  # noqa: UP046
         # >>> [1, 2, 3]
         ```
         """
+        if self._has_secret_display():
+            return ValueObject.__repr__(self)
+
         primitive_types: tuple[type, ...] = (int, float, str, bool, bytes, bytearray, memoryview, type(None))
         collection_types: tuple[type, ...] = (list, dict, tuple, set, frozenset)
 
         list_to_return: list[Any] = []
         for item in self._value:
-            if isinstance(item, BaseModel):
-                list_to_return.append(repr(item))
-
-            elif isinstance(item, Enum):
+            if isinstance(item, Enum):
                 list_to_return.append(item.value)
 
             elif isinstance(item, ValueObject):
-                value = item._value_for_display()
+                value = item._resolved_value_for_display()
 
                 if isinstance(value, Enum):
                     value = value.value
@@ -388,19 +388,19 @@ class ListValueObject(ValueObject[list[T]], Generic[T]):  # noqa: UP046
         # >>> [1, 2, 3]
         ```
         """
+        if self._has_secret_display():
+            return ValueObject.__str__(self)
+
         primitive_types: tuple[type, ...] = (int, float, str, bool, bytes, bytearray, memoryview, type(None))
         collection_types: tuple[type, ...] = (list, dict, tuple, set, frozenset)
 
         list_to_return: list[Any] = []
         for item in self._value:
-            if isinstance(item, BaseModel):
-                list_to_return.append(str(object=item))
-
-            elif isinstance(item, Enum):
+            if isinstance(item, Enum):
                 list_to_return.append(item.value)
 
             elif isinstance(item, ValueObject):
-                value = item._value_for_display()
+                value = item._resolved_value_for_display()
 
                 if isinstance(value, Enum):
                     value = value.value

{value_object_pattern-1.33.0 → value_object_pattern-1.34.0}/value_object_pattern/models/primitive_conversion.py

@@ -20,7 +20,7 @@ def to_primitive(value: Any) -> Any:
     """
     Recursively convert value objects, models, enums, and collections to primitive representations.
 
-    `ValueObject` instances are converted through their display value, `BaseModel`-like objects through
+    `ValueObject` instances are converted through their stored value, `BaseModel`-like objects through
     `to_primitives()`, enums through their `.value`, and collections item by item.
 
     Args:
@@ -49,6 +49,82 @@ def to_primitive(value: Any) -> Any:
     return str(object=value)
 
 
+def to_display_primitive(value: Any) -> Any:
+    """
+    Recursively convert a value for display while honoring value-object redaction.
+
+    Args:
+        value (Any): Value to convert.
+
+    Returns:
+        Any: Display-safe primitive representation.
+    """
+    if isinstance(value, PRIMITIVE_TYPES):
+        return value
+
+    if isinstance(value, Enum):
+        return to_display_primitive(value=value.value)
+
+    if isinstance(value, ValueObject):
+        return _convert_value_for_display(value=value)
+
+    if isinstance(value, (list, tuple, set, frozenset, dict)):
+        return _convert_collection_for_display(value=value)
+
+    if callable(getattr(value, 'to_primitives', None)):
+        return str(object=value)
+
+    if hasattr(value, 'value'):
+        return _convert_value_for_display(value=value)
+
+    return str(object=value)
+
+
+def _convert_value_for_display(*, value: Any) -> Any:
+    """
+    Convert a value-like wrapper through its display value.
+
+    Args:
+        value (Any): Value-like wrapper.
+
+    Returns:
+        Any: Display-safe primitive representation.
+    """
+    nested_value = (
+        value._resolved_value_for_display() if isinstance(value, ValueObject) else getattr(value, 'value', value)
+    )
+
+    if nested_value is value:
+        return str(object=value)
+
+    return to_display_primitive(value=nested_value)
+
+
+def _convert_collection_for_display(*, value: Any) -> Any:
+    """
+    Recursively convert collection values for display.
+
+    Args:
+        value (Any): Collection value.
+
+    Returns:
+        Any: Display-safe collection.
+    """
+    if isinstance(value, list):
+        return [to_display_primitive(value=item) for item in value]
+
+    if isinstance(value, tuple):
+        return tuple(to_display_primitive(value=item) for item in value)
+
+    if isinstance(value, set):
+        return {to_display_primitive(value=item) for item in value}
+
+    if isinstance(value, frozenset):
+        return frozenset(to_display_primitive(value=item) for item in value)
+
+    return {to_display_primitive(value=key): to_display_primitive(value=item) for key, item in value.items()}
+
+
 def from_primitive(*, value: Any, expected_type: Any) -> Any:
     """
     Recursively convert a primitive value into `expected_type` when possible.
@@ -108,7 +184,7 @@ def _convert_with_value_attribute(*, value: Any) -> Any:
         Any: Converted value or sentinel when the branch does not apply.
     """
     if isinstance(value, ValueObject):
-        nested_value = value._value_for_display()
+        nested_value = value.value
         if nested_value is value:
             return str(object=value)
 

value_object_pattern-1.34.0/value_object_pattern/models/secret_value_object.py

@@ -0,0 +1,44 @@
+"""
+Composition marker for display-redacted value objects.
+"""
+
+
+class SecretValueObject:
+    """
+    Redact the display output of any accompanying value-object base.
+
+    This composition-only marker does not store or validate values. Combine it with any `ValueObject` subclass in either
+    inheritance order. The accompanying value object supplies the wrapped type, validation, processing, and primitive
+    conversion behavior.
+
+    The raw value remains available through `.value` and primitive conversion. Redaction is a presentation guard, not
+    encryption or secure secret storage.
+
+    Example:
+    ```python
+    from value_object_pattern import SecretValueObject
+    from value_object_pattern.usables import StringValueObject
+
+
+    class SecretString(SecretValueObject, StringValueObject):
+        pass
+
+
+    secret = SecretString(value='hidden-value')
+    print(secret)
+    # >>> ********
+    ```
+    """
+
+    __slots__ = ()
+
+    _MASK: str = '********'
+
+    def _secret_value_for_display(self) -> str:
+        """
+        Return the fixed display mask.
+
+        Returns:
+            str: Redacted display value.
+        """
+        return self._MASK

{value_object_pattern-1.33.0 → value_object_pattern-1.34.0}/value_object_pattern/models/value_object.py

@@ -143,7 +143,7 @@ class ValueObject(ABC, Generic[T]):  # noqa: UP046
         # >>> IntegerValueObject(value=10)
         ```
         """
-        return f'{self.__class__.__name__}(value={self._value_for_display()!r})'
+        return f'{self.__class__.__name__}(value={self._resolved_value_for_display()!r})'
 
     @override
     def __str__(self) -> str:
@@ -167,7 +167,7 @@ class ValueObject(ABC, Generic[T]):  # noqa: UP046
         # >>> 10
         ```
         """
-        return str(object=self._value_for_display())
+        return str(object=self._resolved_value_for_display())
 
     @override
     def __hash__(self) -> int:
@@ -380,13 +380,35 @@ class ValueObject(ABC, Generic[T]):  # noqa: UP046
 
     def _value_for_display(self) -> Any:
         """
-        Returns the value used by display-oriented representations.
+        Return the value used by display-oriented representations.
 
         Returns:
-            Any: Value safe for string, repr, and primitive display paths.
+            Any: Value safe for string and repr display paths.
         """
         return self.value
 
+    def _resolved_value_for_display(self) -> Any:
+        """
+        Resolve the final display value, giving secret redaction precedence.
+
+        Returns:
+            Any: Redacted value for secret compositions, otherwise the regular display value.
+        """
+        secret_value_for_display = getattr(self, '_secret_value_for_display', None)
+        if callable(secret_value_for_display):
+            return secret_value_for_display()
+
+        return self._value_for_display()
+
+    def _has_secret_display(self) -> bool:
+        """
+        Return whether this value object carries the secret display marker.
+
+        Returns:
+            bool: True when secret display composition is active.
+        """
+        return callable(getattr(self, '_secret_value_for_display', None))
+
     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.

{value_object_pattern-1.33.0 → value_object_pattern-1.34.0}/value_object_pattern/usables/__init__.py

@@ -1,6 +1,11 @@
 from .primitives import (
     AlphaStringValueObject,
     AlphanumericStringValueObject,
+    Base16StringValueObject,
+    Base32StringValueObject,
+    Base36StringValueObject,
+    Base56StringValueObject,
+    Base58StringValueObject,
     Base64StringValueObject,
     BooleanValueObject,
     BytesValueObject,
@@ -9,6 +14,7 @@ from .primitives import (
     EvenIntegerValueObject,
     FalseValueObject,
     FloatValueObject,
+    HexadecimalStringValueObject,
     IntegerValueObject,
     KebabCaseStringValueObject,
     LowercaseStringValueObject,
@@ -27,7 +33,6 @@ from .primitives import (
     PositiveOrZeroIntegerValueObject,
     PrintableStringValueObject,
     ScreamingSnakeCaseStringValueObject,
-    SecretStringValueObject,
     SnakeCaseStringValueObject,
     StringValueObject,
     TrimmedStringValueObject,
@@ -38,6 +43,11 @@ from .primitives import (
 __all__ = (
     'AlphaStringValueObject',
     'AlphanumericStringValueObject',
+    'Base16StringValueObject',
+    'Base32StringValueObject',
+    'Base36StringValueObject',
+    'Base56StringValueObject',
+    'Base58StringValueObject',
     'Base64StringValueObject',
     'BooleanValueObject',
     'BytesValueObject',
@@ -46,6 +56,7 @@ __all__ = (
     'EvenIntegerValueObject',
     'FalseValueObject',
     'FloatValueObject',
+    'HexadecimalStringValueObject',
     'IntegerValueObject',
     'KebabCaseStringValueObject',
     'LowercaseStringValueObject',
@@ -67,7 +78,6 @@ __all__ = (
     'PrintableStringValueObject',
     'PrintableStringValueObject',
     'ScreamingSnakeCaseStringValueObject',
-    'SecretStringValueObject',
     'SnakeCaseStringValueObject',
     'StringValueObject',
     'StringValueObject',

{value_object_pattern-1.33.0 → value_object_pattern-1.34.0}/value_object_pattern/usables/internet/email_address_value_object.py

@@ -214,8 +214,7 @@ class EmailAddressValueObject(NotEmptyStringValueObject, TrimmedStringValueObjec
         try:
             self._internal_domain_part = DomainValueObject(value=self._internal_domain_part).value
 
-        except Exception as exception:
-            print(f'{exception}')
+        except (TypeError, ValueError):
             self._raise_value_invalid_domain_error(value=value, domain_part=self._internal_domain_part)
 
     def _raise_email_address_domain_contains_invalid_characters_error(self, value: str, domain_part: str) -> NoReturn:

{value_object_pattern-1.33.0 → value_object_pattern-1.34.0}/value_object_pattern/usables/internet/uri/http_https_url_value_object.py

@@ -2,6 +2,8 @@
 HttpHttpsUrlValueObject value object.
 """
 
+from typing import NoReturn
+
 from value_object_pattern import validation
 
 from .url_value_object import UrlValueObject, split_url
@@ -36,4 +38,17 @@ class HttpHttpsUrlValueObject(UrlValueObject):
         scheme, *_ = split_url(value=value)
 
         if scheme not in ('http', 'https'):
-            raise ValueError(f'HttpHttpsUrlValueObject value <<<{value}>>> scheme is not HTTP or HTTPS')
+            self._raise_value_is_not_http_https_url(value=value, scheme=scheme)
+
+    def _raise_value_is_not_http_https_url(self, value: str, scheme: str) -> NoReturn:
+        """
+        Raise an error if the URL scheme is not HTTP or HTTPS.
+
+        Args:
+            value (str): The URL value.
+            scheme (str): The invalid scheme.
+
+        Raises:
+            ValueError: If the URL scheme is not HTTP or HTTPS.
+        """
+        raise ValueError(f'HttpHttpsUrlValueObject value <<<{value}>>> scheme is not HTTP or HTTPS')

{value_object_pattern-1.33.0 → value_object_pattern-1.34.0}/value_object_pattern/usables/internet/uri/https_url_value_object.py

@@ -2,6 +2,8 @@
 HttpsUrlValueObject value object.
 """
 
+from typing import NoReturn
+
 from value_object_pattern import validation
 
 from .url_value_object import UrlValueObject, split_url
@@ -36,4 +38,17 @@ class HttpsUrlValueObject(UrlValueObject):
         scheme, *_ = split_url(value=value)
 
         if scheme != 'https':
-            raise ValueError(f'HttpsUrlValueObject value <<<{value}>>> scheme is not HTTPS')
+            self._raise_value_is_not_https_url(value=value, scheme=scheme)
+
+    def _raise_value_is_not_https_url(self, value: str, scheme: str) -> NoReturn:
+        """
+        Raise an error if the URL scheme is not HTTPS.
+
+        Args:
+            value (str): The URL value.
+            scheme (str): The invalid scheme.
+
+        Raises:
+            ValueError: If the URL scheme is not HTTPS.
+        """
+        raise ValueError(f'HttpsUrlValueObject value <<<{value}>>> scheme is not HTTPS')