Validator functions

Validators are used in conjunction with the Instrument.control or Instrument.setting functions to allow properties with complex restrictions for valid values. They are described in more detail in the Restricting values with validators section.

pymeasure.instruments.validators.discreteTruncate(number, discreteSet)

Truncates the number to the closest element in the positive discrete set. Returns False if the number is larger than the maximum value or negative. :rtype: Union[TypeVar(NumericT, bound= Union[float, int, Decimal]), Literal[False]]

Deprecated since version 0.17.0: Use truncated_discrete_set_positive() instead.

pymeasure.instruments.validators.joined_validators(*validators)

Returns a validator function that represents a list of validators joined together.

A value passed to the validator is returned if it passes any validator (not all of them). Otherwise it raises a ValueError.

Note: the joined validator expects values to be a sequence of values appropriate for the respective validators (often sequences themselves).

Example:

>>> from pymeasure.instruments.validators import strict_discrete_set, strict_range
>>> from pymeasure.instruments.validators import joined_validators
>>> joined_v = joined_validators(strict_discrete_set, strict_range)
>>> values = [['MAX','MIN'], range(10)]
>>> joined_v(5, values)
5
>>> joined_v('MAX', values)
'MAX'
>>> joined_v('NONSENSE', values)
Traceback (most recent call last):
...
ValueError: Value of NONSENSE does not match any of the joined validators
Parameters:

validators (Callable[[Any, Any], Any]) – an iterable of other validators

Return type:

Callable[[Any, Any], Any]

pymeasure.instruments.validators.modular_range(value, values)

Provides a validator function that returns the value if it is in the range. Otherwise it returns the value, modulo the max of the range.

Parameters:

  • value (TypeVar(NumericT, bound= Union[float, int, Decimal])) – a value to test

  • values (Union[Sequence[TypeVar(NumericT, bound= Union[float, int, Decimal])], ndarray]) – A set of values that are valid

Return type:

TypeVar(NumericT, bound= Union[float, int, Decimal])

pymeasure.instruments.validators.modular_range_bidirectional(value, values)

Provides a validator function that returns the value if it is in the range. Otherwise it returns the value, modulo the max of the range. Allows negative values.

Parameters:

  • value (TypeVar(NumericT, bound= Union[float, int, Decimal])) – a value to test

  • values (Union[Sequence[TypeVar(NumericT, bound= Union[float, int, Decimal])], ndarray]) – A set of values that are valid

Return type:

TypeVar(NumericT, bound= Union[float, int, Decimal])

pymeasure.instruments.validators.strict_discrete_range(value, values, step)

Provides a validator function that returns the value if its value is less than the maximum and greater than the minimum of the range and is a multiple of step. Otherwise it raises a ValueError.

Parameters:

  • value (TypeVar(NumericT, bound= Union[float, int, Decimal])) – A value to test

  • values (Union[Sequence[TypeVar(NumericT, bound= Union[float, int, Decimal])], ndarray]) – A range of values (range, list, etc.)

  • step (TypeVar(NumericT, bound= Union[float, int, Decimal])) – Minimum stepsize (resolution limit)

Raises:

ValueError if the value is out of the range

Return type:

TypeVar(NumericT, bound= Union[float, int, Decimal])

pymeasure.instruments.validators.strict_discrete_set(value, values)

Provides a validator function that returns the value if it is in the discrete set. Otherwise it raises a ValueError.

Parameters:

  • value (TypeVar(T)) – A value to test

  • values (Union[Iterable[TypeVar(T)], dict[TypeVar(T), Any]]) – A set of values that are valid

Raises:

ValueError if the value is not in the set

Return type:

TypeVar(T)

pymeasure.instruments.validators.strict_range(value, values)

Provides a validator function that returns the value if its value is less than or equal to the maximum and greater than or equal to the minimum of values. Otherwise it raises a ValueError.

Parameters:

  • value (TypeVar(NumericT, bound= Union[float, int, Decimal])) – A value to test

  • values (Union[Sequence[TypeVar(NumericT, bound= Union[float, int, Decimal])], ndarray]) – A range of values (range, list, etc.)

Raises:

ValueError if the value is out of the range

Return type:

TypeVar(NumericT, bound= Union[float, int, Decimal])

pymeasure.instruments.validators.truncated_discrete_set(value, values)

Provides a validator function that returns the value if it is in the discrete set. Otherwise, it returns the smallest value that is larger than the value.

Parameters:

  • value (TypeVar(NumericT, bound= Union[float, int, Decimal])) – A value to test

  • values (Iterable[TypeVar(NumericT, bound= Union[float, int, Decimal])]) – A set of values that are valid

Return type:

TypeVar(NumericT, bound= Union[float, int, Decimal])

Note

Values not in the discrete set are silently mapped without raising an error or otherwise informing the user. The value actually sent to the device may therefore differ from the value the user set. Prefer strict_discrete_set() by default and only use a truncated validator when silent clipping is genuinely desired and the property docstring documents this behavior.

pymeasure.instruments.validators.truncated_discrete_set_positive(number, discrete_set)

Truncates the number to the closest element in the positive discrete set. Returns False if the number is larger than the maximum value or negative. :rtype: Union[TypeVar(NumericT, bound= Union[float, int, Decimal]), Literal[False]]

Note

Invalid values are silently mapped without raising an error or otherwise informing the user. The value actually sent to the device (or the resulting no-op) may therefore differ from what the user set. Prefer strict_discrete_set() by default and only use a truncated validator when silent clipping is genuinely desired and the property docstring documents this behavior.

pymeasure.instruments.validators.truncated_range(value, values)

Provides a validator function that returns the value if it is in the range. Otherwise it returns the closest range bound.

Parameters:

  • value (TypeVar(NumericT, bound= Union[float, int, Decimal])) – A value to test

  • values (Union[Sequence[TypeVar(NumericT, bound= Union[float, int, Decimal])], ndarray]) – A set of values that are valid

Return type:

TypeVar(NumericT, bound= Union[float, int, Decimal])

Note

Out-of-range values are silently clipped to the closest range bound without raising an error or otherwise informing the user. The value actually sent to the device may therefore differ from the value the user set. Prefer strict_range() by default and only use a truncated validator when silent clipping is genuinely desired and the property docstring documents this behavior.