🔍 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 | DAGNodeT, condition: Callable[[T | DAGNodeT], bool]) → T | DAGNodeT¶

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/DAGNode) – tree to search for its child
condition (Callable) – function that takes in node as argument, returns node if condition evaluates to True

Returns:

(BaseNode/DAGNode)

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

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/DAGNode) – tree to search, parent node
name (str) – value to match for name attribute, child node

Returns:

(Node/DAGNode)

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

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/DAGNode) – 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/DAGNode)

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, …])