tree API

exception tree.tree.ChildNotFoundError[source]: Bases: TreeException

exception tree.tree.TreeException[source]: Bases: Exception

class tree.tree.Tree(*args, **kwargs)[source]

Bases: ABC

An abstract lightweight tree class for managing tree structures in MusicXML and musicscore packages.

add_child(child: Tree) → Tree[source]

Tree method

Check and add child to list of children. Child’s parent is set to self.

Parameters:: child –
Returns:: child
Return type:: Tree

get_children() → List[Tree][source]

Tree method

Returns:: list of added children.
Return type:: List[Tree]

get_children_of_type(type) → List[Tree][source]

Tree method

Returns:: list of added children of type.
Return type:: List[Tree]

get_coordinates_in_tree() → str[source]

Tree method

Returns:: 0 for root. 1, 2, … for layer 1. Other layers: x.y.z…. Example: 3.2.2 => third child of secod child of second child of the root.
Return type:: str

>>> class TestTree(Tree):
...   def _check_child_to_be_added(self, child):
...      return True
>>> root = TestTree()
>>> root.get_coordinates_in_tree()
'0'
>>> child1 = root.add_child(TestTree())
>>> child2 = root.add_child(TestTree())
>>> grandchild1 = child2.add_child(TestTree())
>>> grandchild2 = child2.add_child(TestTree())
>>> child1.get_coordinates_in_tree()
'1'
>>> child2.get_coordinates_in_tree()
'2'
>>> grandchild1.get_coordinates_in_tree()
'2.1'
>>> grandchild2.get_coordinates_in_tree()
'2.2'

get_indentation() → str[source]

Tree method

Returns:: indentation according to level (layer number). As default it is used for creating tabs in tree_representation
Return type:: str

get_layer(level: int, key: Callable | None = None) → list[source]

Tree method

Parameters:

level – layer number where 0 is the root.
key – An optional callable for each node in the layer.

Returns:

All nodes on this level. The leaves of branches which are shorter than the given level will be repeated on this and all following layers.

Return type:

list

get_leaves(key: Callable | None = None) → list[source]

Tree method

Parameters:: key – An optional callable to be called on each leaf.
Returns:: nested list of leaves or values of key(leaf) for each leaf
Return type:: nested list of Tree

get_parent() → Tree[source]

Tree method

Returns:: parent. None for root.
Return type:: Tree

get_root() → Tree[source]

Tree method

Returns:: root (upmost node of a tree which has no parent)
Return type:: Tree

iterate_leaves() → Iterator[Tree][source]

Tree method

Returns:: A generator iterating over all leaves.

remove(child: Tree) → None[source]

Tree method

Child’s parent will be set to None and child will be removed from list of children.

Parameters:: child –
Returns:: None

remove_children() → None[source]

Tree method

Calls remove() on all children.

Returns:: None

replace_child(old, new, index: int = 0) → None[source]

Tree method

Parameters:

old – child or function
new – child
index – index of old child in the list of its appearances

Returns:

None

reversed_path_to_root() → Iterator[Tree][source]

Tree method

Returns:: path from self upwards through all ancestors up to the root.

traverse() → Iterator[Tree][source]

Tree method

Traverse all tree nodes.

Returns:: generator

tree_representation(key: Callable | None = None, tab: Callable | None = None) → str[source]

Tree method

Parameters:

key – An optional callable if None compact_repr property of each node is called.
tab – An optional callable if None get_indentation() method of each node is called.

Returns:

a representation of all nodes as string in tree form.

Return type:

str

property compact_repr: str

Tree property

Returns:: compact representation of a node. Default is the string representation. This property is used as default in the tree_representation method and can be customized in subclasses to get the most appropriate representation.
Return type:: str

property is_leaf: bool

Tree property

Returns:: True if self has no children. False if self has one or more children.
Return type:: bool

property is_root: bool

Tree property

Returns:: True if self has no parent, else False.
Return type:: bool

property level: int

Tree property

Returns:: 0 for root, 1, 2 etc. for each layer of children
Return type:: nonnegative int

>>> class TestTree(Tree):
...   def _check_child_to_be_added(self, child):
...      return True
>>> root = TestTree()
>>> root.level
0
>>> ch = root.add_child(TestTree()).add_child(TestTree()).add_child(TestTree())
>>> ch.level
3

property next: Tree | None

Tree property

Returns:: next sibling. None if this is the last current child of the parent.
Return type:: Tree

property previous: Tree | None

Tree property

Returns:: previous sibling. None if this is the first child of the parent.
Return type:: Tree

property up: Tree

Tree property

Returns:: get_parent()
Return type:: Tree