examples.05_truthiness_and_ok

  1"""Demonstrates how the truthiness (`bool()`) and `.ok` attribute of a
  2`ConstrainedValue` instance mirror its internal `Status.OK` state.
  3
  4This example shows:
  5  * A successful value returns `True` for both `.ok` and `bool(instance)`.
  6  * A failed value returns `False` for both.
  7  * How to access `details` for additional diagnostic information.
  8
  9Run directly:
 10
 11    python examples/05_truthiness_and_ok.py
 12
 13Expected output:
 14
 15    g.ok, bool(g) g.details: True True ok
 16    b.ok, bool(b) b.details: False False nope, nothing to see here
 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 Pass(TransformationStrategy[Any, Any]):
 37    """A strategy that always succeeds.
 38
 39    This transformation simply returns the input value unchanged with
 40    `Status.OK`, simulating a successful validation or transformation step.
 41    """
 42
 43    def transform(self, value: Any) -> Response[Any]:
 44        """Return an OK response with the value unchanged.
 45
 46        Args:
 47            value: The input to pass through.
 48
 49        Returns:
 50            Response[Any]: Contains `status=Status.OK`, `details='ok'`, and
 51            the same `value`.
 52        """
 53        return Response(status=Status.OK, details="ok", value=value)
 54
 55
 56class Fail(TransformationStrategy[Any, Any]):
 57    """A strategy that always fails.
 58
 59    This demonstrates how a `ConstrainedValue` propagates a non-OK status and
 60    becomes falsy when evaluated in a boolean context.
 61    """
 62
 63    def transform(self, value: Any) -> Response[Any]:
 64        """Return a failed response.
 65
 66        Args:
 67            value: Any input value (ignored).
 68
 69        Returns:
 70            Response[Any]: Contains `status=Status.EXCEPTION`,
 71            `details='nope, nothing to see here'`, and `value=None`.
 72        """
 73        return Response(
 74            status=Status.EXCEPTION,
 75            details="nope, nothing to see here",
 76            value=None,
 77        )
 78
 79
 80class Good(ConstrainedValue[int]):
 81    """A `ConstrainedValue[int]` that always succeeds.
 82
 83    The pipeline consists of a single `Pass` strategy.
 84    """
 85
 86    def get_strategies(self) -> List[PipeLineStrategy]:
 87        """Return a one-step pass-through pipeline."""
 88        return [Pass()]
 89
 90
 91class Bad(ConstrainedValue[int]):
 92    """A `ConstrainedValue[int]` that always fails.
 93
 94    The pipeline consists of a single `Fail` strategy.
 95    """
 96
 97    def get_strategies(self) -> List[PipeLineStrategy]:
 98        """Return a one-step failing pipeline."""
 99        return [Fail()]
100
101
102def main() -> None:
103    """Run the truthiness and `.ok` demonstration.
104
105    Creates one successful (:class:`Good`) and one failing (:class:`Bad`)
106    constrained value, then prints their `.ok` property, `bool()` result,
107    and `.details`.
108
109    Prints:
110        - `g.ok, bool(g), g.details` → `True True validation successful`
111        - `b.ok, bool(b), b.details` → `False False nope, nothing to see here`
112    """
113    g, b = Good(1), Bad(2)
114    print("g.ok, bool(g) g.details:", g.ok, bool(g), g.details)
115    print("b.ok, bool(b) b.details:", b.ok, bool(b), b.details)
116
117
118if __name__ == "__main__":
119    main()