Merge pull request #70 from kayjan/v0.10.0

V0.10.0

Author: Kay Jan

CHANGELOG.md

@@ -4,6 +4,11 @@ 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.10.0] - 2023-07-15
+### Added
+- [#65] Tree Search: Implement `find_relative_path` to find relative path from node.
+- [#65] Utility Iterator: Implement `zigzag_iter` and `zigzaggroup_iter` Tree traversal methods.
+
 ## [0.9.5] - 2023-07-13
 ### Added
 - Misc: Added init files, add link to discussions to README and pyproject, add sphinx coverage shortcuts.
@@ -284,6 +289,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.10.0]: https://github.com/kayjan/bigtree/compare/0.9.5...0.10.0
 [0.9.5]: https://github.com/kayjan/bigtree/compare/0.9.4...0.9.5
 [0.9.4]: https://github.com/kayjan/bigtree/compare/0.9.3...0.9.4
 [0.9.3]: https://github.com/kayjan/bigtree/compare/0.9.2...0.9.3

bigtree/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.9.5"
+__version__ = "0.10.0"
 
 from bigtree.binarytree.construct import list_to_binarytree
 from bigtree.dag.construct import dataframe_to_dag, dict_to_dag, list_to_dag
@@ -49,6 +49,7 @@
     find_names,
     find_path,
     find_paths,
+    find_relative_path,
     findall,
 )
 from bigtree.utils.exceptions import (
@@ -66,6 +67,8 @@
     levelordergroup_iter,
     postorder_iter,
     preorder_iter,
+    zigzag_iter,
+    zigzaggroup_iter,
 )
 from bigtree.workflows.app_calendar import Calendar
 from bigtree.workflows.app_todo import AppToDo

bigtree/binarytree/construct.py

@@ -10,10 +10,10 @@ def list_to_binarytree(
 ) -> BinaryNode:
     """Construct tree from list of numbers (int or float) in heapq format.
 
-    >>> from bigtree import list_to_binarytree, print_tree, tree_to_dot
+    >>> from bigtree import list_to_binarytree, tree_to_dot
     >>> nums_list = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
     >>> root = list_to_binarytree(nums_list)
-    >>> print_tree(root)
+    >>> root.show()
     1
     ├── 2
     │   ├── 4

bigtree/tree/construct.py

@@ -45,11 +45,11 @@ def add_path_to_tree(
     All paths should start from the same root node.
       - For example: Path strings should be "a/b", "a/c", "a/b/d" etc. and should not start with another root node.
 
-    >>> from bigtree import add_path_to_tree, print_tree
+    >>> from bigtree import add_path_to_tree
     >>> root = Node("a")
     >>> add_path_to_tree(root, "a/b/c")
     Node(/a/b/c, )
-    >>> print_tree(root)
+    >>> root.show()
     a
     └── b
         └── c
@@ -119,7 +119,7 @@ def add_dict_to_tree_by_path(
     All paths should start from the same root node.
       - For example: Path strings should be "a/b", "a/c", "a/b/d" etc. and should not start with another root node.
 
-    >>> from bigtree import Node, add_dict_to_tree_by_path, print_tree
+    >>> from bigtree import Node, add_dict_to_tree_by_path
     >>> root = Node("a")
     >>> path_dict = {
     ...     "a": {"age": 90},
@@ -132,7 +132,7 @@ def add_dict_to_tree_by_path(
     ...     "a/b/e/h": {"age": 6},
     ... }
     >>> root = add_dict_to_tree_by_path(root, path_dict)
-    >>> print_tree(root)
+    >>> root.show()
     a
     ├── b
     │   ├── d
@@ -178,15 +178,15 @@ def add_dict_to_tree_by_name(
     Input dictionary keys that are not existing node names will be ignored.
     Note that if multiple nodes have the same name, attributes will be added to all nodes sharing same name.
 
-    >>> from bigtree import Node, add_dict_to_tree_by_name, print_tree
+    >>> from bigtree import Node, add_dict_to_tree_by_name
     >>> root = Node("a")
     >>> b = Node("b", parent=root)
     >>> name_dict = {
     ...     "a": {"age": 90},
     ...     "b": {"age": 65},
     ... }
     >>> root = add_dict_to_tree_by_name(root, name_dict)
-    >>> print_tree(root, attr_list=["age"])
+    >>> root.show(attr_list=["age"])
     a [age=90]
     └── b [age=65]
 
@@ -235,7 +235,7 @@ def add_dataframe_to_tree_by_path(
       - For example: Path strings should be "a/b", "a/c", "a/b/d" etc. and should not start with another root node.
 
     >>> import pandas as pd
-    >>> from bigtree import add_dataframe_to_tree_by_path, print_tree
+    >>> from bigtree import add_dataframe_to_tree_by_path
     >>> root = Node("a")
     >>> path_data = pd.DataFrame([
     ...     ["a", 90],
@@ -250,7 +250,7 @@ def add_dataframe_to_tree_by_path(
     ...     columns=["PATH", "age"]
     ... )
     >>> root = add_dataframe_to_tree_by_path(root, path_data)
-    >>> print_tree(root, attr_list=["age"])
+    >>> root.show(attr_list=["age"])
     a [age=90]
     ├── b [age=65]
     │   ├── d [age=40]
@@ -333,7 +333,7 @@ def add_dataframe_to_tree_by_name(
     Note that if multiple nodes have the same name, attributes will be added to all nodes sharing same name.
 
     >>> import pandas as pd
-    >>> from bigtree import add_dataframe_to_tree_by_name, print_tree
+    >>> from bigtree import add_dataframe_to_tree_by_name
     >>> root = Node("a")
     >>> b = Node("b", parent=root)
     >>> name_data = pd.DataFrame([
@@ -343,7 +343,7 @@ def add_dataframe_to_tree_by_name(
     ...     columns=["NAME", "age"]
     ... )
     >>> root = add_dataframe_to_tree_by_name(root, name_data)
-    >>> print_tree(root, attr_list=["age"])
+    >>> root.show(attr_list=["age"])
     a [age=90]
     └── b [age=65]
 
@@ -418,10 +418,10 @@ def str_to_tree(
 ) -> Node:
     r"""Construct tree from tree string
 
-    >>> from bigtree import str_to_tree, print_tree
+    >>> from bigtree import str_to_tree
     >>> tree_str = 'a\n├── b\n│   ├── d\n│   └── e\n│       ├── g\n│       └── h\n└── c\n    └── f'
     >>> root = str_to_tree(tree_str, tree_prefix_list=["├──", "└──"])
-    >>> print_tree(root)
+    >>> root.show()
     a
     ├── b
     │   ├── d
@@ -496,10 +496,10 @@ def list_to_tree(
     All paths should start from the same root node.
       - For example: Path strings should be "a/b", "a/c", "a/b/d" etc. and should not start with another root node.
 
-    >>> from bigtree import list_to_tree, print_tree
+    >>> from bigtree import list_to_tree
     >>> path_list = ["a/b", "a/c", "a/b/d", "a/b/e", "a/c/f", "a/b/e/g", "a/b/e/h"]
     >>> root = list_to_tree(path_list)
-    >>> print_tree(root)
+    >>> root.show()
     a
     ├── b
     │   ├── d
@@ -548,10 +548,10 @@ def list_to_tree_by_relation(
     Error will be thrown if names of intermediate nodes are repeated as there will be confusion.
     This error can be ignored by setting `allow_duplicates` to be True.
 
-    >>> from bigtree import list_to_tree_by_relation, print_tree
+    >>> from bigtree import list_to_tree_by_relation
     >>> relations_list = [("a", "b"), ("a", "c"), ("b", "d"), ("b", "e"), ("c", "f"), ("e", "g"), ("e", "h")]
     >>> root = list_to_tree_by_relation(relations_list)
-    >>> print_tree(root)
+    >>> root.show()
     a
     ├── b
     │   ├── d
@@ -601,7 +601,7 @@ def dict_to_tree(
     All paths should start from the same root node.
       - For example: Path strings should be "a/b", "a/c", "a/b/d" etc. and should not start with another root node.
 
-    >>> from bigtree import dict_to_tree, print_tree
+    >>> from bigtree import dict_to_tree
     >>> path_dict = {
     ...     "a": {"age": 90},
     ...     "a/b": {"age": 65},
@@ -613,7 +613,7 @@ def dict_to_tree(
     ...     "a/b/e/h": {"age": 6},
     ... }
     >>> root = dict_to_tree(path_dict)
-    >>> print_tree(root, attr_list=["age"])
+    >>> root.show(attr_list=["age"])
     a [age=90]
     ├── b [age=65]
     │   ├── d [age=40]
@@ -657,7 +657,7 @@ def nested_dict_to_tree(
       - ``value`` of `name_key` (str): node name.
       - ``value`` of `child_key` (List[Dict[str, Any]]): list of dict containing `name_key` and `child_key` (recursive).
 
-    >>> from bigtree import nested_dict_to_tree, print_tree
+    >>> from bigtree import nested_dict_to_tree
     >>> path_dict = {
     ...     "name": "a",
     ...     "age": 90,
@@ -673,7 +673,7 @@ def nested_dict_to_tree(
     ...     ],
     ... }
     >>> root = nested_dict_to_tree(path_dict)
-    >>> print_tree(root, attr_list=["age"])
+    >>> root.show(attr_list=["age"])
     a [age=90]
     └── b [age=65]
         ├── d [age=40]
@@ -733,7 +733,7 @@ def dataframe_to_tree(
       - For example: Path strings should be "a/b", "a/c", "a/b/d" etc. and should not start with another root node.
 
     >>> import pandas as pd
-    >>> from bigtree import dataframe_to_tree, print_tree
+    >>> from bigtree import dataframe_to_tree
     >>> path_data = pd.DataFrame([
     ...     ["a", 90],
     ...     ["a/b", 65],
@@ -747,7 +747,7 @@ def dataframe_to_tree(
     ...     columns=["PATH", "age"]
     ... )
     >>> root = dataframe_to_tree(path_data)
-    >>> print_tree(root, attr_list=["age"])
+    >>> root.show(attr_list=["age"])
     a [age=90]
     ├── b [age=65]
     │   ├── d [age=40]
@@ -832,7 +832,7 @@ def dataframe_to_tree_by_relation(
     columns are `attribute_cols`.
 
     >>> import pandas as pd
-    >>> from bigtree import dataframe_to_tree_by_relation, print_tree
+    >>> from bigtree import dataframe_to_tree_by_relation
     >>> relation_data = pd.DataFrame([
     ...     ["a", None, 90],
     ...     ["b", "a", 65],
@@ -846,7 +846,7 @@ def dataframe_to_tree_by_relation(
     ...     columns=["child", "parent", "age"]
     ... )
     >>> root = dataframe_to_tree_by_relation(relation_data)
-    >>> print_tree(root, attr_list=["age"])
+    >>> root.show(attr_list=["age"])
     a [age=90]
     ├── b [age=65]
     │   ├── d [age=40]

bigtree/tree/helper.py

@@ -60,17 +60,17 @@ def prune_tree(
     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, print_tree
+    >>> from bigtree import Node, prune_tree
     >>> root = Node("a")
     >>> b = Node("b", parent=root)
     >>> c = Node("c", parent=root)
-    >>> print_tree(root)
+    >>> root.show()
     a
     ├── b
     └── c
 
     >>> root_pruned = prune_tree(root, "a/b")
-    >>> print_tree(root_pruned)
+    >>> root_pruned.show()
     a
     └── b
 
@@ -113,13 +113,13 @@ def get_tree_diff(tree: Node, other_tree: Node, only_diff: bool = True) -> Node:
 
     Function can return all original tree nodes and differences, or only the differences.
 
-    >>> from bigtree import Node, get_tree_diff, print_tree
+    >>> from bigtree import Node, get_tree_diff
     >>> root = Node("a")
     >>> b = Node("b", parent=root)
     >>> c = Node("c", parent=root)
     >>> d = Node("d", parent=b)
     >>> e = Node("e", parent=root)
-    >>> print_tree(root)
+    >>> root.show()
     a
     ├── b
     │   └── d
@@ -131,15 +131,15 @@ def get_tree_diff(tree: Node, other_tree: Node, only_diff: bool = True) -> Node:
     >>> c_other = Node("c", parent=b_other)
     >>> d_other = Node("d", parent=root_other)
     >>> e_other = Node("e", parent=root_other)
-    >>> print_tree(root_other)
+    >>> root_other.show()
     a
     ├── b
     │   └── c
     ├── d
     └── e
 
     >>> tree_diff = get_tree_diff(root, root_other)
-    >>> print_tree(tree_diff)
+    >>> tree_diff.show()
     a
     ├── b
     │   ├── c (+)
@@ -148,7 +148,7 @@ def get_tree_diff(tree: Node, other_tree: Node, only_diff: bool = True) -> Node:
     └── d (+)
 
     >>> tree_diff = get_tree_diff(root, root_other, only_diff=False)
-    >>> print_tree(tree_diff)
+    >>> tree_diff.show()
     a
     ├── b
     │   ├── c (+)