🔍 Search

Search methods for Trees.

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_paths`
Node attributes	`find_attr`	`find_attrs`

bigtree.tree.search

findall

findall(
    tree, condition, max_depth=0, min_count=0, max_count=0
)

Search tree for one or more nodes matching condition (callable function).

Examples:

>>> from bigtree import Tree
>>> path_dict = {
...     "a": {"age": 90},
...     "a/b": {"age": 65},
...     "a/c": {"age": 60},
...     "a/c/d": {"age": 40},
... }
>>> tree = Tree.from_dict(path_dict)
>>> tree.findall(lambda node: node.age > 62)
(Node(/a, age=90), Node(/a/b, age=65))

Parameters:

Name	Type	Description	Default
`tree`	`T`	tree to search	required
`condition`	`Callable[[T], bool]`	function that takes in node as argument, returns node if condition evaluates to `True`	required
`max_depth`	`int`	maximum depth to search for, based on the `depth` attribute	`0`
`min_count`	`int`	checks for minimum number of occurrences, raise exceptions.SearchError if the number of results do not meet min_count	`0`
`max_count`	`int`	checks for maximum number of occurrences, raise exceptions.SearchError if the number of results do not meet min_count	`0`

Returns:

Type	Description
`tuple[T, ...]`	Search results

find

find(tree, condition, max_depth=0)

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

Examples:

>>> from bigtree import Tree
>>> path_dict = {
...     "a": {"age": 90},
...     "a/b": {"age": 65},
...     "a/c": {"age": 60},
...     "a/c/d": {"age": 40},
... }
>>> tree = Tree.from_dict(path_dict)
>>> tree.find(lambda node: node.age == 65)
Node(/a/b, age=65)
>>> tree.find(lambda node: node.age > 5)
Traceback (most recent call last):
    ...
bigtree.utils.exceptions.exceptions.SearchError: Expected less than or equal to 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:

Name	Type	Description	Default
`tree`	`T`	tree to search	required
`condition`	`Callable[[T], bool]`	function that takes in node as argument, returns node if condition evaluates to `True`	required
`max_depth`	`int`	maximum depth to search for, based on the `depth` attribute	`0`

Returns:

Type	Description
`T`	Search result

find_name

find_name(tree, name, max_depth=0)

Search tree for a single node matching name attribute.

Examples:

>>> from bigtree import Tree
>>> path_dict = {
...     "a": {"age": 90},
...     "a/b": {"age": 65},
...     "a/c": {"age": 60},
...     "a/c/d": {"age": 40},
... }
>>> tree = Tree.from_dict(path_dict)
>>> tree.find_name("c")
Node(/a/c, age=60)

Parameters:

Name	Type	Description	Default
`tree`	`NodeT`	tree to search	required
`name`	`str`	value to match for name attribute	required
`max_depth`	`int`	maximum depth to search for, based on the `depth` attribute	`0`

Returns:

Type	Description
`NodeT`	Search result

find_names

find_names(tree, name, max_depth=0)

Search tree for one or more nodes matching name attribute.

Examples:

>>> from bigtree import Tree
>>> path_dict = {
...     "a": {"age": 90},
...     "a/b": {"age": 65},
...     "a/c": {"age": 60},
...     "a/c/b": {"age": 40},
... }
>>> tree = Tree.from_dict(path_dict)
>>> tree.find_names("c")
(Node(/a/c, age=60),)
>>> tree.find_names("b")
(Node(/a/b, age=65), Node(/a/c/b, age=40))

Parameters:

Name	Type	Description	Default
`tree`	`NodeT`	tree to search	required
`name`	`str`	value to match for name attribute	required
`max_depth`	`int`	maximum depth to search for, based on the `depth` attribute	`0`

Returns:

Type	Description
`Iterable[NodeT]`	Search results

find_relative_path

find_relative_path(tree, path_name)

Search tree for a 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

Examples:

>>> 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, "../../*")
Traceback (most recent call last):
    ...
bigtree.utils.exceptions.exceptions.SearchError: Expected less than or equal to 1 element(s), found 2 elements
(Node(/a/b, age=65), Node(/a/c, age=60))

Parameters:

Name	Type	Description	Default
`tree`	`NodeT`	tree to search	required
`path_name`	`str`	value to match (relative path) of path_name attribute	required

Returns:

Type	Description
`NodeT`	Search result

find_relative_paths

find_relative_paths(
    tree, path_name, min_count=0, max_count=0
)

Search tree for one or more nodes 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

Examples:

>>> from bigtree import Node, find_relative_paths
>>> 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_paths(d, "..")
(Node(/a/c, age=60),)
>>> find_relative_paths(d, "../../b")
(Node(/a/b, age=65),)
>>> find_relative_paths(d, "../../*")
(Node(/a/b, age=65), Node(/a/c, age=60))

Parameters:

Name	Type	Description	Default
`tree`	`NodeT`	tree to search	required
`path_name`	`str`	value to match (relative path) of path_name attribute	required
`min_count`	`int`	checks for minimum number of occurrences, raise exceptions.SearchError if the number of results do not meet min_count	`0`
`max_count`	`int`	checks for maximum number of occurrences, raise exceptions.SearchError if the number of results do not meet min_count	`0`

Returns:

Type	Description
`tuple[NodeT, ...]`	Search results

find_full_path

find_full_path(tree, path_name)

Search tree for a 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

Examples:

>>> from bigtree import Tree
>>> path_dict = {
...     "a": {"age": 90},
...     "a/b": {"age": 65},
...     "a/c": {"age": 60},
...     "a/c/d": {"age": 40},
... }
>>> tree = Tree.from_dict(path_dict)
>>> tree.find_full_path("/a/c/d")
Node(/a/c/d, age=40)

Parameters:

Name	Type	Description	Default
`tree`	`NodeT`	tree to search	required
`path_name`	`str`	value to match (full path) of path_name attribute	required

Returns:

Type	Description
`NodeT`	Search result

find_path

find_path(tree, path_name)

Search tree for a 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

Examples:

>>> from bigtree import Tree
>>> path_dict = {
...     "a": {"age": 90},
...     "a/b": {"age": 65},
...     "a/c": {"age": 60},
...     "a/c/d": {"age": 40},
... }
>>> tree = Tree.from_dict(path_dict)
>>> tree.find_path("c")
Node(/a/c, age=60)
>>> tree.find_path("/c")
Node(/a/c, age=60)

Parameters:

Name	Type	Description	Default
`tree`	`NodeT`	tree to search	required
`path_name`	`str`	value to match (full path) or trailing part (partial path) of path_name attribute	required

Returns:

Type	Description
`NodeT`	Search result

find_paths

find_paths(tree, path_name)

Search tree for one or more 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

Examples:

>>> from bigtree import Tree
>>> path_dict = {
...     "a": {"age": 90},
...     "a/b": {"age": 65},
...     "a/c": {"age": 60},
...     "a/c/c": {"age": 40},
... }
>>> tree = Tree.from_dict(path_dict)
>>> tree.find_paths("/a/c")
(Node(/a/c, age=60),)
>>> tree.find_paths("/c")
(Node(/a/c, age=60), Node(/a/c/c, age=40))

Parameters:

Name	Type	Description	Default
`tree`	`NodeT`	tree to search	required
`path_name`	`str`	value to match (full path) or trailing part (partial path) of path_name attribute	required

Returns:

Type	Description
`Iterable[NodeT]`	Search results

find_attr

find_attr(tree, attr_name, attr_value, max_depth=0)

Search tree for a single node matching custom attribute.

Examples:

>>> from bigtree import Tree
>>> path_dict = {
...     "a": {"age": 90},
...     "a/b": {"age": 65},
...     "a/c": {"age": 60},
...     "a/c/d": {"age": 40},
... }
>>> tree = Tree.from_dict(path_dict)
>>> tree.find_attr("age", 65)
Node(/a/b, age=65)

Parameters:

Name	Type	Description	Default
`tree`	`BaseNode`	tree to search	required
`attr_name`	`str`	attribute name to perform matching	required
`attr_value`	`Any`	value to match for attr_name attribute	required
`max_depth`	`int`	maximum depth to search for, based on the `depth` attribute	`0`

Returns:

Type	Description
`BaseNode`	Search result

find_attrs

find_attrs(tree, attr_name, attr_value, max_depth=0)

Search tree for one or more nodes matching custom attribute.

Examples:

>>> from bigtree import Tree
>>> path_dict = {
...     "a": {"age": 90},
...     "a/b": {"age": 65},
...     "a/c": {"age": 65},
...     "a/c/d": {"age": 40},
... }
>>> tree = Tree.from_dict(path_dict)
>>> tree.find_attrs("age", 65)
(Node(/a/b, age=65), Node(/a/c, age=65))

Parameters:

Name	Type	Description	Default
`tree`	`BaseNode`	tree to search	required
`attr_name`	`str`	attribute name to perform matching	required
`attr_value`	`Any`	value to match for attr_name attribute	required
`max_depth`	`int`	maximum depth to search for, based on the `depth` attribute	`0`

Returns:

Type	Description
`Iterable[BaseNode]`	Search results

find_children

find_children(tree, condition, min_count=0, max_count=0)

Search children for one or more nodes matching condition (callable function).

Examples:

>>> from bigtree import Node, Tree
>>> path_dict = {
...     "a": {"age": 90},
...     "a/b": {"age": 65},
...     "a/c": {"age": 60},
...     "a/c/d": {"age": 40},
... }
>>> tree = Tree.from_dict(path_dict)
>>> tree.find_children(lambda node: node.age > 30)
(Node(/a/b, age=65), Node(/a/c, age=60))

Parameters:

Name	Type	Description	Default
`tree`	`T \| DAGNodeT`	tree to search for its children	required
`condition`	`Callable[[T \| DAGNodeT], bool]`	function that takes in node as argument, returns node if condition evaluates to `True`	required
`min_count`	`int`	checks for minimum number of occurrences, raise exceptions.SearchError if the number of results do not meet min_count	`0`
`max_count`	`int`	checks for maximum number of occurrences, raise exceptions.SearchError if the number of results do not meet min_count	`0`

Returns:

Type	Description
`tuple[T \| DAGNodeT, ...]`	Search results

find_child

find_child(tree, condition)

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

Examples:

>>> from bigtree import Node, Tree
>>> path_dict = {
...     "a": {"age": 90},
...     "a/b": {"age": 65},
...     "a/c": {"age": 60},
...     "a/c/d": {"age": 40},
... }
>>> tree = Tree.from_dict(path_dict)
>>> tree.find_child(lambda node: node.age > 62)
Node(/a/b, age=65)

Parameters:

Name	Type	Description	Default
`tree`	`T \| DAGNodeT`	tree to search for its child	required
`condition`	`Callable[[T \| DAGNodeT], bool]`	function that takes in node as argument, returns node if condition evaluates to `True`	required

Returns:

Type	Description
`T \| DAGNodeT`	Search result

find_child_by_name

find_child_by_name(tree, name)

Search tree for a single node matching name attribute.

Examples:

>>> from bigtree import Node, Tree
>>> 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)
>>> Tree(root).find_child_by_name("c")
Node(/a/c, age=60)
>>> Tree(c).find_child_by_name("d")
Node(/a/c/d, age=40)

Parameters:

Name	Type	Description	Default
`tree`	`NodeT \| DAGNodeT`	tree to search, parent node	required
`name`	`str`	value to match for name attribute, child node	required

Returns:

Type	Description
`NodeT \| DAGNodeT`	Search result