validobj package

Module contents

Validobj gives you valid objects

Submodules

validobj.validation module

The validation module implements the parse_input() function.

validobj.validation.parse_input(value: Any, spec: Type[T]) → T

This is the main entry point of the validobj module. Validates and processes the input value based on the provided specification.

Parameters:

value (Any) – The value to be processed.
spec (type or typing specification) – The target specification.

Returns:

value – The processed form of value. This can be the input value itself if only a (recursive) type check was performed or a more structured output, based on the type of the specification.

Return type:

Any, compatible with spec

Raises:

ValidationError – Raised if the input cannot be coerced to the spec. An appropriate subclass defined in validobj.errors will contain more specific information as well __cause__ fields chained as neccessary.

Notes

The parameters are described in detail in Input and output.

The error handling is described in Errors.

Examples

Check that a given input is a mapping of string to integer:

>>> validobj.parse_input({'key1': 1, 'key2': 2}, typing.Mapping[str, int])
{'key1': 1, 'key2': 2}

Coerce the input to a dataclass of a valid shape:

>>> import dataclasses
>>> @dataclasses.dataclass
... class Data:
...     key: str
...     key2: int = 4
...
>>> validobj.parse_input({'key': 'Hello'}, Data)
Data(key='Hello', key2=4)

Find a list item that does not conform to the specification:

>>> import typing
>>> try:
...    validobj.parse_input([1,2,'tres'], typing.List[int])
... except validobj.ValidationError as e:
...    e.wrong_index
...
2

validobj.errors module

The errors module defines the exceptions raised by validobj.validation.parse_input() function. These are aleways subclasses of ValidationError.

exception validobj.errors.ValidationError

Bases: Exception

Exception raised when validation cannot be performed for any reason.

exception validobj.errors.WrongTypeError

Bases: ValidationError, TypeError

Exception raised when some input is of the wrong type.

exception validobj.errors.WrongKeysError(missing, unknown, valid, header='')

Bases: MismatchError

Error raised when the keys provided by the input do not match those required by the specification.

Parameters:

missing (set) – Keys that are required my the specification and missing in the input.
unknown (set) – Keys that are present in the input but unknown to the specification.
valid (set) – The set of all valid keys.

exception validobj.errors.NotAnEnumItemError(bad_item, enum_class)

Bases: AlternativeDisplay, ValidationError, ValueError

Exception raised when a string input is not an Enum name.

Parameters:

bad_item (str) – The value of the wrong item.
enum_class (type, enum.Enum subclass) – The enum class that does not contain bad_item

exception validobj.errors.WrongFieldError(*args, wrong_field, **kwargs)

Bases: ValidationError

Exception raised when some field (e.g. in a mapping or dataclass) cannot be processed correctly.

Parameters:: wrong_field (Any) – The key in the input mapping that caused the error.

Notes

The __cause__ attribute of the exception will contain the underlying reason for the error.

exception validobj.errors.WrongListItemError(*args, wrong_index, **kwargs)

Bases: ValidationError

Exception raised when some item in a list cannot be processed correctly.

Parameters:: wrong_index (int) – The index in the list that caused the error.

Notes

The __cause__ attribute of the exception will contain the underlying reason for the error.

exception validobj.errors.UnionValidationError(*args, causes, **kwargs)

Bases: ValidationError

Exception raised when value cannot be coerced to any of the members of an union.

Parameters:: causes (List[ValidationError]) – A list of ValidationError exceptions containing the failure for each of the members of the union.

validobj.custom module

Tools for custom validation of types. Works with Python 3.9 only.

class validobj.custom.InputType(type: Type)

Bases: object

A wrapper over an input type, for use in the custom processing.

Parameters:: type (Type) – The wrapped type.

class validobj.custom.Validator(func: Callable)

Bases: object

A wrapper over a validation function, for use in the custom processing.

Parameters:: func (Callable) – The wrapped function.

validobj.custom.Parser(func: Callable[[Any], T]) → Type[T]

Read the type annotations of func and return a typing.Annotated with the function’s return type as the set type and the requisite metadata so that func is used by validobj.parse_input().

Parameters:: func (Callable) – The wrapped function. It should have one positional parameter. If the parameter is annotated, Validobj will cast the input consitently with the annotation before presenting it to the function.
Returns:: annotated – Annotation of the return type of the function with two metadata parameters: InputType with the type annotation of the first parameter and Validator with the function itself.
Return type:: typing._AnnotatedAlias

Examples

Add support for decimal.Decimal.

>>> import typing
>>> import decimal
>>> from validobj import parse_input, ValidationError
>>> from validobj.custom import Parser
>>> def to_decimal(inp: typing.Union[str, int, float]) -> decimal.Decimal:
...     try:
...         return decimal.Decimal(inp)
...     except decimal.InvalidOperation as e:
...         raise ValidationError("Invalid decimal") from e
...
>>> Decimal = Parser(to_decimal)
>>> print(Decimal)
typing.Annotated[decimal.Decimal, InputType(typing.Union[str, int, float]), Validator(<function to_decimal at ...>)]
>>> parse_input(0.5, Decimal)
Decimal('0.5')