examples.23_config_validation

  1"""Demonstrates validating a configuration dictionary using constrained value
  2types such as :class:`RangeValue` and :class:`EnumValue`.
  3
  4This example shows:
  5  * How to validate multiple fields in a configuration dictionary.
  6  * How to enforce numeric ranges, enumerated string values, and boolean flags.
  7  * How to aggregate and return validation results in a structured form.
  8
  9Run directly:
 10
 11    python examples/23_config_validation.py
 12
 13Expected output:
 14
 15    GOOD: (True, {'port': 8080, 'log_level': 'info', 'feature_x': True})
 16    BAD : (False, {'port': "Value must be one of 'int', got 'str'", 'log_level':
 17               "Value must be one of ('debug', 'info', 'warn', 'error'), got verbose",
 18               'feature_x': "Value must be one of 'bool', got 'str'"})
 19"""
 20
 21import sys
 22import pathlib
 23from enum import Enum
 24from typing import Dict, Tuple, Any
 25
 26# ---------------------------------------------------------------------------
 27# Make repo root importable when running this file directly
 28# ---------------------------------------------------------------------------
 29sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
 30
 31from constrained_values import RangeValue, Status, EnumValue
 32
 33
 34class LogLevel(Enum):
 35    """A simple enumeration representing valid log levels."""
 36    DEBUG = "debug"
 37    INFO = "info"
 38    WARN = "warn"
 39    ERROR = "error"
 40
 41
 42def validate_config(cfg: Dict[str, Any]) -> Tuple[bool, Dict[str, Any]]:
 43    """Validate a configuration dictionary.
 44
 45    Uses constrained value types to validate each configuration field:
 46
 47      * **port** — must be within `[1024, 65535]`
 48      * **log_level** — must match a member of :class:`LogLevel`
 49      * **feature_x** — must be a boolean (`True` or `False`)
 50
 51    Args:
 52        cfg: The configuration dictionary to validate.
 53
 54    Returns:
 55        Tuple[bool, Dict[str, Any]]: A tuple containing:
 56            * `True` and the validated config dict if all checks pass.
 57            * `False` and a dict of error messages if validation fails.
 58    """
 59    errors = {}
 60
 61    port = RangeValue(cfg.get("port"), 1024, 65535)
 62    if port.status != Status.OK:
 63        errors["port"] = port.details
 64
 65    level = EnumValue(cfg.get("log_level"), LogLevel)
 66    if level.status != Status.OK:
 67        errors["log_level"] = level.details
 68
 69    feature = EnumValue(cfg.get("feature_x"), [True, False])
 70    if feature.status != Status.OK:
 71        errors["feature_x"] = feature.details
 72
 73    if errors:
 74        return False, errors
 75
 76    return True, {
 77        "port": port.value,
 78        "log_level": level.value,
 79        "feature_x": feature.value,
 80    }
 81
 82
 83def main() -> None:
 84    """Run the configuration validation demonstration.
 85
 86    Creates two configuration dictionaries — one valid, one invalid — and
 87    validates them using :func:`validate_config`.
 88
 89    Prints:
 90        * The validation result for a good configuration (True, normalized dict).
 91        * The validation result for a bad configuration (False, errors).
 92    """
 93    good = {"port": 8080, "log_level": "info", "feature_x": True}
 94    bad = {"port": "8080", "log_level": "verbose", "feature_x": "yes"}
 95
 96    print("GOOD:", validate_config(good))
 97    print("BAD :", validate_config(bad))
 98
 99
100if __name__ == "__main__":
101    main()