extended-data 8.0.0__py3-none-any.whl

extended_data/containers/sequences.py

@@ -0,0 +1,403 @@
+"""Extended sequence containers built on Tier 1 primitives."""
+
+from __future__ import annotations
+
+from collections import UserList
+from collections.abc import Callable, Iterable, Iterator, MutableSet
+from operator import index as operator_index
+from typing import Any, SupportsIndex, TypeVar, cast, overload
+
+from extended_data.containers.mappings import ExtendedDict
+from extended_data.primitives.mappings import zipmap as primitive_zipmap
+from extended_data.primitives.sequences import filter_list, flatten_list
+from extended_data.primitives.splitting import split_list_by_type
+from extended_data.primitives.state import first_non_empty as primitive_first_non_empty
+from extended_data.primitives.state import is_nothing
+from extended_data.primitives.types import make_hashable, reconstruct_special_types
+
+
+T = TypeVar("T")
+U = TypeVar("U")
+
+
+class ExtendedList(UserList[T]):
+    """List wrapper with chainable primitive operations."""
+
+    def __init__(self, initlist: Iterable[T] | None = None) -> None:
+        """Initialize the extended list."""
+        super().__init__()
+        self.extend(initlist or [])
+
+    @staticmethod
+    def _wrap_item(item: T) -> T:
+        """Promote nested built-in containers to extended containers."""
+        from extended_data.containers.factory import extend_data
+
+        return cast(T, extend_data(item))
+
+    @overload
+    def __setitem__(self, i: SupportsIndex, item: T) -> None: ...
+
+    @overload
+    def __setitem__(self, i: slice, item: Iterable[T]) -> None: ...
+
+    def __setitem__(self, i: SupportsIndex | slice, item: T | Iterable[T]) -> None:
+        """Set values while preserving extended nested containers."""
+        if isinstance(i, slice):
+            self.data[i] = [self._wrap_item(value) for value in cast(Iterable[T], item)]
+            return
+        self.data[i] = self._wrap_item(cast(T, item))
+
+    def append(self, item: T) -> None:
+        """Append a value while preserving extended nested containers."""
+        self.data.append(self._wrap_item(item))
+
+    def extend(self, other: Iterable[T]) -> None:
+        """Extend values while preserving extended nested containers."""
+        self.data.extend(self._wrap_item(item) for item in other)
+
+    def __iadd__(self, other: Iterable[T]) -> ExtendedList[T]:
+        """Extend in place while preserving extended nested containers."""
+        self.extend(other)
+        return self
+
+    def __imul__(self, count: SupportsIndex) -> ExtendedList[T]:
+        """Repeat in place while preserving extended nested containers."""
+        self.data *= operator_index(count)
+        self.data[:] = [self._wrap_item(item) for item in self.data]
+        return self
+
+    def insert(self, i: int, item: T) -> None:
+        """Insert a value while preserving extended nested containers."""
+        self.data.insert(i, self._wrap_item(item))
+
+    def flatten(self) -> ExtendedList[Any]:
+        """Return a recursively flattened copy."""
+        from extended_data.containers.factory import extend_data, to_builtin
+
+        return extend_data(flatten_list(to_builtin(self.data)))
+
+    def compact(self) -> ExtendedList[T]:
+        """Return a copy without values considered empty."""
+        return ExtendedList(item for item in self.data if not is_nothing(item))
+
+    def map(self, func: Callable[[T], U]) -> ExtendedList[U]:
+        """Return a copy with a callable applied to each item."""
+        return ExtendedList(func(item) for item in self.data)
+
+    def filter(self, predicate: Callable[[T], bool]) -> ExtendedList[T]:
+        """Return a copy containing items accepted by a predicate."""
+        return ExtendedList(item for item in self.data if predicate(item))
+
+    def filter_values(
+        self,
+        *,
+        allowlist: Iterable[T] | None = None,
+        denylist: Iterable[T] | None = None,
+    ) -> ExtendedList[T]:
+        """Return a copy filtered by explicit allowed and denied values."""
+        return ExtendedList(filter_list(self.data, allowlist=allowlist, denylist=denylist))
+
+    def split_by_type(self, *, primitive_only: bool = False) -> ExtendedDict:
+        """Return values grouped by type name."""
+        from extended_data.containers.factory import extend_data, to_builtin
+
+        grouped = split_list_by_type(to_builtin(self.data), primitive_only=primitive_only)
+        return extend_data({type_key.__name__: values for type_key, values in grouped.items()})
+
+    def first_non_empty(self) -> T | None:
+        """Return the first value not considered empty."""
+        return cast(T | None, primitive_first_non_empty(*self.data))
+
+    def zipmap(self, values: Iterable[str]) -> ExtendedDict:
+        """Return an extended mapping from this list's values to provided values."""
+        from extended_data.containers.factory import extend_data, to_builtin
+
+        keys = [str(item) for item in to_builtin(self.data)]
+        mapped_values = [str(item) for item in to_builtin(list(values))]
+        return extend_data(primitive_zipmap(keys, mapped_values))
+
+    def reconstruct_special_types(self, *, fail_silently: bool = False) -> ExtendedList[Any]:
+        """Return a copy with string-like special values reconstructed."""
+        from extended_data.containers.factory import extend_data, to_builtin
+
+        return extend_data(reconstruct_special_types(to_builtin(self.data), fail_silently=fail_silently))
+
+    def to_export_safe(self, *, export_to_yaml: bool = False) -> Any:
+        """Return this list converted to export-safe primitive data."""
+        from extended_data.io.exporters import make_raw_data_export_safe
+
+        return make_raw_data_export_safe(self.data, export_to_yaml=export_to_yaml)
+
+    def wrap_for_export(self, allow_encoding: bool | str = True, **format_opts: Any) -> str:
+        """Return this list wrapped as an encoded export string."""
+        from extended_data.io.exporters import wrap_raw_data_for_export
+
+        return wrap_raw_data_for_export(self.data, allow_encoding=allow_encoding, **format_opts)
+
+    def unique(self) -> ExtendedList[T]:
+        """Return a copy with duplicate values removed while preserving order."""
+        seen: set[Any] = set()
+        values: list[T] = []
+        for item in self.data:
+            marker = make_hashable(item)
+            if marker in seen:
+                continue
+            seen.add(marker)
+            values.append(item)
+        return ExtendedList(values)
+
+
+class ExtendedTuple(tuple[T, ...]):
+    """Tuple wrapper with immutable chainable sequence operations."""
+
+    __slots__ = ()
+
+    def __new__(cls, values: Iterable[T] | None = None) -> ExtendedTuple[T]:
+        """Initialize the extended tuple."""
+        items = () if values is None else values
+        return super().__new__(cls, (cls._wrap_item(item) for item in items))
+
+    @staticmethod
+    def _wrap_item(item: T) -> T:
+        """Promote nested built-in containers to extended containers."""
+        from extended_data.containers.factory import extend_data
+
+        return cast(T, extend_data(item))
+
+    @overload
+    def __getitem__(self, index: SupportsIndex) -> T: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> ExtendedTuple[T]: ...
+
+    def __getitem__(self, index: SupportsIndex | slice) -> T | ExtendedTuple[T]:
+        """Return sliced values as ExtendedTuple instances."""
+        value = super().__getitem__(index)
+        if isinstance(index, slice):
+            return ExtendedTuple(cast(tuple[T, ...], value))
+        return cast(T, value)
+
+    @overload
+    def __add__(self, other: tuple[T, ...]) -> ExtendedTuple[T]: ...
+
+    @overload
+    def __add__(self, other: tuple[U, ...]) -> ExtendedTuple[T | U]: ...
+
+    def __add__(self, other: tuple[Any, ...]) -> ExtendedTuple[Any]:
+        """Concatenate tuples while preserving the ExtendedTuple surface."""
+        return ExtendedTuple((*tuple(self), *other))
+
+    def __radd__(self, other: tuple[Any, ...]) -> ExtendedTuple[Any]:
+        """Concatenate tuples while preserving the ExtendedTuple surface."""
+        return ExtendedTuple((*other, *tuple(self)))
+
+    def __mul__(self, count: SupportsIndex) -> ExtendedTuple[T]:
+        """Repeat tuple values while preserving the ExtendedTuple surface."""
+        return ExtendedTuple(tuple(self) * operator_index(count))
+
+    def __rmul__(self, count: SupportsIndex) -> ExtendedTuple[T]:
+        """Repeat tuple values while preserving the ExtendedTuple surface."""
+        return self * count
+
+    def flatten(self) -> ExtendedTuple[Any]:
+        """Return a recursively flattened tuple copy."""
+        from extended_data.containers.factory import to_builtin
+
+        def _flatten(items: Iterable[Any]) -> list[Any]:
+            flattened: list[Any] = []
+            for item in items:
+                plain_item = to_builtin(item)
+                if isinstance(plain_item, list | tuple):
+                    flattened.extend(_flatten(plain_item))
+                else:
+                    flattened.append(plain_item)
+            return flattened
+
+        return ExtendedTuple(_flatten(self))
+
+    def compact(self) -> ExtendedTuple[T]:
+        """Return a copy without values considered empty."""
+        return ExtendedTuple(item for item in self if not is_nothing(item))
+
+    def map(self, func: Callable[[T], U]) -> ExtendedTuple[U]:
+        """Return a copy with a callable applied to each item."""
+        return ExtendedTuple(func(item) for item in self)
+
+    def filter(self, predicate: Callable[[T], bool]) -> ExtendedTuple[T]:
+        """Return a copy containing items accepted by a predicate."""
+        return ExtendedTuple(item for item in self if predicate(item))
+
+    def unique(self) -> ExtendedTuple[T]:
+        """Return a copy with duplicate values removed while preserving order."""
+        seen: set[Any] = set()
+        values: list[T] = []
+        for item in self:
+            marker = make_hashable(item)
+            if marker in seen:
+                continue
+            seen.add(marker)
+            values.append(item)
+        return ExtendedTuple(values)
+
+    def split_by_type(self, *, primitive_only: bool = False) -> ExtendedDict:
+        """Return values grouped by type name while keeping tuple-shaped groups."""
+        from extended_data.containers.factory import extend_data, to_builtin
+
+        grouped = split_list_by_type(list(to_builtin(self)), primitive_only=primitive_only)
+        return extend_data({type_key.__name__: tuple(values) for type_key, values in grouped.items()})
+
+    def first_non_empty(self) -> T | None:
+        """Return the first value not considered empty."""
+        return cast(T | None, primitive_first_non_empty(*self))
+
+    def zipmap(self, values: Iterable[str]) -> ExtendedDict:
+        """Return an extended mapping from this tuple's values to provided values."""
+        from extended_data.containers.factory import extend_data, to_builtin
+
+        keys = [str(item) for item in to_builtin(tuple(self))]
+        mapped_values = [str(item) for item in to_builtin(list(values))]
+        return extend_data(primitive_zipmap(keys, mapped_values))
+
+    def reconstruct_special_types(self, *, fail_silently: bool = False) -> ExtendedTuple[Any]:
+        """Return a copy with string-like special values reconstructed."""
+        from extended_data.containers.factory import extend_data, to_builtin
+
+        return extend_data(reconstruct_special_types(to_builtin(tuple(self)), fail_silently=fail_silently))
+
+    def to_export_safe(self, *, export_to_yaml: bool = False) -> Any:
+        """Return this tuple converted to export-safe primitive data."""
+        from extended_data.io.exporters import make_raw_data_export_safe
+
+        return make_raw_data_export_safe(tuple(self), export_to_yaml=export_to_yaml)
+
+    def wrap_for_export(self, allow_encoding: bool | str = True, **format_opts: Any) -> str:
+        """Return this tuple wrapped as an encoded export string."""
+        from extended_data.io.exporters import wrap_raw_data_for_export
+
+        return wrap_raw_data_for_export(tuple(self), allow_encoding=allow_encoding, **format_opts)
+
+    def to_tuple(self) -> tuple[T, ...]:
+        """Return a plain tuple copy."""
+        return tuple(self)
+
+
+class ExtendedSet(MutableSet[T]):
+    """Set wrapper with explicit chainable operations."""
+
+    def __init__(self, values: Iterable[T] | None = None) -> None:
+        """Initialize the extended set."""
+        self._data: set[T] = set()
+        for value in values or []:
+            self.add(value)
+
+    @staticmethod
+    def _wrap_item(item: T) -> T:
+        """Promote nested built-in containers to extended containers."""
+        from extended_data.containers.factory import extend_data
+
+        return cast(T, extend_data(item))
+
+    def __contains__(self, value: object) -> bool:
+        """Return whether the set contains a value."""
+        return value in self._data
+
+    def __iter__(self) -> Iterator[T]:
+        """Iterate over set values."""
+        return iter(self._data)
+
+    def __len__(self) -> int:
+        """Return the number of set values."""
+        return len(self._data)
+
+    def __repr__(self) -> str:
+        """Return a value-oriented representation."""
+        return f"{self.__class__.__name__}({self._data!r})"
+
+    def add(self, value: T) -> None:
+        """Add a value to the set."""
+        self._data.add(self._wrap_item(value))
+
+    def update(self, *others: Iterable[T]) -> None:
+        """Add values from one or more iterables."""
+        for other in others:
+            for value in other:
+                self.add(value)
+
+    def discard(self, value: T) -> None:
+        """Remove a value from the set if present."""
+        self._data.discard(value)
+
+    def copy(self) -> ExtendedSet[T]:
+        """Return a shallow copy."""
+        return ExtendedSet(self._data)
+
+    def compact(self) -> ExtendedSet[T]:
+        """Return a copy without values considered empty."""
+        return ExtendedSet(item for item in self._data if not is_nothing(item))
+
+    def reconstruct_special_types(self, *, fail_silently: bool = False) -> ExtendedSet[Any]:
+        """Return a copy with string-like special values reconstructed."""
+        from extended_data.containers.factory import extend_data, to_builtin
+
+        return extend_data(reconstruct_special_types(to_builtin(self._data), fail_silently=fail_silently))
+
+    def to_export_safe(self, *, export_to_yaml: bool = False) -> Any:
+        """Return this set converted to export-safe primitive data."""
+        from extended_data.io.exporters import make_raw_data_export_safe
+
+        return make_raw_data_export_safe(self._data, export_to_yaml=export_to_yaml)
+
+    def wrap_for_export(self, allow_encoding: bool | str = True, **format_opts: Any) -> str:
+        """Return this set wrapped as an encoded export string."""
+        from extended_data.io.exporters import wrap_raw_data_for_export
+
+        return wrap_raw_data_for_export(self._data, allow_encoding=allow_encoding, **format_opts)
+
+    def union(self, *others: Iterable[T]) -> ExtendedSet[T]:
+        """Return a union with other iterables."""
+        result = set(self._data)
+        for other in others:
+            result.update(other)
+        return ExtendedSet(result)
+
+    def intersection(self, *others: Iterable[T]) -> ExtendedSet[T]:
+        """Return an intersection with other iterables."""
+        result = set(self._data)
+        for other in others:
+            result.intersection_update(other)
+        return ExtendedSet(result)
+
+    def difference(self, *others: Iterable[T]) -> ExtendedSet[T]:
+        """Return a difference against other iterables."""
+        result = set(self._data)
+        for other in others:
+            result.difference_update(other)
+        return ExtendedSet(result)
+
+    def symmetric_difference(self, other: Iterable[T]) -> ExtendedSet[T]:
+        """Return a symmetric difference against another iterable."""
+        result = set(self._data)
+        for value in other:
+            wrapped = self._wrap_item(value)
+            if wrapped in result:
+                result.remove(wrapped)
+            else:
+                result.add(wrapped)
+        return ExtendedSet(result)
+
+    def intersection_update(self, *others: Iterable[T]) -> None:
+        """Keep only values found in all other iterables."""
+        self._data = self.intersection(*others)._data
+
+    def difference_update(self, *others: Iterable[T]) -> None:
+        """Remove values found in other iterables."""
+        self._data = self.difference(*others)._data
+
+    def symmetric_difference_update(self, other: Iterable[T]) -> None:
+        """Replace values with the symmetric difference against another iterable."""
+        self._data = self.symmetric_difference(other)._data
+
+    def to_set(self) -> set[T]:
+        """Return a plain set copy."""
+        return set(self._data)

extended_data/containers/strings.py

@@ -0,0 +1,276 @@
+"""Extended string container built on Tier 1 primitives."""
+
+from __future__ import annotations
+
+import datetime
+
+from collections import UserString
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import extended_data.primitives.matching as primitive_matching
+
+from extended_data.primitives.string_transforms import (
+    humanize,
+    ordinalize,
+    pluralize,
+    singularize,
+    titleize,
+    to_camel_case,
+    to_kebab_case,
+    to_pascal_case,
+    to_snake_case,
+)
+from extended_data.primitives.strings import (
+    is_url,
+    lower_first_char,
+    sanitize_key,
+    titleize_name,
+    truncate,
+    upper_first_char,
+)
+from extended_data.primitives.types import (
+    reconstruct_special_type,
+    string_to_bool,
+    string_to_date,
+    string_to_datetime,
+    string_to_float,
+    string_to_int,
+    string_to_path,
+    string_to_time,
+)
+
+
+if TYPE_CHECKING:
+    from extended_data.containers.sequences import ExtendedList, ExtendedTuple
+
+
+def _coerce_string_argument(value: str | UserString) -> str:
+    """Coerce stdlib user strings while preserving normal str errors elsewhere."""
+    return str(value) if isinstance(value, UserString) else value
+
+
+class ExtendedString(UserString):
+    """String wrapper with chainable primitive operations."""
+
+    def lower_first(self) -> ExtendedString:
+        """Return a copy with the first character lowercased."""
+        return ExtendedString(lower_first_char(self.data))
+
+    def upper_first(self) -> ExtendedString:
+        """Return a copy with the first character uppercased."""
+        return ExtendedString(upper_first_char(self.data))
+
+    def remove_prefix(self, prefix: str) -> ExtendedString:
+        """Return a copy with a leading prefix removed."""
+        return ExtendedString(self.data.removeprefix(str(prefix)))
+
+    def remove_suffix(self, suffix: str) -> ExtendedString:
+        """Return a copy with a trailing suffix removed."""
+        return ExtendedString(self.data.removesuffix(str(suffix)))
+
+    def sanitize(self, delim: str = "_") -> ExtendedString:
+        """Return a key-safe copy."""
+        return ExtendedString(sanitize_key(self.data, delim=delim))
+
+    def truncate(self, max_length: int, ender: str = "...") -> ExtendedString:
+        """Return a truncated copy."""
+        return ExtendedString(truncate(self.data, max_length=max_length, ender=ender))
+
+    def titleize_name(self) -> ExtendedString:
+        """Return a titleized name copy."""
+        return ExtendedString(titleize_name(self.data))
+
+    def to_snake_case(self) -> ExtendedString:
+        """Return a snake_case copy."""
+        return ExtendedString(to_snake_case(self.data))
+
+    def to_camel_case(self, *, uppercase_first: bool = False) -> ExtendedString:
+        """Return a camelCase copy."""
+        return ExtendedString(to_camel_case(self.data, uppercase_first=uppercase_first))
+
+    def to_pascal_case(self) -> ExtendedString:
+        """Return a PascalCase copy."""
+        return ExtendedString(to_pascal_case(self.data))
+
+    def to_kebab_case(self) -> ExtendedString:
+        """Return a kebab-case copy."""
+        return ExtendedString(to_kebab_case(self.data))
+
+    def pluralize(self) -> ExtendedString:
+        """Return a pluralized copy."""
+        return ExtendedString(pluralize(self.data))
+
+    def singularize(self) -> ExtendedString:
+        """Return a singularized copy."""
+        return ExtendedString(singularize(self.data))
+
+    def humanize(self) -> ExtendedString:
+        """Return a human-readable copy."""
+        return ExtendedString(humanize(self.data))
+
+    def titleize(self) -> ExtendedString:
+        """Return a title-case copy."""
+        return ExtendedString(titleize(self.data))
+
+    def ordinalize(self) -> ExtendedString:
+        """Return an ordinalized copy."""
+        return ExtendedString(ordinalize(self.data))
+
+    def format(self, *args: object, **kwargs: object) -> ExtendedString:  # type: ignore[override]
+        """Format values into an extended string."""
+        return ExtendedString(self.data.format(*args, **kwargs))
+
+    def format_map(self, mapping: Mapping[str, object]) -> ExtendedString:  # type: ignore[override]
+        """Format mapping values into an extended string."""
+        return ExtendedString(self.data.format_map(mapping))
+
+    def split(self, sep: str | UserString | None = None, maxsplit: int = -1) -> ExtendedList[ExtendedString]:  # type: ignore[override]
+        """Split into extended string parts."""
+        from extended_data.containers.sequences import ExtendedList
+
+        separator = None if sep is None else _coerce_string_argument(sep)
+        return ExtendedList(ExtendedString(part) for part in self.data.split(separator, maxsplit))
+
+    def rsplit(self, sep: str | UserString | None = None, maxsplit: int = -1) -> ExtendedList[ExtendedString]:  # type: ignore[override]
+        """Split from the right into extended string parts."""
+        from extended_data.containers.sequences import ExtendedList
+
+        separator = None if sep is None else _coerce_string_argument(sep)
+        return ExtendedList(ExtendedString(part) for part in self.data.rsplit(separator, maxsplit))
+
+    def splitlines(self, keepends: bool = False) -> ExtendedList[ExtendedString]:  # type: ignore[override]
+        """Split lines into extended string parts."""
+        from extended_data.containers.sequences import ExtendedList
+
+        return ExtendedList(ExtendedString(part) for part in self.data.splitlines(keepends))
+
+    def partition(self, sep: str | UserString) -> ExtendedTuple[ExtendedString]:  # type: ignore[override]
+        """Partition into extended string parts."""
+        from extended_data.containers.sequences import ExtendedTuple
+
+        return ExtendedTuple(ExtendedString(part) for part in self.data.partition(_coerce_string_argument(sep)))
+
+    def rpartition(self, sep: str | UserString) -> ExtendedTuple[ExtendedString]:  # type: ignore[override]
+        """Partition from the right into extended string parts."""
+        from extended_data.containers.sequences import ExtendedTuple
+
+        return ExtendedTuple(ExtendedString(part) for part in self.data.rpartition(_coerce_string_argument(sep)))
+
+    def join(self, seq: Iterable[str | UserString]) -> ExtendedString:  # type: ignore[override]
+        """Join string-like values into an extended string."""
+        return ExtendedString(self.data.join(_coerce_string_argument(item) for item in seq))
+
+    def is_partial_match(self, other: str | None, *, check_prefix_only: bool = False) -> bool:
+        """Return whether this string partially matches another string."""
+        return primitive_matching.is_partial_match(self.data, other, check_prefix_only=check_prefix_only)
+
+    def is_non_empty_match(self, other: object) -> bool:
+        """Return whether this string matches another non-empty string value."""
+        return primitive_matching.is_non_empty_match(self.data, other)
+
+    def is_url(self) -> bool:
+        """Return whether the string is a URL."""
+        return is_url(self.data)
+
+    def to_bool(self, *, raise_on_error: bool = False) -> bool | None:
+        """Return a boolean parsed from the string."""
+        return string_to_bool(self.data, raise_on_error=raise_on_error)
+
+    def to_float(self, *, raise_on_error: bool = False) -> float | None:
+        """Return a float parsed from the string."""
+        return string_to_float(self.data, raise_on_error=raise_on_error)
+
+    def to_int(self, *, raise_on_error: bool = False) -> int | None:
+        """Return an integer parsed from the string."""
+        return string_to_int(self.data, raise_on_error=raise_on_error)
+
+    def to_path(self, *, raise_on_error: bool = False) -> Path | None:
+        """Return a path parsed from the string."""
+        return string_to_path(self.data, raise_on_error=raise_on_error)
+
+    def to_date(self, *, raise_on_error: bool = False) -> datetime.date | None:
+        """Return a date parsed from the string."""
+        return string_to_date(self.data, raise_on_error=raise_on_error)
+
+    def to_datetime(self, *, raise_on_error: bool = False) -> datetime.datetime | None:
+        """Return a datetime parsed from the string."""
+        return string_to_datetime(self.data, raise_on_error=raise_on_error)
+
+    def to_time(self, *, raise_on_error: bool = False) -> datetime.time | None:
+        """Return a time parsed from the string."""
+        return string_to_time(self.data, raise_on_error=raise_on_error)
+
+    def reconstruct_special_type(self, *, fail_silently: bool = False) -> object:
+        """Return the string reconstructed as a known scalar or structured value."""
+        from extended_data.containers.factory import extend_data
+
+        return extend_data(reconstruct_special_type(self.data, fail_silently=fail_silently))
+
+    def decode_json(self, *, as_extended: bool = True) -> Any:
+        """Decode this JSON string, promoting structured values by default."""
+        from extended_data.containers.factory import extend_data
+        from extended_data.primitives.formats.json import decode_json
+
+        decoded = decode_json(self.data)
+        return extend_data(decoded) if as_extended else decoded
+
+    def decode_yaml(self, *, as_extended: bool = True) -> Any:
+        """Decode this YAML string, promoting structured values by default."""
+        from extended_data.containers.factory import extend_data
+        from extended_data.primitives.formats.yaml import decode_yaml
+
+        decoded = decode_yaml(self.data)
+        return extend_data(decoded) if as_extended else decoded
+
+    def decode_toml(self, *, as_extended: bool = True) -> Any:
+        """Decode this TOML string, promoting structured values by default."""
+        from extended_data.containers.factory import extend_data
+        from extended_data.primitives.formats.toml import decode_toml
+
+        decoded = decode_toml(self.data)
+        return extend_data(decoded) if as_extended else decoded
+
+    def decode_hcl2(self, *, as_extended: bool = True) -> Any:
+        """Decode this HCL2 string, promoting structured values by default."""
+        from extended_data.containers.factory import extend_data
+        from extended_data.primitives.formats.hcl import decode_hcl2
+
+        decoded = decode_hcl2(self.data)
+        return extend_data(decoded) if as_extended else decoded
+
+    def encode_base64(self, *, wrap_raw_data: bool = True) -> ExtendedString:
+        """Return this string encoded as Base64."""
+        from extended_data.io.base64 import base64_encode
+
+        return ExtendedString(base64_encode(self.data, wrap_raw_data=wrap_raw_data))
+
+    def decode_base64(
+        self,
+        unwrap_raw_data: bool = True,
+        encoding: str = "yaml",
+        *,
+        as_extended: bool = True,
+    ) -> Any:
+        """Decode this Base64 string, promoting structured values by default."""
+        from extended_data.io.base64 import base64_decode
+
+        return base64_decode(
+            self.data,
+            unwrap_raw_data=unwrap_raw_data,
+            encoding=encoding,
+            as_extended=as_extended,
+        )
+
+    def to_export_safe(self, *, export_to_yaml: bool = False) -> Any:
+        """Return this value converted to export-safe primitive data."""
+        from extended_data.io.exporters import make_raw_data_export_safe
+
+        return make_raw_data_export_safe(self.data, export_to_yaml=export_to_yaml)
+
+    def wrap_for_export(self, allow_encoding: bool | str = True, **format_opts: Any) -> str:
+        """Return this value wrapped as an encoded export string."""
+        from extended_data.io.exporters import wrap_raw_data_for_export
+
+        return wrap_raw_data_for_export(self.data, allow_encoding=allow_encoding, **format_opts)