Skip to content

textual.walk

Functions for walking the DOM.

Note

For most purposes you would be better off using query, which uses these functions internally.

walk_breadth_first

walk_breadth_first(
    root: DOMNode, *, with_root: bool = True
) -> Iterable[DOMNode]
walk_breadth_first(
    root: WalkType,
    filter_type: type[WalkType],
    *,
    with_root: bool = True
) -> Iterable[WalkType]
walk_breadth_first(
    root, filter_type=None, *, with_root=True
)

Walk the tree breadth first (children first).

Note

Avoid changing the DOM (mounting, removing etc.) while iterating with this function. Consider walk_children which doesn't have this limitation.

Parameters:

Name Type Description Default

root

DOMNode

The root note (starting point).

required

filter_type

type[WalkType] | None

Optional DOMNode subclass to filter by, or None for no filter.

None

with_root

bool

Include the root in the walk.

True

Returns:

Type Description
Iterable[DOMNode] | Iterable[WalkType]

An iterable of DOMNodes, or the type specified in filter_type.

walk_breadth_search_id

walk_breadth_search_id(root, node_id, *, with_root=True)

Special case to walk breadth first searching for a node with a given id.

This is more efficient than walk_breadth_first for this special case, as it can use an index.

Parameters:

Name Type Description Default

root

DOMNode

The root node (starting point).

required

node_id

str

Node id to search for.

required

with_root

bool

Consider the root node? If the root has the node id, then return it.

True

Returns:

Type Description
DOMNode | None

A DOMNode if a node was found, otherwise None.

walk_depth_first

walk_depth_first(
    root: DOMNode, *, with_root: bool = True
) -> Iterable[DOMNode]
walk_depth_first(
    root: WalkType,
    filter_type: type[WalkType],
    *,
    with_root: bool = True
) -> Iterable[WalkType]
walk_depth_first(root, filter_type=None, *, with_root=True)

Walk the tree depth first (parents first).

Note

Avoid changing the DOM (mounting, removing etc.) while iterating with this function. Consider walk_children which doesn't have this limitation.

Parameters:

Name Type Description Default

root

DOMNode

The root note (starting point).

required

filter_type

type[WalkType] | None

Optional DOMNode subclass to filter by, or None for no filter.

None

with_root

bool

Include the root in the walk.

True

Returns:

Type Description
Iterable[DOMNode] | Iterable[WalkType]

An iterable of DOMNodes, or the type specified in filter_type.