Construct tree from rich tree using Tree.from_rich (#438)

* test: rename variables

* test: rename variables + ensure tree helper methods return Tree type

* docs: enhance docstring

* feat: add get_subtree as plugin

* docs: enhance docstring

* docs: update CHANGELOG

* test: rename variables

* feat: get_attr to support nested attr

* bump: v1.3.0

* test: handle warning from polar tests

* test: handle warning from polar tests

* fix: handle pandas v3

* fix: handle pandas v3

* fix: handle pandas v3

* fix: handle pandas v3

* docs: more examples for listing directories

* docs: more examples for listing directories

* docs: more examples for listing directories

* docs: Fix CHANGELOG

* bump: update CHANGELOG

* fix: Fix attr square brackets being confused as rich formatting

* bump: v1.3.1

* feat: construct tree using rich using Tree.from_rich

* docs: Update docs

* feat: add exceptions

Author: kayjan

CHANGELOG.md

@@ -5,14 +5,10 @@ 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]
-### Added:
-- Docs: More examples for listing directories.
-### Fixed:
-- Docs: Some grammar improvements in docstring.
-- Setup: Test with different Python environments.
 
-## [1.3.1] - 2026-02-13
+## [1.3.1] - 2026-02-14
 ### Added:
+- Tree Construct: Construct tree from rich tree using `rich_to_tree` or `Tree.from_rich`.
 - Docs: More examples for listing directories.
 ### Fixed:
 - Tree Export: Fix attr square brackets being confused as rich formatting.
@@ -905,7 +901,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/1.3.0...HEAD
+[Unreleased]: https://github.com/kayjan/bigtree/compare/1.3.1...HEAD
+[1.3.1]: https://github.com/kayjan/bigtree/compare/1.3.0...1.3.1
 [1.3.0]: https://github.com/kayjan/bigtree/compare/1.2.0...1.3.0
 [1.2.0]: https://github.com/kayjan/bigtree/compare/1.1.0...1.2.0
 [1.1.0]: https://github.com/kayjan/bigtree/compare/1.0.4...1.1.0

README.md

@@ -42,9 +42,10 @@ For **Tree** implementation, there are 12 main components.
    5. From *pandas DataFrame*, using paths or parent-child columns
    6. From *polars DataFrame*, using paths or parent-child columns
    7. From *interactive UI*
-   8. Add nodes to existing tree using path string
-   9. Add nodes and attributes to existing tree using *dictionary*, *pandas DataFrame*, or *polars DataFrame*, using path
-   10. Add only attributes to existing tree using *dictionary*, *pandas DataFrame*, or *polars DataFrame*, using node name
+   8. From *rich trees*
+   9. Add nodes to existing tree using path string
+   10. Add nodes and attributes to existing tree using *dictionary*, *pandas DataFrame*, or *polars DataFrame*, using path
+   11. Add only attributes to existing tree using *dictionary*, *pandas DataFrame*, or *polars DataFrame*, using node name
 4. [**➰ Traversing Tree**](https://bigtree.readthedocs.io/stable/bigtree/utils/iterators/)
    1. Pre-Order Traversal
    2. Post-Order Traversal

bigtree/__init__.py

@@ -30,6 +30,7 @@
     polars_to_tree,
     polars_to_tree_by_relation,
     render_tree,
+    rich_to_tree,
     str_to_tree,
 )
 from bigtree.tree.export import (

bigtree/_plugins.py

@@ -81,6 +81,7 @@ def register_tree_plugins() -> None:
             "from_list_relation": construct.list_to_tree_by_relation,
             "from_str": construct.str_to_tree,
             "from_newick": construct.newick_to_tree,
+            "from_rich": construct.rich_to_tree,
         },
         method="class",
     )

bigtree/tree/construct/__init__.py

@@ -17,7 +17,7 @@
 )
 from .lists import list_to_tree, list_to_tree_by_relation
 from .render import render_tree
-from .strings import add_path_to_tree, newick_to_tree, str_to_tree
+from .strings import add_path_to_tree, newick_to_tree, rich_to_tree, str_to_tree
 
 __all__ = [
     "add_dataframe_to_tree_by_name",
@@ -38,5 +38,6 @@
     "render_tree",
     "add_path_to_tree",
     "newick_to_tree",
+    "rich_to_tree",
     "str_to_tree",
 ]

bigtree/tree/construct/strings.py

@@ -8,10 +8,19 @@
 from bigtree.tree import search
 from bigtree.utils import assertions, constants, exceptions
 
+try:
+    import rich
+except ImportError:  # pragma: no cover
+    from unittest.mock import MagicMock
+
+    rich = MagicMock()
+
+
 __all__ = [
     "add_path_to_tree",
     "str_to_tree",
     "newick_to_tree",
+    "rich_to_tree",
 ]
 
 T = TypeVar("T", bound=node.Node)
@@ -469,3 +478,61 @@ def _raise_value_error(tree_idx: int) -> None:
         current_depth,
     )
     return current_node
+
+
+@exceptions.optional_dependencies_rich
+def rich_to_tree(
+    rich_tree: rich.tree.Tree, node_format_attr: str = "style"
+) -> node.Node:
+    """Construct tree from rich tree to allow more tree operations, return root of tree.
+
+    If the rich node label is of type rich.text.Text, it will save the style, if any, as
+    a node attribute. This does not support inferring rich node label string using
+    square brackets.
+
+    Examples:
+        >>> from bigtree import Tree
+        >>> from rich.tree import Tree as RichTree
+        >>> from rich.text import Text
+        >>> rich_root = RichTree(Text("Grandparent", style="magenta"))
+        >>> child = rich_root.add("Child")
+        >>> _ = child.add(Text("Grandchild", style="red"))
+        >>> _ = rich_root.add("Child 2")
+        >>> tree = Tree.rich_to_tree(rich_root)
+        >>> tree.show(all_attrs=True)  # Try with rich=True, node_format_attr="style"
+        Grandparent [style=magenta]
+        ├── Child
+        │   └── Grandchild [style=red]
+        └── Child 2
+
+    Args:
+        rich_tree: rich Tree
+        node_format_attr: attribute name for the node format
+
+    Returns:
+        Node
+    """
+
+    def extract_label_and_style(label: rich.text.Text | str) -> tuple[str, str | None]:
+        """Extract label and list of styles spans from a rich label.
+
+        Returns:
+            label and style (if label is rich.text.Text and has style)
+        """
+        if isinstance(label, rich.text.Text):
+            return label.plain, label.style
+        else:
+            return str(label), None
+
+    def convert_node(
+        rich_node: rich.tree.Tree, parent: node.Node | None = None
+    ) -> node.Node:
+        node_name, node_format = extract_label_and_style(rich_node.label)
+        _node = node.Node(node_name, parent=parent)
+        if node_format:
+            _node.set_attrs({node_format_attr: node_format})
+        for child in rich_node.children:
+            convert_node(child, parent=_node)
+        return _node
+
+    return convert_node(rich_tree)

bigtree/tree/export/stdout.py

@@ -277,6 +277,13 @@ def print_tree(
             # Handle specific case where [ will be mistaken as rich formatting
             attr_bracket = ("\\" + attr_bracket[0], attr_bracket[1])
 
+        # Handle specific case where [ will be mistaken as rich formatting
+        attr_bracket = (
+            ("\\" + attr_bracket[0], attr_bracket[1])
+            if attr_bracket[0] == "["
+            else attr_bracket
+        )
+
     for pre_str, fill_str, _node in yield_tree(
         tree=tree,
         node_name_or_path=node_name_or_path,

docs/bigtree/tree/construct.md

@@ -19,6 +19,10 @@ To decide which method to use, consider your data type and data values.
 | polars DataFrame    | `polars_to_tree`    | `polars_to_tree_by_relation`                     | NA               | Yes                                                  |
 | Interactive UI      | NA                  | `render_tree`                                    | NA               | No                                                   |
 
+| Construct tree from | Notation       | Add node attributes   |
+|---------------------|----------------|-----------------------|
+| rich Tree           | `rich_to_tree` | Only style attributes |
+
 ## Tree Add Attributes Methods
 
 To add attributes to an existing tree,

docs/bigtree/tree/tree.md

@@ -25,6 +25,10 @@ methods.
 | pandas DataFrame    | `Tree.from_dataframe` | `Tree.from_dataframe_relation`                       | NA                 | Yes                                                      |
 | polars DataFrame    | `Tree.from_polars`    | `Tree.from_polars_relation`                          | NA                 | Yes                                                      |
 
+| Construct tree from | Notation            | Add node attributes   |
+|---------------------|---------------------|-----------------------|
+| rich Tree           | `Tree.from_rich`    | Only style attributes |
+
 To add attributes to an existing tree,
 
 | Add attributes from | Using full path         | Using node name         |

docs/gettingstarted/demo/tree.md

@@ -377,6 +377,31 @@ Construct nodes with attributes. *DataFrame* can contain either <mark>path colum
     # └── c [age=60]
     ```
 
+### 6. From rich Trees
+
+Convert rich.tree.Tree to bigtree Trees.
+
+=== "rich"
+    ```python hl_lines="10"
+    from rich.tree import Tree as RichTree
+    from rich.text import Text
+
+    from bigtree import Tree
+
+    rich_root = RichTree(Text("a", style="magenta"))
+    b = rich_root.add(Text("b", style="red"))
+    d = b.add("d")
+    c = rich_root.add(Text("c", style="red"))
+    tree = Tree.from_rich(rich_root)
+
+    # Style does not show up in documentation
+    tree.show(rich=True, node_format_attr="style")
+    # a
+    # ├── b
+    # │   └── d
+    # └── c
+    ```
+
 !!! note
 
     If tree is already created, nodes can still be added using path string, dictionary, and pandas/polars DataFrame!<br>
@@ -544,7 +569,7 @@ Other customisations for printing are also available, such as:
     ```
 === "Rich Render"
     ```python
-    # Does not show up in documentation
+    # Style does not show up in documentation
     tree.show(rich=True, node_format="bold magenta", edge_format="blue")
     # a
     # ├── b