NodeSet

Cluster node set module.

A module to efficiently deal with node sets and node groups. Instances of NodeSet provide similar operations than the builtin set() type, see http://www.python.org/doc/lib/set-objects.html

Usage example

>>> # Import NodeSet class
... from ClusterShell.NodeSet import NodeSet
>>>
>>> # Create a new nodeset from string
... nodeset = NodeSet("cluster[1-30]")
>>> # Add cluster32 to nodeset
... nodeset.update("cluster32")
>>> # Remove from nodeset
... nodeset.difference_update("cluster[2-5,8-31]")
>>> # Print nodeset as a pdsh-like pattern
... print nodeset
cluster[1,6-7,32]
>>> # Iterate over node names in nodeset
... for node in nodeset:
...     print node
cluster1
cluster6
cluster7
cluster32
class ClusterShell.NodeSet.NodeSet(nodes=None, autostep=None, resolver=None, fold_axis=None)

Iterable class of nodes with node ranges support.

NodeSet creation examples:

>>> nodeset = NodeSet()               # empty NodeSet
>>> nodeset = NodeSet("cluster3")     # contains only cluster3
>>> nodeset = NodeSet("cluster[5,10-42]")
>>> nodeset = NodeSet("cluster[0-10/2]")
>>> nodeset = NodeSet("cluster[0-10/2],othername[7-9,120-300]")

NodeSet provides methods like update(), intersection_update() or difference_update() methods, which conform to the Python Set API. However, unlike RangeSet or standard Set, NodeSet is somewhat not so strict for convenience, and understands NodeSet instance or NodeSet string as argument. Also, there is no strict definition of one element, for example, it IS allowed to do:

>>> nodeset = NodeSet("blue[1-50]")
>>> nodeset.remove("blue[36-40]")
>>> print nodeset
blue[1-35,41-50]

Additionally, the NodeSet class recognizes the “extended string pattern” which adds support for union (special character ”,”), difference (”!”), intersection (“&”) and symmetric difference (“^”) operations. String patterns are read from left to right, by proceeding any character operators accordinately.

Extended string pattern usage examples:

>>> nodeset = NodeSet("node[0-10],node[14-16]") # union
>>> nodeset = NodeSet("node[0-10]!node[8-10]")  # difference
>>> nodeset = NodeSet("node[0-10]&node[5-13]")  # intersection
>>> nodeset = NodeSet("node[0-10]^node[5-13]")  # xor
__and__(other)

Implements the & operator. So s & t returns a new nodeset with elements common to s and t.

__contains__(other)

Is node contained in NodeSet ?

__copy__()

Return a shallow copy of a NodeSet.

__delattr__

x.__delattr__(‘name’) <==> del x.name

__eq__(other)

NodeSet equality comparison.

__format__()

default object formatter

__ge__(other)

Report whether this nodeset contains another nodeset.

__getattribute__

x.__getattribute__(‘name’) <==> x.name

__getitem__(index)

Return the node at specified index or a subnodeset when a slice is specified.

__getstate__()

Called when pickling: remove references to group resolver.

__gt__(other)

x.__gt__(y) <==> x>y

__hash__
__iand__(other)

Implements the &= operator. So s &= t returns nodeset s keeping only elements also found in t. (Python version 2.5+ required)

__init__(nodes=None, autostep=None, resolver=None, fold_axis=None)

Initialize a NodeSet object.

The nodes argument may be a valid nodeset string or a NodeSet object. If no nodes are specified, an empty NodeSet is created.

The optional autostep argument is passed to underlying RangeSet.RangeSet objects and aims to enable and make use of the range/step syntax (eg. node[1-9/2]) when converting NodeSet to string (using folding). To enable this feature, autostep must be set there to the min number of indexes that are found at equal distance of each other inside a range before NodeSet starts to use this syntax. For example, autostep=3 (or less) will pack n[2,4,6] into n[2-6/2]. Default autostep value is None which means “inherit whenever possible”, ie. do not enable it unless set in NodeSet objects passed as nodes here or during arithmetic operations. You may however use the special AUTOSTEP_DISABLED constant to force turning off autostep feature.

The optional resolver argument may be used to override the group resolving behavior for this NodeSet object. It can either be set to a NodeUtils.GroupResolver object, to the RESOLVER_NOGROUP constant to disable any group resolution, or to None (default) to use standard NodeSet group resolver (see set_std_group_resolver() at the module level to change it if needed).

nD nodeset only: the optional fold_axis parameter, if specified, set the public instance member fold_axis to an iterable over nD 0-indexed axis integers. This parameter may be used to disengage some nD folding. That may be useful as all cluster tools don’t support folded-nD nodeset syntax. Pass [0], for example, to only fold along first axis (that is, to fold first dimension using [a-b] rangeset syntax whenever possible). Using fold_axis ensures that rangeset won’t be folded on unspecified axis, but please note however, that using fold_axis may lead to suboptimial folding, this is because NodeSet algorithms are optimized for folding along all axis (default behavior).

__ior__(other)

Implements the |= operator. So s |= t returns nodeset s with elements added from t. (Python version 2.5+ required)

__isub__(other)

Implement the -= operator. So s -= t returns nodeset s after removing elements found in t. (Python version 2.5+ required)

__iter__()

Iterator on single nodes as string.

__ixor__(other)

Implement the ^= operator. So s ^= t returns nodeset s after keeping all nodes that are in exactly one of the nodesets. (Python version 2.5+ required)

__le__(other)

Report whether another nodeset contains this nodeset.

__len__()

Get the number of nodes in NodeSet.

__lt__(other)

x.__lt__(y) <==> x<y

__new__(S, ...) → a new object with type S, a subtype of T
__or__(other)

Implements the | operator. So s | t returns a new nodeset with elements from both s and t.

__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__repr__
__setattr__

x.__setattr__(‘name’, value) <==> x.name = value

__setstate__(dic)

Called when unpickling: restore parser using non group resolver.

__sizeof__() → int

size of object in memory, in bytes

__str__()

Get ranges-based pattern of node list.

__sub__(other)

Implement the - operator. So s - t returns a new nodeset with elements in s but not in t.

__subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

__weakref__

list of weak references to the object (if defined)

__xor__(other)

Implement the ^ operator. So s ^ t returns a new NodeSet with nodes that are in exactly one of the nodesets.

add(other)

Add node to NodeSet.

autostep

Get autostep value (property)

clear()

Remove all nodes from this nodeset.

contiguous()

Object-based NodeSet iterator on contiguous node sets.

Contiguous node set contains nodes with same pattern name and a contiguous range of indexes, like foobar[1-100].

copy()

Return a shallow copy of a NodeSet.

difference(other)

s.difference(t) returns a new NodeSet with elements in s but not in t.

difference_update(other, strict=False)

s.difference_update(t) removes from s all the elements found in t. If strict is True, raise KeyError if an element in t cannot be removed from s.

classmethod fromall(groupsource=None, autostep=None, resolver=None)

Class method that returns a new NodeSet with all nodes from optional groupsource.

classmethod fromlist(nodelist, autostep=None, resolver=None)

Class method that returns a new NodeSet with nodes from provided list.

get_autostep()

Get autostep value (property)

groups(groupsource=None, noprefix=False)

Find node groups this nodeset belongs to.

Return a dictionary of the form:
group_name => (group_nodeset, contained_nodeset)

Group names are always prefixed with “@”. If groupsource is provided, they are prefixed with “@groupsource:”, unless noprefix is True.

intersection(other)

s.intersection(t) returns a new set with elements common to s and t.

intersection_update(other)

s.intersection_update(t) returns nodeset s keeping only elements also found in t.

issubset(other)

Report whether another nodeset contains this nodeset.

issuperset(other)

Report whether this nodeset contains another nodeset.

nsiter()

Object-based NodeSet iterator on single nodes.

regroup(groupsource=None, autostep=None, overlap=False, noprefix=False)

Regroup nodeset using node groups.

Try to find fully matching node groups (within specified groupsource) and return a string that represents this node set (containing these potential node groups). When no matching node groups are found, this method returns the same result as str().

remove(elem)

Remove element elem from the nodeset. Raise KeyError if elem is not contained in the nodeset.

Raises:KeyError – elem is not contained in the nodeset
set_autostep(val)

Set autostep value (property)

split(nbr)

Split the nodeset into nbr sub-nodesets (at most). Each sub-nodeset will have the same number of elements more or less 1. Current nodeset remains unmodified.

>>> for nodeset in NodeSet("foo[1-5]").split(3):
...     print nodeset
foo[1-2]
foo[3-4]
foo5
striter()

Iterator on single nodes as string.

symmetric_difference(other)

s.symmetric_difference(t) returns the symmetric difference of two nodesets as a new NodeSet.

(ie. all nodes that are in exactly one of the nodesets.)

symmetric_difference_update(other)

s.symmetric_difference_update(t) returns nodeset s keeping all nodes that are in exactly one of the nodesets.

union(other)

s.union(t) returns a new set with elements from both s and t.

update(other)

s.update(t) returns nodeset s with elements added from t.

updaten(others)

s.updaten(list) returns nodeset s with elements added from given list.

ClusterShell.NodeSet.expand(pat)

Commodity function that expands a nodeset pattern into a list of nodes.

ClusterShell.NodeSet.fold(pat)

Commodity function that clean dups and fold provided pattern with ranges and “/step” support.

ClusterShell.NodeSet.grouplist(namespace=None, resolver=None)

Commodity function that retrieves the list of raw groups for a specified group namespace (or use default namespace). Group names are not prefixed with “@”.

ClusterShell.NodeSet.std_group_resolver()

Get the current resolver used for standard “@” group resolution.

ClusterShell.NodeSet.set_std_group_resolver(new_resolver)

Override the resolver used for standard “@” group resolution. The new resolver should be either an instance of NodeUtils.GroupResolver or None. In the latter case, the group resolver is restored to the default one.