value-object-pattern 1.33.1__tar.gz → 1.38.0__tar.gz

{value_object_pattern-1.33.1 → value_object_pattern-1.38.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: value-object-pattern
-Version: 1.33.1
+Version: 1.38.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.1 → value_object_pattern-1.38.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.1 → value_object_pattern-1.38.0}/pyproject.toml

@@ -55,7 +55,7 @@ develop = ['pre-commit>=3.0.0']
 format = ['ruff>=0.11.10']
 lint = [
     'ruff>=0.11.10',
-    'mypy[reports]>=1.0.0',
+    'ty>=0.0.72',
     { include-group = 'test' },
     { include-group = 'types' },
 ]
@@ -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']
@@ -80,6 +80,7 @@ all = [
 
 [tool.pytest.ini_options]
 pythonpath = '.'
+testpaths = ['tests']
 addopts = [
     '--strict-config',  # fail if an unregistered option is used
     '--strict-markers', # fail if an unregistered marker is used
@@ -183,15 +184,11 @@ known-first-party = ['value_object_pattern']
 combine-as-imports = true
 
 
-[tool.mypy]
-strict = true
-warn_unreachable = true
-enable_error_code = [
-    'redundant-expr',
-    'possibly-undefined',
-    'truthy-bool',
-    'explicit-override',
-]
+[tool.ty.rules]
+missing-override-decorator = 'error'
+missing-type-argument = 'error'
+possibly-unresolved-reference = 'warn'
+unsound-return-statement = 'error'
 
 
 [tool.semantic_release]

{value_object_pattern-1.33.1 → value_object_pattern-1.38.0}/value_object_pattern/__init__.py

@@ -1,11 +1,12 @@
-__version__ = '1.33.1'
+__version__ = '1.38.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.1 → value_object_pattern-1.38.0}/value_object_pattern/decorators/value_object_process.py

@@ -2,8 +2,7 @@
 Decorator used to register value-object processing hooks.
 """
 
-from functools import wraps
-from typing import Any, Callable, TypeVar
+from typing import Callable, TypeVar
 
 T = TypeVar('T')
 
@@ -23,7 +22,7 @@ def process(order: int | None = None) -> Callable[[Callable[..., T]], Callable[.
         ValueError: If the order is not equal or greater than 0.
 
     Returns:
-        Callable[[Callable[..., T]], Callable[..., T]]: Wrapper function for the process.
+        Callable[[Callable[..., T]], Callable[..., T]]: Decorator that marks the process function.
 
     Example:
     ```python
@@ -54,7 +53,7 @@ def process(order: int | None = None) -> Callable[[Callable[..., T]], Callable[.
             ValueError: If the order is not equal or greater than 0.
 
         Returns:
-            Callable[..., T]: Wrapper function for the process.
+            Callable[..., T]: The marked process function.
         """
         if order is not None:
             if type(order) is not int:
@@ -63,23 +62,9 @@ def process(order: int | None = None) -> Callable[[Callable[..., T]], Callable[.
             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]
+        function._is_process = True  # type: ignore[ty:unresolved-attribute]
+        function._order = function.__name__ if order is None else str(order)  # type: ignore[ty:unresolved-attribute]
 
-        @wraps(function)
-        def wrapper(*args: tuple[Any, ...], **kwargs: dict[str, Any]) -> T:
-            """
-            Execute the wrapped processing method.
-
-            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 function
 
     return decorator

{value_object_pattern-1.33.1 → value_object_pattern-1.38.0}/value_object_pattern/decorators/value_object_validation.py

@@ -2,8 +2,7 @@
 Decorator used to register value-object validation hooks.
 """
 
-from functools import wraps
-from typing import Any, Callable
+from typing import Callable
 
 
 def validation(
@@ -27,7 +26,7 @@ def validation(
         TypeError: If early_process is not a boolean.
 
     Returns:
-        Callable[[Callable[..., None]], Callable[..., None]]: Wrapper function for the validation.
+        Callable[[Callable[..., None]], Callable[..., None]]: Decorator that marks the validation function.
 
     Example:
     ```python
@@ -59,7 +58,7 @@ def validation(
             TypeError: If early_process is not a boolean.
 
         Returns:
-            Callable[..., None]: Wrapper function for the validation.
+            Callable[..., None]: The marked validation function.
         """
         if order is not None:
             if type(order) is not int:
@@ -71,21 +70,10 @@ def validation(
         if type(early_process) is not bool:
             raise TypeError(f'Validation early_process <<<{early_process}>>> must be a boolean. Got <<<{type(early_process).__name__}>>> type.')  # noqa: E501  # fmt: skip
 
-        function._is_validation = True  # type: ignore[attr-defined]
-        function._order = function.__name__ if order is None else str(order)  # type: ignore[attr-defined]
-        function._early_process = early_process  # type: ignore[attr-defined]
+        function._is_validation = True  # type: ignore[ty:unresolved-attribute]
+        function._order = function.__name__ if order is None else str(order)  # type: ignore[ty:unresolved-attribute]
+        function._early_process = early_process  # type: ignore[ty:unresolved-attribute]
 
-        @wraps(function)
-        def wrapper(*args: tuple[Any, ...], **kwargs: dict[str, Any]) -> None:
-            """
-            Execute the wrapped validation method.
-
-            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 function
 
     return decorator

{value_object_pattern-1.33.1 → value_object_pattern-1.38.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.1 → value_object_pattern-1.38.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)})'
 
@@ -306,7 +306,7 @@ class BaseModel(ABC):
         ```
         """
         if id(self) in memo:
-            return memo[id(self)]  # type: ignore[no-any-return]
+            return memo[id(self)]  # type: ignore[ty:unsound-return-statement]
 
         cls = self.__class__
         clone = cls.__new__(cls)
@@ -385,7 +385,7 @@ class BaseModel(ABC):
         # >>> {'name': 'John Doe', 'birthdate': '1900-01-01T00:00:00+00:00'}
         ```
         """  # noqa: E501
-        if not isinstance(primitives, dict) or not all(isinstance(key, str) for key in primitives):  # type: ignore[redundant-expr]
+        if not isinstance(primitives, dict) or not all(isinstance(key, str) for key in primitives):
             cls._raise_value_is_not_dict_of_strings(value=primitives)
 
         constructor_signature = signature(obj=cls.__init__)
@@ -470,7 +470,7 @@ class BaseModel(ABC):
             return 'Any'
 
         if hasattr(type, '__name__'):
-            return type.__name__  # type: ignore[no-any-return]
+            return type.__name__  # type: ignore[ty:unsound-return-statement]
 
         return str(type).replace('typing.', '')
 

{value_object_pattern-1.33.1 → value_object_pattern-1.38.0}/value_object_pattern/models/collections/dict_value_object.py

@@ -182,7 +182,7 @@ class _DictValueObjectAlias:
             return ' | '.join(_DictValueObjectAlias._format_type_argument(type=allowed) for allowed in get_args(type))
 
         if hasattr(type, '__name__'):
-            return type.__name__  # type: ignore[no-any-return]
+            return type.__name__  # type: ignore[ty:unsound-return-statement]
 
         return str(type).replace('typing.', '')
 
@@ -357,12 +357,12 @@ class DictValueObject(ValueObject[dict[K, V]], Generic[K, V]):  # noqa: UP046
         """
         return len(self._value)
 
-    def __getitem__(self, key: K) -> V:
+    def __getitem__(self, key: Any) -> V:
         """
-        Returns the value for the specified key.
+        Returns the value for the specified key, converting primitive keys when needed.
 
         Args:
-            key (K): The key to get the value for.
+            key (Any): The key or primitive key to get the value for.
 
         Raises:
             KeyError: If the key is not found.
@@ -544,12 +544,12 @@ class DictValueObject(ValueObject[dict[K, V]], Generic[K, V]):  # noqa: UP046
         """
         raise TypeError(f'DictValueObject value <<<{value}>>> must be of type <<<{self._type_label(type=self._value_type)}>>> type. Got <<<{type(value).__name__}>>> type.')  # noqa: E501  # fmt: skip
 
-    def get(self, *, key: K, default: V | None = None) -> V | None:
+    def get(self, *, key: Any, default: V | None = None) -> V | None:
         """
-        Returns the value for the specified key if key is in dictionary, else default.
+        Returns the value for the specified key or primitive key if it is in the dictionary, else default.
 
         Args:
-            key (K): The key to get the value for.
+            key (Any): The key or primitive key to get the value for.
             default (V | None, optional): The default value to return if the key is not found. Defaults to None.
 
         Returns:
@@ -630,7 +630,7 @@ class DictValueObject(ValueObject[dict[K, V]], Generic[K, V]):  # noqa: UP046
             return 'Any'
 
         if hasattr(type, '__name__'):
-            return type.__name__  # type: ignore[no-any-return]
+            return type.__name__  # type: ignore[ty:unsound-return-statement]
 
         return str(type).replace('typing.', '')
 

{value_object_pattern-1.33.1 → value_object_pattern-1.38.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
 
@@ -141,7 +141,7 @@ class _ListValueObjectAlias:
             return ' | '.join(_ListValueObjectAlias._format_type_argument(type=allowed) for allowed in get_args(type))
 
         if hasattr(type, '__name__'):
-            return type.__name__  # type: ignore[no-any-return]
+            return type.__name__  # type: ignore[ty:unsound-return-statement]
 
         return str(type).replace('typing.', '')
 
@@ -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
@@ -505,12 +505,12 @@ class ListValueObject(ValueObject[list[T]], Generic[T]):  # noqa: UP046
         """
         return not self._value
 
-    def add(self, *, item: T) -> Self:
+    def add(self, *, item: Any) -> Self:
         """
-        Returns a new ListValueObject with the item added to the end.
+        Returns a new ListValueObject with a typed or primitive item added to the end.
 
         Args:
-            item (T): The item to add.
+            item (Any): The typed or primitive item to convert and add.
 
         Raises:
             TypeError: If the item is not of type T.
@@ -576,12 +576,12 @@ class ListValueObject(ValueObject[list[T]], Generic[T]):  # noqa: UP046
 
         return self.add(item=item)
 
-    def extend(self, *, items: list[T]) -> Self:
+    def extend(self, *, items: list[Any]) -> Self:
         """
-        Returns a new ListValueObject with multiple items added to the end.
+        Returns a new ListValueObject with typed or primitive items added to the end.
 
         Args:
-            items (list[T]): The items to add.
+            items (list[Any]): The typed or primitive items to convert and add.
 
         Raises:
             TypeError: If the items are not of the correct type.
@@ -647,12 +647,12 @@ class ListValueObject(ValueObject[list[T]], Generic[T]):  # noqa: UP046
 
         return self.extend(items=items)
 
-    def delete(self, *, item: T) -> Self:
+    def delete(self, *, item: Any) -> Self:
         """
-        Returns a new ListValueObject with the first occurrence of the item deleted.
+        Returns a new ListValueObject with the first occurrence of a typed or primitive item deleted.
 
         Args:
-            item (T): The item to delete.
+            item (Any): The typed or primitive item to convert and delete.
 
         Raises:
             ValueError: If the item is not in the list.
@@ -844,7 +844,7 @@ class ListValueObject(ValueObject[list[T]], Generic[T]):  # noqa: UP046
             return 'Any'
 
         if hasattr(type, '__name__'):
-            return type.__name__  # type: ignore[no-any-return]
+            return type.__name__  # type: ignore[ty:unsound-return-statement]
 
         return str(type).replace('typing.', '')
 

{value_object_pattern-1.33.1 → value_object_pattern-1.38.0}/value_object_pattern/models/enumeration_value_object.py

@@ -77,7 +77,7 @@ class EnumerationValueObject(ValueObject[Any | E], Generic[E]):  # noqa: UP046
                 if not (isclass(object=enumeration) and issubclass(enumeration, Enum)):
                     raise TypeError(f'EnumerationValueObject[...] <<<{enumeration}>>> must be an Enum subclass. Got <<<{type(enumeration).__name__}>>> type.')  # noqa: E501  # fmt: skip
 
-                cls._enumeration = enumeration  # type: ignore[assignment]
+                cls._enumeration = enumeration
                 return
 
         raise TypeError('EnumerationValueObject must be parameterized, e.g. "class ColorValueObject(EnumerationValueObject[ColorEnumeration])".')  # noqa: E501  # fmt: skip
@@ -168,4 +168,4 @@ class EnumerationValueObject(ValueObject[Any | E], Generic[E]):  # noqa: UP046
         # >>> ColorEnumeration.RED
         ```
         """
-        return self._value
+        return self._value  # type: ignore[ty:unsound-return-statement]

{value_object_pattern-1.33.1 → value_object_pattern-1.38.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)