Python Toolkit API Command Table

This module provides a :class:CommandTable class to create and modify ZI device command tables.

zhinst.toolkit.command_table.CommandTable(json_schema, active_validation=True)

Representation of a ZI device command table.

The class provides functionality to create and modify existing command tables. The CommandTable can be modified by via header and table properties.

Parameters:

Name	Type	Description	Default
json_schema	Union[str, dict]	JSON Schema of the command table.	required
active_validation	bool	Active validation of table entries. (default = True) Active validation enabled: Each time a table entry is accessed, the values are validated against the given JSON schema. It is suggested to keep disabled in production code as it will slow the command table creation. Active validation disabled: No validation happens during command table entry modifications, thus making the creation of the command table faster. Method is_valid() can be used for command table validation when active validation is disabled. It is recommended to avoid it in production code.	True

Example:

>>> from zhinst.toolkit import CommandTable
>>> ct = CommandTable(json_schema)

The header and table and then be called:

>>> ct.header.version
"1.1"
>>> ct.header.userString = "My table"
>>> ct.table[0].amplitude.value = 1
>>> ct.table[0].amplitude
1
>>> ct.as_dict()

Example: Active validation

Using active validation, error raised instantly on incorrect value:

>>> ct = CommandTable(json_schema, active_validation=True)
>>> ct.table[0].amplitude0.value = 999e9
ValidationError

Disabling active validation:

No ValidationError is raised during the creation of the command table, but once it is uploaded or called as_dict(), the validation happens.

>>> ct = CommandTable(json_schema, active_validation=False)
>>> ct.table[0].amplitude0.value = 999e9  # No errors raised
>>> ct.as_dict()
ValidationError

Disabling active validation improves the speed of large command tables:

>>> for i in range(1024):
>>>    ct.table[i].waveform.index = 1
>>>    ct.table[i].amplitude0.value = 1
>>>    ct.table[i].amplitude1.value = -0.0
>>>    ct.table[i].amplitude0.increment = False
>>>    ct.table[i].amplitude0.increment = True

active_validation: bool property writable

State of active validation.

Returns:

Type	Description
bool	True if active validation is enabled.

header: HeaderEntry property

Header of the built command table.

Returns:

Type	Description
HeaderEntry	Header Entry

table: ListEntry property

Table entry of the built command table.

Returns:

Type	Description
ListEntry	List Entry

as_dict()

Return a dictionary representation of the CommandTable.

The function formats the returner value into a schema which is accepted by the ZI devices which support command tables.

The table is validated against the given schema.

Returns:

Type	Description
dict	CommandTable as a Python dictionary.

Raises:

Type	Description
`~zhinst.toolkit.exceptions.ValidateError`	The command table does not correspond to the given JSON schema.

clear()

Clear CommandTable back to its initial state.

is_valid(raise_for_invalid=False)

Checks if the command table is valid.

Parameters:

Name	Type	Description	Default
raise_for_invalid	bool	Raises exception if the command table is invalid. The flag can be used for getting feedback on what is wrong in the command table.	False

Returns:

Type	Description
bool	True if the command table is valid.

Raises:

Type	Description
ValidationError	If raise_for_invalid was set to True and the command table is invalid.

update(command_table)

Update the existing instance of CommandTable with command table JSON.

If both command tables have the same properties, the existing ones are overwritten by the new command table.

Parameters:

Name	Type	Description	Default
command_table	Union[str, dict]	Existing command table JSON.	required

zhinst.toolkit.command_table.HeaderEntry(schema, path, version=None, active_validation=True)

Bases: ParentEntry

Header entry of a command table.

Parameters:

Name	Type	Description	Default
schema	dict	JSON schema of the node.	required
path	tuple	Path representation of the node.	required
version	Optional[str]	JSON schema version	None
active_validation	bool	Enable active validation.	True

version: str property

Version of the schema.

zhinst.toolkit.command_table.ListEntry(schema, index_schema, path, active_validation=True)

Bases: ParentNode

List entry of a command table.

Parameters:

Name	Type	Description	Default
schema	dict	JSON schema of the node.	required
path	tuple[str, ...]	Path representation of the node.	required
active_validation	bool	Enable active validation.	True

range: tuple[int, int] property

Get the range for number of minimum and maximum items in the table.

Returns:

Type	Description
tuple[int, int]	Range for number of items in the table.

as_list()

Return a list representation of the table.

Returns:

Type	Description
list[dict]	List of dictionary representation of entries in the table.

zhinst.toolkit.command_table.ParentEntry(schema, path, active_validation=True)

Bases: ParentNode

Parent entry of the CommandTable.

The parent can have both properties and child properties.

Parameters:

Name	Type	Description	Default
schema	dict	JSON schema of the node.	required
path	tuple[str, ...]	Path representation of the node.	required
active_validation	bool	Enable active validation.	True

as_dict()

Return a dictionary presentation of the table node.

Returns:

Name	Type	Description
dict	dict	Table node as dictionary.

clear()

Clear all properties from the object.

info(value=None)

Get info about the property.

Parameters:

Name	Type	Description	Default
value	Optional[str]	Info about to specific property. Otherwise return info about the whole property.	None

Returns:

Type	Description
dict	Info about the property.

zhinst.toolkit.command_table.ParentNode(schema, path, active_validation=True)

ParentNode of the command table.

ParentNode can contain one or multiple arguments and child ParentNodes. It offers a dictionary-like object to manipulate command table properties. Similar to the device nodes, it supports accessing the properties by attribute.

Parameters:

Name	Type	Description	Default
schema	dict	JSON schema of the node.	required
path	tuple[str, ...]	Path representation of the node.	required
active_validation	bool	Enable active validation.	True

is_empty()

Check if the Node is empty and has no properties.

Returns:

Name	Type	Description
bool	bool	If children exists.