🔍 Search

Search methods for Trees.

Tree Search Methods

Search by	One node	One or more nodes
General method	find, find_child	findall, find_children
Node name	find_name, find_child_by_name	find_names
Node path	find_path, find_full_path, find_relative_path	find_paths, find_relative_path
Node attributes	find_attr	find_attrs

Functions:

find(tree, condition[, max_depth])	Search tree for single node matching condition (callable function).
find_attr(tree, attr_name, attr_value[, ...])	Search tree for single node matching custom attribute.
find_attrs(tree, attr_name, attr_value[, ...])	Search tree for node(s) matching custom attribute.
find_child(tree, condition)	Search children for single node matching condition (callable function).
find_child_by_name(tree, name)	Search tree for single node matching name attribute.
find_children(tree, condition[, min_count, ...])	Search children for nodes matching condition (callable function).
find_full_path(tree, path_name)	Search tree for single node matching path attribute.
find_name(tree, name[, max_depth])	Search tree for single node matching name attribute.
find_names(tree, name[, max_depth])	Search tree for multiple node(s) matching name attribute.
find_path(tree, path_name)	Search tree for single node matching path attribute.
find_paths(tree, path_name)	Search tree for multiple nodes matching path attribute.
find_relative_path(tree, path_name)	Search tree for single node matching relative path attribute.
findall(tree, condition[, max_depth, ...])	Search tree for nodes matching condition (callable function).

bigtree.tree.search.find(tree: T, condition: Callable[[T], bool], max_depth: int = 0) → T

Search tree for single node matching condition (callable function).

>>> from bigtree import Node, find
>>> root = Node("a", age=90)
>>> b = Node("b", age=65, parent=root)
>>> c = Node("c", age=60, parent=root)
>>> d = Node("d", age=40, parent=c)
>>> find(root, lambda node: node.age == 65)
Node(/a/b, age=65)
>>> find(root, lambda node: node.age > 5)
Traceback (most recent call last):
    ...
bigtree.utils.exceptions.SearchError: Expected less than 1 element(s), found 4 elements
(Node(/a, age=90), Node(/a/b, age=65), Node(/a/c, age=60), Node(/a/c/d, age=40))

Parameters:

• tree (BaseNode) – tree to search

• condition (Callable) – function that takes in node as argument, returns node if condition evaluates to True

• max_depth (int) – maximum depth to search for, based on the depth attribute, defaults to None

Returns:

(BaseNode)

bigtree.tree.search.find_attr(tree: BaseNode, attr_name: str, attr_value: Any, max_depth: int = 0) → BaseNode

Search tree for single node matching custom attribute.

>>> from bigtree import Node, find_attr
>>> root = Node("a", age=90)
>>> b = Node("b", age=65, parent=root)
>>> c = Node("c", age=60, parent=root)
>>> d = Node("d", age=40, parent=c)
>>> find_attr(root, "age", 65)
Node(/a/b, age=65)

Parameters:

• tree (BaseNode) – tree to search

• attr_name (str) – attribute name to perform matching

• attr_value (Any) – value to match for attr_name attribute

• max_depth (int) – maximum depth to search for, based on the depth attribute, defaults to None

Returns:

(BaseNode)

bigtree.tree.search.find_attrs(tree: BaseNode, attr_name: str, attr_value: Any, max_depth: int = 0) → Tuple[BaseNode, ...]

Search tree for node(s) matching custom attribute.

>>> from bigtree import Node, find_attrs
>>> root = Node("a", age=90)
>>> b = Node("b", age=65, parent=root)
>>> c = Node("c", age=65, parent=root)
>>> d = Node("d", age=40, parent=c)
>>> find_attrs(root, "age", 65)
(Node(/a/b, age=65), Node(/a/c, age=65))

Parameters:

• tree (BaseNode) – tree to search

• attr_name (str) – attribute name to perform matching

• attr_value (Any) – value to match for attr_name attribute

• max_depth (int) – maximum depth to search for, based on the depth attribute, defaults to None

Returns:

(Tuple[BaseNode, …])

bigtree.tree.search.find_child(tree: T, condition: Callable[[T], bool]) → T

Search children for single node matching condition (callable function).

>>> from bigtree import Node, find_child
>>> root = Node("a", age=90)
>>> b = Node("b", age=65, parent=root)
>>> c = Node("c", age=60, parent=root)
>>> d = Node("d", age=40, parent=c)
>>> find_child(root, lambda node: node.age > 62)
Node(/a/b, age=65)

Parameters:

• tree (BaseNode) – tree to search for its child

• condition (Callable) – function that takes in node as argument, returns node if condition evaluates to True

Returns:

(BaseNode)

bigtree.tree.search.find_child_by_name(tree: NodeT, name: str) → NodeT

Search tree for single node matching name attribute.

>>> from bigtree import Node, find_child_by_name
>>> root = Node("a", age=90)
>>> b = Node("b", age=65, parent=root)
>>> c = Node("c", age=60, parent=root)
>>> d = Node("d", age=40, parent=c)
>>> find_child_by_name(root, "c")
Node(/a/c, age=60)
>>> find_child_by_name(c, "d")
Node(/a/c/d, age=40)

Parameters:

• tree (Node) – tree to search, parent node

• name (str) – value to match for name attribute, child node

Returns:

(Node)

bigtree.tree.search.find_children(tree: T, condition: Callable[[T], bool], min_count: int = 0, max_count: int = 0) → Tuple[T, ...]

Search children for nodes matching condition (callable function).

>>> from bigtree import Node, find_children
>>> root = Node("a", age=90)
>>> b = Node("b", age=65, parent=root)
>>> c = Node("c", age=60, parent=root)
>>> d = Node("d", age=40, parent=c)
>>> find_children(root, lambda node: node.age > 30)
(Node(/a/b, age=65), Node(/a/c, age=60))

Parameters:

• tree (BaseNode) – tree to search for its children

• condition (Callable) – function that takes in node as argument, returns node if condition evaluates to True

• min_count (int) – checks for minimum number of occurrences, raise SearchError if the number of results do not meet min_count, defaults to None

• max_count (int) – checks for maximum number of occurrences, raise SearchError if the number of results do not meet min_count, defaults to None

Returns:

(BaseNode)

bigtree.tree.search.find_full_path(tree: NodeT, path_name: str) → NodeT

Search tree for single node matching path attribute.

• Path name can be with or without leading tree path separator symbol.

• Path name must be full path, works similar to find_path but faster.

>>> from bigtree import Node, find_full_path
>>> root = Node("a", age=90)
>>> b = Node("b", age=65, parent=root)
>>> c = Node("c", age=60, parent=root)
>>> d = Node("d", age=40, parent=c)
>>> find_full_path(root, "/a/c/d")
Node(/a/c/d, age=40)

Parameters:

• tree (Node) – tree to search

• path_name (str) – value to match (full path) of path_name attribute

Returns:

(Node)

bigtree.tree.search.find_name(tree: NodeT, name: str, max_depth: int = 0) → NodeT

Search tree for single node matching name attribute.

>>> from bigtree import Node, find_name
>>> root = Node("a", age=90)
>>> b = Node("b", age=65, parent=root)
>>> c = Node("c", age=60, parent=root)
>>> d = Node("d", age=40, parent=c)
>>> find_name(root, "c")
Node(/a/c, age=60)

Parameters:

• tree (Node) – tree to search

• name (str) – value to match for name attribute

• max_depth (int) – maximum depth to search for, based on the depth attribute, defaults to None

Returns:

(Node)

bigtree.tree.search.find_names(tree: NodeT, name: str, max_depth: int = 0) → Iterable[NodeT]

Search tree for multiple node(s) matching name attribute.

>>> from bigtree import Node, find_names
>>> root = Node("a", age=90)
>>> b = Node("b", age=65, parent=root)
>>> c = Node("c", age=60, parent=root)
>>> d = Node("b", age=40, parent=c)
>>> find_names(root, "c")
(Node(/a/c, age=60),)
>>> find_names(root, "b")
(Node(/a/b, age=65), Node(/a/c/b, age=40))

Parameters:

• tree (Node) – tree to search

• name (str) – value to match for name attribute

• max_depth (int) – maximum depth to search for, based on the depth attribute, defaults to None

Returns:

(Iterable[Node])

bigtree.tree.search.find_path(tree: NodeT, path_name: str) → NodeT

Search tree for single node matching path attribute.

• Path name can be with or without leading tree path separator symbol.

• Path name can be full path or partial path (trailing part of path) or node name.

>>> from bigtree import Node, find_path
>>> root = Node("a", age=90)
>>> b = Node("b", age=65, parent=root)
>>> c = Node("c", age=60, parent=root)
>>> d = Node("d", age=40, parent=c)
>>> find_path(root, "c")
Node(/a/c, age=60)
>>> find_path(root, "/c")
Node(/a/c, age=60)

Parameters:

• tree (Node) – tree to search

• path_name (str) – value to match (full path) or trailing part (partial path) of path_name attribute

Returns:

(Node)

bigtree.tree.search.find_paths(tree: NodeT, path_name: str) → Tuple[NodeT, ...]

Search tree for multiple nodes matching path attribute.

• Path name can be with or without leading tree path separator symbol.

• Path name can be partial path (trailing part of path) or node name.

>>> from bigtree import Node, find_paths
>>> root = Node("a", age=90)
>>> b = Node("b", age=65, parent=root)
>>> c = Node("c", age=60, parent=root)
>>> d = Node("c", age=40, parent=c)
>>> find_paths(root, "/a/c")
(Node(/a/c, age=60),)
>>> find_paths(root, "/c")
(Node(/a/c, age=60), Node(/a/c/c, age=40))

Parameters:

• tree (Node) – tree to search

• path_name (str) – value to match (full path) or trailing part (partial path) of path_name attribute

Returns:

(Tuple[Node, …])

bigtree.tree.search.find_relative_path(tree: NodeT, path_name: str) → Iterable[NodeT]

Search tree for single node matching relative path attribute.

• Supports unix folder expression for relative path, i.e., ‘../../node_name’

• Supports wildcards, i.e., ‘*/node_name’

• If path name starts with leading separator symbol, it will start at root node.

>>> from bigtree import Node, find_relative_path
>>> root = Node("a", age=90)
>>> b = Node("b", age=65, parent=root)
>>> c = Node("c", age=60, parent=root)
>>> d = Node("d", age=40, parent=c)
>>> find_relative_path(d, "..")
(Node(/a/c, age=60),)
>>> find_relative_path(d, "../../b")
(Node(/a/b, age=65),)
>>> find_relative_path(d, "../../*")
(Node(/a/b, age=65), Node(/a/c, age=60))

Parameters:

• tree (Node) – tree to search

• path_name (str) – value to match (relative path) of path_name attribute

Returns:

(Iterable[Node])

bigtree.tree.search.findall(tree: T, condition: Callable[[T], bool], max_depth: int = 0, min_count: int = 0, max_count: int = 0) → Tuple[T, ...]

Search tree for nodes matching condition (callable function).

>>> from bigtree import Node, findall
>>> root = Node("a", age=90)
>>> b = Node("b", age=65, parent=root)
>>> c = Node("c", age=60, parent=root)
>>> d = Node("d", age=40, parent=c)
>>> findall(root, lambda node: node.age > 62)
(Node(/a, age=90), Node(/a/b, age=65))

Parameters:

• tree (BaseNode) – tree to search

• condition (Callable) – function that takes in node as argument, returns node if condition evaluates to True

• max_depth (int) – maximum depth to search for, based on the depth attribute, defaults to None

• min_count (int) – checks for minimum number of occurrences, raise SearchError if the number of results do not meet min_count, defaults to None

• max_count (int) – checks for maximum number of occurrences, raise SearchError if the number of results do not meet min_count, defaults to None

Returns:

(Tuple[BaseNode, …])