RangeSet

Cluster range set module.

Instances of RangeSet provide similar operations than the builtin set type, extended to support cluster ranges-like format and stepping support ("0-8/2").

class ClusterShell.RangeSet.RangeSet(pattern=None, autostep=None)

Mutable set of cluster node indexes featuring a fast range-based API.

This class aims to ease the management of potentially large cluster range sets and is used by the NodeSet class.

RangeSet basic constructors:

>>> rset = RangeSet()            # empty RangeSet
>>> rset = RangeSet("5,10-42")   # contains '5', '10' to '42'
>>> rset = RangeSet("0-10/2")    # contains '0', '2', '4', '6', '8', '10'
>>> rset = RangeSet("00-10/2")   # contains '00', '02', '04', '06', '08', '10'

Also any iterable of integers can be specified as first argument:

>>> RangeSet([3, 6, 8, 7, 1])
1,3,6-8
>>> rset2 = RangeSet(rset)

Padding of ranges (eg. "003-009") is inferred from input arguments and managed automatically. This is new in ClusterShell v1.9, where mixed lengths zero padding is now supported within the same RangeSet. The instance variable padding has become a property that can still be used to either get the max padding length in the set, or force a fixed length zero-padding on the set.

RangeSet is itself a set and as such, provides an iterator over its items as strings (strings are used since v1.9). It is recommended to use the explicit iterators RangeSet.intiter() and RangeSet.striter() when iterating over a RangeSet.

RangeSet provides methods like RangeSet.union(), RangeSet.intersection(), RangeSet.difference(), RangeSet.symmetric_difference() and their in-place versions RangeSet.update(), RangeSet.intersection_update(), RangeSet.difference_update(), RangeSet.symmetric_difference_update() which conform to the Python Set API.

__and__(other)

Return the intersection of two RangeSets as a new RangeSet.

(I.e. all elements that are in both sets.)

__contains__(element)

Report whether an element is a member of a RangeSet. Element can be either another RangeSet object, a string or an integer.

Called in response to the expression element in self.

__copy__()

Return a shallow copy of a RangeSet.

__eq__(other)

RangeSet equality comparison.

__ge__(other)

Report whether this RangeSet contains another set.

__getitem__(index)

Return the element at index or a subrange when a slice is specified.

__gt__(other)

Return self>value.

__iand__(other)

Update a RangeSet with the intersection of itself and another.

__init__(pattern=None, autostep=None)

Initialize RangeSet object.

Parameters:
  • pattern -- optional string pattern
  • autostep -- optional autostep threshold
__ior__(other)

Update a RangeSet with the union of itself and another.

__isub__(other)

Remove all elements of another set from this RangeSet.

__iter__()

Iterate over each element in RangeSet, currently as integers, with no padding information. To guarantee future compatibility, please use the methods intiter() or striter() instead.

__ixor__(other)

Update a RangeSet with the symmetric difference of itself and another.

__le__(other)

Report whether another set contains this RangeSet.

__lt__(other)

Return self<value.

__or__(other)

Return the union of two RangeSets as a new RangeSet.

(I.e. all elements that are in either set.)

__reduce__()

Return state information for pickling.

__repr__()

Get comma-separated range-based string (x-y/step format).

__setstate__(dic)

called upon unpickling

__str__()

Get comma-separated range-based string (x-y/step format).

__sub__(other)

Return the difference of two RangeSets as a new RangeSet.

(I.e. all elements that are in this set and not in the other.)

__xor__(other)

Return the symmetric difference of two RangeSets as a new RangeSet.

(I.e. all elements that are in exactly one of the sets.)

add(element, pad=0)

Add an element to a RangeSet. This has no effect if the element is already present.

ClusterShell 1.9+ uses strings instead of integers to better manage zero-padded ranges with mixed lengths. This method supports either a string or an integer with padding info.

Parameters:
  • element -- the element to add (integer or string)
  • pad -- zero padding length (integer); ignored if element is string
add_range(start, stop, step=1, pad=0)

Add a range (start, stop, step and padding length) to RangeSet. Like the Python built-in function range(), the last element is the largest start + i * step less than stop.

autostep

autostep threshold public instance attribute

clear()

Remove all elements from this RangeSet.

contiguous()

Object-based iterator over contiguous range sets.

copy()

Return a shallow copy of a RangeSet.

difference(other)

Return the difference of two RangeSets as a new RangeSet.

(I.e. all elements that are in this set and not in the other.)

difference_update(other, strict=False)

Remove all elements of another set from this RangeSet.

If strict is True, raise KeyError if an element cannot be removed. (strict is a RangeSet addition)

dim()

Get the number of dimensions of this RangeSet object. Common method with RangeSetND. Here, it will always return 1 unless the object is empty, in that case it will return 0.

discard(element, pad=0)

Discard an element from a RangeSet if it is a member.

If the element is not a member, do nothing.

ClusterShell 1.9+ uses strings instead of integers to better manage zero-padded ranges with mixed lengths. This method supports either a string or an integer with padding info.

Parameters:
  • element -- the element to remove (integer or string)
  • pad -- zero padding length (integer); ignored if element is string
classmethod fromlist(rnglist, autostep=None)

Class method that returns a new RangeSet with ranges from provided list.

classmethod fromone(index, pad=0, autostep=None)

Class method that returns a new RangeSet of one single item or a single range. Accepted input arguments can be: - integer and padding length - slice object and padding length - string (1.9+) with padding automatically detected (pad is ignored)

get_autostep()

Get autostep value (property)

intersection(other)

Return the intersection of two RangeSets as a new RangeSet.

(I.e. all elements that are in both sets.)

intersection_update(other)

Update a RangeSet with the intersection of itself and another.

intiter()

Iterate over each element in RangeSet as integer. Zero padding info is ignored.

issubset(other)

Report whether another set contains this RangeSet.

issuperset(other)

Report whether this RangeSet contains another set.

padding

Get largest padding value of whole set

remove(element, pad=0)

Remove an element from a RangeSet.

ClusterShell 1.9+ uses strings instead of integers to better manage zero-padded ranges with mixed lengths. This method supports either a string or an integer with padding info.

Parameters:
  • element -- the element to remove (integer or string)
  • pad -- zero padding length (integer); ignored if element is string
Raises:
  • KeyError -- element is not contained in RangeSet
  • ValueError -- element is not castable to integer
set_autostep(val)

Set autostep value (property)

slices()

Iterate over RangeSet ranges as Python slide objects. NOTE: zero-padding info is not provided

split(nbr)

Split the rangeset into nbr sub-rangesets (at most). Each sub-rangeset will have the same number of elements more or less 1. Current rangeset remains unmodified. Returns an iterator.

>>> RangeSet("1-5").split(3) 
RangeSet("1-2")
RangeSet("3-4")
RangeSet("foo5")
striter()

Iterate over each element in RangeSet as strings with optional zero-padding.

symmetric_difference(other)

Return the symmetric difference of two RangeSets as a new RangeSet.

(ie. all elements that are in exactly one of the sets.)

symmetric_difference_update(other)

Update a RangeSet with the symmetric difference of itself and another.

union(other)

Return the union of two RangeSets as a new RangeSet.

(I.e. all elements that are in either set.)

union_update(other)

Update a RangeSet with the union of itself and another.

update(iterable)

Add all indexes (as strings) from an iterable (such as a list).

updaten(rangesets)

Update a rangeset with the union of itself and several others.

RangeSetND

class ClusterShell.RangeSet.RangeSetND(args=None, pads=None, autostep=None, copy_rangeset=True)

Build a N-dimensional RangeSet object.

Warning

You don't usually need to use this class directly, use NodeSet instead that has ND support.

Empty constructor:

RangeSetND()

Build from a list of list of RangeSet objects:

RangeSetND([[rs1, rs2, rs3, ...], ...])

Strings are also supported:

RangeSetND([["0-3", "4-10", ...], ...])

Integers are also supported:

RangeSetND([(0, 4), (0, 5), (1, 4), (1, 5), ...]
__and__(other)

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

__contains__(**kwargs)

Report whether an element is a member of a RangeSetND. Element can be either another RangeSetND object, a string or an integer.

Called in response to the expression element in self.

__copy__(**kwargs)

Return a new, mutable shallow copy of a RangeSetND.

__eq__(other)

RangeSetND equality comparison.

__ge__(**kwargs)

Report whether this RangeSetND contains another RangeSetND.

__getitem__(**kwargs)

Return the element at index or a subrange when a slice is specified.

__gt__(other)

Return self>value.

__iand__(other)

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

__init__(args=None, pads=None, autostep=None, copy_rangeset=True)

RangeSetND initializer

All parameters are optional.

Parameters:
  • args -- generic "list of list" input argument (default is None)
  • pads -- list of 0-padding length (default is to not pad any dimensions)
  • autostep -- autostep threshold (use range/step notation if more than #autostep items meet the condition) - default is off (None)
  • copy_rangeset -- (advanced) if set to False, do not copy RangeSet objects from args (transfer ownership), which is faster. In that case, you should not modify these objects afterwards (default is True).
__ior__(other)

Update a RangeSetND with the union of itself and another.

__isub__(other)

Remove all elements of another set from this RangeSetND.

__ixor__(other)

Implement the ^= operator. So s ^= t returns object s after keeping all items that are in exactly one of the RangeSetND (Python 2.5+ required).

__le__(other)

Report whether another set contains this RangeSetND.

__len__()

Count unique elements in N-dimensional rangeset.

__lt__(other)

Return self<value.

__or__(other)

Return the union of two RangeSetNDs as a new RangeSetND.

(I.e. all elements that are in either set.)

__str__(**kwargs)

String representation of N-dimensional RangeSet.

__sub__(other)

Return the difference of two RangeSetNDs as a new RangeSetND.

(I.e. all elements that are in this set and not in the other.)

__weakref__

list of weak references to the object (if defined)

__xor__(other)

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

autostep

autostep threshold public instance attribute

contiguous(**kwargs)

Object-based iterator over contiguous range sets.

copy(**kwargs)

Return a new, mutable shallow copy of a RangeSetND.

difference(other)

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

difference_update(other, strict=False)

Remove all elements of another set from this RangeSetND.

If strict is True, raise KeyError if an element cannot be removed (strict is a RangeSet addition)

dim()

Get the current number of dimensions of this RangeSetND object. Return 0 when object is empty.

fold(**kwargs)

Explicit folding call. Please note that folding of RangeSetND nD vectors are automatically managed, so you should not have to call this method. It may be still useful in some extreme cases where the RangeSetND is heavily modified.

get_autostep()

Get autostep value (property)

intersection(other)

s.intersection(t) returns a new object 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 set contains this RangeSetND.

issuperset(**kwargs)

Report whether this RangeSetND contains another RangeSetND.

iter_padding(**kwargs)

Iterate through individual items as tuples with padding info. As of v1.9, this method returns the largest padding value of each items, as mixed length padding is allowed.

pads()

Get a tuple of padding length info for each dimension.

class precond_fold

Decorator to ease internal folding management

__call__(func)

Call self as a function.

__weakref__

list of weak references to the object (if defined)

set_autostep(val)

Set autostep value (property)

symmetric_difference(other)

s.symmetric_difference(t) returns the symmetric difference of two objects as a new RangeSetND.

(ie. all items that are in exactly one of the RangeSetND.)

symmetric_difference_update(other)

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

union(other)

Return the union of two RangeSetNDs as a new RangeSetND.

(I.e. all elements that are in either set.)

union_update(other)

Add all RangeSetND elements to this RangeSetND.

update(other)

Add all RangeSetND elements to this RangeSetND.

veclist

Get folded veclist

vectors()

Get underlying RangeSet vectors