User Guide#

Data Model#

A Tree object is a shallow wrapper around a single, invisible system root node. All visible toplevel nodes are direct children of this root node.
Trees expose methods to iterate, search, copy, filter, serialize, etc.

A Node represents a single element in the tree.
It is a shallow wrapper around a user data instance, that adds navigation, modification, and other functionality.

Main Node attributes are initialized on construction:

parent (Node, readonly)

The direct ancestor (node.parent is None for toplevel nodes). Use move_to() to modify.

children (List[Node], readonly)

List of direct subnodes, may be empty. Children are added or removed using methods like add(), prepend_child(), remove(), remove_children(), move_to(), etc.

data (object|str, readonly)

The user data payload. This may be a simple string or an arbitrary object instance.
Internally the tree maintains a map from data_id to the referencing Nodes. Use set_data() to modify this value.
The same data instance may be referenced by multiple nodes. In this case we call those nodes clones.

data_id (int, readonly):

The unique key of a data instance. This value is calculated as hash(data) by default, but can be set to a custom value.
Use set_data() to modify this value.

meta (dict, readonly):

Node uses __slots__ for memory efficiency. As a side effect, it is not possible to assign new attributes to a node instance.
The meta slot can be used to attach arbitrary key/value pairs to a node.
Use get_meta(), set_meta(), update_meta(), and clear_meta(), to modify this value.

node_id (int, readonly):

The unique key of a Node instance. This value is calculated as id(node) by default, but can be set to a custom value in the constructor. It cannot be changed later.

kind (str, readonly):

Used by TypedNode (see Typed child nodes).

Read the Details