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). Usemove_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. Useset_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.
Useset_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.
Useget_meta()
,set_meta()
,update_meta()
, andclear_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