Merge pull request #156 from kayjan/v0.15.3

Added: get_subtree method + docstring examples + update README

Author: kayjan

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.15.3] - 2024-01-08
+### Added
+- Tree Helper: `get_subtree` method to retrieve subtree.
+
 ## [0.15.2] - 2024-01-08
 ### Added
 - Tree Exporter: `hprint_tree` and `hyield_tree` to print and retrieve results for tree in horizontal orientation.
@@ -432,6 +436,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Utility Iterator: Tree traversal methods.
 - Workflow To Do App: Tree use case with to-do list implementation.
 
+[0.15.3]: https://github.com/kayjan/bigtree/compare/0.15.3...0.15.2
 [0.15.2]: https://github.com/kayjan/bigtree/compare/0.15.2...0.15.1
 [0.15.1]: https://github.com/kayjan/bigtree/compare/0.15.1...0.15.0
 [0.15.0]: https://github.com/kayjan/bigtree/compare/0.15.0...0.14.8

README.md

@@ -61,8 +61,9 @@ For **Tree** implementation, there are 9 main components.
    4. Find single child node based on name, user-defined condition
 6. [**🔧 Helper Function**](https://bigtree.readthedocs.io/en/latest/bigtree/tree/helper.html)
    1. Cloning tree to another `Node` type
-   2. Prune tree
-   3. Get difference between two trees
+   2. Get subtree (smaller tree with different root)
+   3. Prune tree (smaller tree with same root)
+   4. Get difference between two trees
 7. [**📊 Plotting Tree**](https://bigtree.readthedocs.io/en/latest/bigtree/utils/plot.html)
    1. Enhanced Reingold Tilford Algorithm to retrieve (x, y) coordinates for a tree structure
 8. [**🔨 Exporting Tree**](https://bigtree.readthedocs.io/en/latest/bigtree/tree/export.html)
@@ -835,58 +836,80 @@ find_child_by_name(c, "c")
 
 ### Helper Utility
 
-There following are helper functions for cloning tree to another `Node` type, pruning tree, and getting difference
-between two trees.
+There following are helper functions for
+1. Cloning tree to another `Node` type
+2. Getting subtree (smaller tree with different root)
+3. Pruning tree (smaller tree with same root)
+4. Getting difference between two trees
 
 {emphasize-lines="6,18,38,43"}
 ```python
-from bigtree import BaseNode, Node, clone_tree, prune_tree, get_tree_diff
+from bigtree import BaseNode, Node, clone_tree, get_subtree, get_tree_diff, prune_tree, str_to_tree
 
-# Cloning tree from `BaseNode` to `Node` type
+# 1. Cloning tree from `BaseNode` to `Node` type
 root = BaseNode(name="a")
 b = BaseNode(name="b", parent=root)
 clone_tree(root, Node)
 # Node(/a, )
 
-# Prune tree to only path a/b
-root = Node("a")
-b = Node("b", parent=root)
-c = Node("c", parent=root)
-root.show()
-# a
-# ├── b
-# └── c
+# Create a tree for future sections
+root = str_to_tree("""
+a
+├── b
+│   ├── d
+│   └── e
+└── c
+    └── f
+""")
 
+# 2. Getting subtree with root b
+root_subtree = get_subtree(root, "b")
+root_subtree.show()
+# b
+# ├── d
+# └── e
+
+# 3.1 Prune tree to only path a/b
 root_pruned = prune_tree(root, "a/b")
 root_pruned.show()
 # a
 # └── b
+#     ├── d
+#     └── e
 
-# Get difference between two trees
-root = Node("a")
-b = Node("b", parent=root)
-c = Node("c", parent=root)
-root.show()
-# a
-# ├── b
-# └── c
-
-root_other = Node("a")
-b_other = Node("b", parent=root_other)
-root_other.show()
+# 3.1 Prune tree to exactly path a/b
+root_pruned = prune_tree(root, "a/b", exact=True)
+root_pruned.show()
 # a
 # └── b
 
+# 4. Get difference between two trees
+root_other = str_to_tree("""
+a
+├── b
+│   └── d
+└── c
+    └── g
+""")
+
 tree_diff = get_tree_diff(root, root_other)
 tree_diff.show()
 # a
-# └── c (-)
+# ├── b
+# │   └── e (-)
+# └── c
+#     ├── f (-)
+#     └── g (+)
 
 tree_diff = get_tree_diff(root, root_other, only_diff=False)
 tree_diff.show()
 # a
 # ├── b
-# └── c (-)
+# │   ├── d
+# │   └── e (-)
+# └── c
+#     ├── f (-)
+#     └── g (+)
 ```
 
 ### Export Tree

bigtree/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.15.2"
+__version__ = "0.15.3"
 
 from bigtree.binarytree.construct import list_to_binarytree
 from bigtree.dag.construct import dataframe_to_dag, dict_to_dag, list_to_dag
@@ -35,7 +35,7 @@
     tree_to_pillow,
     yield_tree,
 )
-from bigtree.tree.helper import clone_tree, get_tree_diff, prune_tree
+from bigtree.tree.helper import clone_tree, get_subtree, get_tree_diff, prune_tree
 from bigtree.tree.modify import (
     copy_and_replace_nodes_from_tree_to_tree,
     copy_nodes,

bigtree/tree/helper.py

@@ -10,7 +10,7 @@
 from bigtree.utils.exceptions import NotFoundError
 from bigtree.utils.iterators import levelordergroup_iter
 
-__all__ = ["clone_tree", "prune_tree", "get_tree_diff"]
+__all__ = ["clone_tree", "get_subtree", "prune_tree", "get_tree_diff"]
 BaseNodeT = TypeVar("BaseNodeT", bound=BaseNode)
 BinaryNodeT = TypeVar("BinaryNodeT", bound=BinaryNode)
 NodeT = TypeVar("NodeT", bound=Node)
@@ -61,6 +61,27 @@ def get_subtree(
 ) -> 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
+
     Args:
         tree (Node): existing tree
         node_name_or_path (str): node name or path to get subtree, defaults to None