skshapes.input_validation package¶

Input validation module

This module contains the input validation functions used in the library.

Notes

For developers: when writing a new decorator, it is important to use the functools.wraps decorator to preserve the decorated function’s metadata (name, docstring, etc.). Otherwise, the decorated function will be relaced by the decorator’s wrapper function, and the metadata will be lost. This will cause problems with beartype, which relies on the metadata to perform type checking.

Submodules¶

skshapes.input_validation.converters module¶

Converters for arguments.

skshapes.input_validation.converters.convert_inputs(func)¶

Convert a function’s inputs to the right type.

It converts the inputs arrays to the right type (torch.Tensor) and convert the dtype of the tensor to the right one (float32 for float, int64 for int), before calling the function. It allows to use the function with numpy arrays or torch tensors, but keep in mind that scikit-shapes will always convert the inputs to torch tensors.

If used in combination with the typecheck decorator, it must be called first :

import numpy as np
import skshapes as sks
from skshapes.types import NumericalTensor


@sks.convert_inputs
@sks.typecheck
def foo(a: NumericalTensor) -> NumericalTensor:
    return a


foo(np.zeros(10))  # OK


@sks.typecheck
@sks.convert_inputs
def bar(a: NumericalTensor) -> NumericalTensor:
    return a


bar(np.zeros(10))  # Beartype error

TODO: so far, it only works with numpy arrays and torch tensors. Is it relevant to add support for lists and tuples ? -> must be careful on which arguments are converted (only the ones that are supposed to be converted to torch.Tensor).

skshapes.input_validation.notnone_rules module¶

Not-None rules.

This module define decorators that allows to do some checks for functions that can be called by different arguments combinations. For example, a function can be called with one of the arguments a, b or c but not with more than one of them. This can be done with the one_and_only_one decorator:

@one_and_only_one(["a", "b", "c"])
def foo(a=None, b=None, c=None):
    pass


foo(a=1)  # OK
foo(b=1)  # OK
foo(c=1)  # OK
foo(a=1, b=1)  # InputStructureError

Decorators already implemented:

one_and_only_one : one and only one of the parameters must be not None
no_more_than_one : no more than one of the parameters must be not None

skshapes.input_validation.notnone_rules.generator_notnone_rule(rule)¶

Not-None rules decorator generator.

A not-None rule decorator decorates functions that have a number of keywords arguments that are None by default and that must be provided within certain rules (for example, one and only one of these arguments must be specified)

Parameters:: rule – A function with the number of not none keywords arguments from a list that raises an error if this number does not satisfies certain condition
Returns:: A decorator that can be parametrized with a list of parameters and a boolean arguments to determine if typecheck must be applied
Return type:: Callable

skshapes.input_validation.notnone_rules.no_more_than_one(parameters)¶

Checker for less than one not None parameter.

Parameters:: parameters (list[str]) – the list of parameters to check
Returns:: the decorated function
Return type:: callable
Raises:: InputStructureError – if more than one parameter is not None

Examples

>>> @no_more_than_one(["a", "b"])
>>> def func(a=None, b=None):
>>>     pass
>>> func()
>>> func(a=1)
>>> func(b=1)
>>> func(a=1, b=1)
InputStructureError: No more than one of the parameters a, b must be not None  # noqa E501

skshapes.input_validation.notnone_rules.one_and_only_one(parameters)¶

Checker for only one not None parameter.

Parameters:: parameters (list[str]) – the list of parameters to check
Returns:: the decorated function
Return type:: callable
Raises:: InputStructureError – if more than one parameter is not None

Examples

>>> @one_and_only_one(["a", "b"])
>>> def func(a=None, b=None):
>>>     pass
>>> func(a=1)
>>> func(b=1)
>>> func(a=1, b=1)
InputStructureError: Only one of the parameters a, b must be not None

skshapes.input_validation.notnone_rules.rule_no_more_than_one(not_none, parameters)¶

Rule that checks that no more than one of the parameters is not None.

Return type:: None

skshapes.input_validation.notnone_rules.rule_one_and_only_one(not_none, parameters)¶

Rule that checks that one and only one of the parameters is not None.

Return type:: None

skshapes.input_validation.typechecking module¶

Runtime checker for function’s arguments.

skshapes.input_validation.typechecking.typecheck(func)¶

Runtime checker for function’s arguments.

This is a combination of the beartype and jaxtyping decorators. Jaxtyped allows to use jaxtyping typing hints for arrays/tensors while beartype is a runtime type checker. This decorator allows to use both.

Parameters:: func (callable) – the function to decorate
Returns:: the decorated function
Return type:: callable