Class TreeNode

xarray/core/treenode.py:46–660

Base class representing a node of a tree, with methods for traversing and altering the tree. This class stores no data, it has only parents and children attributes, and various methods. Stores child nodes in a dict, ensuring that equality checks between trees and order of child no

class TreeNode:
    """
    Base class representing a node of a tree, with methods for traversing and altering the tree.

    This class stores no data, it has only parents and children attributes, and various methods.

    Stores child nodes in a dict, ensuring that equality checks between trees
    and order of child nodes is preserved (since python 3.7).

    Nodes themselves are intrinsically unnamed (do not possess a ._name attribute), but if the node has a parent you can
    find the key it is stored under via the .name property.

    The .parent attribute is read-only: to replace the parent using public API you must set this node as the child of a
    new parent using `new_parent.children[name] = child_node`, or to instead detach from the current parent use
    `child_node.orphan()`.

    This class is intended to be subclassed by DataTree, which will overwrite some of the inherited behaviour,
    in particular to make names an inherent attribute, and allow setting parents directly. The intention is to mirror
    the class structure of xarray.Variable & xarray.DataArray, where Variable is unnamed but DataArray is (optionally)
    named.

    Also allows access to any other node in the tree via unix-like paths, including upwards referencing via '../'.

    (This class is heavily inspired by the anytree library's NodeMixin class.)

    """

    _parent: Self | None
    _children: dict[str, Self]

    def __init__(self, children: Mapping[str, Self] | None = None):
        """Create a parentless node."""
        self._parent = None
        self._children = {}

        if children:
            # shallow copy to avoid modifying arguments in-place (see GH issue #9196)
            self.children = {name: child.copy() for name, child in children.items()}

    @property
    def parent(self) -> Self | None:
        """Parent of this node."""
        return self._parent

    @parent.setter
    def parent(self, new_parent: Self) -> None:
        raise AttributeError(
            "Cannot set parent attribute directly, you must modify the children of the other node instead using dict-like syntax"
        )

    def _set_parent(
        self, new_parent: Self | None, child_name: str | None = None
    ) -> None:
        # TODO is it possible to refactor in a way that removes this private method?

        if new_parent is not None and not isinstance(new_parent, TreeNode):
            raise TypeError(
                "Parent nodes must be of type DataTree or None, "