Validation

coola.validation ¶

Contain functions to validate function/method arguments.

Every validator follows the same rules:

It returns None when the value is valid, and never converts the value.
A value of the wrong type raises TypeError, and a value of the right type that breaks the constraint raises ValueError.
The message names the argument (name, a keyword-only option), the constraint and the value received.
The type checks are strict (bool is rejected by validate_int and validate_number), the comparisons accept whatever supports them.
A NaN is never valid.
The package imports the standard library only.

A validator exists only if it states a constraint that isinstance or one comparison cannot state without a special case: validate_int exists for the bool case, validate_number for the numbers.Real plus bool case, and validate_finite for the overflow of math.isfinite and the NaN. validate_str(x) is validate_isinstance(x, str) and validate_positive(x) is validate_gt(x, 0). Validate an argument with this package instead of writing raise ValueError for a type, range or membership check.

coola.validation.validate_finite ¶

validate_finite(
    value: float, *, name: str = "value"
) -> None

Validate that value is finite (neither infinite nor NaN).

Parameters:

Name	Type	Description	Default
`value`	`float`	The value to validate.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` is not a real number (`bool` is rejected).
`ValueError`	If `value` is infinite or NaN.

Example

>>> from coola.validation import validate_finite
>>> validate_finite(1.0)

coola.validation.validate_ge ¶

validate_ge(
    value: Any, low: Any, *, name: str = "value"
) -> None

Validate that value is greater than or equal to low.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to validate.	required
`low`	`Any`	The lower bound, inclusive.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` cannot be compared (for example `None`, a `str` or an array with several items).
`ValueError`	If `value` is lower than `low`.

Example

>>> from coola.validation import validate_ge
>>> validate_ge(1, 0)

coola.validation.validate_gt ¶

validate_gt(
    value: Any, low: Any, *, name: str = "value"
) -> None

Validate that value is strictly greater than low.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to validate.	required
`low`	`Any`	The lower bound, exclusive.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` cannot be compared (for example `None`, a `str` or an array with several items).
`ValueError`	If `value` is lower than or equal to `low`.

Example

>>> from coola.validation import validate_gt
>>> validate_gt(1, 0)

coola.validation.validate_in ¶

validate_in(
    value: Any,
    valid: Container[Any],
    *,
    name: str = "value",
) -> None

Validate that value belongs to valid.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to validate.	required
`valid`	`Container[Any]`	The container of valid values.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`ValueError`	If `value` is not in `valid` (an unhashable value is not in a `set`). The listing of `valid` in the message is truncated to 20 items. Pass a `tuple` for a stable listing, the order of a `set` is not stable.

Example

>>> from coola.validation import validate_in
>>> validate_in("a", ("a", "b", "c"))

coola.validation.validate_int ¶

validate_int(value: Any, *, name: str = 'value') -> None

Validate that value is an int.

Booleans are rejected, even though bool subclasses int.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to validate.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` is not an int.

Example

>>> from coola.validation import validate_int
>>> validate_int(1)

coola.validation.validate_isinstance ¶

validate_isinstance(
    value: Any,
    cls: type | tuple[type, ...] | UnionType,
    *,
    name: str = "value",
) -> None

Validate that value is an instance of cls.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to validate.	required
`cls`	`type \| tuple[type, ...] \| UnionType`	The type or tuple of types that `value` must be an instance of.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` is not an instance of `cls`.

Example

>>> from coola.validation import validate_isinstance
>>> validate_isinstance(1, int)

coola.validation.validate_le ¶

validate_le(
    value: Any, high: Any, *, name: str = "value"
) -> None

Validate that value is less than or equal to high.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to validate.	required
`high`	`Any`	The upper bound, inclusive.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` cannot be compared (for example `None`, a `str` or an array with several items).
`ValueError`	If `value` is greater than `high`.

Example

>>> from coola.validation import validate_le
>>> validate_le(0, 1)

coola.validation.validate_lt ¶

validate_lt(
    value: Any, high: Any, *, name: str = "value"
) -> None

Validate that value is strictly less than high.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to validate.	required
`high`	`Any`	The upper bound, exclusive.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` cannot be compared (for example `None`, a `str` or an array with several items).
`ValueError`	If `value` is greater than or equal to `high`.

Example

>>> from coola.validation import validate_lt
>>> validate_lt(0, 1)

coola.validation.validate_not_empty ¶

validate_not_empty(
    value: Sized, *, name: str = "value"
) -> None

Validate that value is not empty.

Parameters:

Name	Type	Description	Default
`value`	`Sized`	The value to validate.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` has no length (for example an iterator, which is never consumed).
`ValueError`	If `value` is empty.

Example

>>> from coola.validation import validate_not_empty
>>> validate_not_empty([1, 2, 3])

coola.validation.validate_number ¶

validate_number(value: Any, *, name: str = 'value') -> None

Validate that value is a real number.

Booleans are rejected, even though bool subclasses int. The NumPy scalars (numpy.float32, numpy.int64...) are accepted.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to validate.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` is not a real number or is a `bool`.

Example

>>> from coola.validation import validate_number
>>> validate_number(1)
>>> validate_number(1.5)

coola.validation.validate_range ¶

validate_range(
    value: Any,
    low: Any,
    high: Any,
    *,
    low_inclusive: bool = True,
    high_inclusive: bool = True,
    name: str = "value",
) -> None

Validate that value is in the range from low to high.

By default, the range is closed (low <= value <= high). The two flags exclude a bound, which gives the open range low < value < high or a half-open range. The range is written with the usual notation in the error message, for example [0, 1).

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to validate.	required
`low`	`Any`	The lower bound.	required
`high`	`Any`	The upper bound.	required
`low_inclusive`	`bool`	If `True`, `low` is a valid value.	`True`
`high_inclusive`	`bool`	If `True`, `high` is a valid value.	`True`
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` cannot be compared with the bounds (for example `None`, a `str` or an array with several items).
`ValueError`	If the range is empty (for example `low > high`), or if `value` is not in the range (or is NaN).

Example

>>> from coola.validation import validate_range
>>> validate_range(0.5, 0, 1)
>>> validate_range(0, 0, 1, high_inclusive=False)

coola.validation.comparison ¶

Contain functions to validate comparisons.

coola.validation.comparison.validate_finite ¶

validate_finite(
    value: float, *, name: str = "value"
) -> None

Validate that value is finite (neither infinite nor NaN).

Parameters:

Name	Type	Description	Default
`value`	`float`	The value to validate.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` is not a real number (`bool` is rejected).
`ValueError`	If `value` is infinite or NaN.

Example

>>> from coola.validation import validate_finite
>>> validate_finite(1.0)

coola.validation.comparison.validate_ge ¶

validate_ge(
    value: Any, low: Any, *, name: str = "value"
) -> None

Validate that value is greater than or equal to low.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to validate.	required
`low`	`Any`	The lower bound, inclusive.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` cannot be compared (for example `None`, a `str` or an array with several items).
`ValueError`	If `value` is lower than `low`.

Example

>>> from coola.validation import validate_ge
>>> validate_ge(1, 0)

coola.validation.comparison.validate_gt ¶

validate_gt(
    value: Any, low: Any, *, name: str = "value"
) -> None

Validate that value is strictly greater than low.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to validate.	required
`low`	`Any`	The lower bound, exclusive.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` cannot be compared (for example `None`, a `str` or an array with several items).
`ValueError`	If `value` is lower than or equal to `low`.

Example

>>> from coola.validation import validate_gt
>>> validate_gt(1, 0)

coola.validation.comparison.validate_le ¶

validate_le(
    value: Any, high: Any, *, name: str = "value"
) -> None

Validate that value is less than or equal to high.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to validate.	required
`high`	`Any`	The upper bound, inclusive.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` cannot be compared (for example `None`, a `str` or an array with several items).
`ValueError`	If `value` is greater than `high`.

Example

>>> from coola.validation import validate_le
>>> validate_le(0, 1)

coola.validation.comparison.validate_lt ¶

validate_lt(
    value: Any, high: Any, *, name: str = "value"
) -> None

Validate that value is strictly less than high.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to validate.	required
`high`	`Any`	The upper bound, exclusive.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` cannot be compared (for example `None`, a `str` or an array with several items).
`ValueError`	If `value` is greater than or equal to `high`.

Example

>>> from coola.validation import validate_lt
>>> validate_lt(0, 1)

coola.validation.comparison.validate_range ¶

validate_range(
    value: Any,
    low: Any,
    high: Any,
    *,
    low_inclusive: bool = True,
    high_inclusive: bool = True,
    name: str = "value",
) -> None

Validate that value is in the range from low to high.

By default, the range is closed (low <= value <= high). The two flags exclude a bound, which gives the open range low < value < high or a half-open range. The range is written with the usual notation in the error message, for example [0, 1).

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to validate.	required
`low`	`Any`	The lower bound.	required
`high`	`Any`	The upper bound.	required
`low_inclusive`	`bool`	If `True`, `low` is a valid value.	`True`
`high_inclusive`	`bool`	If `True`, `high` is a valid value.	`True`
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` cannot be compared with the bounds (for example `None`, a `str` or an array with several items).
`ValueError`	If the range is empty (for example `low > high`), or if `value` is not in the range (or is NaN).

Example

>>> from coola.validation import validate_range
>>> validate_range(0.5, 0, 1)
>>> validate_range(0, 0, 1, high_inclusive=False)

coola.validation.container ¶

Contain functions to validate containers.

coola.validation.container.validate_in ¶

validate_in(
    value: Any,
    valid: Container[Any],
    *,
    name: str = "value",
) -> None

Validate that value belongs to valid.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to validate.	required
`valid`	`Container[Any]`	The container of valid values.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`ValueError`	If `value` is not in `valid` (an unhashable value is not in a `set`). The listing of `valid` in the message is truncated to 20 items. Pass a `tuple` for a stable listing, the order of a `set` is not stable.

Example

>>> from coola.validation import validate_in
>>> validate_in("a", ("a", "b", "c"))

coola.validation.container.validate_not_empty ¶

validate_not_empty(
    value: Sized, *, name: str = "value"
) -> None

Validate that value is not empty.

Parameters:

Name	Type	Description	Default
`value`	`Sized`	The value to validate.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` has no length (for example an iterator, which is never consumed).
`ValueError`	If `value` is empty.

Example

>>> from coola.validation import validate_not_empty
>>> validate_not_empty([1, 2, 3])

coola.validation.type ¶

Contain functions to validate types.

The checks are strict and do not convert the value. validate_isinstance is the general function. validate_int and validate_number exist because they reject bool, which subclasses int. A validator is added only if it states a constraint that isinstance or one comparison cannot state without a special case.

coola.validation.type.validate_int ¶

validate_int(value: Any, *, name: str = 'value') -> None

Validate that value is an int.

Booleans are rejected, even though bool subclasses int.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to validate.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` is not an int.

Example

>>> from coola.validation import validate_int
>>> validate_int(1)

coola.validation.type.validate_isinstance ¶

validate_isinstance(
    value: Any,
    cls: type | tuple[type, ...] | UnionType,
    *,
    name: str = "value",
) -> None

Validate that value is an instance of cls.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to validate.	required
`cls`	`type \| tuple[type, ...] \| UnionType`	The type or tuple of types that `value` must be an instance of.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` is not an instance of `cls`.

Example

>>> from coola.validation import validate_isinstance
>>> validate_isinstance(1, int)

coola.validation.type.validate_number ¶

validate_number(value: Any, *, name: str = 'value') -> None

Validate that value is a real number.

Booleans are rejected, even though bool subclasses int. The NumPy scalars (numpy.float32, numpy.int64...) are accepted.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to validate.	required
`name`	`str`	The name of the value, used in the error message.	`'value'`

Raises:

Type	Description
`TypeError`	If `value` is not a real number or is a `bool`.

Example

>>> from coola.validation import validate_number
>>> validate_number(1)
>>> validate_number(1.5)