Construct/Export to nested_dict_key to support child_key=None (#400)

* feat: nested_key_dict to tree to support child_key=None

* feat: tree to nested_key_dict to support child_key=None

* docs: update CHANGELOG and docs

* fix: fix doctest

Author: kayjan

CHANGELOG.md

@@ -4,7 +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).
 
-## [Unreleased]
+## [0.30.1] - 2025-09-10
+### Added:
+- Tree Construct: `nested_dict_key_to_tree` to support child_key=None.
+- Tree Export: `tree_to_nested_dict_key` to support child_key=None.
 ### Changed
 - Misc: Some code refactoring, enhance assemble_attributes.
 ### Fixed
@@ -808,7 +811,8 @@ ignore null attribute columns.
 - Utility Iterator: Tree traversal methods.
 - Workflow To Do App: Tree use case with to-do list implementation.
 
-[Unreleased]: https://github.com/kayjan/bigtree/compare/0.30.0...HEAD
+[Unreleased]: https://github.com/kayjan/bigtree/compare/0.30.1...HEAD
+[0.30.1]: https://github.com/kayjan/bigtree/compare/0.30.0...0.30.1
 [0.30.0]: https://github.com/kayjan/bigtree/compare/0.29.2...0.30.0
 [0.29.2]: https://github.com/kayjan/bigtree/compare/0.29.1...0.29.2
 [0.29.1]: https://github.com/kayjan/bigtree/compare/0.29.0...0.29.1

bigtree/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.30.0"
+__version__ = "0.30.1"
 
 from bigtree.binarytree.construct import list_to_binarytree
 from bigtree.dag.construct import dataframe_to_dag, dict_to_dag, list_to_dag

bigtree/dag/construct.py

@@ -40,14 +40,14 @@ def list_to_dag(
     assertions.assert_length_not_empty(relations, "Input list", "relations")
 
     node_dict: Dict[str, T] = dict()
-    child_name: str = ""
+    parent_name: str = ""
 
     for parent_name, child_name in relations:
         node_dict[parent_name] = node_dict.get(parent_name, node_type(parent_name))
         node_dict[child_name] = node_dict.get(child_name, node_type(child_name))
         node_dict[child_name].parents = [node_dict[parent_name]]
 
-    return node_dict[child_name]
+    return node_dict[parent_name]
 
 
 def dict_to_dag(

bigtree/tree/construct/dictionaries.py

@@ -305,11 +305,13 @@ def _recursive_add_child(
 
 def nested_dict_key_to_tree(
     node_attrs: Mapping[str, Mapping[str, Any]],
-    child_key: str = "children",
+    child_key: Optional[str] = "children",
     node_type: Type[T] = node.Node,  # type: ignore[assignment]
 ) -> T:
     """Construct tree from nested recursive dictionary, where the keys are node names.
 
+    If child_key is a string
+
     - ``key``: node name
     - ``value``: dict of node attributes and node children (recursive)
 
@@ -318,6 +320,15 @@ def nested_dict_key_to_tree(
     - ``key`` that is not ``child_key`` has node attribute as value
     - ``key`` that is ``child_key`` has dictionary of node children as value (recursive)
 
+    ---
+
+    If child_key is None
+
+    - ``key``: node name
+    - ``value``: dict of node children (recursive), there are no node attributes
+
+    Value dictionary consist of ``key`` that is node names of children
+
     Examples:
         >>> from bigtree import nested_dict_key_to_tree
         >>> nested_dict = {
@@ -345,6 +356,23 @@ def nested_dict_key_to_tree(
             └── e [age=35]
                 └── g [age=10]
 
+        >>> from bigtree import nested_dict_key_to_tree
+        >>> nested_dict = {
+        ...     "a": {
+        ...         "b": {
+        ...             "d": {},
+        ...             "e": {"g": {}},
+        ...         },
+        ...     }
+        ... }
+        >>> root = nested_dict_key_to_tree(nested_dict, child_key=None)
+        >>> root.show()
+        a
+        └── b
+            ├── d
+            └── e
+                └── g
+
     Args:
         node_attrs: node, children, and node attribute information,
             key: node name
@@ -370,8 +398,12 @@ def _recursive_add_child(
         Returns:
             Node
         """
-        child_dict = dict(child_dict)
-        node_children = child_dict.pop(child_key, {})
+        if child_key:
+            child_dict = dict(child_dict)
+            node_children = child_dict.pop(child_key, {})
+        else:
+            node_children = child_dict
+            child_dict = {}
         if not isinstance(node_children, Mapping):
             raise TypeError(
                 f"child_key {child_key} should be Dict type, received {node_children}"

bigtree/tree/export/dictionaries.py

@@ -150,7 +150,7 @@ def _recursive_append(_node: T, parent_dict: Dict[str, Any]) -> None:
 
 def tree_to_nested_dict_key(
     tree: T,
-    child_key: str = "children",
+    child_key: Optional[str] = "children",
     attr_dict: Optional[Dict[str, str]] = None,
     all_attrs: bool = False,
     max_depth: int = 0,
@@ -160,6 +160,7 @@ def tree_to_nested_dict_key(
     All descendants from `tree` will be exported, `tree` can be the root node or child node of tree.
 
     Exported dictionary will have key as node names, and children as node attributes and nested recursive dictionary.
+    If child_key is None, the children key is nested recursive dictionary of node names (there will be no attributes).
 
     Examples:
         >>> from bigtree import Node, tree_to_nested_dict_key
@@ -171,6 +172,9 @@ def tree_to_nested_dict_key(
         >>> tree_to_nested_dict_key(root, all_attrs=True)
         {'a': {'age': 90, 'children': {'b': {'age': 65, 'children': {'d': {'age': 40}, 'e': {'age': 35}}}, 'c': {'age': 60}}}}
 
+        >>> tree_to_nested_dict_key(root, child_key=None)
+        {'a': {'b': {'d': {}, 'e': {}}, 'c': {}}}
+
     Args:
         tree: tree to be exported
         child_key: dictionary key for children
@@ -190,16 +194,25 @@ def _recursive_append(_node: T, parent_dict: Dict[str, Any]) -> None:
             _node: current node
             parent_dict: parent dictionary
         """
+        if child_key is None:
+            if attr_dict or all_attrs:
+                raise ValueError(
+                    "If child_key is None, no node attributes can be exported"
+                )
+
         if _node:
             if not max_depth or _node.depth <= max_depth:
                 data_child = common.assemble_attributes(_node, attr_dict, all_attrs)
-                if child_key in parent_dict:
-                    parent_dict[child_key][_node.node_name] = data_child
+                if child_key:
+                    if child_key in parent_dict:
+                        parent_dict[child_key][_node.node_name] = data_child
+                    else:
+                        parent_dict[child_key] = {_node.node_name: data_child}
                 else:
-                    parent_dict[child_key] = {_node.node_name: data_child}
+                    parent_dict[_node.node_name] = data_child
 
                 for _child in _node.children:
                     _recursive_append(_child, data_child)
 
     _recursive_append(tree, data_dict)
-    return data_dict[child_key]
+    return data_dict[child_key] if child_key else data_dict

docs/gettingstarted/demo/tree.md

@@ -229,8 +229,8 @@ names and `value` is node attribute values, and list of children (recursive).
     # └── c [age=60]
     ```
 
-=== "Recursive structure 2"
-    ```python hl_lines="17"
+=== "Recursive structure by key"
+    ```python hl_lines="17 31"
     from bigtree import nested_dict_key_to_tree
 
     nested_dict = {
@@ -254,6 +254,20 @@ names and `value` is node attribute values, and list of children (recursive).
     # ├── b [age=65]
     # │   └── d [age=40]
     # └── c [age=60]
+
+    nested_dict = {
+        "a": {
+            "b": {"d": {}},
+            "c": {},
+        }
+    }
+    root = nested_dict_key_to_tree(nested_dict, child_key=None)
+
+    root.show()
+    # a
+    # ├── b
+    # │   └── d
+    # └── c
     ```
 
 
@@ -1294,15 +1308,18 @@ root.show()
     # }
     ```
 
-=== "Dictionary (recursive structure 2)"
-    ```python hl_lines="3"
+=== "Dictionary (recursive structure by key)"
+    ```python hl_lines="3 9"
     from bigtree import tree_to_nested_dict_key
 
     tree_to_nested_dict_key(root, all_attrs=True)
     # {'a': {'age': 90,
     #        'children': {'b': {'age': 65,
     #                           'children': {'d': {'age': 40}, 'e': {'age': 35}}},
     #                     'c': {'age': 60}}}}
+
+    tree_to_nested_dict_key(root, child_key=None)
+    # {'a': {'b': {'d': {}, 'e': {}}, 'c': {}}}
     ```
 
 === "pandas DataFrame"

tests/test_constants.py

@@ -136,6 +136,9 @@ class Constants:
 
     # tree/export
     ERROR_NODE_TYPE = "Tree should be of type `{type}`, or inherit from `{type}`"
+    ERROR_NODE_EXPORT_DICT_NO_ATTRS = (
+        "If child_key is None, no node attributes can be exported"
+    )
     ERROR_NODE_EXPORT_PRINT_ATTR_BRACKET = (
         "Expect open and close brackets in `attr_bracket`, received {attr_bracket}"
     )

tests/tree/construct/test_dictionaries.py

@@ -1016,3 +1016,93 @@ def test_nested_dict_key_to_tree_custom_node_type():
         assert_tree_structure_basenode_root(root)
         assert_tree_structure_customnode_root_attr(root)
         assert_tree_structure_node_root(root)
+
+
+class TestNestedDictKeyToTreeNullKey(unittest.TestCase):
+    def setUp(self):
+        """
+        Tree should have structure
+        a
+        |-- b
+        |   |-- d
+        |   +-- e
+        |       |-- g
+        |       +-- h
+        +-- c
+            +-- f
+        """
+        self.nested_dict = {
+            "a": {
+                "b": {
+                    "d": {},
+                    "e": {
+                        "g": {},
+                        "h": {},
+                    },
+                },
+                "c": {"f": {}},
+            }
+        }
+
+    def tearDown(self):
+        self.nested_dict = None
+
+    def test_nested_dict_key_to_tree(self):
+        root = construct.nested_dict_key_to_tree(self.nested_dict, child_key=None)
+        assert_tree_structure_basenode_root(root)
+        assert_tree_structure_node_root(root)
+
+    @staticmethod
+    def test_nested_dict_key_to_tree_null_children_error():
+        child_key = None
+        child = None
+        nested_dict = {
+            "a": {
+                "b": {
+                    "d": {},
+                    "e": {
+                        "g": child,
+                        "h": {},
+                    },
+                },
+                "c": {"f": {}},
+            }
+        }
+        with pytest.raises(TypeError) as exc_info:
+            construct.nested_dict_key_to_tree(nested_dict, child_key=child_key)
+        assert str(exc_info.value) == Constants.ERROR_NODE_DICT_CHILD_TYPE.format(
+            child_key=child_key, type="Dict", child=child
+        )
+
+    @staticmethod
+    def test_nested_dict_key_to_tree_int_children_error():
+        child_key = None
+        child = 1
+        nested_dict = {
+            "a": {
+                "b": {
+                    "d": {},
+                    "e": {
+                        "g": child,
+                        "h": {},
+                    },
+                },
+                "c": {"f": {}},
+            }
+        }
+        with pytest.raises(TypeError) as exc_info:
+            construct.nested_dict_key_to_tree(nested_dict, child_key=child_key)
+        assert str(exc_info.value) == Constants.ERROR_NODE_DICT_CHILD_TYPE.format(
+            child_key=child_key, type="Dict", child=child
+        )
+
+    def test_nested_dict_key_to_tree_node_type(self):
+        root = construct.nested_dict_key_to_tree(
+            self.nested_dict, child_key=None, node_type=NodeA
+        )
+        assert isinstance(root, NodeA), Constants.ERROR_CUSTOM_TYPE.format(type="NodeA")
+        assert all(
+            isinstance(_node, NodeA) for _node in root.children
+        ), Constants.ERROR_CUSTOM_TYPE.format(type="NodeA")
+        assert_tree_structure_basenode_root(root)
+        assert_tree_structure_node_root(root)