ClusterShell message tree module. The purpose of MsgTree is to provide a shared message tree for storing message lines received from ClusterShell Workers (for example, from remote cluster commands). It should be efficient, in term of algorithm and memory consumption, especially when remote messages are the same.

class ClusterShell.MsgTree.MsgTree(mode=0)

MsgTree maps key objects to multi-lines messages.

MsgTree is a mutable object. Keys are almost arbitrary values (must be hashable). Message lines are organized as a tree internally. MsgTree provides low memory consumption especially on a cluster when all nodes return similar messages. Also, the gathering of messages is done automatically.


Return the message of MsgTree with specified key. Raises a KeyError if key is not in the MsgTree.


MsgTree initializer

The mode parameter should be set to one of the following constant:

MODE_DEFER: all messages are processed immediately, saving memory from duplicate message lines, but keys are associated to tree elements usually later when tree is first "walked", saving useless state updates and CPU time. Once the tree is "walked" for the first time, its mode changes to MODE_SHIFT to keep track of further tree updates. This is the default mode.

MODE_SHIFT: all keys and messages are processed immediately, it is more CPU time consuming as MsgTree full state is updated at each add() call.

MODE_TRACE: all keys and messages and processed immediately, and keys are kept for each message element of the tree. The special method walk_trace() is then available to walk all elements of the tree.


Return an iterator over MsgTree's keys.


Return the number of keys contained in the MsgTree.


list of weak references to the object (if defined)

add(key, msgline)

Add a message line (in bytes) associated with the given key to the MsgTree.


Remove all items from the MsgTree.

get(key, default=None)

Return the message for key if key is in the MsgTree, else default. If default is not given, it defaults to None, so that this method never raises a KeyError.

items(match=None, mapper=None)

Return (key, message) for each key of the MsgTree.


Return an iterator over MsgTree's keys.


Return an iterator over MsgTree's messages.


Modify the tree by removing any matching key references from the messages tree.

Example of use:
>>> msgtree.remove(lambda k: k > 3)
walk(match=None, mapper=None)

Walk the tree. Optionally filter keys on match parameter, and optionally map resulting keys with mapper function. Return an iterator over (message, keys) tuples for each different message in the tree.

walk_trace(match=None, mapper=None)

Walk the tree in trace mode. Optionally filter keys on match parameter, and optionally map resulting keys with mapper function. Return an iterator over 4-length tuples (msgline, keys, depth, num_children).