examples.06_unwrap_usage

  1"""Demonstrates how the `.unwrap()` method of a `ConstrainedValue` behaves.
  2
  3This example shows:
  4  * When the status is `Status.OK`, `.unwrap()` returns the underlying
  5    canonical value.
  6  * When the status is not OK (e.g. `Status.EXCEPTION`), `.unwrap()` raises
  7    a `ValueError` containing the failure details.
  8
  9Run directly:
 10
 11    python examples/06_unwrap_usage.py
 12
 13Expected output:
 14
 15    unwrap OK: 456
 16    caught: Bad invalid: boom unwrap
 17"""
 18
 19import sys
 20import pathlib
 21from typing import Any, List
 22
 23# ---------------------------------------------------------------------------
 24# Make repo root importable when running this file directly
 25# ---------------------------------------------------------------------------
 26sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
 27
 28from constrained_values import Response, Status
 29from constrained_values.value import (
 30    TransformationStrategy,
 31    PipeLineStrategy,
 32    ConstrainedValue,
 33)
 34
 35
 36class Pass(TransformationStrategy[Any, Any]):
 37    """A transformation strategy that always succeeds.
 38
 39    This simply passes the input value through unchanged, returning an
 40    OK `Response`.
 41    """
 42
 43    def transform(self, value: Any) -> Response[Any]:
 44        """Return the input value with an OK status.
 45
 46        Args:
 47            value: The input to pass through.
 48
 49        Returns:
 50            Response[Any]: A successful response containing:
 51                * `status = Status.OK`
 52                * `details = "ok"`
 53                * `value` equal to the input
 54        """
 55        return Response(status=Status.OK, details="ok", value=value)
 56
 57
 58class Fail(TransformationStrategy[Any, Any]):
 59    """A transformation strategy that always fails.
 60
 61    Used to show how `.unwrap()` raises when the `ConstrainedValue` has
 62    a non-OK status.
 63    """
 64
 65    def transform(self, value: Any) -> Response[Any]:
 66        """Return a failure response.
 67
 68        Args:
 69            value: Any input value (ignored).
 70
 71        Returns:
 72            Response[Any]: A failed response with:
 73                * `status = Status.EXCEPTION`
 74                * `details = "boom unwrap"`
 75                * `value = None`
 76        """
 77        return Response(status=Status.EXCEPTION, details="boom unwrap", value=None)
 78
 79
 80class Good(ConstrainedValue[int]):
 81    """A `ConstrainedValue[int]` that always succeeds."""
 82
 83    def get_strategies(self) -> List[PipeLineStrategy]:
 84        """Return a one-step pass-through pipeline."""
 85        return [Pass()]
 86
 87
 88class Bad(ConstrainedValue[int]):
 89    """A `ConstrainedValue[int]` that always fails."""
 90
 91    def get_strategies(self) -> List[PipeLineStrategy]:
 92        """Return a one-step failing pipeline."""
 93        return [Fail()]
 94
 95
 96def main() -> None:
 97    """Run the `.unwrap()` demonstration.
 98
 99    Creates one successful and one failing constrained value, and shows
100    how `.unwrap()` behaves for each.
101
102    Steps:
103        1. `Good(456)` unwraps successfully and prints the value.
104        2. `Bad(999)` raises a `ValueError`, which is caught and printed.
105
106    Prints:
107        * `"unwrap OK: 456"`
108        * `"caught: Bad invalid: boom unwrap"`
109    """
110    x = Good(456)
111    print("unwrap OK:", x.unwrap())
112
113    y = Bad(999)
114    try:
115        print("unwrap BAD (should raise):", y.unwrap())
116    except ValueError as e:
117        print("caught:", e)
118
119
120if __name__ == "__main__":
121    main()