examples.18_custom_sanitizer_transform

  1"""Demonstrates a multi-step sanitization and validation pipeline that trims
  2and lowercases user input before applying type and enumeration validation.
  3
  4This example shows:
  5  * How to compose multiple string preprocessing transformations.
  6  * How to validate cleaned strings against an allowed list of values.
  7  * How a value passes through sequential strategies before validation.
  8
  9Run directly:
 10
 11    python examples/18_custom_sanitizer_transform.py
 12
 13Expected output:
 14
 15    x: OK apple
 16    y: EXCEPTION Value must be one of ('apple', 'pear', 'plum'), got banana
 17"""
 18
 19import sys
 20import pathlib
 21from typing import 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, TypeValidationStrategy, EnumValidationStrategy
 29from constrained_values.value import TransformationStrategy, ConstrainedValue, PipeLineStrategy
 30
 31
 32class Trim(TransformationStrategy[str, str]):
 33    """A transformation that removes leading and trailing whitespace."""
 34
 35    def transform(self, value: str) -> Response[str]:
 36        """Trim the input string.
 37
 38        Args:
 39            value: The input string.
 40
 41        Returns:
 42            Response[str]: Contains:
 43                * `status = Status.OK`
 44                * `details = "trim"`
 45                * `value` — the trimmed string
 46        """
 47        return Response(status=Status.OK, details="trim", value=value.strip())
 48
 49
 50class Lower(TransformationStrategy[str, str]):
 51    """A transformation that converts input text to lowercase."""
 52
 53    def transform(self, value: str) -> Response[str]:
 54        """Convert the string to lowercase.
 55
 56        Args:
 57            value: The input string.
 58
 59        Returns:
 60            Response[str]: Contains:
 61                * `status = Status.OK`
 62                * `details = "lower"`
 63                * `value` — the lowercase string
 64        """
 65        return Response(status=Status.OK, details="lower", value=value.lower())
 66
 67
 68class CleanFruit(ConstrainedValue[str]):
 69    """A constrained string value that sanitizes and validates fruit names.
 70
 71    The transformation pipeline performs the following steps:
 72        1. `Trim()` — remove leading/trailing spaces.
 73        2. `Lower()` — convert to lowercase.
 74        3. `TypeValidationStrategy(str)` — ensure the value is a string.
 75        4. `EnumValidationStrategy(("apple", "pear", "plum"))` — check membership.
 76
 77    Inputs that pass all transformations and validations yield `Status.OK`.
 78    """
 79
 80    def get_strategies(self) -> List[PipeLineStrategy]:
 81        """Return the sanitization and validation pipeline."""
 82        return [
 83            Trim(),
 84            Lower(),
 85            TypeValidationStrategy(str),
 86            EnumValidationStrategy(("apple", "pear", "plum")),
 87        ]
 88
 89
 90def main() -> None:
 91    """Run the custom sanitizer demonstration.
 92
 93    Creates two :class:`CleanFruit` constrained values:
 94        1. Input `"  Apple  "` — trimmed, lowercased, and validated → OK.
 95        2. Input `" Banana "` — not in the allowed list → EXCEPTION.
 96
 97    Prints:
 98        * `"x: OK apple"`
 99        * `"y: EXCEPTION Value must be one of ('apple', 'pear', 'plum'), got banana"`
100    """
101    x = CleanFruit("  Apple  ")
102    y = CleanFruit(" Banana ")
103    print("x:", x.status.name, x.value)
104    print("y:", y.status.name, y.details)
105
106
107if __name__ == "__main__":
108    main()