Validate API Reference¶

@dataclasses.dataclass(frozen=True, slots=True)
class Gt:
    """Value must be strictly greater than *val*."""

    val: float

    def check(self, value: Any) -> bool:
        return value > self.val

    def schema_kw(self) -> dict[str, Any]:
        return {"exclusiveMinimum": self.val}

    def __str__(self) -> str:
        return f"> {self.val}"

@dataclasses.dataclass(frozen=True, slots=True)
class Ge:
    """Value must be greater than or equal to *val*."""

    val: float

    def check(self, value: Any) -> bool:
        return value >= self.val

    def schema_kw(self) -> dict[str, Any]:
        return {"minimum": self.val}

    def __str__(self) -> str:
        return f">= {self.val}"

@dataclasses.dataclass(frozen=True, slots=True)
class Lt:
    """Value must be strictly less than *val*."""

    val: float

    def check(self, value: Any) -> bool:
        return value < self.val

    def schema_kw(self) -> dict[str, Any]:
        return {"exclusiveMaximum": self.val}

    def __str__(self) -> str:
        return f"< {self.val}"

@dataclasses.dataclass(frozen=True, slots=True)
class Le:
    """Value must be less than or equal to *val*."""

    val: float

    def check(self, value: Any) -> bool:
        return value <= self.val

    def schema_kw(self) -> dict[str, Any]:
        return {"maximum": self.val}

    def __str__(self) -> str:
        return f"<= {self.val}"

@dataclasses.dataclass(frozen=True, slots=True)
class MinLen:
    """Length must be at least *val*."""

    val: int

    def check(self, value: Any) -> bool:
        return len(value) >= self.val

    def schema_kw(self) -> dict[str, Any]:
        if isinstance(self.val, int):
            return {"minLength": self.val}
        return {"minLength": self.val}

    def schema_kw_array(self) -> dict[str, Any]:
        return {"minItems": self.val}

    def __str__(self) -> str:
        return f"len >= {self.val}"

@dataclasses.dataclass(frozen=True, slots=True)
class MaxLen:
    """Length must be at most *val*."""

    val: int

    def check(self, value: Any) -> bool:
        return len(value) <= self.val

    def schema_kw(self) -> dict[str, Any]:
        return {"maxLength": self.val}

    def schema_kw_array(self) -> dict[str, Any]:
        return {"maxItems": self.val}

    def __str__(self) -> str:
        return f"len <= {self.val}"

@dataclasses.dataclass(frozen=True, slots=True)
class Match:
    """Value must match *pattern* (via ``re.fullmatch``)."""

    pattern: str

    def check(self, value: Any) -> bool:
        return re.fullmatch(self.pattern, value) is not None

    def schema_kw(self) -> dict[str, Any]:
        return {"pattern": self.pattern}

    def __str__(self) -> str:
        return f"match({self.pattern!r})"

@dataclasses.dataclass(frozen=True, slots=True)
class Predicate:
    """Value must satisfy a custom predicate function.

    Args:
        fn: A callable ``(value) -> bool``.
        description: Human-readable description for error messages.
    """

    fn: Callable[[Any], bool]
    description: str = "custom predicate"

    def check(self, value: Any) -> bool:
        return self.fn(value)

    def schema_kw(self) -> dict[str, Any]:
        return {}

    def __str__(self) -> str:
        return self.description

@dataclasses.dataclass(frozen=True, slots=True)
class FieldValidator:
    """Custom validator that can transform the field value.

    Unlike ``Predicate`` (which returns bool), the function receives the
    validated value and returns a (possibly transformed) value.  Raise
    ``ValueError`` or ``AssertionError`` to signal failure.

    Args:
        fn: A callable ``(value) -> value``.  Raise on failure.
        description: Human-readable description for error messages.
    """

    fn: Callable[[Any], Any]
    description: str = "custom validator"

    def validate(self, value: Any) -> Any:
        return self.fn(value)

    def schema_kw(self) -> dict[str, Any]:
        return {}

    def __str__(self) -> str:
        return self.description

@dataclasses.dataclass(frozen=True, slots=True)
class Doc:
    """Field description marker for ``Annotated`` types.

    Attaches a human-readable description to a type annotation.  The
    description is emitted as ``{"description": ...}`` in JSON Schema
    and has no effect on validation.

    Example::

        Annotated[str, Doc("The user's full name")]
    """

    description: str

    def check(self, value: Any) -> bool:
        return True

    def schema_kw(self) -> dict[str, Any]:
        return {"description": self.description}

    def __str__(self) -> str:
        return self.description

@dataclasses.dataclass
class ErrorDetail:
    """A single validation error.

    Attributes:
        path: Dotted/bracketed path to the failing field (e.g. ``"items[2].name"``).
        expected: Expected type or constraint description.
        actual: Actual type or value description.
        message: Human-readable error message.
    """

    path: str
    expected: str
    actual: str
    message: str

class ValidationError(Exception):
    """Raised when validation fails.

    Attributes:
        errors: List of all validation errors found.
    """

    def __init__(self, errors: list[ErrorDetail]) -> None:
        self.errors = errors
        msgs = "; ".join(e.message for e in errors[:5])
        if len(errors) > 5:
            msgs += f" ... and {len(errors) - 5} more"
        super().__init__(f"{len(errors)} validation error(s): {msgs}")