π§ Helper
Helper functions that can come in handy.
bigtree.tree.helper
clone_tree
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 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
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 |
0
|
Returns:
Type | Description |
---|---|
NodeT
|
(Node) |
prune_tree
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
Prune multiple paths
>>> root_pruned = prune_tree(root, ["a/b/d", "a/e"])
>>> root_pruned.show()
a
βββ b
β βββ d
βββ e
Prune by depth
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 |
'/'
|
max_depth |
int
|
maximum depth of pruned tree, based on |
0
|
Returns:
Type | Description |
---|---|
Union[BinaryNodeT, NodeT]
|
(Union[BinaryNode, Node]) |
get_tree_diff
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 nottree
. - For example: (-) refers to nodes that are in
tree
but notother_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 inother_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) |