It turns out that we do need a visitor approach to complement the simple walk() function.

@laserkelvin, I've been working on this recently and I have what I think is quite an elegant solution. But there's an open design question that I'd like your feedback on before I finalize the implementation and open a pull request.

The basic idea is to have a visit function that accepts any callable, and then invoke that callable on every node in the tree. For very simple cases the callable can be a lambda or a function, and for more complicated cases (that require state) you can use an object.

For example, the following could be used to count all the nodes in the tree:

class NodeCounter:

  def __init__(self):
    self.count = 0

  def __call__(self, node):
    self.count += 1
    return True # see below

visitor = NodeCounter()
tree.visit(visitor)
print(visitor.count)

The return True is the bit I'm unsure about. What it currently means is "visit the children of this node", but it doesn't feel obvious and I can imagine people wanting slightly different use-cases (e.g., "don't visit any more nodes at all", "skip the children of this node", "return to the parent of this node", etc).

My proposal is to change the return handling such that:

• None (or no return statement at all) => Visit the next node.
• Visit.NEXT => Same as above.
• Visit.NEXT_SIBLING => Don't process this node's children, and skip to its next sibling.

None or Visit.NEXT would be equivalent to returning True in the current implementation, while Visit.NEXT_SIBLING would be equivalent to returning False in the current implementation. I think that explicit values would be more readable, and we can extend things later if we decide we need to support more patterns.

What do you think?