examples.04_constrained_failure

 1"""Demonstrates how a `ConstrainedValue` behaves when one of its transformation
 2strategies fails. This example shows:
 3
 4  * How a `TransformationStrategy` can signal failure with `Status.EXCEPTION`.
 5  * How a `ConstrainedValue` exposes its failure status, details, and value.
 6  * What a failed value looks like in use.
 7
 8Run directly:
 9
10    python examples/04_constrained_failure.py
11
12Expected output:
13
14    status: EXCEPTION
15    details: boom
16    value: None
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    ConstrainedValue,
32    PipeLineStrategy,
33)
34
35
36class Fail(TransformationStrategy[Any, Any]):
37    """A transformation strategy that always fails.
38
39    This intentionally raises a failure condition to demonstrate how a
40    `ConstrainedValue` reacts when a pipeline step produces an error.
41
42    Methods:
43        transform: Always returns a `Response` with `Status.EXCEPTION`.
44    """
45
46    def transform(self, value: Any) -> Response[Any]:
47        """Simulate a failure transformation.
48
49        Args:
50            value: Any input value (ignored).
51
52        Returns:
53            Response[Any]: A response object containing:
54                * `status = Status.EXCEPTION`
55                * `details = "boom"`
56                * `value = None`
57        """
58        return Response(status=Status.EXCEPTION, details="boom", value=None)
59
60
61class Broken(ConstrainedValue[int]):
62    """A `ConstrainedValue[int]` whose pipeline always fails.
63
64    The single pipeline step is a `Fail` strategy, so any input value will
65    result in `Status.EXCEPTION` and a `None` output value.
66    """
67
68    def get_strategies(self) -> List[PipeLineStrategy]:
69        """Return the failing strategy pipeline.
70
71        Returns:
72            List[PipeLineStrategy]: A single-element list containing `Fail()`.
73        """
74        return [Fail()]
75
76
77def main() -> None:
78    """Run the failure demonstration.
79
80    Creates a :class:`Broken` constrained value with input `999` and prints its
81    resulting `status`, `details`, and `value`.
82
83    Prints:
84        * The status name (`EXCEPTION`)
85        * The details string (`boom`)
86        * The resulting value (`None`)
87    """
88    y = Broken(999)
89    print("status:", y.status.name)
90    print("details:", y.details)
91    print("value:", y.value)
92
93
94if __name__ == "__main__":
95    main()