🔧 Helper

Helper functions that can come in handy.

bigtree.tree.helper

clone_tree

clone_tree(tree, node_type)

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

Examples:

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

Parameters:

Name	Type	Description	Default
`tree`	`BaseNode`	tree to be cloned, must inherit from BaseNode	required
`node_type`	`Type[BaseNode]`	type of cloned tree	required

Returns:

Type	Description
`BaseNodeT`	(BaseNode)

get_subtree

get_subtree(tree, node_name_or_path='', max_depth=0)

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

Examples:

>>> 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:

Name	Type	Description	Default
`tree`	`Node`	existing tree	required
`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	`0`

Returns:

Type	Description
`NodeT`	(Node)

prune_tree

prune_tree(
    tree, prune_path="", exact=False, sep="/", max_depth=0
)

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").

Examples:

>>> 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:

Name	Type	Description	Default
`tree`	`Union[BinaryNode, Node]`	existing tree	required
`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)	`False`
`sep`	`str`	path separator of `prune_path`	`'/'`
`max_depth`	`int`	maximum depth of pruned tree, based on `depth` attribute, defaults to None	`0`

Returns:

Type	Description
`Union[BinaryNodeT, NodeT]`	(Union[BinaryNode, Node])

get_tree_diff

get_tree_diff(
    tree, other_tree, only_diff=True, attr_list=[]
)

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.

Examples:

>>> # 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:

Name	Type	Description	Default
`tree`	`Node`	tree to be compared against	required
`other_tree`	`Node`	tree to be compared with	required
`only_diff`	`bool`	indicator to show all nodes or only nodes that are different (+/-), defaults to True	`True`
`attr_list`	`List[str]`	tree attributes to check for difference, defaults to empty list	`[]`

Returns:

Type	Description
`Node`	(Node)