examples.07_str_and_format

  1"""Demonstrates how valid and invalid `ConstrainedValue` objects behave when
  2formatted with `str()` or `format()`.
  3
  4This example shows:
  5  * A successful value supports numeric formatting (e.g., `.2f`).
  6  * A failed value falls back to `str()` representation when formatting fails.
  7  * The `details` field differentiates success vs. failure.
  8
  9Run directly:
 10
 11    python examples/07_str_and_format.py
 12
 13Expected output:
 14
 15    format ok .2f: 12.35
 16    format bad .2f (falls back to str): <invalid BadF: boom fmt>
 17    str(bad): <invalid BadF: boom fmt>
 18"""
 19
 20import sys
 21import pathlib
 22from typing import Any, List
 23
 24# ---------------------------------------------------------------------------
 25# Make repo root importable when running this file directly
 26# ---------------------------------------------------------------------------
 27sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
 28
 29from constrained_values import Response, Status
 30from constrained_values.value import (
 31    TransformationStrategy,
 32    ConstrainedValue,
 33    PipeLineStrategy,
 34)
 35
 36
 37class Pass(TransformationStrategy[Any, Any]):
 38    """A transformation strategy that always succeeds.
 39
 40    Produces an `OK` response with the input value unchanged.
 41    """
 42
 43    def transform(self, value: Any) -> Response[Any]:
 44        """Return an OK response with the input value.
 45
 46        Args:
 47            value: Any input value to pass through.
 48
 49        Returns:
 50            Response[Any]: Contains `status=Status.OK`,
 51            `details='ok fmt'`, and the same `value`.
 52        """
 53        return Response(status=Status.OK, details="ok fmt", value=value)
 54
 55
 56class Fail(TransformationStrategy[Any, Any]):
 57    """A transformation strategy that always fails.
 58
 59    Used to demonstrate how formatting behaves for invalid constrained values.
 60    """
 61
 62    def transform(self, value: Any) -> Response[Any]:
 63        """Return a failed response.
 64
 65        Args:
 66            value: Any input value (ignored).
 67
 68        Returns:
 69            Response[Any]: Contains `status=Status.EXCEPTION`,
 70            `details='boom fmt'`, and `value=None`.
 71        """
 72        return Response(status=Status.EXCEPTION, details="boom fmt", value=None)
 73
 74
 75class GoodF(ConstrainedValue[float]):
 76    """A `ConstrainedValue[float]` that always succeeds."""
 77
 78    def get_strategies(self) -> List[PipeLineStrategy]:
 79        """Return a one-step success pipeline."""
 80        return [Pass()]
 81
 82
 83class BadF(ConstrainedValue[float]):
 84    """A `ConstrainedValue[float]` that always fails."""
 85
 86    def get_strategies(self) -> List[PipeLineStrategy]:
 87        """Return a one-step failure pipeline."""
 88        return [Fail()]
 89
 90
 91def main() -> None:
 92    """Run the `__str__` and `__format__` demonstration.
 93
 94    Creates two constrained values:
 95      * `GoodF` → succeeds and supports numeric formatting (e.g., `".2f"`).
 96      * `BadF` → fails and falls back to its `str()` representation.
 97
 98    Prints:
 99        * Formatted output for the successful value (`12.35`)
100        * Formatted output for the failed value (string fallback)
101        * Direct `str()` representation of the failed value
102    """
103    ok = GoodF(12.3456)
104    bad = BadF(12.3456)
105
106    print("format ok .2f:", format(ok, ".2f"))
107    print("format bad .2f (falls back to str):", format(bad, ".2f"))
108    print("str(bad):", str(bad))
109
110
111if __name__ == "__main__":
112    main()