typing_validation.validation_failure

Validation failure tracking functionality.

Acc

Acc = ~Acc

Type variable for the accumulator in ValidationFailure.visit.

FailureTreeVisitor

class FailureTreeVisitor(*args, **kwargs)

Bases: Protocol[Acc]

Structural type for visitor functions that can be passed to ValidationFailure.visit.

InvalidNumpyDTypeValidationFailure

class InvalidNumpyDTypeValidationFailure(val, t, *, type_aliases=None)

Bases: ValidationFailure

Validation failures arising because of invalid NumPy dtype.

MissingKeysValidationFailure

class MissingKeysValidationFailure(val, t, missing_keys, *, type_aliases=None)

Bases: ValidationFailure

Validation failures arising because of missing required keys in a mapping.

property missing_keys

The required key(s) missing from the mapping.

Return type:

tuple[Any, …]

SubtypeValidationFailure

class SubtypeValidationFailure(s, t, *, type_aliases=None)

Bases: ValidationFailure

Validation failures arising from validate(s, Type[t]) when s is not a subtype of t.

TypeVarBoundValidationFailure

class TypeVarBoundValidationFailure(val, t, bound_cause, *, type_aliases=None)

Bases: ValidationFailure

Validation failures arising from the bound of a type variable.

UnionValidationFailure

class UnionValidationFailure(val, t, *causes, type_aliases=None)

Bases: ValidationFailure

Validation failures arising from union types.

ValidationFailure

class ValidationFailure(val, t, *causes, type_aliases=None)

Bases: object

Generic validation failures.

property causes

Validation failure that in turn caused this failure (if any).

Return type:

Tuple[ValidationFailure, …]

rich_print()

Pretty-prints the validation failure tree using rich:

>>> from typing import Union, Collection
>>> from typing_validation import validate, latest_validation_failure
>>> validate([[0, 1, 2], {"hi": 0}], list[Union[Collection[int], dict[str, str]]])
TypeError: ...
>>> latest_validation_failure().rich_print()
Failure tree
└── (list[typing.Union[typing.Collection[int], dict[str, str]]], [[0, 1, 2], {'hi': 0}])
    └── (typing.Union[typing.Collection[int], dict[str, str]], {'hi': 0})
        ├── (typing.Collection[int], {'hi': 0})
        │   └── (<class 'int'>, 'hi')
        └── (dict[str, str], {'hi': 0})
            └── (<class 'str'>, 0)

Raises ModuleNotFoundError if rich is not installed.

Return type:

None

property t

The type involved in the validation failure.

Return type:

Any

property type_aliases

The type aliases that were set at the time of validation.

Return type:

Mapping[str, Any]

property val

The value involved in the validation failure.

Return type:

Any

visit(fun, acc)

Performs a pre-order visit of the validation failure tree:

1. applies fun(self.val, self.t, acc) to the failure,

2. saves the return value as new_acc

3. recurses on all causes using new_acc.

For example, this can be used to implement pretty-prenting of validation failures (see ValidationFailure.rich_print):

>>> import rich
>>> from rich.tree import Tree
>>> from rich.text import Text
>>> from typing import Any, Collection, Union
>>> from typing_validation import validate, latest_validation_failure
>>> validate([[0, 1, 2], {"hi": 0}], list[Union[Collection[int], dict[str, str]]])
TypeError: ...
>>> failure_tree = Tree("Failure tree")
>>> def tree_builder(val: Any, t: Any, tree_tip: Tree) -> Tree:
...     label = Text(f"({repr(t)}, {repr(val)})")
...     tree_tip.add(label) # see https://rich.readthedocs.io/en/latest/tree.html
...     return tree_tip
...
>>> latest_validation_failure().visit(tree_builder, failure_tree)
>>> rich.print(failure_tree)
Failure tree
└── (list[typing.Union[typing.Collection[int], dict[str, str]]], [[0, 1, 2], {'hi': 0}])
    └── (typing.Union[typing.Collection[int], dict[str, str]], {'hi': 0})
        ├── (typing.Collection[int], {'hi': 0})
        │   └── (<class 'int'>, 'hi')
        └── (dict[str, str], {'hi': 0})
            └── (<class 'str'>, 0)

Parameters:

• fun (Callable[[Any, Any, Acc], Acc]) – the function that will be called on each element of the failure tree during the visit

• acc (any type Acc) – the initial value for the accumulator

Return type:

None

ValidationFailureAtIdx

class ValidationFailureAtIdx(val, t, idx_cause, idx, *, ordered=True, type_aliases=None)

Bases: ValidationFailure

Validation failures arising at a given index of a sequence.

property idx

The of the collection item at which this failure arose.

Return type:

int

property ordered

Whether the collection is ordered. If not, the item idx might not be stable.

Return type:

bool

ValidationFailureAtKey

class ValidationFailureAtKey(val, t, key_cause, key, *, type_aliases=None)

Bases: ValidationFailure

Validation failures arising at a given key of a mapping.

property key

The key of the outer sequence at which this failure arose.

Return type:

Any

get_validation_failure

get_validation_failure(err)

Programmatic access to the validation failure tree for the latest validation call.

>>> from typing_validation import validate, get_validation_failure
>>> try:
...     validate([[0, 1], [1, 2], [2, "hi"]], list[list[int]])
... except TypeError as err:
...     validation_failure = get_validation_failure(err)
...
>>> validation_failure
ValidationFailure([[0, 1], [1, 2], [2, 'hi']], list[list[int]],
    ValidationFailure([2, 'hi'], list[int],
        ValidationFailure('hi', <class 'int'>)))

Parameters:

err (TypeError) – type error raised by validate

Raises TypeError if the given error err is a TypeError. Raises ValueError if no validation failure data is available (when err is not a validation error raised by this library).

Return type:

ValidationFailure

latest_validation_failure

latest_validation_failure()

Programmatic access to the validation failure tree for the latest validation call. Uses sys.last_value, so it must be called immediately after the error occurred.

>>> from typing_validation import validate, latest_validation_failure
>>> validate([[0, 1], [1, 2], [2, "hi"]], list[list[int]])
TypeError: ...
>>> latest_validation_failure()
ValidationFailure([[0, 1], [1, 2], [2, 'hi']], list[list[int]],
    ValidationFailure([2, 'hi'], list[int],
        ValidationFailure('hi', <class 'int'>)))

This validation failure information is also set by is_valid in case of failed validation, even though no error is raised.

Return type:

Optional[ValidationFailure]