Python Toolkit API Node Tree

zhinst.toolkit.nodetree.nodetree.NodeTree(connection, prefix_hide=None, list_nodes=None, preloaded_json=None)

High-level generic lazy node tree.

All interactions with an Zurich Instruments device or a LabOne module happens through manipulating nodes. The NodeTree provides a pythonic way for that.

It reads all available nodes its additional information from the provided connection and makes them available in nested dictionary like interface. The interface also supports accessing the nodes by attribute.

>>> nodetree = NodeTree(connection)
>>> nodetree.example.nodes[8].test
/example/nodes/8/test

To speed up the initialization time the node tree is initialized lazy. Meaning the dictionary is kept as a flat dictionary and is not converted into a nested one. In addition the nested node objects returned by the NodeTree also are just simple placeholders. Only when performing operations on a node its validity is checked an the calls get translated to the correct node string. (For more information on how to manipulate nodes refer to zhinst.toolkit.nodetree.node.Node).

Example

nodetree = NodeTree(daq) nodetree.dev123.demods[0].freq /dev123/demods/0/freq nodetree = NodeTree(daq, prefix_hide = "dev123", list_nodes = ["/dev123/*"]) nodetree.demods[0].freq /dev123/demods/0/freq

Parameters:

Name	Type	Description	Default
connection	Connection	Underlying connection for the node tree. All operations are converted into calls to that connection.	required
prefix_hide	Optional[str]	Prefix, e.g. device id, that should be hidden in the nodetree. (Hidden means that users do not need to specify it and it will be added automatically to the nodes if necessary) (default = None)	None
list_nodes	Optional[list]	List of nodes that should be downloaded from the connection. By default all available nodes are downloaded. (default = None)	None
preloaded_json	Optional[NodeDoc]	Optional preloaded node information. (e.g for the HF2 that does not support the listNodesJson function)	None

connection: Connection property

Underlying connection.

Returns:

Type	Description
Connection	Underlying connection.

prefix_hide: t.Optional[str] property

Prefix (e.g device id), that is hidden in the nodetree.

Hidden means that users do not need to specify it and it will be added automatically to the nodes if necessary.

Returns:

Type	Description
Optional[str]	Prefix that is hidden in the nodetree.

raw_dict: dict property

Underlying flat dictionary with all node information.

Returns:

Type	Description
dict	Underlying flat dictionary with all node information.

transaction: Transaction property

Transaction manager.

Returns:

Type	Description
Transaction	Transaction manager.

get_node_info(node)

Get the node information for a node.

The nodetree caches the node information for each node. This enables lazy created nodes to access its information fast without additional cost.

Please note that this function returns a valid object for all node objects. Even if the node does not exist on the device.

The cache (dict) lifetime is bound to the nodetree object and each session/nodetree instance must have its own cache.

Parameters:

Name	Type	Description	Default
node	Node	Node object	required

Returns:

Type	Description
	Node information

get_node_info_raw(node)

Get the information/data for a node.

Unix shell-style wildcards are supported.

Parameters:

Name	Type	Description	Default
node	Union[Node, str]	Node object or string representation.	required

Returns:

Type	Description
dict[Node, Optional[dict]]	Node(s) information.

Raises:

Type	Description
ValueError	If the node is passed as a string in form of a relative path and no prefix can be added.

node_to_raw_path(node)

Converts a node into a raw node path string.

The function does not check if the node exists, but if the node exist the returned raw node path exists in the underlying dictionary.

Parameters:

Name	Type	Description	Default
node	Node	Node object.	required

Returns:

Type	Description
str	Raw node path that can be used a key in the internal dictionary.

raw_path_to_node(raw_path)

Converts a raw node path string into a Node object.

The function does not check if the node exists, but if the node exist the returned node does correspond also to that node.

Parameters:

Name	Type	Description	Default
raw_path	str	Raw node path (e.g. /dev1234/relative/path/to/node).	required

Returns:

Type	Description
Node	The corresponding node object linked to this nodetree.

set_transaction()

Context manager for a transactional set.

Can be used as a context in a with statement and bundles all node set commands into a single transaction. This reduces the network overhead and often increases the speed.

Within the with block all set commands to a node will be buffered and grouped into a single command at the end of the context automatically. (All other operations, e.g. getting the value of a node, will not be affected)

Warning

The set is always performed as deep set if called on device nodes.

Example

with nodetree.set_transaction(): nodetree.test[0].a(1) nodetree.test[1].a(2)

string_to_raw_path(node)

Converts a string representation of a node into a raw node path string.

The function does not check if the node exists, but if the node exist the returned raw node path exists in the underlying dictionary.

If the string does not represent a absolute path (leading slash) the :obj:prefix_hide will be added to the node string.

Parameters:

Name	Type	Description	Default
node	str	A string representation of the node.	required

Returns:

Type	Description
str	Raw node path that can be used a key in the internal dictionary.

Raises:

Type	Description
ValueError	If the node is a relative path and no prefix can be added.

to_raw_path(node)

Converts a node into a raw node path string.

The function does not check if the node exists, but if the node exist the returned raw node path exists in the underlying dictionary.

Parameters:

Name	Type	Description	Default
node	Union[Node, str]	Node object or string representing the node.	required

Returns:

Type	Description
str	Raw node path that can be used a key in the internal dictionary.

Raises:

Type	Description
ValueError	If the node is passed as a string in form of a relative

update_node(node, updates, *, add=False)

Update a node in the NodeTree.

Nodes containing wildcards will be resolved but it is not possible to add new nodes with a node argument containing wildcards.

Parameters:

Name	Type	Description	Default
node	Union[Node, str]	Node object or string representation.	required
updates	dict[str, Any]	Data that will be updated (overwrites the existing values).	required
add	bool	Flag a non-existing node should be added (default = False).	False

Raises:

Type	Description
KeyError	If node does not exist and the add Flag is not set
ValueError	If the node is passed as a string in form of a relative path and no prefix can be added.

update_nodes(update_dict, *, add=False, raise_for_invalid_node=True)

Update multiple nodes in the NodeTree.

Similar to :func:update_node but for multiple elements that are represented as a dict.

Parameters:

Name	Type	Description	Default
update_dict	dict[Union[Node, str], dict[str, Any]]	Dictionary with node as keys and entries that will be updated as values.	required
add	bool	Flag a non-existing node should be added (default = False).	False
raise_for_invalid_node	bool	If set to True, when add is False and the node(s) are invalid/nonexistent, an error is raised. Otherwise will issue a warning and continue adding the valid nodes.	True

Raises:

Type	Description
KeyError	If node does not exist and the add flag is not set

zhinst.toolkit.nodetree.nodetree.Transaction(nodetree)

Transaction Manager.

Buffers commands (node, value pairs)

Parameters:

Name	Type	Description	Default
nodetree	NodeTree	Underlying Nodetree	required

add(node, value)

Adds a single node set command to the set transaction.

Parameters:

Name	Type	Description	Default
node	Union[Node, str]	Node object or string representing the node.	required
value	Any	Value that should be set to the node.	required

Raises:

Type	Description
AttributeError	If no transaction is in progress.
ValueError	If the node is passed as a string in form of a relative path and no prefix can be added.

add_raw_list(node_value_pairs)

Adds multiple set commands at a time.

Parameters:

Name	Type	Description	Default
node_value_pairs	list[tuple[str, Any]]	List of settings in the form of (node_string, value)	required

Raises:

Type	Description
TookitError	if this function is called outside a transaction. It is exclusively designed to be used within transactions.

Note

settings can only take strings which to describe a node, but no node objects

in_progress()

Flag if the transaction is in progress.

result()

Resulting transaction list.

Returns:

Type	Description
Optional[list[tuple[str, Any]]]	List of all added node value pairs.

start(add_callback=None)

Start the transaction.

Parameters:

Name	Type	Description	Default
add_callback	Optional[Callable[[str, Any], None]]	Callback to be called when ever a node value pare has been added to the queue. Only valid for the started transaction.	None

Raises:

Type	Description
ToolkitError	A transaction is already in progress.

stop()

Stop the transaction.