examples.03_constrained_pass_through

 1"""Demonstrates the smallest useful `ConstrainedValue` implementation: a single
 2transformation strategy that **accepts any input** and returns it unchanged.
 3
 4What this shows:
 5  * How to define a `TransformationStrategy` that always returns `Status.OK`.
 6  * How to plug that strategy into a `ConstrainedValue` via `get_strategies()`.
 7  * How to read the resulting `status` and `value`.
 8
 9Run directly:
10
11    python examples/03_constrained_pass_through.py
12
13Expected output:
14
15    status: OK
16    value: 123
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 PassThrough(TransformationStrategy[Any, Any]):
37    """A transformation strategy that accepts the input as-is.
38
39    This strategy always returns `Status.OK` and echoes the input `value`
40    unchanged. It’s useful as a baseline or for wiring tests where no
41    validation or transformation is needed.
42    """
43
44    def transform(self, value: Any) -> Response[Any]:
45        """Return the input value unchanged with an OK status.
46
47        Args:
48            value: The input to pass through.
49
50        Returns:
51            Response[Any]: A response carrying:
52                * `status = Status.OK`
53                * `details = "ok"`
54                * `value` equal to the input
55        """
56        return Response(status=Status.OK, details="ok", value=value)
57
58
59class MyNumber(ConstrainedValue[int]):
60    """A `ConstrainedValue[int]` that uses the pass-through strategy.
61
62    The pipeline contains a single `PassThrough` step, so any integer is
63    accepted and propagated unchanged.
64    """
65
66    def get_strategies(self) -> List[PipeLineStrategy]:
67        """Return the pipeline of strategies for this constrained value.
68
69        Returns:
70            List[PipeLineStrategy]: A single-step pipeline with `PassThrough`.
71        """
72        return [PassThrough()]
73
74
75def main() -> None:
76    """Run the pass-through demonstration.
77
78    Creates a :class:`MyNumber` with the input `123` and prints the resulting
79    `status` and `value`.
80
81    Prints:
82        The status name (expected: `OK`) and the value (expected: `123`).
83    """
84    x = MyNumber(123)
85    print("status:", x.status.name)
86    print("value:", x.value)
87
88
89if __name__ == "__main__":
90    main()