🔧 Helper

Helper functions that can come in handy.

Functions:

clone_tree(tree, node_type)

Clone tree to another Node type.

get_subtree(tree[, node_name_or_path, max_depth])

Get subtree based on node name or node path, and/or maximum depth of tree.

get_tree_diff(tree, other_tree[, only_diff, ...])

Get difference of tree to other_tree, changes are relative to tree.

prune_tree(tree[, prune_path, exact, sep, ...])

Prune tree by path or depth, returns the root of a copy of the original tree.
bigtree.tree.helper.clone_tree(tree: BaseNode, node_type: Type[BaseNodeT]) → BaseNodeT

Clone tree to another Node type. If the same type is needed, simply do a tree.copy().

>>> from bigtree import BaseNode, Node, clone_tree
>>> root = BaseNode(name="a")
>>> b = BaseNode(name="b", parent=root)
>>> clone_tree(root, Node)
Node(/a, )
Parameters:

  • tree (BaseNode) – tree to be cloned, must inherit from BaseNode

  • node_type (Type[BaseNode]) – type of cloned tree

Returns:

(BaseNode)

bigtree.tree.helper.get_subtree(tree: NodeT, node_name_or_path: str = '', max_depth: int = 0) → NodeT

Get subtree based on node name or node path, and/or maximum depth of tree.

>>> from bigtree import Node, get_subtree
>>> root = Node("a")
>>> b = Node("b", parent=root)
>>> c = Node("c", parent=b)
>>> d = Node("d", parent=b)
>>> e = Node("e", parent=root)
>>> root.show()
a
├── b
│   ├── c
│   └── d
└── e

Get subtree

>>> root_subtree = get_subtree(root, "b")
>>> root_subtree.show()
b
├── c
└── d
Parameters:

  • tree (Node) – existing tree

  • node_name_or_path (str) – node name or path to get subtree, defaults to None

  • max_depth (int) – maximum depth of subtree, based on depth attribute, defaults to None

Returns:

(Node)

bigtree.tree.helper.get_tree_diff(tree: Node, other_tree: Node, only_diff: bool = True, attr_list: List[str] = []) → Node

Get difference of tree to other_tree, changes are relative to tree.

Compares the difference in tree structure (default), but can also compare tree attributes using attr_list. Function can return only the differences (default), or all original tree nodes and differences.

Comparing tree structure
(+) and (-) will be added to node name relative to tree.

  • For example: (+) refers to nodes that are in other_tree but not tree.

  • For example: (-) refers to nodes that are in tree but not other_tree.

>>> # Create original tree
>>> from bigtree import Node, get_tree_diff, list_to_tree
>>> root = list_to_tree(["Downloads/Pictures/photo1.jpg", "Downloads/file1.doc", "Downloads/photo2.jpg"])
>>> root.show()
Downloads
├── Pictures
│   └── photo1.jpg
├── file1.doc
└── photo2.jpg

>>> # Create other tree
>>> root_other = list_to_tree(["Downloads/Pictures/photo1.jpg", "Downloads/Pictures/photo2.jpg", "Downloads/file1.doc"])
>>> root_other.show()
Downloads
├── Pictures
│   ├── photo1.jpg
│   └── photo2.jpg
└── file1.doc

>>> # Get tree differences
>>> tree_diff = get_tree_diff(root, root_other)
>>> tree_diff.show()
Downloads
├── photo2.jpg (-)
└── Pictures
    └── photo2.jpg (+)

>>> tree_diff = get_tree_diff(root, root_other, only_diff=False)
>>> tree_diff.show()
Downloads
├── Pictures
│   ├── photo1.jpg
│   └── photo2.jpg (+)
├── file1.doc
└── photo2.jpg (-)
Comparing tree attributes

(~) will be added to node name if there are differences in tree attributes defined in attr_list. The node’s attributes will be a list of [value in tree, value in other_tree]

>>> # Create original tree
>>> root = Node("Downloads")
>>> picture_folder = Node("Pictures", parent=root)
>>> photo2 = Node("photo1.jpg", tags="photo1", parent=picture_folder)
>>> file1 = Node("file1.doc", tags="file1", parent=root)
>>> root.show(attr_list=["tags"])
Downloads
├── Pictures
│   └── photo1.jpg [tags=photo1]
└── file1.doc [tags=file1]

>>> # Create other tree
>>> root_other = Node("Downloads")
>>> picture_folder = Node("Pictures", parent=root_other)
>>> photo1 = Node("photo1.jpg", tags="photo1-edited", parent=picture_folder)
>>> photo2 = Node("photo2.jpg", tags="photo2-new", parent=picture_folder)
>>> file1 = Node("file1.doc", tags="file1", parent=root_other)
>>> root_other.show(attr_list=["tags"])
Downloads
├── Pictures
│   ├── photo1.jpg [tags=photo1-edited]
│   └── photo2.jpg [tags=photo2-new]
└── file1.doc [tags=file1]

>>> # Get tree differences
>>> tree_diff = get_tree_diff(root, root_other, attr_list=["tags"])
>>> tree_diff.show(attr_list=["tags"])
Downloads
└── Pictures
    ├── photo1.jpg (~) [tags=('photo1', 'photo1-edited')]
    └── photo2.jpg (+)
Parameters:

  • tree (Node) – tree to be compared against

  • other_tree (Node) – tree to be compared with

  • only_diff (bool) – indicator to show all nodes or only nodes that are different (+/-), defaults to True

  • attr_list (List[str]) – tree attributes to check for difference, defaults to empty list

Returns:

(Node)

bigtree.tree.helper.prune_tree(tree: BinaryNodeT | NodeT, prune_path: List[str] | str = '', exact: bool = False, sep: str = '/', max_depth: int = 0) → BinaryNodeT | NodeT

Prune tree by path or depth, returns the root of a copy of the original tree.

For pruning by prune_path,

  • All siblings along the prune path will be removed.

  • If exact=True, all descendants of prune path will be removed.

  • Prune path can be string (only one path) or a list of strings (multiple paths).

  • Prune path name should be unique, can be full path, partial path (trailing part of path), or node name.

For pruning by max_depth,

  • All nodes that are beyond max_depth will be removed.

Path should contain Node name, separated by sep.

  • For example: Path string “a/b” refers to Node(“b”) with parent Node(“a”).

>>> from bigtree import Node, prune_tree
>>> root = Node("a")
>>> b = Node("b", parent=root)
>>> c = Node("c", parent=b)
>>> d = Node("d", parent=b)
>>> e = Node("e", parent=root)
>>> root.show()
a
├── b
│   ├── c
│   └── d
└── e

Prune (default is keep descendants)

>>> root_pruned = prune_tree(root, "a/b")
>>> root_pruned.show()
a
└── b
    ├── c
    └── d

Prune exact path

>>> root_pruned = prune_tree(root, "a/b", exact=True)
>>> root_pruned.show()
a
└── b

Prune multiple paths

>>> root_pruned = prune_tree(root, ["a/b/d", "a/e"])
>>> root_pruned.show()
a
├── b
│   └── d
└── e

Prune by depth

>>> root_pruned = prune_tree(root, max_depth=2)
>>> root_pruned.show()
a
├── b
└── e
Parameters:

  • tree (Union[BinaryNode, Node]) – existing tree

  • prune_path (List[str] | str) – prune path(s), all siblings along the prune path(s) will be removed

  • exact (bool) – prune path(s) to be exactly the path, defaults to False (descendants of the path are retained)

  • sep (str) – path separator of prune_path

  • max_depth (int) – maximum depth of pruned tree, based on depth attribute, defaults to None

Returns:

(Union[BinaryNode, Node])