examples.20_sorting_with_invalid

  1"""Demonstrates how sorting a list containing both valid and invalid
  2:class:`ConstrainedValue` instances results in an error.
  3
  4This example shows:
  5  * Valid constrained values (`Status.OK`) are comparable and sortable.
  6  * Invalid values (`Status.EXCEPTION`) cannot be meaningfully compared.
  7  * Sorting such a mixed list raises a `TypeError`.
  8
  9Run directly:
 10
 11    python examples/20_sorting_with_invalid.py
 12
 13Expected output:
 14
 15    sort raised: '<' not supported between instances of 'Bad' and 'Good'
 16"""
 17
 18import sys
 19import pathlib
 20from typing import Any, List
 21
 22# ---------------------------------------------------------------------------
 23# Make repo root importable when running this file directly
 24# ---------------------------------------------------------------------------
 25sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
 26
 27from constrained_values import Response, Status
 28from constrained_values.value import TransformationStrategy, ConstrainedValue, PipeLineStrategy
 29
 30
 31class Pass(TransformationStrategy[Any, Any]):
 32    """A transformation that always succeeds."""
 33
 34    def transform(self, value: Any) -> Response[Any]:
 35        """Return a successful response with the input value unchanged.
 36
 37        Args:
 38            value: The input to pass through.
 39
 40        Returns:
 41            Response[Any]: Contains:
 42                * `status = Status.OK`
 43                * `details = "ok"`
 44                * `value` equal to the input
 45        """
 46        return Response(status=Status.OK, details="ok", value=value)
 47
 48
 49class Fail(TransformationStrategy[Any, Any]):
 50    """A transformation that always fails."""
 51
 52    def transform(self, value: Any) -> Response[Any]:
 53        """Return a failed response with no usable value.
 54
 55        Args:
 56            value: Any input value (ignored).
 57
 58        Returns:
 59            Response[Any]: Contains:
 60                * `status = Status.EXCEPTION`
 61                * `details = "bad"`
 62                * `value = None`
 63        """
 64        return Response(status=Status.EXCEPTION, details="bad", value=None)
 65
 66
 67class Good(ConstrainedValue[int]):
 68    """A `ConstrainedValue[int]` that always succeeds."""
 69
 70    def get_strategies(self) -> List[PipeLineStrategy]:
 71        """Return a one-step successful pipeline."""
 72        return [Pass()]
 73
 74
 75class Bad(ConstrainedValue[int]):
 76    """A `ConstrainedValue[int]` that always fails."""
 77
 78    def get_strategies(self) -> List[PipeLineStrategy]:
 79        """Return a one-step failing pipeline."""
 80        return [Fail()]
 81
 82
 83def main() -> None:
 84    """Run the sorting demonstration.
 85
 86    Creates a mixed list of valid and invalid constrained values and attempts
 87    to sort it. Because invalid values cannot be compared meaningfully, a
 88    `TypeError` is raised.
 89
 90    Steps:
 91        1. Create `[Good(3), Bad(99), Good(1)]`.
 92        2. Attempt to `list.sort()`.
 93        3. Catch and print the resulting `TypeError`.
 94
 95    Prints:
 96        * `"sort raised: '<' not supported between instances of 'Bad' and 'Good'"`
 97    """
 98    items = [Good(3), Bad(99), Good(1)]
 99    try:
100        items.sort()
101    except TypeError as e:
102        print("sort raised:", e)
103
104
105if __name__ == "__main__":
106    main()