# validation

Python API: `luxonis_ml.utils.validation`

Human-readable rendering of pydantic validation errors.

Pydantic's default `ValidationError` message is accurate but noisy: it repeats the raw error type, the truncated input value, and
a documentation URL for every problem, and it reports union failures once per union member. This module turns such an error into a
short list of
[ValidationProblem](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/validation.md)
entries and renders them either as plain text or as a [rich](https://rich.readthedocs.io/en/stable/) panel.

> **Example**
> ```python
from pydantic import ValidationError
from rich.console import Console

from luxonis_ml.utils.validation import render_validation_error

try:
    MyModel(**data)
except ValidationError as e:
    Console().print(render_validation_error(e))
```

The model that failed is recovered from the error's own traceback. Knowing it lets the formatter tell a field name from a mapping key or from one of pydantic's internal union member tags, and suggest the closest valid field name for a misspelled key. Pass `model` explicitly for an error that arrives without its traceback, or one raised by a `pydantic.TypeAdapter`, which validates something that need not be a model at all.

## Classes

### ValidationProblem

A single validation failure, phrased for a human reader.

#### Attributes

##### hint

Optional follow-up suggestion, such as the closest matching field name for a misspelled key.

##### location

Dotted path to the offending value, using `[i]` for sequence indices, e.g. `model.inputs[0].dtype`. Empty for a problem concerning the top-level value itself.

##### message

What is wrong, as a lowercase sentence fragment. A union whose members failed on their own fields spans several lines: a header, then one indented line per alternative.

##### value

Optional repr of the offending input value.

## Functions

### format_validation_error

```python
def format_validation_error(error: ValidationError, *, model: type[BaseModel] | None = None, title: str | None = None) -> str:
```

Format a validation error as readable plain text.

Parameters

 * `error` (`ValidationError`): The validation error to format.
 * `model` (`type[BaseModel] | None`): Model that was validated. Used to resolve error locations and to suggest valid field names for misspelled keys. Defaults to the model recovered from the error's traceback.
 * `title` (`str | None`): Headline for the message. Defaults to a line naming the model that failed to validate.

Returns

 * `str`: A multi-line message with one indented block per problem.

### install_excepthook

```python
def install_excepthook(*, use_rich: bool = True, enabled: bool = True):
```

Configure summaries for uncaught validation errors.

Wraps `sys.excepthook` with one that first lets the previously installed hook run — so the traceback still shows where the error came from, and crash reporters still see it — and then prints a readable summary of the `ValidationError` as the last thing the reader sees. An existing Luxonis hook is reconfigured, or removed when `enabled` is False. Calling this more than once is harmless.

Parameters

 * `use_rich` (`bool`): If True, the summary is a `rich` panel. If False, it is plain text.
 * `enabled` (`bool`): Whether validation error summaries are enabled.

### iter_validation_problems

```python
def iter_validation_problems(error: ValidationError, *, model: type[BaseModel] | None = None) -> Iterator[ValidationProblem]:
```

Convert a validation error into humanized problems.

Union failures reported once per union member are collapsed into a single problem, and duplicate problems are dropped.

Parameters

 * `error` (`ValidationError`): The validation error to inspect.
 * `model` (`type[BaseModel] | None`): Model that was validated. Used to resolve error locations and to suggest valid field names for misspelled keys. Defaults to the model recovered from the error's traceback.

Returns

 * `Iterator[ValidationProblem]`

Yields

 * One problem per distinct validation failure.

### render_validation_error

```python
def render_validation_error(error: ValidationError, *, model: type[BaseModel] | None = None, title: str | None = None) ->
RenderableType:
```

Render a validation error as a [rich](https://rich.readthedocs.io/en/stable/) panel.

Parameters

 * `error` (`ValidationError`): The validation error to render.
 * `model` (`type[BaseModel] | None`): Model that was validated. Used to resolve error locations and to suggest valid field names for misspelled keys. Defaults to the model recovered from the error's traceback.
 * `title` (`str | None`): Headline shown in the panel border. Defaults to a line naming the model that failed to validate.

Returns

 * `RenderableType`: A renderable suitable for `rich.console.Console.print`.