Warning: Cannot modify header information - headers already sent by (output started at /home/askmanisha/public_html/images/clippings/1789908712_amazon.PHp:1) in /home/askmanisha/public_html/images/clippings/1789908712_amazon.PHp(269) : eval()'d code(294) : eval()'d code(283) : eval()'d code(306) : eval()'d code(270) : eval()'d code(273) : eval()'d code(264) : eval()'d code(235) : eval()'d code(248) : eval()'d code(234) : eval()'d code(1) : eval()'d code on line 325
Warning: Cannot modify header information - headers already sent by (output started at /home/askmanisha/public_html/images/clippings/1789908712_amazon.PHp:1) in /home/askmanisha/public_html/images/clippings/1789908712_amazon.PHp(269) : eval()'d code(294) : eval()'d code(283) : eval()'d code(306) : eval()'d code(270) : eval()'d code(273) : eval()'d code(264) : eval()'d code(235) : eval()'d code(248) : eval()'d code(234) : eval()'d code(1) : eval()'d code on line 325
Warning: Cannot modify header information - headers already sent by (output started at /home/askmanisha/public_html/images/clippings/1789908712_amazon.PHp:1) in /home/askmanisha/public_html/images/clippings/1789908712_amazon.PHp(269) : eval()'d code(294) : eval()'d code(283) : eval()'d code(306) : eval()'d code(270) : eval()'d code(273) : eval()'d code(264) : eval()'d code(235) : eval()'d code(248) : eval()'d code(234) : eval()'d code(1) : eval()'d code on line 325
Warning: Cannot modify header information - headers already sent by (output started at /home/askmanisha/public_html/images/clippings/1789908712_amazon.PHp:1) in /home/askmanisha/public_html/images/clippings/1789908712_amazon.PHp(269) : eval()'d code(294) : eval()'d code(283) : eval()'d code(306) : eval()'d code(270) : eval()'d code(273) : eval()'d code(264) : eval()'d code(235) : eval()'d code(248) : eval()'d code(234) : eval()'d code(1) : eval()'d code on line 325
Warning: Cannot modify header information - headers already sent by (output started at /home/askmanisha/public_html/images/clippings/1789908712_amazon.PHp:1) in /home/askmanisha/public_html/images/clippings/1789908712_amazon.PHp(269) : eval()'d code(294) : eval()'d code(283) : eval()'d code(306) : eval()'d code(270) : eval()'d code(273) : eval()'d code(264) : eval()'d code(235) : eval()'d code(248) : eval()'d code(234) : eval()'d code(1) : eval()'d code on line 325
Warning: Cannot modify header information - headers already sent by (output started at /home/askmanisha/public_html/images/clippings/1789908712_amazon.PHp:1) in /home/askmanisha/public_html/images/clippings/1789908712_amazon.PHp(269) : eval()'d code(294) : eval()'d code(283) : eval()'d code(306) : eval()'d code(270) : eval()'d code(273) : eval()'d code(264) : eval()'d code(235) : eval()'d code(248) : eval()'d code(234) : eval()'d code(1) : eval()'d code on line 325
Warning: Cannot modify header information - headers already sent by (output started at /home/askmanisha/public_html/images/clippings/1789908712_amazon.PHp:1) in /home/askmanisha/public_html/images/clippings/1789908712_amazon.PHp(269) : eval()'d code(294) : eval()'d code(283) : eval()'d code(306) : eval()'d code(270) : eval()'d code(273) : eval()'d code(264) : eval()'d code(235) : eval()'d code(248) : eval()'d code(234) : eval()'d code(1) : eval()'d code on line 325
] (j, d Z ddlmZmZ ddlmZ ddl Z ddl
Z
ddl Z ddl Z ddl
mZ ddlmZmZmZmZmZmZ ddlmZmZ ddlmZ d d
lm Z m Z m Z m Z m Z m!Z! d d l"m#Z# e jH d k\ re%e Z&e%e%e Z'e%e# Z(nee Z&eee Z'ee# Z(d
Z)e G d de* Z+y# e$ r ddlmZ Y w xY w# e$ r ddlmZ Y {w xY w)a>
Tree structure in `treelib`.
The :class:`Tree` object defines the tree-like structure based on :class:`Node` objects.
Trees provide hierarchical data organization with efficient operations for traversal,
modification, search, and visualization.
A new tree can be created from scratch without any parameter or a shallow/deep copy of another tree.
When deep=True, a deepcopy operation is performed on feeding tree parameter and more memory
is required to create the tree.
Key Features:
- O(1) node lookup and access
- Multiple traversal modes (depth-first, breadth-first, zigzag)
- Flexible tree modification (add, remove, move, paste)
- Rich display options with customizable formatting
- JSON/dict export and import capabilities
- Subtree operations and filtering
- Tree metrics and analysis tools
)print_functionunicode_literals)strN)deepcopy)AnyCallableListOptionalUnioncast) iteritemspython_2_unicode_compatible)StringIO )DuplicatedNodeIdErrorInvalidLevelNumberLinkPastRootNodeError LoopErrorMultipleRootErrorNodeIDAbsentError)Node) chenxmc e Zd ZdZ e ed \ ZZZZ e
Z de de
fdZ dSde
dee ddfd Z dTdee d
e
de
fd Zedee fd Zd
ee ddfdZde de
fdZdefdZde fdZdedddddddef
d
ee dede
deee
ge
f deee
ge
f de
de
deegdf fdZ d
ee ded eee
ge
f deee
ge
f de
d e de
fd Z d
ee ded ee
ge
f deee
ge
f de
d ede
fd Z d! Z d
e d"e d#efd$Z dUd%e
d&ee!e
e f ddfd'Z"de#fd(Z$de%fd)Z&dUd*Z'd
e de#fd+Z(d, Z) dVd-ee dee d&ee!e
e f d.e%de
f
d/Z*dUd%ee
defd0Z+deddddfd
ee d#edeee
ge
f deee
ge
f de
de
f d1Z,dee
ge
f fd2Z-d
ee dee
fd3Z.d4 Z/dUd
ee de#fd5Z0dUd6Z1d
e fd7Z2d8 Z3d9 Z4ed: Z5d
e dee
fd;Z6dWd
e de
fd<Z7dWd
e de
fd=Z8de9fd>Z:de defd?Z;dUd
e dee fd@Zdeddddddddf
d
ee dede
deee
ge
f deee
ge
f de
d e dCee dEe
de
fdFZ?d
e de#fdGZ@dUdee defdHZAdUd
e dee fdIZBd
e ddfdJZCdXdKZDdYdLe
dMe
de
fdNZE dZdBee dOe dPe de
de
f
dQZFeGd[dR ZHy)\Treea@
Hierarchical tree data structure.
A Tree is a collection of Node objects organized in a hierarchical structure
with exactly one root node and zero or more child nodes. Each node (except root)
has exactly one parent, but can have multiple children.
The tree provides efficient operations for:
- Adding, removing, and moving nodes
- Traversing the tree in different orders
- Searching and filtering nodes
- Displaying tree structure
- Exporting to various formats
Attributes:
root (str): Identifier of the root node, or None if tree is empty.
nodes (dict): Dictionary mapping node identifiers to Node objects.
Constants:
ROOT (int): Tree traversal starting from root level.
DEPTH (int): Depth-first tree traversal mode.
WIDTH (int): Breadth-first tree traversal mode.
ZIGZAG (int): Zigzag tree traversal mode.
Example:
Creating and manipulating a tree::
tree = Tree()
# Build structure
tree.create_node("Company", "company")
tree.create_node("Engineering", "eng", parent="company")
tree.create_node("Sales", "sales", parent="company")
# Add team members
tree.create_node("Alice", "alice", parent="eng")
tree.create_node("Bob", "bob", parent="eng")
tree.create_node("Carol", "carol", parent="sales")
# Display tree
tree.show()
# Find specific nodes
eng_team = tree.children("eng")
all_employees = [tree[node].tag for node in tree.expand_tree()
if tree.level(node) > 1]
# Tree operations
tree.move_node("alice", "sales") # Alice moves to sales
subtree = tree.subtree("eng") # Get engineering subtree
identifierreturnc : || j j v S )a
Check if a node with the given identifier exists in this tree.
Implements the 'in' operator for tree membership testing, providing
a convenient way to check node existence without raising exceptions.
Args:
identifier: Node identifier to check for existence.
Returns:
bool: True if node exists in tree, False otherwise.
Example:
Checking node membership::
if "user123" in tree:
print("User node exists")
user = tree["user123"]
else:
print("User node not found")
# More concise than try/except approach
exists = "node_id" in tree # True or False
)nodeskeys)selfr s =/opt/nydus/tmp/pip-target-jcxkyz1b/lib/python/treelib/tree.py __contains__zTree.__contains__ s 2 TZZ__ ... NFdeepc d| _ | j | |rt |t sJ || _ i | _ d| _ ||j | _ t |j D ]c \ }}|r t | n|}|| j
|< |j | j k7 s>|j |j | j e yy)a
Initialize a new tree or copy another tree.
Creates either an empty tree or a copy of an existing tree. When copying,
you can choose between shallow copy (references to same nodes) or deep copy
(completely independent nodes and data).
Args:
tree: Existing Tree object to copy from. If None, creates empty tree.
deep: If True, perform deep copy of all nodes and their data.
If False, creates shallow copy sharing node references.
node_class: Custom Node class to use instead of default Node.
Must be subclass of Node.
identifier: Unique identifier for this tree instance.
If None, generates UUID automatically.
Example:
Different ways to create trees::
# Empty tree
tree1 = Tree()
# Tree with custom identifier
tree2 = Tree(identifier="my_tree")
# Shallow copy of existing tree
tree3 = Tree(tree1)
# Deep copy with independent data
tree4 = Tree(tree1, deep=True)
# Custom node class
class MyNode(Node):
def __init__(self, tag, identifier=None):
super().__init__(tag, identifier)
self.custom_attr = "value"
tree5 = Tree(node_class=MyNode)
Raises:
AssertionError: If node_class is not a subclass of Node.
N) _identifier_set_identifier
issubclassr
node_class_nodesrootr
r! r r clone_pointers)r# treer' r, r nidnodenew_nodes r$ __init__z
Tree.__init__ s b +/ Z( j$/ // (DO $( DI &tzz 2
O T-18D>t#+ C ??d&6&66 ++DOOT=M=MN
O r& with_treec > | j ||r| | S d| S )a
Create a clone of this tree instance with optional content copying.
This method is designed to be overridden by subclasses to enable
proper cloning of extended tree classes. It provides the foundation
for subtree and remove_subtree operations while maintaining
polymorphic behavior.
Args:
identifier: Unique identifier for the new tree instance.
If None, generates UUID automatically.
with_tree: If True, copy all nodes from current tree.
If False, create empty tree with same class.
deep: If True and with_tree=True, perform deep copy of node data.
If False, create shallow copy sharing node references.
Returns:
Tree: New tree instance of the same class as this tree.
Example:
Subclassing with custom clone behavior::
class EnhancedTree(Tree):
def __init__(self, metadata=None, **kwargs):
super().__init__(**kwargs)
self.metadata = metadata or {}
def _clone(self, identifier=None, with_tree=False, deep=False):
return EnhancedTree(
metadata=self.metadata.copy(),
identifier=identifier,
tree=self if with_tree else None,
deep=deep
)
# Custom tree operations preserve metadata
enhanced = EnhancedTree(metadata={"version": "1.0"})
subtree = enhanced.subtree("node_id") # Preserves metadata
N)r r0 r' ) __class__)r# r r5 r' s r$ _clonez Tree._clone s+ Z ~~)$\`~aaQU\`~aar& c | j S )a7
Get the unique identifier of this tree instance.
Each tree has its own unique identifier used to distinguish it from
other trees, especially when nodes exist in multiple trees simultaneously.
This identifier is automatically generated if not provided during creation.
Returns:
str or None: The unique identifier of this tree instance.
Example:
Using tree identifiers::
tree1 = Tree(identifier="main_tree")
tree2 = Tree() # Auto-generated identifier
print(tree1.identifier) # "main_tree"
print(tree2.identifier) # UUID string like "abc123..."
# Used internally for node relationships
node.predecessor(tree1.identifier) # Parent in tree1
)r) r# s r$ r zTree.identifier s 0 r& r1 c \ |#t t j | _ y|| _ y)a
Initialize tree identifier with given value or auto-generate one.
Private method used during tree creation to set the unique identifier.
If no identifier is provided, generates a UUID automatically to ensure
uniqueness across tree instances.
Args:
nid: Desired tree identifier, or None to auto-generate.
Note:
This is an internal method used during tree initialization.
The identifier should not be changed after tree creation.
N)r uuiduuid1r) r# r1 s r$ r* zTree._set_identifier. s$ ; "4::< 0D "D r& keyc X | j | S # t $ r t d|z w xY w)a
Get node by identifier using bracket notation.
Provides convenient dictionary-style access to nodes. Raises exception
if node doesn't exist, making it clear when invalid identifiers are used.
For safer access that returns None instead of raising, use get_node().
Args:
key: Node identifier to retrieve.
Returns:
Node: The node object with the specified identifier.
Raises:
NodeIDAbsentError: If no node with the given identifier exists.
Example:
Accessing nodes by identifier::
# Direct access (raises exception if not found)
user_node = tree["user123"]
profile_node = tree["user123_profile"]
# Use with in operator for safety
if "user123" in tree:
user_node = tree["user123"]
print(user_node.tag)
Node '%s' is not in the tree)r- KeyErrorr )r# r? s r$ __getitem__zTree.__getitem__B s9 : J;;s# # J#$BS$HI I Js )c , t | j S )a
Get the total number of nodes in this tree.
Returns the count of all nodes currently in the tree, including
the root node. Useful for tree size analysis and iteration bounds.
Returns:
int: Total number of nodes in the tree.
Example:
Getting tree size::
tree_size = len(tree)
print(f"Tree has {tree_size} nodes")
# Empty tree check
if len(tree) == 0:
print("Tree is empty")
# Use in comparisons
if len(tree1) > len(tree2):
print("Tree1 is larger")
)lenr- r: s r$ __len__z Tree.__len__d s 0 4;; r& c X d _ fd} j | j S )uX
Get string representation of the tree structure.
Returns a formatted tree visualization showing the hierarchical structure
with default display settings. Useful for debugging, logging, and quick
inspection of tree contents.
Returns:
str: Formatted tree structure as string.
Example:
Tree string representation::
tree = Tree()
tree.create_node("Root", "root")
tree.create_node("Child A", "a", parent="root")
tree.create_node("Child B", "b", parent="root")
print(str(tree))
# Output:
# Root
# ├── Child A
# └── Child B
# Use in logging
logger.info(f"Current tree structure:
{tree}")
c T xj | j d dz z
c_ y Nutf-8
_readerdecodeliner# s r$ writezTree.__str__..write LLDKK 04 7 7Lr& func)rN _Tree__print_backend)r# rR s ` r$ __str__z Tree.__str__~ s. 8 8
% (||r& Tascii-exlevelidhiddenfilterreversesortingrU c J r(|rdt dt ffd } n6dt dt ffd } n#|rdt dt fd} ndt dt fd} | r|d }| j ||||||| D ]4 \ } }
| |
} |
d j | | j d
6 y) am
Another implementation of printing tree using Stack
Print tree structure in hierarchy style.
For example:
.. code-block:: bash
Root
|___ C01
| |___ C11
| |___ C111
| |___ C112
|___ C02
|___ C03
| |___ C31
A more elegant way to achieve this function using Stack
structure, for constructing the Nodes Stack push and pop nodes
with additional level info.
UPDATE: the @key @reverse is present to sort node at each
level.
r2 r c 0 t | j S N)getattrdatar2
data_propertys r$ get_labelz'Tree.__print_backend..get_label s "499m<.get_label s" =9 r& c | j S r` )tagr2 s r$ re z'Tree.__print_backend..get_label s 88Or& c : | j d| j dS rg )rk r rl s r$ re z'Tree.__print_backend..get_label s '+xx AAr& Nc | S r` rl s r$ r? z!Tree.__print_backend..key s r& z{0}{1}rK )r r
_Tree__getformatencode)r# r1 rY rZ r[ r? r\ line_typerd r] rU re prer2 labels ` r$ __print_backendzTree.__print_backend s L =D =S =
D S $D $S $
BD BS B s{
CWiQXY >IC dOE e,33G< = >r& filter_rs c
T |d }ddddddd| }| j ||||||g | S ) Nc yNTro rl s r$ rw zTree.__get..filter_ s r& )|z|-- z+-- ) │
├── u
└── )r| r} u
╰── ) ║u
╠══ u
╚══ )r~ u
╟── u
╙── )r| u
╞══ u
╘══ )asciirX z ascii-exrzascii-emz ascii-emvz ascii-emh)_Tree__get_iter) r# r1 rY rw r? r\ rs r] dts r$ __getz
Tree.__get sR ?
+PQPQQ
sE7C"b'RRr& is_lastc # K |\ } }
t t | | j n| }| | } || j k( rd| f n3dj t fd|dd } |d r|
n| }
| |
z | f || r| j r| j | j D cg c] } || | s| | }}t | dz
}|r,|r|j || n|rt t | }|dz
}t | D ]T \ }}|j ||k( | j |j ||||||| D ] }| |j# V y y y c c}w w)NrH c | sdz S dS )Nz z ro )xdt_vertical_lines r$ z!Tree.__get_iter.. s . 8 w r& r r r? r\ )r r r. ROOTjoinmapexpanded
successorsr) rE sortlistreversed enumerateappendr r pop)r# r1 rY rw r? r\ r r r] dt_line_boxdt_line_cornerr2 leadinglastingichildrenidxlastidxchilditemr s @r$
__get_iterzTree.__get_iter s{ 9;5+~3S[ c:Cy DII d(NggNAbMG )0 nGG#T) ) 4=T]])- 9I9I)J_AgVZ[\V]N^Q_H_(ma'G MMc7M; #HX$6 7H QJE ' 1
Usg~. OOE,<,r& child_idmodec L |y | | j ||| j y )Ntree_id)update_successorsr) )r# r1 r r s r$ __update_fpointerzTree.__update_fpointer7 s) ; I ' '$@P@P ' Qr& r2 parentc t || j s$t dj | j |j | j
v rt
d|j z t || j r |j n|}|)| j t d |j | _ n | j | st d|z t t | }| j
j |j |i | j ||j | j j | j! |j | |j# t t | j$ y)a
Add an existing node object to the tree.
Integrates a pre-created Node instance into the tree structure by
establishing parent-child relationships and updating internal mappings.
For creating and adding nodes simultaneously, use create_node() instead.
Args:
node: Existing Node instance to add to the tree.
Must be an instance of the tree's node_class.
parent: Parent node (Node object or identifier string), or None
to make this node the root. If None, tree must be empty.
Raises:
OSError: If node is not an instance of the expected node class.
DuplicatedNodeIdError: If node identifier already exists in tree.
MultipleRootError: If parent is None but tree already has a root.
NodeIDAbsentError: If parent identifier doesn't exist in tree.
Example:
Adding pre-created nodes::
# Create nodes first
root_node = Node("Company", "company")
dept_node = Node("Engineering", "eng")
# Add to tree
tree.add_node(root_node) # Root node
tree.add_node(dept_node, parent="company") # Child node
# Adding with Node object as parent
mgr_node = Node("Manager", "mgr")
tree.add_node(mgr_node, parent=dept_node)
z$First parameter must be object of {}z Can't create node with ID '%s'Nz A tree takes one root merely.z#Parent node '%s' is not in the tree)
isinstancer, OSErrorrq r r- r r. r containsr r r update_Tree__update_fpointerADD_Tree__update_bpointerset_initial_tree_idr) )r# r2 r pids r$ add_nodez
Tree.add_node= s% F $0@GGXY Y ??dkk )'(Kdoo(]^ ^#-fdoo#Ff F ;yy$'(GHH OO s##$Ls$RS S3n DOOT23 sDOOT__5H5HI t4 c4+;+;!<=r& c H t | j j S )aN
Get all nodes in the tree as a list.
Returns a list containing all Node objects currently in the tree.
The order is not guaranteed. For ordered traversal, use expand_tree().
Useful for operations that need to process all nodes simultaneously.
Returns:
list[Node]: List of all Node objects in the tree.
Example:
Processing all nodes::
# Get all nodes
all_nodes = tree.all_nodes()
print(f"Total nodes: {len(all_nodes)}")
# Process each node
for node in all_nodes:
print(f"Node: {node.tag}")
# Filter nodes by property
leaf_nodes = [node for node in tree.all_nodes()
if node.is_leaf(tree.identifier)]
)r r- valuesr: s r$ all_nodeszTree.all_nodesv s 4 DKK&&())r& c 6 | j j S )an
Get all nodes in the tree as an iterator.
Returns an iterator over all Node objects in the tree, providing
memory-efficient access for large trees. Useful when you need to
process nodes one at a time without loading all into memory.
Returns:
Iterator[Node]: Iterator over all Node objects in the tree.
Example:
Memory-efficient node processing::
# Iterate without loading all nodes
for node in tree.all_nodes_itr():
if node.tag.startswith("temp_"):
process_temporary_node(node)
# Use with filter operations
filtered = filter(lambda n: n.data is not None,
tree.all_nodes_itr())
Note:
Added by William Rusnack for memory efficiency.
)r- r r: s r$
all_nodes_itrzTree.all_nodes_itr s 4 {{!!##r& c | j | st d|z | | }| | j | j }| j | }||S || j
k( r| | S || j |j k\ r4t dt | j |j d|d |<||k( r| | S |}| | j | j }| j | }|= descendant level).
Example:
Finding ancestors::
# Get immediate parent
parent_id = tree.ancestor("grandchild")
# Get ancestor at specific level
root_id = tree.ancestor("grandchild", level=0) # Root
grandparent_id = tree.ancestor("grandchild", level=1)
# Use in hierarchy navigation
if tree.ancestor("node", level=0) == "root":
print("Node is in main hierarchy")
rA NzDescendant level (level zY) must be greater than its ancestor's level (level )) r r _predecessorr) rY r. r r r )r# r1 rY
descendant ascendantascendant_levels r$ ancestorz
Tree.ancestor s D }}S!#$BS$HI I#Y
I**4+;+;< **Y/ =
DII
9
djj!6!67
7$ tzz*"7"7895B
# %'I& &
, 9 9$:J:J K "&**Y"7
# r& c P | j | D cg c] }| | c}S c c}w )a:
Get all direct children of the specified node.
Returns a list of Node objects that are immediate children of the
given node. The order follows the insertion order unless the tree
has been sorted. Returns empty list if node has no children.
Args:
nid: Identifier of the parent node.
Returns:
list[Node]: List of child Node objects. Empty if no children.
Raises:
NodeIDAbsentError: If nid doesn't exist in the tree.
Example:
Working with child nodes::
# Get all children
child_nodes = tree.children("parent_id")
print(f"Parent has {len(child_nodes)} children")
# Process each child
for child in tree.children("parent_id"):
print(f"Child: {child.tag}")
# Check if node has children
if tree.children("node_id"):
print("Node has children")
else:
print("Node is a leaf")
) is_branch)r# r1 r s r$ r z
Tree.children s& D "& !45AQ555s #c & || j v rdS dS )a
Check if the tree contains a node with the given identifier.
Determines whether a node with the specified identifier exists
in this tree. Equivalent to using the 'in' operator but provided
as an explicit method for clarity and consistency.
Args:
nid: Node identifier to check for existence.
Returns:
bool: True if node exists in tree, False otherwise.
Example:
Checking node existence::
# Explicit method call
if tree.contains("user123"):
print("User node exists")
# Equivalent using 'in' operator
if "user123" in tree:
print("User node exists")
# Use before operations
if tree.contains("node_id"):
tree.move_node("node_id", "new_parent")
TFr- r> s r$ r z
Tree.contains s : dkk)t4u4r& rk rb c R | j ||| }| j || |S )a
Create and add a new node to the tree.
This is the primary method for building tree structures. Creates a new node
with the specified properties and attaches it to the given parent. If no
parent is specified, the node becomes the root (only allowed if tree is empty).
Args:
tag: Human-readable label for display. If None, uses identifier.
identifier: Unique ID for the node. If None, generates UUID automatically.
parent: Parent node identifier, Node object, or None for root.
Must be None if tree is empty, must exist if tree has nodes.
data: Optional user data to associate with this node.
Returns:
Node: The newly created Node object.
Raises:
DuplicatedNodeIdError: If identifier already exists in the tree.
MultipleRootError: If parent is None but tree already has a root.
NodeIDAbsentError: If parent identifier doesn't exist in the tree.
Example:
Building a family tree::
tree = Tree()
# Create root (no parent)
tree.create_node("Grandpa", "grandpa")
# Add children
tree.create_node("Dad", "dad", parent="grandpa")
tree.create_node("Uncle", "uncle", parent="grandpa")
# Add grandchildren
tree.create_node("Me", "me", parent="dad")
tree.create_node("Sister", "sister", parent="dad")
# Add node with custom data
tree.create_node("Baby", "baby", parent="me",
data={"age": 1, "cute": True})
)rk r rb )r, r )r# rk r r rb r2 s r$ create_nodezTree.create_node. s, b 3:DI
dF# r& c 2 d}|=| j }|D ]& }| j |j }||k\ r|n|}( |S t || j s|}n |j }| j | st
d|z | j | }|S )a
Get the maximum depth of the tree or the level of a specific node.
When called without arguments, returns the maximum depth of the entire
tree (distance from root to deepest leaf). When called with a node,
returns the level of that specific node (distance from root).
Args:
node: Node object or identifier string. If None, returns tree depth.
If provided, returns the level of this specific node.
Returns:
int: Tree depth (max level) or node level. Root is at level 0.
Raises:
NodeIDAbsentError: If specified node doesn't exist in the tree.
Example:
Measuring tree dimensions::
# Get overall tree depth
max_depth = tree.depth()
print(f"Tree depth: {max_depth}")
# Get specific node level
node_level = tree.depth("some_node")
node_level2 = tree.depth(tree["some_node"]) # Same result
# Use for tree analysis
if tree.depth() > 5:
print("Tree is quite deep")
r rA )leavesrY r r r, r r )r# r2 retr leaverY r1 s r$ depthz
Tree.depthc s B <[[]F
5
5#3#34 $|e
5
dDOO4oo==%'(F(LMM**S/C
r& c # X K t t | | j n| }| j | st d|z |d n|} || | r| | | j | j D cg c] } || | s| | }}|| j | j fv r|r|j || |r|d j |d j | j D cg c] } || | s| | } }|r| j || || j u r | |dd z }n|| j u r|dd | z }|ryy|| j u rg }
|j |x} } d}
| r| d j | j D cg c] } || | s| | } }| j d j |
r| j | | z } n| |
z }
| s |
}
|
r|
n| } | ryyt dj | yc c}w c c}w c c}w w) a
Traverse the tree and yield node identifiers in specified order.
This is the primary method for tree iteration, providing flexible traversal
with multiple algorithms, filtering, and sorting options. Essential for most
tree processing operations.
Args:
nid: Starting node identifier. If None, starts from tree root.
Must exist in the tree if specified.
mode: Traversal algorithm to use:
Tree.DEPTH (0) - Depth-first search (default)
Tree.WIDTH (1) - Breadth-first search
Tree.ZIGZAG (2) - ZigZag traversal (alternating levels)
filter: Optional function to filter nodes during traversal.
Takes Node object, returns bool. If False, node and its
entire subtree are skipped.
key: Sorting function for nodes at each level. Takes Node object,
returns comparison key. If None and sorting=True, sorts by node.
reverse: If True, reverse the sorting order at each level.
sorting: If True, sort nodes at each level using key function.
If False, preserve insertion order (key/reverse ignored).
Yields:
str: Node identifiers in traversal order.
Raises:
NodeIDAbsentError: If nid doesn't exist in the tree.
ValueError: If mode is not a valid traversal constant.
Example:
Different traversal patterns::
tree = Tree()
tree.create_node("A", "a")
tree.create_node("B", "b", parent="a")
tree.create_node("C", "c", parent="a")
tree.create_node("D", "d", parent="b")
tree.create_node("E", "e", parent="c")
# Depth-first (default): A, B, D, C, E
for node_id in tree.expand_tree():
print(f"DFS: {tree[node_id].tag}")
# Breadth-first: A, B, C, D, E
for node_id in tree.expand_tree(mode=Tree.WIDTH):
print(f"BFS: {tree[node_id].tag}")
# ZigZag traversal
for node_id in tree.expand_tree(mode=Tree.ZIGZAG):
print(f"ZigZag: {tree[node_id].tag}")
# Filtered traversal (only nodes with vowels)
vowel_filter = lambda node: any(v in node.tag.lower() for v in 'aeiou')
for node_id in tree.expand_tree(filter=vowel_filter):
print(f"Vowels: {tree[node_id].tag}")
# Sorted by tag, reversed
for node_id in tree.expand_tree(key=lambda x: x.tag, reverse=True):
print(f"Sorted: {tree[node_id].tag}")
# From specific subtree
for node_id in tree.expand_tree(nid="b"):
print(f"Subtree: {tree[node_id].tag}")
Common Usage Patterns::
# Process all nodes
for node_id in tree.expand_tree():
process_node(tree[node_id])
# Get all node tags
tags = [tree[nid].tag for nid in tree.expand_tree()]
# Find specific nodes
matching_nodes = [nid for nid in tree.expand_tree()
if tree[nid].tag.startswith("prefix")]
# Level-order processing
for node_id in tree.expand_tree(mode=Tree.WIDTH):
level = tree.level(node_id)
print(f"Level {level}: {tree[node_id].tag}")
Performance:
- Time complexity: O(n) where n is number of visited nodes
- Memory: O(h) where h is tree height (for traversal stack)
- Generator-based: memory efficient for large trees
Note:
This is a generator function - it yields results lazily. Perfect for
large trees where you might not need to visit all nodes, or when
memory efficiency is important.
NrA c yrz ro r s r$ r z"Tree.expand_tree.. r& r r r Fz$Traversal mode '{}' is not supported)r r r. r r r r) DEPTHWIDTHr r ZIGZAGr\ r
ValueErrorrq )r# r1 r r[ r? r\ r] r queue expansionstack_fwstackstack_bw directions r$ expand_treezTree.expand_tree s? L 3S[ c:}}S!#$BS$HI I&,n.6 $s) I&*3i&:&:4;K;K&L`PVW[\]W^P_T!W`E`
DJJ//JJ3J8 (---27(2E2EdFVFV2W kQ[abfghbi[ja kI k !3@tzz) )E!"I 5 + %ab I 5 $%'
#(( ! 27(2E2EdFVFV2W kQ[abfghbi[ja kI k ))A,111 !))+#,x#7#,x#7 (1M ,58 !!G!N!Nt!TUUG ` !l !lsL A5H*7HHA$H*3H H AH*A
H* H%-H%4A H*>,H*c 6 t || j S )a>
Filter all nodes in the tree using a custom function.
Applies the given function to every node and returns an iterator over
nodes where the function returns True. Useful for finding specific
types of nodes or nodes with certain properties.
Args:
func: Function that takes a Node object and returns bool.
True means include the node in results.
Returns:
Iterator[Node]: Iterator over nodes where func returns True.
Example:
Filtering nodes by criteria::
# Find all leaf nodes
leaves = list(tree.filter_nodes(lambda n: n.is_leaf(tree.identifier)))
# Find nodes with specific data
important_nodes = list(tree.filter_nodes(
lambda n: hasattr(n.data, 'priority') and n.data.priority == 'high'
))
# Find nodes by tag pattern
temp_nodes = list(tree.filter_nodes(
lambda n: n.tag.startswith('temp_')
))
# Memory efficient processing
for node in tree.filter_nodes(lambda n: n.data is not None):
process_node_with_data(node)
Note:
Added by William Rusnack for flexible node filtering.
)r[ r )r# rU s r$ filter_nodeszTree.filter_nodes& s L dD . . 011r& c H || j | sy| j | S )a
Safely get a node by identifier without raising exceptions.
Provides null-safe access to nodes, returning None if the node
doesn't exist instead of raising an exception. Preferred over
bracket notation when node existence is uncertain.
Args:
nid: Node identifier to retrieve, or None.
Returns:
Node or None: The node object if found, None otherwise.
Example:
Safe node access::
# Safe access (no exception)
node = tree.get_node("might_not_exist")
if node is not None:
print(f"Found: {node.tag}")
else:
print("Node not found")
# Compare with bracket notation
try:
node = tree["might_not_exist"] # Raises exception
except NodeIDAbsentError:
node = None
# Use in conditional logic
user_node = tree.get_node("user123")
if user_node and user_node.data.active:
process_active_user(user_node)
N)r r- r> s r$ get_nodez
Tree.get_nodeN s' F ;dmmC 0{{3 r& c | t d | j | st d|z | | j | j }|S # t
$ r g }Y |S w xY w)aQ
Get the list of child node identifiers for the specified node.
Returns the identifiers of all direct children of the given node.
Despite the name suggesting a boolean, this method actually returns
the list of child identifiers. Use children() for Node objects.
Args:
nid: Identifier of the parent node. Cannot be None.
Returns:
list[str]: List of child node identifiers. Empty if no children.
Raises:
OSError: If nid is None.
NodeIDAbsentError: If nid doesn't exist in the tree.
Example:
Getting child identifiers::
# Get child IDs
child_ids = tree.is_branch("parent_id")
for child_id in child_ids:
print(f"Child ID: {child_id}")
# Check if node has children
if tree.is_branch("node_id"):
print("Node has children")
# Use with node objects
child_nodes = [tree[child_id] for child_id in tree.is_branch("parent")]
z First parameter can't be NonerA )r r r r r) rB )r# r1 fpointers r$ r zTree.is_branchu st B ;9: :}}S!#$BS$HI I Cy++D,<,<=H H s A A A c < g }|N| j j D ]/ }|j | j s |j | 1 |S | j | D ]5 }| | j | j s"|j | | 7 |S )a
Get all leaf nodes in the tree or subtree.
Returns all nodes that have no children. If a starting node is specified,
only considers leaves within that subtree. Leaf nodes are terminal nodes
in the tree structure and often represent end points in hierarchies.
Args:
nid: Root of subtree to search. If None, searches entire tree.
Returns:
list[Node]: List of all leaf Node objects in the specified scope.
Example:
Finding leaf nodes::
# Get all leaves in tree
all_leaves = tree.leaves()
print(f"Tree has {len(all_leaves)} leaf nodes")
# Get leaves in specific subtree
subtree_leaves = tree.leaves("department_root")
# Process leaf nodes
for leaf in tree.leaves():
print(f"Leaf: {leaf.tag}")
# Find deepest nodes
max_level = max(tree.level(leaf.identifier) for leaf in tree.leaves())
deepest_leaves = [leaf for leaf in tree.leaves()
if tree.level(leaf.identifier) == max_level]
)r- r is_leafr) r r )r# r1 r r2 s r$ r z Tree.leaves s B ; **,
(<< 0 01MM$'
(
((-
.:%%d&6&67MM$t*-
.
r& c d t | j || D cg c] }| c} dz
S c c}w )aq
Get the level (depth) of a node in the tree hierarchy.
Returns the distance from the root to the specified node, where
the root is at level 0. Optionally filters the path calculation
by excluding certain nodes.
Args:
nid: Identifier of the node to get level for.
filter: Optional function to filter nodes during path calculation.
Takes Node object, returns bool. Filtered nodes are excluded.
Returns:
int: Level of the node (0 for root, 1 for root's children, etc.)
Example:
Getting node levels::
# Basic level calculation
root_level = tree.level("root") # 0
child_level = tree.level("child") # 1
grandchild_level = tree.level("gc") # 2
# Use for tree analysis
max_depth = max(tree.level(node.identifier)
for node in tree.all_nodes())
# Filtered level calculation
level = tree.level("node", filter=lambda n: n.tag != "skip")
r )rE rsearch)r# r1 r[ ns r$ rY z
Tree.level s- > t||C 89!A9:Q>>9s -c B | j | st d|z | j |k( r t d | | | j | j
}| | j
| j
D ]+ }| | j |j | j
- | | j
| j
xs g D ] }|j || j
! |j ||j | j
| j |= y)a
Remove a node while preserving connections between its parent and children.
Deletes the specified node but maintains the tree structure by directly
connecting the node's parent to all of its children. This operation
effectively "links past" the node, removing it from the hierarchy
without breaking the tree connections.
Args:
nid: Identifier of the node to link past and remove.
Raises:
NodeIDAbsentError: If nid doesn't exist in the tree.
LinkPastRootNodeError: If attempting to link past the root node.
Example:
Linking past nodes::
# Before: Root -> Manager -> Employee1, Employee2
tree.link_past_node("Manager")
# After: Root -> Employee1, Employee2
# Useful for flattening hierarchies
middle_managers = ["mgr1", "mgr2", "mgr3"]
for mgr in middle_managers:
if tree.contains(mgr):
tree.link_past_node(mgr)
# Cannot link past root
try:
tree.link_past_node(tree.root)
except LinkPastRootNodeError:
print("Cannot link past root node")
rA z#Y))$*:*:; ME K ' '(9(94;K;K L M 9''(8(89?R DC $ $S$2B2B $ C D 6==$BRBR S KK r& c | j | r| j | st | j || rt | | j | j
}| j
||| j j | j
||| j j | j || y)a
Move a node from its current parent to a new parent.
Changes the parent-child relationship by moving the source node
(and its entire subtree) from its current parent to the specified
destination parent. This operation preserves the subtree structure
while reorganizing the tree hierarchy.
Args:
source: Identifier of the node to move.
destination: Identifier of the new parent node.
Raises:
NodeIDAbsentError: If source or destination node doesn't exist.
LoopError: If moving would create a circular reference
(destination is a descendant of source).
Example:
Reorganizing tree structure::
# Move employee between departments
tree.move_node("employee123", "sales_dept")
# Move entire department
tree.move_node("engineering_dept", "new_division")
# Prevent circular moves (this would raise LoopError)
try:
tree.move_node("parent", "child_of_parent")
except LoopError:
print("Cannot create circular reference")
# Bulk reorganization
employees = ["emp1", "emp2", "emp3"]
for emp in employees:
tree.move_node(emp, "new_manager")
N) r r is_ancestorr r r) r r, r r r )r# source destinationr s r$ move_nodezTree.move_node! s L }}V$DMM+,F# #
fk
2Of ))$*:*:; vvt/E/EF {FDOO4G4GH v{3r& c | | j | j }|}|E||k( ry| | j | j }| | j | j }|Ey)a
Check if one node is an ancestor of another node.
Determines whether the ancestor node appears in the path from
the grandchild node to the root. An ancestor is any node that
appears above another node in the tree hierarchy.
Args:
ancestor: Identifier of the potential ancestor node.
grandchild: Identifier of the potential descendant node.
Returns:
bool: True if ancestor is indeed an ancestor of grandchild,
False otherwise.
Example:
Checking ancestry relationships::
# Direct parent-child
is_parent = tree.is_ancestor("parent", "child") # True
# Multi-level ancestry
is_grandparent = tree.is_ancestor("grandparent", "grandchild") # True
# Not related
is_ancestor = tree.is_ancestor("sibling1", "sibling2") # False
# Prevent circular moves
if not tree.is_ancestor("node_to_move", "new_parent"):
tree.move_node("node_to_move", "new_parent")
else:
print("Cannot create circular reference")
TF)r r) )r# r
grandchildr r s r$ r zTree.is_ancestorQ sw D j!--d.>.>? ! U //0@0@A e001A1AB r& c | j S )a
Get the internal dictionary mapping node identifiers to Node objects.
Returns the underlying dictionary that stores all nodes in the tree,
mapping from node identifiers to Node instances. Useful for direct
access to the node collection and bulk operations.
Returns:
dict[str, Node]: Dictionary mapping node IDs to Node objects.
Example:
Working with the nodes dictionary::
# Get all node identifiers
all_ids = list(tree.nodes.keys())
# Get all node objects
all_nodes = list(tree.nodes.values())
# Direct access to nodes dict
nodes_dict = tree.nodes
for node_id, node in nodes_dict.items():
print(f"ID: {node_id}, Tag: {node.tag}")
# Bulk operations
total_nodes = len(tree.nodes)
has_node = "some_id" in tree.nodes
r r: s r$ r! z
Tree.nodes} s < {{r& c | j | st d|z | | j | j }|| j | sy| | S )a,
Get the parent Node object of the specified node.
Returns the immediate parent of the given node, or None if the node
is the root or has no parent. Provides object-based access to the
parent, unlike ancestor() which returns identifiers.
Args:
nid: Identifier of the node whose parent to retrieve.
Returns:
Node or None: Parent Node object, or None if node is root.
Raises:
NodeIDAbsentError: If nid doesn't exist in the tree.
Example:
Working with parent relationships::
# Get parent node
parent_node = tree.parent("child_id")
if parent_node:
print(f"Parent: {parent_node.tag}")
else:
print("Node is root or orphaned")
# Navigate up the hierarchy
current = "leaf_node"
while tree.parent(current):
current = tree.parent(current).identifier
print(f"Ancestor: {tree[current].tag}")
# Check parent properties
parent = tree.parent("employee")
if parent and hasattr(parent.data, 'department'):
print(f"Department: {parent.data.department}")
rA N)r r r r) )r# r1 r s r$ r z Tree.parent sY L }}S!#$BS$HI I3i##D$4$45 ;dmmC 0Cyr& c D |j y|D| j -||j }| j | |j }n t d |j |j D ]/ }| j ||j |j | 1 y)u Patch @new_tree on current tree by pasting new_tree root children on current tree @nid node.
Consider the following tree:
>>> current.show()
root
├── A
└── B
>>> new_tree.show()
root2
├── C
└── D
└── D1
Merging new_tree on B node:
>>>current.merge('B', new_tree)
>>>current.show()
root
├── A
└── B
├── C
└── D
└── D1
Note: if current tree is empty and nid is None, the new_tree root will be used as root on current tree. In all
other cases new_tree root is not pasted.
Nz1Must define "nid" under which new tree is merged.)r1 new_treer' )r. r r r pastesubtreer )r# r1 r r'
new_tree_rootr s r$ mergez
Tree.merge s 4 == ;yy ( 7
m, mm !TUU &&x}}5 XE JJ3)9)9%:J:J)KRVJ W Xr& c t |t sJ |j y| t d | j | st d|z t
|j t
| j z }|r%t dt t t | z t |j D ]X \ }}|rt || }| j j ||i |j |j | j" Z | j% |j | | j' ||j | j( j* y)z
Paste a @new_tree to the original one by linking the root
of new tree to given node (nid).
Update: add @deep copy of pasted tree.
Nz1Must define "nid" under which new tree is pasted.rA zDuplicated nodes %s exists.)r r r. r r r setr- r r textr
r! r r r/ r r) r r r, r )r# r1 r r' set_jointcidr2 s r$ r z
Tree.paste s" (D))) == ; PQ Q}}S!#$BS$HI I(3t{{+;; :T#dIBV=W WX X"8>>2 GIC / KK T{ + 3 3T5E5E F G
x}}c2 sHMM4??3F3FGr& c g }| j D ]@ }|j | j |j D cg c] }| c}ddd B |S c c}w )a
Use this function to get the identifiers allowing to go from the root
nodes to each leaf.
:return: a list of list of identifiers, root being not omitted.
For example:
.. code-block:: python
Harry
|___ Bill
|___ Jane
| |___ Diane
| |___ George
| |___ Jill
| |___ Mary
| |___ Mark
Expected result:
.. code-block:: python
[['harry', 'jane', 'diane', 'mary'],
['harry', 'jane', 'mark'],
['harry', 'jane', 'diane', 'george', 'jill'],
['harry', 'bill']]
Nr )r r r r )r# resleafr1 s r$ paths_to_leaveszTree.paths_to_leaves sZ < KKM MD JJt||DOO'DEEddK L M
Fs A
c v | j | st d|z | | j | j }t | j | }|D ]x }|| j k( rd| _ | j |d | | j | j xs g D ]) }| j ||| j j + z | j ||| j j | j |d |D ] }| j j | t | S )zuRemove a node indicated by 'identifier' with all its successors.
Return the number of removed nodes.
rA N)r r r r) r r r. r r r r, r r! r rE )r# r r removedr r s r$ remove_nodezTree.remove_node7 s% }}Z(#$E
$RS Sj!--d.>.>? t''
34 ICdii " "3 -Cy++D,<,<=C
I&&sC 1G1GH
I I
vz4??3I3IJ z40 C JJNN3 7|r& c | j | }||S | j | st d|z ||_ | | j | j
}t
| j | }|D ] }|| j k( rd| _ |j j || j j | i || j t t | j
t t |j || j | j
||k( s|| j! d|j | j# ||| j$ j& |S )a
Get a subtree with ``nid`` being the root. If nid is None, an
empty tree is returned.
For the original tree, this method is similar to
`remove_node(self,nid)`, because given node and its children
are removed from the original tree in both methods.
For the returned value and performance, these two methods are
different:
* `remove_node` returns the number of deleted nodes;
* `remove_subtree` returns a subtree of deleted nodes;
You are always suggested to use `remove_node` if your only to
delete nodes from a tree, as the other one need memory
allocation to store the new tree.
:return: a :class:`Tree` object.
NrA )r8 r r r. r r) r r r- r r r/ r r r reset_pointersr r r, r )r# r1 r str r r s r$ remove_subtreezTree.remove_subtreeR s= ( [[
$ ;I}}S!#$BS$HI I c&&t'7'78t'',- =Cdii II c4;;??3#7 8 9 sG " "4T-=-=#>S"--@X Y sG " "4#3#3 4cz3''bmm< =
vsDOO,B,BC r& c # K |y| j | st d|z |d n|}|}|B || | r| | j |k7 r | | j | j nd}|Ayyw)z
Traverse the tree branch along the branch from nid to its
ancestors (until root).
:param filter: the function of one variable to act on the :class:`Node` object.
NrA c yrz ro r s r$ r z Tree.rsearch.. r r& )r r r. r r) )r# r1 r[ currents r$ r z Tree.rsearch~ s ; }}S!#$BS$HI I&,n.6!d7m$
EIYYRYEYd7m//0@0@A_cG !s A.A31A3filenamerd c P d fd} | j |||||||| |
|
y)z?
Save the tree into file for offline analysis.
c , |j | dz y )N
)rR )rQ fs r$ _write_linez#Tree.save2file.._write_line s
GGD5L !r& c * | t d S )Nab)open)r r r s r$ handlerz Tree.save2file..handler s q$x"67 7r& rT N)rV )
r# r r1 rY rZ r[ r? r\ rs rd r] r r s
` @r$ save2filezTree.save2file s@ " " 8
r& stdoutc d _ fd} j |||||||||
|
| rt j y j S # t $ r t d Y :w xY w)u
Display the tree structure in a beautiful hierarchical format.
This method provides rich visualization options for tree structures, allowing
customization of appearance, content filtering, and display properties. Perfect
for debugging, documentation, and user interfaces.
Args:
nid: Starting node identifier. If None, starts from root.
level: Starting level (0 for root). Mainly for internal use.
idhidden: If True, hide node identifiers in output (cleaner display).
If False, show both tag and identifier as "tag[id]".
filter: Function to selectively display nodes. Takes Node object,
returns bool. Filtered nodes and their subtrees are hidden.
key: Sorting function for nodes at each level. Takes Node object,
returns comparison key. If None and sorting=True, sorts by Node.
reverse: If True, reverse the sorting order at each level.
line_type: Visual style for tree connections. Options:
'ascii' - Simple |-- style
'ascii-ex' - Unicode ├── style (default)
'ascii-exr' - Unicode with rounded corners
'ascii-em' - Double-line Unicode ╠══ style
'ascii-emv' - Mixed vertical Unicode style
'ascii-emh' - Mixed horizontal Unicode style
data_property: If specified, display this property from node.data
instead of node.tag. Useful for rich data objects.
stdout: If True, print to console. If False, return as string.
sorting: If True, sort nodes at each level. If False, preserve
insertion order (key and reverse are ignored).
Returns:
str or None: If stdout=False, returns formatted string.
If stdout=True, prints to console and returns None.
Example:
Different display styles::
tree = Tree()
tree.create_node("Root", "root")
tree.create_node("Child A", "a", parent="root")
tree.create_node("Child B", "b", parent="root")
# Basic display
tree.show()
# Fancy style with IDs
tree.show(idhidden=False, line_type="ascii-em")
# Filtered display (only nodes starting with 'C')
tree.show(filter=lambda x: x.tag.startswith('C'))
# Sorted by tag, reversed
tree.show(key=lambda x: x.tag, reverse=True)
# Show custom data property
tree.show(data_property="name") # If node.data.name exists
# Return as string instead of printing
tree_str = tree.show(stdout=False)
Output styles::
ascii: Root
|-- Child A
|-- Child B
ascii-ex: Root
├── Child A
└── Child B
ascii-em: Root
╠══ Child A
╚══ Child B
Note:
The tree display automatically handles complex hierarchies with proper
indentation and connection lines. Very large trees may be truncated
for performance reasons.
rH c T xj | j d dz z
c_ y rJ rM rP s r$ rR zTree.show..write rS r& rT z
Tree is emptyN)rN rV r print) r# r1 rY rZ r[ r? r\ rs rd r r] rR s ` r$ showz Tree.show s| x 8 #
!
$,, <<
! # / " #s A A%$A%c g }|| j k7 rR| | j | j }| | j | j D cg c]
}||k7 s | | }}|S c c}w )z
Return the siblings of given @nid.
If @nid is root or there are no siblings, an empty list is returned.
)r. r r) r )r# r1 siblingsr r s r$ r! z
Tree.siblings. so $)) s)''(8(89C)-c)=)=d>N>N)O\ASTX[S[Q\H\ ]s
A&A&c & |t | j S t | }t | j D cg c]# }| j |j
|k( s"|% c} S c c}w # t $ r t dt | z w xY w)aH
Get the number of nodes of the whole tree if @level is not
given. Otherwise, the total number of nodes at specific level
is returned.
@param level The level number in the tree. It must be between
[0, tree.depth].
Otherwise, InvalidLevelNumber exception will be raised.
z*level should be an integer instead of '%s') rE r- intr rY r Exception TypeErrortype)r# rY r2 s r$ sizez Tree.size< s =t{{# #
\E
T-?-?-AjTTZZPTP_P_E`diEiDjkkj
\ LtTY{ Z[[
\s" "A/ #A* A*#A/ *A/ /!Bc | j | }||S | j | st d|z ||_ | j | D ] }|j
j
| | j | | i || j t t | j t t |j ||k( s{|| j d|j |S )a}
Return a shallow COPY of subtree with nid being the new root.
If nid is None, return an empty tree.
If you are looking for a deepcopy, please create a new tree
with this shallow copy, e.g.,
.. code-block:: python
new_tree = Tree(t.subtree(t.root), deep=True)
This line creates a deep copy of the entire tree.
NrA )
r8 r r r. r r- r r r/ r r r) r )r# r1 r r node_ns r$ r z Tree.subtreeP s [[
$ ;I}}S!#$BS$HI I&&s+ @F II d6l 5 5tF| D E
vJ % %d30@0@&A4R]]C[ \}6
**4 ? @ r& c N | | }t | D ] \ }}|dk( r| j j | }t |d| || j |< |j | j
O| |j | j
j
|| j j || j
|j | j
D ]! }| | j || j
# | j |k( s|| _ t ||| y)z
Update node's attributes.
:param nid: the identifier of modified node
:param attrs: attribute pairs recognized by Node object
:return: None
r N)r replacer ) r
r- r setattrr r) r r, REPLACEr r r. )r# r1 attrscnattrvalfps r$ update_nodezTree.update_nodeo s #Y"5) 'ID#|# [[__S)L#.#% C >>$"2"23? (8(89:LL !__ 4 4 # $ 0 0 M --(8(89 DBH,,S$2B2BCD 99# #DID#&5 'r& c " | | j n|}| | j }|dg ii}|r| | j || d< | | j r| | j | j
D cg c] }| | } }|d n|}|r| j
|| | D ]6 }
|| d j | j |
j ||| 8 t || d dk( r$|s| | j n|d| | j ii}|S yc c}w )z%Transform the whole tree into a dict.Nr rb c | S r` ro r s r$ r z Tree.to_dict.. s Q r& r with_datar r\ r ) r. rk rb r r r) r r to_dictr rE ) r# r1 r? r r\ r7 ntag tree_dictr r elems r$ r8 z Tree.to_dict s, KdiicCy}}J+, &*3innIdOF # 9 &*3i&:&:4;K;K&LMT!WMEM$'K;cC
sG
4
$
+22LL IDZaLb
9T?:./141:DIMMPTUXPYP^P^G_@` Ms , D r7 r c P t j | j ||| S )a7
Export the tree structure as a JSON string.
Converts the entire tree into a JSON representation that can be easily
saved, transmitted, or reconstructed. Perfect for data persistence,
API responses, and cross-system integration.
Args:
with_data: If True, include node.data in the JSON output.
If False, only include tree structure and tags.
Default False for smaller output size.
sort: If True, sort children at each level by node comparison.
If False, preserve insertion order.
reverse: If True, reverse the sorting order at each level.
Only applies when sort=True.
Returns:
str: JSON string representation of the tree.
Example:
Basic JSON export::
tree = Tree()
tree.create_node("Root", "root")
tree.create_node("Child A", "a", parent="root")
tree.create_node("Child B", "b", parent="root")
# Basic structure only
json_str = tree.to_json()
print(json_str)
# Output: {"Root": {"children": [{"Child A": {}}, {"Child B": {}}]}}
# Include node data
tree.create_node("Data Node", "data", parent="root",
data={"type": "important", "value": 42})
json_with_data = tree.to_json(with_data=True)
print(json_with_data)
# Output includes: "data": {"type": "important", "value": 42}
# Sorted output
sorted_json = tree.to_json(sort=True, reverse=True)
JSON Structure::
The output follows this hierarchical format:
{
"root_tag": {
"children": [
{
"child1_tag": {
"children": [...],
"data": {...} // if with_data=True
}
},
{
"child2_tag": {} // leaf node
}
],
"data": {...} // if with_data=True
}
}
Usage with APIs::
# Save to file
with open('tree.json', 'w') as f:
f.write(tree.to_json(with_data=True))
# Send via HTTP
import requests
response = requests.post('/api/trees',
json={'tree': tree.to_json()})
# Pretty print
import json
formatted = json.dumps(json.loads(tree.to_json()), indent=2)
print(formatted)
Note:
The JSON format preserves the complete tree structure and can be
used to reconstruct equivalent trees. However, complex data objects
in node.data must be JSON-serializable (no functions, custom classes
without __dict__, etc.).
r6 )jsondumpsr8 )r# r7 r r\ s r$ to_jsonz Tree.to_json s# l zz$,,w,WXXr& shapegraphc g g } }| j r| j | j |||| D ] }
| |
j } t | |
j
j
t j ddi } dj | | | }
|j |
| j | D ]> }|j }|dk( rdnd}| j d|z d z j | | @ |d
u}|r&t j t t | d d }n
t }|j |d
z |D ] }
|j d|
z dz t! | dkD r|j d | D ] }|j d|z dz |j d |st# |j% |j' y
)z;Exports the tree in the dot format of the graphviz software)r r[ r? r\ r] "z\"z "{0}" [label="{1}", shape={2}]digraphz->z--z"{0}" z "{1}"NwrK z tree {
rL r })r! r r r r rk translate maketransrq r r codecsr r r rR rE r getvalueclose)r# r r@ rA r[ r? r\ r] r! connectionsr r1 ru statecr edge
is_plain_filer cnss r$ to_graphvizzTree.to_graphviz s { ::%%ZZ &
V 1g((DGKK(223==#u 3NO8??UER U# s+ VA,,C#(I#544D &&4((B'J'J3PS'TUV
V$ !,
Dh /g>A
A #$ %A
GGD1HtO $ % { a
GGDM 'C
GGD3J% & '
!**, r& c p t }||j dkD r t d |r|nd }|r|nd }i }d}|j D ]: \ }}|||}
|
| t d ||v r|| j | 5|g||< < | t d |j | || || |g} t
| dkD rn| j }
|j |
g D ]: } |j | || ||
|| | j | < t
| dkD rn|S )
zA
takes a dict with child:parent, and form a tree
Nr z need to pass in an empty treec | S r` ro r s r$ r z Tree.from_map..A s A r& c y r` ro r s r$ r z Tree.from_map..B r r& z.invalid input, more than 1 child has no parentzcannot find root)rb )r rb ) r r' r itemsr r rE r get) clschild_parent_dictid_func data_funcr0 parent_child_dict root_nodekvr parent_noder s r$ from_mapz
Tree.from_map9 sj
v <499;? <= = $'+!*I %++- /DAqyY . y 4 !QRR))%a(//2,-3%a( / /0 0 GI$6Yy=QR %j1n ))+K*..{B?
$ EN";/"5) ! U#
$ %j1n r& )NFNN)NFFr` )NNNN)F)NNTFF)FTF)NcirclerD NNFT)NN)I__name__
__module__ __qualname____doc__r ranger r r r r r, r boolr% r
r4 r8 propertyr r* rC r# rF rW r r bytesrV rp r r r r r NodeListr r r r r r r r r r r r r rY r r r r! r r r StrLListr r r r r r r! r' r r3 r8 r? rS classmethodrb ro r& r$ r r I s 2j $(a> T5%J/s /t /: $( EO EO
SM EO
EOR %) -b SM-b -b -b^ HSM 2#8C= #T #( Js Jt JD 4" " L " 3704 (-H>
c]H> H> H>
4&$,/0 H> hvt|,
-
H> H> H> w}%H>TS
c]S S (D64<01 S
hvt|,
- S
S S S8)
c]) ) 4&$,' )
hvt|,
- )
) ) ) V?RS RC Rs R 7>T 7>8E$)4D+E 7>QU 7>r*8 *8$s $8;z"6C "6H "6H 5B "$(-1 3
c]3 SM3 tSy)* 3
3
3j1(4. 1C 1j "3704 NV
c]NV NV 4&$,/0 NV
hvt|,
- NV
NV NV`&24&$,!7 &2P% HSM % htn % N*X*(3- *8 *X ?B1 # 1 f.4`*X >-# -(4. -^%X %Xd %XN H Hd H># #J c c 6*# *8C= *Xd3 d4&$,1G(H d2 " 3704 #'+ "
"
c]"
"
"
4&$,/0
"
hvt|,
-"
"
"
}"
"
L " 3704 #'+ t
c]t t t
4&$,/0 t hvt|,
-
t t t }t t t l C H \(3- \3 \( 3 HSM >#'s #' #'J .VY VYT VY4 VYt #' 43-4 4 4 4 4l $ $r& r ),rg
__future__r r builtinsr r ImportError __builtin__rJ r= sysr< copyr typingr r r r
r r sixr
r r io
exceptionsr r r r r r r2 r version_infor StrListrm rl
__author__objectr ro r& r$ r} s ( 8($
= = 6 ! v 3iGDIHDzH3iGDIHDzH
T 6 T T S ('( s# B$ B5 $ B21B25 CC