NodeSet (class)

NodeSet

Presentation

NodeSet is a kind of set of indexed node names. It's a convenient way to deal with cluster nodes and ease their administration. NodeSet is implemented with the help of another ClusterShell public class named RangeSet which implements the numeric ranges lists methods.

The ClusterShell library also provides a nodeset command which allows users to use most of the NodeSet class features directly from the command line.

Class API documentation

Please use the following command to see NodeSet API documentation:

$ pydoc ClusterShell.NodeSet.NodeSet

Class features

This section introduces some features of the NodeSet class. Please note that the NodeSet class is largely inspired from the standard Python Set class.

Contructors

nodeset0 = NodeSet()
nodeset1 = NodeSet("node[10-42]")
nodeset2 = NodeSet.fromlist(["node10", "node12", "node42"])

Iterator

for node in nodeset1:
	print node

Conditions

"node12" in nodeset2          # returns True

nodeset2.issubset(nodeset1)   # returns True

nodeset2 <= nodeset1          # returns True

nodeset2.issuperset(nodeset1) # returns False

nodeset2 >= nodeset1          # returns False

Accessors

nodeset1[0]   # returns "node10"

Slicing:

nodeset1[2:4]   # returns NodeSet("node[12-13]")

Size

To get the size of a NodeSet, ie. the number of nodes in it, use the standard len() method:

len(nodeset1)

Common methods

Mutable NodeSet methods

nodeset1.add("node10")     # add "node10" to nodeset1 (ie. modify nodeset1)
nodeset1.remove("node10")  # remove "node10" from nodeset1 (ie. modify nodeset1)
nodeset1.update(nodeset2)  # modify nodeset1 by adding nodes from nodeset2
nodeset1.clear()           # remove all nodes from this NodeSet

Immutable NodeSet methods

nodeset1.union(nodeset2)   # returns a new NodeSet object with nodes from both nodeset1 and nodeset2

Set methods

Nodeset intersection

To compute the intersection of two Nodesets, use the following methods:

ns = nodeset1.intersection(nodeset2)   # returns a new NodeSet with nodes common to nodeset1 and nodeset2
ns = nodeset1 & nodeset2               # same using the & Python operator

nodeset1.intersection_update(nodeset2) # modify nodeset1 (mutable) keeping only nodes also found in nodeset2
nodeset1 &= nodeset2                   # same using the &= Python 2.5+ operator

Nodeset difference

To compute the difference of two Nodesets, use the following methods:

ns = nodeset1.difference(nodeset2)     # returns a new NodeSet with nodes in nodeset1 but not in nodeset2
ns = nodeset1 – nodeset2               # same using the - Python operator

nodeset1.difference_update(nodeset2)   # modify nodeset1 after removing nodes found in nodeset2
nodeset1 -= nodeset2                   # same using the -= Python 2.5+ operator

Nodeset symmetric difference (XOR)

ns = nodeset1.symmetric_difference(nodeset2)   # returns a new NodeSet with nodes that are in exactly one of the nodesets
ns = nodeset1 ^ nodeset2                       # same using the ^ Python operator

nodeset1.symmetric_difference_update(nodeset2) # modify nodeset1
nodeset1 ^= nodeset2                           # same using the ^= Python 2.5 operator

NodeSet String Parsing Engine

The NodeSet class is associated with a string parsing engine (ParsingEngine) used to parse the string arguments of the NodeSet class constructor and methods, but also which can use an optional resolver object (that is able to resolve, for instance, external node groups).

Extended string pattern

The default string parsing engine of NodeSet is able to understand an 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

Example of use

 from ClusterShell.NodeSet import NodeSet
 
 ns1 = NodeSet("node[10-42]")
 ns2 = NodeSet("node[11-16,18-39]")
 print ns1.difference(ns2)           # returns node[10,17,40-42]
 print ns1 – ns2                     # returns node[10,17,40-42]
 
 ns3 = NodeSet("node[1-14,40-200]")
 print ns3.intersection(ns1)         # returns node[10-14,40-42]

Example of valid NodeSet strings

 tigrou3
 cws-tigrou
 tigrou[2,6,21-69]
 tigrou2,tigrou7,tigrou[9-11]
 tigrou[3-8],winnie[0-6,8]
 tigrou[2-12/2]
 corsair[001-050,075-077]
 corsair[1-12,14]-hat
 tigrou[3-7]!tigrou4
 tigrou[3-8]&tigrou[5,7-10]
 tigrou[2-10]^tigrou[3-11/2]