Documentation

Although thedocumentation claims thatast.walk generates nodes "in no specified order" and even describes its behavior as "Recursively yield all descendant nodes...", a look at thesource code reveals that it really performs a breadth-first traversal by iteratively yielding child nodes in a queue:

defwalk(node):"""    Recursively yield all descendant nodes in the tree starting at *node*    (including *node* itself), in no specified order.  This is useful if you    only want to modify nodes in place and don't care about the context.    """fromcollectionsimportdequetodo=deque([node])whiletodo:node=todo.popleft()todo.extend(iter_child_nodes(node))yieldnode

I thought that maybe this function used to be recursive but found that it has not been modified since its first appearance in CPython 2.6.3.

I think we should at the minimum remove the wording "Recursively" from the description, and optionally:

1. Clarify the actual ordering by changing "in no specified order" to "in breadth-first order".
2. Add a keyword argument such asdepth_first that defaults toFalse such that when it is true, switches to a depth-first traversal that behaves like:

defdfs_walk(node):yieldnodeforchildinast.iter_child_nodes(node):yieldfromdfs_walk(child)