SettingNode

SettingNode#

class SettingNode(name, **children)#

Bases: object

A tree-structured Setting container.

Each child of the node is a Setting, or another SettingNode. Iterating over the node returns all children, recursively. Settings can be accessed by dictionary syntax or attribute syntax:

>>> from exa.common.data.parameter import Parameter
>>> from exa.common.data.setting_node import SettingNode
>>> p1 = Parameter("voltage", "Voltage")
>>> settings = SettingNode('name', volt=p1)
>>> settings.volt.parameter is p1
True
>>> settings['volt'].parameter is p1
True
>>> settings.volt.value is None
True
>>> settings.volt = 7  # updates to Setting(p1, 7)
>>> settings.volt.value
7

Parameters:

name (str) – Name of the node.
children – The children given as keyword arguments. Each argument must be a Setting, Parameter, or a SettingNode. The keywords are used as the names of the nodes. Parameters will be cast into Settings with the value None.

Module: exa.common.data.setting_node

Attributes

`all_settings`	Yields all `Setting` instances inside this node, recursively.
`child_nodes`	ItemsView of immediate child nodes of this node.
`child_settings`	ItemsView of settings of this node.
`children`	Dictionary of immediate child nodes of this node.

Methods

`copy`	Return a deepcopy of this SettingNode.
`diff`	Recursive diff between two SettingNodes.
`find_by_name`	Find first occurrence of Setting or SettingNode by name, by iterating recursively through all children.
`get_parent_of`	Get the first SettingNode that has a Setting named name.
`merge`	Recursively combine the tree structures and values of two SettingNodes.
`merge_values`	Recursively combine the values from another `SettingNode` to this one.
`nodes_by_type`	Yields all nodes, filtered by given node_types.
`print_tree`	Print a tree representation of the contents of this node.
`prune`	Recursively delete all branches from this SettingNode that are not found in `other`.
`set_from_dict`	Recursively set values to Settings, taking values from a dictionary that has similar tree structure.
`setting_with_path_name`	Get Setting from `self` where the name of the parameter is replaced with its path in `self`.
`transform_node_types`	Reduce any subclass of SettingNode and it's contents into instances of cls.
`update_setting`	Update an existing Setting in this tree.

_ipython_key_completions_()#: List items and subtree names, so they occur in IPython autocomplete after node[<TAB>

nodes_by_type(node_types=None, recursive=False)#

Yields all nodes, filtered by given node_types.

Used to find and iterate over nodes of specific types.

Parameters:

node_types (type | tuple[type, ...] | None) – when iterating over the tree, yields only instances that match this type or any of the types in the tuple. By default, yields Settings and SettingNodes.
recursive (bool) – If True, the search is carried recursively. If False, the search is limited to immediate child nodes.

Returns:

Iterator that yields the filtered nodes.

Return type:

Iterator

update_setting(setting)#

Update an existing Setting in this tree.

Parameters:: setting (Setting) – Setting that will replace an existing Setting with the same name. Or if the setting is an element-wise setting (i.e. it has a non-empty value of setting.element_indices), the corresponding element will be updated in the collection.
Raises:: UnknownSettingError – If no setting is found in the children of this tree.
Return type:: None

property all_settings: Generator[Setting]#: Yields all Setting instances inside this node, recursively.

property children: dict[str, Setting | SettingNode]#: Dictionary of immediate child nodes of this node.

property child_settings: ItemsView[str, Setting]#: ItemsView of settings of this node.

property child_nodes: ItemsView[str, SettingNode]#: ItemsView of immediate child nodes of this node.

copy()#

Return a deepcopy of this SettingNode.

Return type:: SettingNode

get_parent_of(name)#

Get the first SettingNode that has a Setting named name.

Parameters:: name (str) – Name of the setting to look for.
Returns:: A SettingNode that has a child name.
Return type:: SettingNode

find_by_name(name)#

Find first occurrence of Setting or SettingNode by name, by iterating recursively through all children.

Parameters:: name (str) – Name of the Setting or SettingNode to look for.
Returns:: First found item, or None if nothing is found.
Return type:: SettingNode | Setting | None

static merge(first, second)#

Recursively combine the tree structures and values of two SettingNodes.

In case of conflicting nodes,values in first take priority regardless of the replaced content in second. None values are never prioritized.

Parameters:

first (SettingNode) – SettingNode to merge, whose values and structure take priority
second (SettingNode) – SettingNode to merge.

Returns:

A new SettingNode constructed from arguments.

Return type:

SettingNode

merge_values(other, prioritize_other=False)#

Recursively combine the values from another SettingNode to this one.

The resulting tree structure the same as that of self.

Parameters:

other (SettingNode) – SettingNode to merge.
prioritize_other (bool) – If True, will prioritize values in other. If False (default), only None values in self will be replaced.

prune(other)#

Recursively delete all branches from this SettingNode that are not found in other.

Parameters:: other (SettingNode) –
Return type:: None

print_tree(levels=5)#

Print a tree representation of the contents of this node.

Parameters:: levels (int) – display this many levels, starting from the root.
Return type:: None

classmethod transform_node_types(node)#

Reduce any subclass of SettingNode and it’s contents into instances of cls.

Parameters:: node (SettingNode) – node to transform.
Returns:: A new SettingNode with the same structure as the original, but where node instances are of type cls.
Return type:: SettingNode

set_from_dict(dct, strict=False)#

Recursively set values to Settings, taking values from a dictionary that has similar tree structure. Keys that are not found in self are ignored, unless strict is True.

Parameters:

dct (dict[str, Any]) – Dictionary containing the new values to use.
strict (bool) – If True, will raise error if dct contains a setting that is not found in self.

Raises:

UnknownSettingError – If the condition of strict happens.

Return type:

None

setting_with_path_name(setting)#

Get Setting from self where the name of the parameter is replaced with its path in self.

The path is defined as the sequence of attribute keys leading to the node with setting in it. The method is used for conveniently saving settings tree observations with their settings tree path as the dut_field.

Parameters:: setting (Setting) – Setting to search for.
Returns:: Copy of Setting setting where the parameter name is replaced with its path in self.
Raises:: UnknownSettingError – If name is not found within self.
Return type:: Setting

diff(other, *, path='')#

Recursive diff between two SettingNodes.

This function is meant to produce human-readable output, e.g. for debugging purposes. It returns the differences in a list of strings, each string detailing one specific difference. The diff is non-symmetric.

Parameters:

other (SettingNode) – second node to compare self to
path (str) – node path to the currently compared nodes (used in printing the results)

Returns:

differences from self to other, in depth-first order

Return type:

list[str]

_withsiprefix(val, unit)#

Turn a numerical value and unit, and return rescaled value and SI prefixed unit.

Unit must be a whitelisted SI base unit.

SettingNode

Contents

SettingNode#