check_values

plasmapy.utils.decorators.checks.check_values(

func=None,

checks_on_return: dict[str, bool] | None = None,

**checks: dict[str, bool],

)[source]

A decorator to ‘check’ — limit/control — the values of input and return arguments to a function or method.

Parameters:

func – The function to be decorated
checks_on_return (Dict[str, bool]) – Specifications for value checks on the return of the function being wrapped. (see check values for valid specifications)

**checks (Dict[str, Dict[str, bool]]) –

Specifications for value checks on the input arguments of the function being wrapped. Each keyword argument in checks is the name of a function argument to be checked and the keyword value contains the value check specifications.

The value check specifications are defined within a dictionary containing the keys defined below. If the dictionary is empty or omitting keys, then the default value will be assumed for the missing keys.

Key	Type	Description
can_be_negative	`bool`	[DEFAULT `True`] values can be negative
can_be_complex	`bool`	[DEFAULT `False`] values can be complex numbers
can_be_inf	`bool`	[DEFAULT `True`] values can be `inf`
can_be_nan	`bool`	[DEFAULT `True`] values can be `nan`
none_shall_pass	`bool`	[DEFAULT `False`] values can be a python `None`
can_be_zero	`bool`	[DEFAULT `True`] values can be zero

Notes

Checking of function arguments *args and **kwargs is not supported.
Full functionality is defined by the class CheckValues.

Examples

from plasmapy.utils.decorators import check_values

@check_values(
    arg1={"can_be_negative": False, "can_be_nan": False},
    arg2={"can_be_inf": False},
    checks_on_return={"none_shall_pass": True},
)
def foo(arg1, arg2):
    return None


# on a method
class Foo:
    @check_values(
        arg1={"can_be_negative": False, "can_be_nan": False},
        arg2={"can_be_inf": False},
        checks_on_return={"none_shall_pass": True},
    )
    def bar(self, arg1, arg2):
        return None