Add format() method for transformations and measurements

Adds a format() method for converting transformations and measurements into
human-readable strings. Most components use a default implementation based on
inspecting each class to get its public properties, but some (most notably any
component with multiple children) use custom formatting logic. Also adds a
`tmlt.core.utils.format` module containing shared helpers used during
formatting.

#31

Author: tmager

CHANGELOG.rst

@@ -3,10 +3,14 @@
 Changelog
 =========
 
-
 Unreleased
 ----------
 
+Added
+~~~~~
+
+- :class:`.Transformation`\s and :class:`.Measurement`\ s have a new ``format`` method, which renders a human-readable string showing the structure of the transformation/measurement to aid in visualization and debugging.
+
 .. _v0.19.0:
 
 0.19.0 - 2026-05-22

src/tmlt/core/measurements/base.py

@@ -3,18 +3,24 @@
 # SPDX-License-Identifier: Apache-2.0
 # Copyright Tumult Labs 2026
 from abc import ABC, abstractmethod
-from typing import Any
+from typing import Any, FrozenSet
 
 from typeguard import typechecked
 
 from tmlt.core.domains.base import Domain
 from tmlt.core.measures import Measure
 from tmlt.core.metrics import Metric, UnsupportedCombinationError
+from tmlt.core.utils.format import default_format_attrs, default_format_children
 
 
 class Measurement(ABC):
     """Abstract base class for measurements."""
 
+    _FORMAT_EXCLUDED_ATTRS: FrozenSet[str] = frozenset(
+        {"input_domain", "input_metric", "output_measure", "is_interactive"}
+    )
+    """Fields hidden from output when formatting this measurement."""
+
     @typechecked
     def __init__(
         self,
@@ -96,3 +102,29 @@ def privacy_relation(self, d_in: Any, d_out: Any) -> bool:
     @abstractmethod
     def __call__(self, data: Any) -> Any:
         """Performs measurement."""
+
+    def format(self) -> str:
+        """Return a human-readable multi-line description of this measurement.
+
+        The default implementation assembles :meth:`_format_head` and
+        :meth:`_format_children`; subclasses can override either of these
+        hooks (or :meth:`format` itself) to customize the rendering.
+        """
+        head = self._format_head()
+        children = self._format_children()
+        if not children:
+            return head
+        return f"{head}\n{children}"
+
+    def _format_head(self) -> str:
+        """Render this measurement's head line: class name followed by its attrs."""
+        parts = [type(self).__name__]
+        parts.extend(
+            f"{name}={value}"
+            for name, value in default_format_attrs(self, self._FORMAT_EXCLUDED_ATTRS)
+        )
+        return " ".join(parts)
+
+    def _format_children(self) -> str:
+        """Return the rendered block for nested transformations/measurements."""
+        return default_format_children(self)

src/tmlt/core/measurements/chaining.py

@@ -10,6 +10,7 @@
 from tmlt.core.exceptions import DomainMismatchError, MetricMismatchError
 from tmlt.core.measurements.base import Measurement
 from tmlt.core.transformations.base import Transformation
+from tmlt.core.utils.format import format_chain, get_chain_children
 
 
 class ChainTM(Measurement):
@@ -140,3 +141,7 @@ def privacy_relation(self, d_in: Any, d_out: Any) -> bool:
     def __call__(self, data: Any) -> Any:
         """Computes measurement after applying transformation on input data."""
         return self._measurement(self._transformation(data))
+
+    def format(self) -> str:
+        """Return a human-readable multi-line description of this measurement."""
+        return format_chain(get_chain_children(self))

src/tmlt/core/measurements/composition.py

@@ -15,6 +15,7 @@
 )
 from tmlt.core.measurements.base import Measurement
 from tmlt.core.measures import ApproxDP, PureDP, RhoZCDP
+from tmlt.core.utils.format import format_siblings
 
 
 class Composition(Measurement):
@@ -178,3 +179,6 @@ def privacy_relation(self, d_in: Any, d_out: Any) -> bool:
     def __call__(self, data: Any) -> List:
         """Return answers to composed measurements."""
         return [measurement(data) for measurement in self._measurements]
+
+    def _format_children(self) -> str:
+        return format_siblings(self._measurements)

src/tmlt/core/measurements/interactive_measurements.py

@@ -35,6 +35,7 @@
 from tmlt.core.transformations.base import Transformation
 from tmlt.core.transformations.chaining import ChainTT
 from tmlt.core.transformations.identity import Identity
+from tmlt.core.utils.format import format_siblings
 from tmlt.core.utils.misc import copy_if_mutable
 
 
@@ -720,6 +721,9 @@ def __call__(self, data: Any) -> ParallelQueryable:
         """Returns a :class:`~.ParallelQueryable`."""
         return ParallelQueryable(data, self._measurements)
 
+    def _format_children(self) -> str:
+        return format_siblings(self._measurements)
+
 
 class MakeInteractive(Measurement):
     """Creates a :class:`~.GetAnswerQueryable`.

src/tmlt/core/measurements/pandas_measurements/dataframe.py

@@ -26,6 +26,7 @@
 from tmlt.core.measures import Measure, PureDP, RhoZCDP
 from tmlt.core.metrics import HammingDistance, SymmetricDifference
 from tmlt.core.utils.exact_number import ExactNumber, ExactNumberInput
+from tmlt.core.utils.format import format_labeled_siblings
 
 
 class Aggregate(Measurement):
@@ -273,3 +274,14 @@ def __call__(self, df: pd.DataFrame) -> pd.DataFrame:
                 for column_name, aggregation in self.column_to_aggregation.items()
             }
         )
+
+    def format(self) -> str:
+        """Return a human-readable multi-line description of this measurement.
+
+        The per-column aggregations are rendered as labeled sibling children
+        (the ``output_schema`` is derivable from them, so it is not shown).
+        """
+        return (
+            f"{type(self).__name__}\n"
+            f"{format_labeled_siblings(self.column_to_aggregation.items())}"
+        )

src/tmlt/core/transformations/base.py

@@ -6,18 +6,24 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import Any, Union, overload
+from typing import Any, FrozenSet, Union, overload
 
 from typeguard import check_type, typechecked
 
 from tmlt.core.domains.base import Domain
 from tmlt.core.measurements.base import Measurement
 from tmlt.core.metrics import Metric, UnsupportedCombinationError
+from tmlt.core.utils.format import default_format_attrs, default_format_children
 
 
 class Transformation(ABC):
     """Abstract base class for transformations."""
 
+    _FORMAT_EXCLUDED_ATTRS: FrozenSet[str] = frozenset(
+        {"input_domain", "input_metric", "output_domain", "output_metric"}
+    )
+    """Fields hidden from output when formatting this transformation."""
+
     @typechecked
     def __init__(
         self,
@@ -125,3 +131,29 @@ def __or__(self, other: Any) -> Union[Measurement, Transformation]:
     @abstractmethod
     def __call__(self, data: Any) -> Any:
         """Perform transformation."""
+
+    def format(self) -> str:
+        """Return a human-readable multi-line description of this transformation.
+
+        The default implementation assembles :meth:`_format_head` and
+        :meth:`_format_children`; subclasses can override either of these
+        hooks (or :meth:`format` itself) to customize the rendering.
+        """
+        head = self._format_head()
+        children = self._format_children()
+        if not children:
+            return head
+        return f"{head}\n{children}"
+
+    def _format_head(self) -> str:
+        """Render this component's head line: class name followed by its attrs."""
+        parts = [type(self).__name__]
+        parts.extend(
+            f"{name}={value}"
+            for name, value in default_format_attrs(self, self._FORMAT_EXCLUDED_ATTRS)
+        )
+        return " ".join(parts)
+
+    def _format_children(self) -> str:
+        """Return the rendered block for nested transformations."""
+        return default_format_children(self)

src/tmlt/core/transformations/chaining.py

@@ -9,6 +9,7 @@
 
 from tmlt.core.exceptions import DomainMismatchError, MetricMismatchError
 from tmlt.core.transformations.base import Transformation
+from tmlt.core.utils.format import format_chain, get_chain_children
 
 
 class ChainTT(Transformation):
@@ -126,3 +127,7 @@ def transformation2(self) -> Transformation:
     def __call__(self, data: Any) -> Any:
         """Performs transformation1 followed by transformation2."""
         return self._transformation2(self._transformation1(data))
+
+    def format(self) -> str:
+        """Return a human-readable multi-line description of this measurement."""
+        return format_chain(get_chain_children(self))

src/tmlt/core/transformations/spark_transformations/groupby.py

@@ -123,6 +123,11 @@ class GroupBy(Transformation):
             1
     """  # noqa: E501
 
+    # When formatted, group_keys provides no information that isn't in groupby_columns
+    _FORMAT_EXCLUDED_ATTRS = Transformation._FORMAT_EXCLUDED_ATTRS | {  # noqa: SLF001
+        "group_keys"
+    }
+
     @typechecked
     def __init__(
         self,