qcodes.validators

Classes:

Anything()

Allow any value to pass.

Arrays([min_value, max_value, shape, ...])

Validator for numerical numpy arrays of numeric types (int, float, complex).

Bool()

Requires a boolean.

Callable()

Validator for callables such as functions.

ComplexNumbers()

A validator for complex numbers.

Dict([allowed_keys])

Validator for dictionaries.

Enum(*values)

Requires one of a provided set of values.

Ints([min_value, max_value])

Requires an integer.

Lists(elt_validator)

Validator for lists

MultiType(*validators[, combiner])

Allow the combination of several different validators.

MultiTypeAnd(*validators)

Allow the combination of several different validators.

MultiTypeOr(*validators)

Allow the combination of several different validators.

Multiples([divisor])

A validator that checks if a value is an integer multiple of a fixed divisor.

Nothing(reason)

Allow no value to pass.

Numbers([min_value, max_value])

Requires a number of type int, float, numpy.integer or numpy.floating.

OnOff()

Requires either the string 'on' or 'off'.

PermissiveInts([min_value, max_value])

Requires an integer or a float close to an integer optional parameters min_value and max_value enforce min_value <= value <= max_value.

PermissiveMultiples(divisor[, precision])

A validator that checks whether a value is an integer multiple of a fixed divisor (to within some precision).

Sequence(elt_validator, length, require_sorted)

Validator for Sequences.

Strings([min_length, max_length])

Requires a string optional parameters min_length and max_length limit the allowed length to min_length <= len(value) <= max_length

Validator()

Base class for all value validators each validator should implement:

Functions:

validate_all(*args[, context])

Takes a list of (validator, value) couplets and tests whether they are all valid, raising ValueError otherwise.

class qcodes.validators.Anything[source]

Bases: Validator[Any]

Allow any value to pass.

Methods:

validate(value[, context])

__class_getitem__(params)

Parameterizes a generic class.

Attributes:

validate(value: Any, context: str = '') None[source]
is_numeric = True
classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

property valid_values: tuple[T, ...]
class qcodes.validators.Arrays(min_value: float | int | floating | integer | None = None, max_value: float | int | floating | integer | None = None, shape: Sequence[int | Callable[[], int]] | None = None, valid_types: Sequence[type] | None = None)[source]

Bases: Validator[ndarray]

Validator for numerical numpy arrays of numeric types (int, float, complex). By default it validates int and float arrays.

Min and max validation is not supported for complex numbers.

Parameters:
  • min_value – Min value allowed, default None for which min value check is not performed

  • max_value – Max value allowed, default None for which max value check is not performed

  • shape – The shape of the array, tuple of either ints or Callables taking no arguments that return the size along that dim as an int.

  • valid_types – Sequence of types that the validator should support. Should be a subset of the supported types, or None. If None, all real datatypes will validate.

Raises:

TypeError – If value of arrays are not supported.

Attributes:

Methods:

validate(value[, context])

__class_getitem__(params)

Parameterizes a generic class.

property valid_values: tuple[ndarray]
property shape_unevaluated: tuple[int | Callable[[], int], ...] | None
property shape: tuple[int, ...] | None
validate(value: ndarray, context: str = '') None[source]
is_numeric = True
property min_value: float | None
property max_value: float | None
classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

class qcodes.validators.Bool[source]

Bases: Validator[bool | bool]

Requires a boolean.

Methods:

validate(value[, context])

Validates if bool else raises error.

__class_getitem__(params)

Parameterizes a generic class.

Attributes:

validate(value: bool | bool, context: str = '') None[source]

Validates if bool else raises error.

Parameters:
  • value – Bool

  • context – Context for validation.

Raises:

TypeError – IF not a boolean.

classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

is_numeric = False
property valid_values: tuple[T, ...]
class qcodes.validators.Callable[source]

Bases: Validator[Callable[[…], Any]]

Validator for callables such as functions.

Methods:

validate(value[, context])

Validates if callable else raise typeerror.

__class_getitem__(params)

Parameterizes a generic class.

Attributes:

validate(value: Callable[[...], Any], context: str = '') None[source]

Validates if callable else raise typeerror.

Parameters:
  • value – Value to validate.

  • context – Context for validation.

Raises:

TypeError – If not a callable.

classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

is_numeric = False
property valid_values: tuple[T, ...]
class qcodes.validators.ComplexNumbers[source]

Bases: Validator[complex | complexfloating[Any, Any]]

A validator for complex numbers.

Attributes:

Methods:

validate(value[, context])

Validates if complex number else raises error.

__class_getitem__(params)

Parameterizes a generic class.

validtypes = (<class 'complex'>, <class 'numpy.complex128'>, <class 'numpy.complex64'>)
validate(value: complex | complexfloating[Any, Any], context: str = '') None[source]

Validates if complex number else raises error.

Parameters:
  • value – A complex number.

  • context – Context for validation.

Raises:

TypeError – If not a complex number.

is_numeric = False
classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

property valid_values: tuple[T, ...]
class qcodes.validators.Dict(allowed_keys: Sequence[Hashable] | None = None)[source]

Bases: Validator[dict[Hashable, Any]]

Validator for dictionaries.

Validator for dictionary keys

Parameters:

allowed_keys – if set, all keys must be in allowed_keys

Methods:

__class_getitem__(params)

Parameterizes a generic class.

validate(value[, context])

Validates dictionary keys else raise typeerror.

Attributes:

classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

is_numeric = False
property valid_values: tuple[T, ...]
validate(value: dict[Hashable, Any], context: str = '') None[source]

Validates dictionary keys else raise typeerror.

Parameters:
  • value – Dictionary.

  • context – Context for validation.

Raises:
property allowed_keys: Sequence[Hashable] | None
class qcodes.validators.Enum(*values: Hashable | None)[source]

Bases: Validator[Hashable]

Requires one of a provided set of values. eg. Enum(val1, val2, val3)

Raises:

TypeError – If no value provided

Methods:

validate(value[, context])

__class_getitem__(params)

Parameterizes a generic class.

Attributes:

validate(value: Hashable, context: str = '') None[source]
property values: set[Hashable]
classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

is_numeric = False
property valid_values: tuple[T, ...]
class qcodes.validators.Ints(min_value: inttypes = -1000000000000000000, max_value: inttypes = 1000000000000000000)[source]

Bases: Validator[int | integer[Any] | bool]

Requires an integer. Optional parameters min_value and max_value, enforce min_value <= value <= max_value.

Parameters:
  • max_value – value must be <= max_value

  • min_value – value must be >= min_value

Raises:

TypeError – If min_value and max_value is not an integer. Or min_value is larger than the min_value.

Attributes:

Methods:

validate(value[, context])

Validates if int else raises error.

__class_getitem__(params)

Parameterizes a generic class.

validtypes = (<class 'int'>, <class 'numpy.integer'>)
inttypes = int | numpy.integer
validate(value: inttypes, context: str = '') None[source]

Validates if int else raises error.

Parameters:
  • value – An integer.

  • context – Context for validation.

Raises:
is_numeric = True
property min_value: int
property max_value: int
classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

property valid_values: tuple[T, ...]
class qcodes.validators.Lists(elt_validator: ~qcodes.validators.validators.Validator[~qcodes.validators.validators.T] = <Anything>)[source]

Bases: Validator[list[T]]

Validator for lists

Parameters:

elt_validator – Used to validate the individual elements of the list.

Methods:

validate(value[, context])

Validate if list else raises error.

__class_getitem__(params)

Parameterizes a generic class.

Attributes:

validate(value: list[T], context: str = '') None[source]

Validate if list else raises error.

Parameters:
  • value – A list.

  • context – Context for validation.

Raises:

TypeError – If not list.

property elt_validator: Validator[Any]
classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

is_numeric = False
property valid_values: tuple[T, ...]
class qcodes.validators.MultiType(*validators: Validator[Any], combiner: Literal['OR', 'AND'] = 'OR')[source]

Bases: Validator[Any]

Allow the combination of several different validators. By default, the resulting validator acts as a logical OR between the different validators. Pass combiner=’AND’ to require all validators to return True instead of atleast one returning True.

Examples

  1. To allow numbers as well as “off”:

>>> MultiType(Numbers(), Enum("off"))

or:

>>> MultiType(Numbers(), Enum("off"), combiner='OR')
  1. To require values that are divisible by 0.001 while >=0.002 and <=50000.0

>>> MultiType(PermissiveMultiples(divisor=1e-3),
>>>           Numbers(min_value=2e-3, max_value=5e4),
>>>           combiner='AND')
Raises:

TypeError – If no validators provided. Or if any of the provided argument is not a valid validator. Or if combiner is not in [‘OR’, ‘AND’].

Attributes:

Methods:

validate(value[, context])

__class_getitem__(params)

Parameterizes a generic class.

is_numeric = False
validate(value: Any, context: str = '') None[source]
property combiner: Literal['OR', 'AND']
property validators: tuple[Validator[Any], ...]
classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

property valid_values: tuple[T, ...]
class qcodes.validators.MultiTypeAnd(*validators: Validator[Any])[source]

Bases: MultiType

Allow the combination of several different validators. The resulting validator acts as a logical AND between the different validators.

Example

To require values that are divisible by 0.001 while >=0.002 and <=50000.0

>>> MultiType(PermissiveMultiples(divisor=1e-3),
>>>           Numbers(min_value=2e-3, max_value=5e4),
>>>           combiner='AND')
Raises:

TypeError – If no validators provided. Or if any of the provided argument is not a valid validator.

Methods:

__class_getitem__(params)

Parameterizes a generic class.

validate(value[, context])

Attributes:

classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

property combiner: Literal['OR', 'AND']
is_numeric = False
property valid_values: tuple[T, ...]
validate(value: Any, context: str = '') None
property validators: tuple[Validator[Any], ...]
class qcodes.validators.MultiTypeOr(*validators: Validator[Any])[source]

Bases: MultiType

Allow the combination of several different validators. The resulting validator acts as a logical OR between the different validators.

Example

To allow numbers as well as “off”:

>>> MultiTypeOr(Numbers(), Enum("off"))
Raises:

TypeError – If no validators provided. Or if any of the provided argument is not a valid validator.

Methods:

__class_getitem__(params)

Parameterizes a generic class.

validate(value[, context])

Attributes:

classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

property combiner: Literal['OR', 'AND']
is_numeric = False
property valid_values: tuple[T, ...]
validate(value: Any, context: str = '') None
property validators: tuple[Validator[Any], ...]
class qcodes.validators.Multiples(divisor: int = 1, **kwargs: Any)[source]

Bases: Ints

A validator that checks if a value is an integer multiple of a fixed divisor. This class extends validators.Ints such that the value is also checked for being integer between an optional min_value and max_value. Furthermore this validator checks that the value is an integer multiple of an fixed, integer divisor. (i.e. value % divisor == 0)

Parameters:
  • divisor – the value need the be a multiple of this divisor

  • max_value – value must be <= max_value

  • min_value – value must be >= min_value

Methods:

validate(value[, context])

Validates if the value is a integer multiple of divisor else raises error.

__class_getitem__(params)

Parameterizes a generic class.

Attributes:

validate(value: int | integer[Any], context: str = '') None[source]

Validates if the value is a integer multiple of divisor else raises error.

Parameters:
  • value – An integer.

  • context – Context for validation.

Raises:

ValueError – If not a multiple of a divisor.

is_numeric = True
property divisor: int
classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

inttypes = int | numpy.integer
property max_value: int
property min_value: int
property valid_values: tuple[T, ...]
validtypes = (<class 'int'>, <class 'numpy.integer'>)
class qcodes.validators.Nothing(reason: str)[source]

Bases: Validator[Any]

Allow no value to pass.

Methods:

validate(value[, context])

__class_getitem__(params)

Parameterizes a generic class.

Attributes:

validate(value: Any, context: str = '') None[source]
property reason: str
classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

is_numeric = False
property valid_values: tuple[T, ...]
class qcodes.validators.Numbers(min_value: float | int | floating | integer = -inf, max_value: float | int | floating | integer = inf)[source]

Bases: Validator[float | int | floating | integer]

Requires a number of type int, float, numpy.integer or numpy.floating.

Parameters:
  • min_value – Minimal value allowed, default -inf.

  • max_value – Maximal value allowed, default inf.

Raises:

TypeError – If min or max value not a number. Or if min_value is larger than the max_value.

Attributes:

Methods:

validate(value[, context])

Validate if number else raises error.

__class_getitem__(params)

Parameterizes a generic class.

validtypes = (<class 'float'>, <class 'int'>, <class 'numpy.integer'>, <class 'numpy.floating'>)
validate(value: float | int | floating | integer, context: str = '') None[source]

Validate if number else raises error.

Parameters:
  • value – A number.

  • context – Context for validation.

Raises:
  • TypeError – If not int or float.

  • ValueError – If number is not between the min and the max value.

is_numeric = True
property min_value: float
property max_value: float
classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

property valid_values: tuple[T, ...]
class qcodes.validators.OnOff[source]

Bases: Validator[str]

Requires either the string ‘on’ or ‘off’.

Methods:

validate(value[, context])

__class_getitem__(params)

Parameterizes a generic class.

Attributes:

validate(value: str, context: str = '') None[source]
classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

is_numeric = False
property valid_values: tuple[T, ...]
class qcodes.validators.PermissiveInts(min_value: inttypes = -1000000000000000000, max_value: inttypes = 1000000000000000000)[source]

Bases: Ints

Requires an integer or a float close to an integer optional parameters min_value and max_value enforce min_value <= value <= max_value. Note that you probably always want to use this with a set_parser that converts the float repr to an actual int.

Methods:

validate(value[, context])

Validates if int or close to int (remainder to the rounded value is less than 1e-5) else raises error.

__class_getitem__(params)

Parameterizes a generic class.

Attributes:

validate(value: float | int | floating | integer, context: str = '') None[source]

Validates if int or close to int (remainder to the rounded value is less than 1e-5) else raises error.

Parameters:
  • value – Integer or close to integer.

  • context – Context for validation.

Raises:

TypeError – If not an int or close to it.

classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

inttypes = int | numpy.integer
is_numeric = True
property max_value: int
property min_value: int
property valid_values: tuple[T, ...]
validtypes = (<class 'int'>, <class 'numpy.integer'>)
class qcodes.validators.PermissiveMultiples(divisor: float | int | floating | integer, precision: float = 1e-09)[source]

Bases: Validator[float | int | floating | integer]

A validator that checks whether a value is an integer multiple of a fixed divisor (to within some precision). If both value and divisor are integers, the (exact) Multiples validator is used.

We also allow negative values, meaning that zero by construction is always a valid value.

Parameters:
  • divisor – The number that the validated value should be an integer multiple of.

  • precision – The maximally allowed absolute error between the value and the nearest true multiple.

Raises:

ValueError – If divisor is zero.

Methods:

validate(value[, context])

Validate the given value.

__class_getitem__(params)

Parameterizes a generic class.

Attributes:

validate(value: float | int | floating | integer, context: str = '') None[source]

Validate the given value. Note that this validator does not use context for anything.

Raises:

ValueError – If value is not the multiple of divisor.

is_numeric = True
property divisor: float | int | floating | integer
property precision: float
classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

property valid_values: tuple[T, ...]
class qcodes.validators.Sequence(elt_validator: ~qcodes.validators.validators.Validator[~typing.Any] = <Anything>, length: int | None = None, require_sorted: bool = False)[source]

Bases: Validator[Sequence[Any]]

Validator for Sequences.

Parameters:
  • elt_validator – Used to validate the individual elements of the Sequence.

  • length – Length of sequence.

  • require_sorted – True or False.

Methods:

validate(value[, context])

Validates if sequence else raise typeerror.

__class_getitem__(params)

Parameterizes a generic class.

Attributes:

validate(value: Sequence[Any], context: str = '') None[source]

Validates if sequence else raise typeerror.

Parameters:
  • value – A sequence.

  • context – Context for validation.

Raises:
property elt_validator: Validator[Any]
property length: int | None
property require_sorted: bool
classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

is_numeric = False
property valid_values: tuple[T, ...]
class qcodes.validators.Strings(min_length: int = 0, max_length: int = 1000000000)[source]

Bases: Validator[str]

Requires a string optional parameters min_length and max_length limit the allowed length to min_length <= len(value) <= max_length

Raises:

TypeError – If min_length or max_length negative. Or max_length lower than min_length.

Methods:

validate(value[, context])

Validates if string else raises error.

__class_getitem__(params)

Parameterizes a generic class.

Attributes:

validate(value: str, context: str = '') None[source]

Validates if string else raises error.

Parameters:
  • value – A string.

  • context – Context for validation.

Raises:
  • TypeError – If not a string.

  • ValueError – If length is not between min_length and max_length.

property min_length: int
property max_length: int
classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

is_numeric = False
property valid_values: tuple[T, ...]
class qcodes.validators.Validator[source]

Bases: Generic[T]

Base class for all value validators each validator should implement:

__init__:

Here a private attribute, _valid_values, should be set. _valid_values must be a tuple of at least one valid value. If possible, it should include all valid values. The purpose of this attribute is to make it possible to find a valid value for a Parameter, given its validator.

validate:

Function of two args: value, context value is what you’re testing. context is a string identifying the caller better.

Raises an error (TypeError or ValueError) if the value fails.

is_numeric:

A boolean flag that marks if this a numeric type.

The base class implements,

valid_values:

A property exposing _valid_values, which is a tuple of examples of valid values. For very simple validators, like Bool or Enum, the tuple contains all valid values, but in general it just holds SOME valid values. These example values are intended to be useful when simulating instruments.

Alternatively you may override _valid_values and provide your own implementation of getting valid values.

Attributes:

Methods:

validate(value[, context])

__class_getitem__(params)

Parameterizes a generic class.

is_numeric = False
validate(value: T, context: str = '') None[source]
property valid_values: tuple[T, ...]
classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

qcodes.validators.validate_all(*args: tuple[Validator[Any], Any], context: str = '') None[source]

Takes a list of (validator, value) couplets and tests whether they are all valid, raising ValueError otherwise.

Parameters:
  • *args – Values to validate.

  • context – keyword-only arg with a string to include in the error message giving the user context for the error.