#
# Copyright (C) 2007-2016 CEA/DAM
# Copyright (C) 2007-2017 Aurelien Degremont <aurelien.degremont@cea.fr>
# Copyright (C) 2015-2017 Stephane Thiell <sthiell@stanford.edu>
#
# This file is part of ClusterShell.
#
# ClusterShell is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# ClusterShell is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with ClusterShell; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
"""
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
"""
import fnmatch
import re
import string
import sys
from ClusterShell.Defaults import config_paths, DEFAULTS
import ClusterShell.NodeUtils as NodeUtils
# Import all RangeSet module public objects
from ClusterShell.RangeSet import RangeSet, RangeSetND, AUTOSTEP_DISABLED
from ClusterShell.RangeSet import RangeSetParseError
# Python 3 compatibility
try:
basestring
except NameError:
basestring = str
# Define default GroupResolver object used by NodeSet
DEF_GROUPS_CONFIGS = config_paths('groups.conf')
ILLEGAL_GROUP_CHARS = set("@,!&^*")
_DEF_RESOLVER_STD_GROUP = NodeUtils.GroupResolverConfig(DEF_GROUPS_CONFIGS,
ILLEGAL_GROUP_CHARS)
# Standard group resolver
RESOLVER_STD_GROUP = _DEF_RESOLVER_STD_GROUP
# Special constants for NodeSet's resolver parameter
# RESOLVER_NOGROUP => avoid any group resolution at all
# RESOLVER_NOINIT => reserved use for optimized copy()
RESOLVER_NOGROUP = -1
RESOLVER_NOINIT = -2
# 1.5 compat (deprecated)
STD_GROUP_RESOLVER = RESOLVER_STD_GROUP
NOGROUP_RESOLVER = RESOLVER_NOGROUP
class NodeSetException(Exception):
"""Base NodeSet exception class."""
class NodeSetError(NodeSetException):
"""Raised when an error is encountered."""
class NodeSetParseError(NodeSetError):
"""Raised when NodeSet parsing cannot be done properly."""
def __init__(self, part, msg):
if part:
msg = "%s: \"%s\"" % (msg, part)
NodeSetError.__init__(self, msg)
# faulty part; this allows you to target the error
self.part = part
class NodeSetParseRangeError(NodeSetParseError):
"""Raised when bad range is encountered during NodeSet parsing."""
def __init__(self, rset_exc):
NodeSetParseError.__init__(self, str(rset_exc), "bad range")
class NodeSetExternalError(NodeSetError):
"""Raised when an external error is encountered."""
class NodeSetBase(object):
"""
Base class for NodeSet.
This class allows node set base object creation from specified string
pattern and rangeset object. If optional copy_rangeset boolean flag is
set to True (default), provided rangeset object is copied (if needed),
otherwise it may be referenced (should be seen as an ownership transfer
upon creation).
This class implements core node set arithmetic (no string parsing here).
Example:
>>> nsb = NodeSetBase('node%s-ipmi', RangeSet('1-5,7'), False)
>>> str(nsb)
'node[1-5,7]-ipmi'
>>> nsb = NodeSetBase('node%s-ib%s', RangeSetND([['1-5,7', '1-2']]), False)
>>> str(nsb)
'node[1-5,7]-ib[1-2]'
"""
def __init__(self, pattern=None, rangeset=None, copy_rangeset=True,
autostep=None, fold_axis=None):
"""New NodeSetBase object initializer"""
self._autostep = autostep
self._length = 0
self._patterns = {}
self.fold_axis = fold_axis #: iterable over nD 0-indexed axis
if self.fold_axis is None and DEFAULTS.fold_axis:
self.fold_axis = DEFAULTS.fold_axis # non-empty tuple
if pattern:
self._add(pattern, rangeset, copy_rangeset)
elif rangeset:
raise ValueError("missing pattern")
def get_autostep(self):
"""Get autostep value (property)"""
return self._autostep
def set_autostep(self, val):
"""Set autostep value (property)"""
if val is None:
self._autostep = None
else:
# Work around the pickling issue of sys.maxint (+inf) in py2.4
self._autostep = min(int(val), AUTOSTEP_DISABLED)
# Update our RangeSet/RangeSetND objects
for pat, rset in self._patterns.items():
if rset:
rset.autostep = self._autostep
autostep = property(get_autostep, set_autostep)
def _iter(self):
"""Iterator on internal item tuples
(pattern, indexes, autostep)."""
for pat, rset in sorted(self._patterns.items()):
if rset:
autostep = rset.autostep
if rset.dim() == 1:
assert isinstance(rset, RangeSet)
for idx in rset:
yield pat, (idx,), autostep
else:
for rvec in rset:
yield pat, rvec, autostep
else:
yield pat, None, None
def _iterbase(self):
"""Iterator on single, one-item NodeSetBase objects."""
for pat, ivec, autostep in self._iter():
rset = None # 'no node index' by default
if ivec is not None:
assert len(ivec) > 0
if len(ivec) == 1:
rset = RangeSet.fromone(ivec[0], autostep)
else:
rset = RangeSetND([ivec], autostep)
yield NodeSetBase(pat, rset)
def __iter__(self):
"""Iterator on single nodes as string."""
# Does not call self._iterbase() + str() for better performance.
for pat, ivec, _ in self._iter():
if ivec is not None:
yield pat % ivec
else:
yield pat % ()
# define striter() alias for convenience (to match RangeSet.striter())
striter = __iter__
# define nsiter() as an object-based iterator that could be used for
# __iter__() in the future...
def nsiter(self):
"""Object-based NodeSet iterator on single nodes."""
for pat, ivec, autostep in self._iter():
nodeset = self.__class__()
if ivec is not None:
if len(ivec) == 1:
nodeset._add_new(pat, RangeSet.fromone(ivec[0]))
else:
nodeset._add_new(pat, RangeSetND([ivec], autostep))
else:
nodeset._add_new(pat, None)
yield nodeset
def contiguous(self):
"""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]."""
for pat, rangeset in sorted(self._patterns.items()):
if rangeset:
for cont_rset in rangeset.contiguous():
nodeset = self.__class__()
nodeset._add_new(pat, cont_rset)
yield nodeset
else:
nodeset = self.__class__()
nodeset._add_new(pat, None)
yield nodeset
def __len__(self):
"""Get the number of nodes in NodeSet."""
cnt = 0
for rangeset in self._patterns.values():
if rangeset:
cnt += len(rangeset)
else:
cnt += 1
return cnt
def _iter_nd_pat(self, pat, rset):
"""
Take a pattern and a RangeSetND object and iterate over nD computed
nodeset strings while following fold_axis constraints.
"""
try:
dimcnt = rset.dim()
if self.fold_axis is None:
# fold along all axis (default)
fold_axis = range(dimcnt)
else:
# set of user-provided fold axis (support negative numbers)
fold_axis = [int(x) % dimcnt for x in self.fold_axis
if -dimcnt <= int(x) < dimcnt]
except (TypeError, ValueError) as exc:
raise NodeSetParseError("fold_axis=%s" % self.fold_axis, exc)
for rgvec in rset.vectors():
rgnargs = [] # list of str rangeset args
for axis, rangeset in enumerate(rgvec):
# build an iterator over rangeset strings to add
if len(rangeset) > 1:
if axis not in fold_axis: # expand
rgstrit = rangeset.striter()
else:
rgstrit = ["[%s]" % rangeset]
else:
rgstrit = [str(rangeset)]
# aggregate/expand along previous computed axis...
t_rgnargs = []
for rgstr in rgstrit: # 1-time when not expanding
if not rgnargs:
t_rgnargs.append([rgstr])
else:
for rga in rgnargs:
t_rgnargs.append(rga + [rgstr])
rgnargs = t_rgnargs
# get nodeset patterns formatted with range strings
for rgargs in rgnargs:
yield pat % tuple(rgargs)
def __str__(self):
"""Get ranges-based pattern of node list."""
results = []
try:
for pat, rset in sorted(self._patterns.items()):
if not rset:
results.append(pat % ())
elif rset.dim() == 1:
# check if allowed to fold even for 1D pattern
if self.fold_axis is None or \
list(x for x in self.fold_axis if -1 <= int(x) < 1):
rgs = str(rset)
cnt = len(rset)
if cnt > 1:
rgs = "[%s]" % rgs
results.append(pat % rgs)
else:
results.extend((pat % rgs for rgs in rset.striter()))
elif rset.dim() > 1:
results.extend(self._iter_nd_pat(pat, rset))
except TypeError:
raise NodeSetParseError(pat, "Internal error: node pattern and "
"ranges mismatch")
return ",".join(results)
def copy(self):
"""Return a shallow copy."""
cpy = self.__class__()
cpy.fold_axis = self.fold_axis
cpy._autostep = self._autostep
cpy._length = self._length
dic = {}
for pat, rangeset in self._patterns.items():
if rangeset is None:
dic[pat] = None
else:
dic[pat] = rangeset.copy()
cpy._patterns = dic
return cpy
def __contains__(self, other):
"""Is node contained in NodeSet ?"""
return self.issuperset(other)
def _binary_sanity_check(self, other):
# check that the other argument to a binary operation is also
# a NodeSet, raising a TypeError otherwise.
if not isinstance(other, NodeSetBase):
raise TypeError("Binary operation only permitted between "
"NodeSetBase")
def issubset(self, other):
"""Report whether another nodeset contains this nodeset."""
self._binary_sanity_check(other)
return other.issuperset(self)
def issuperset(self, other):
"""Report whether this nodeset contains another nodeset."""
self._binary_sanity_check(other)
status = True
for pat, erangeset in other._patterns.items():
rangeset = self._patterns.get(pat)
if rangeset:
status = rangeset.issuperset(erangeset)
else:
# might be an unnumbered node (key in dict but no value)
status = pat in self._patterns
if not status:
break
return status
def __eq__(self, other):
"""NodeSet equality comparison."""
# See comment for for RangeSet.__eq__()
if not isinstance(other, NodeSetBase):
return NotImplemented
return len(self) == len(other) and self.issuperset(other)
# inequality comparisons using the is-subset relation
__le__ = issubset
__ge__ = issuperset
def __lt__(self, other):
"""x.__lt__(y) <==> x<y"""
self._binary_sanity_check(other)
return len(self) < len(other) and self.issubset(other)
def __gt__(self, other):
"""x.__gt__(y) <==> x>y"""
self._binary_sanity_check(other)
return len(self) > len(other) and self.issuperset(other)
def _extractslice(self, index):
"""Private utility function: extract slice parameters from slice object
`index` for an list-like object of size `length`."""
length = len(self)
if index.start is None:
sl_start = 0
elif index.start < 0:
sl_start = max(0, length + index.start)
else:
sl_start = index.start
if index.stop is None:
sl_stop = sys.maxsize
elif index.stop < 0:
sl_stop = max(0, length + index.stop)
else:
sl_stop = index.stop
if index.step is None:
sl_step = 1
elif index.step < 0:
# We support negative step slicing with no start/stop, ie. r[::-n].
if index.start is not None or index.stop is not None:
raise IndexError("illegal start and stop when negative step "
"is used")
# As RangeSet elements are ordered internally, adjust sl_start
# to fake backward stepping in case of negative slice step.
stepmod = (length + -index.step - 1) % -index.step
if stepmod > 0:
sl_start += stepmod
sl_step = -index.step
else:
sl_step = index.step
if not isinstance(sl_start, int) or not isinstance(sl_stop, int) \
or not isinstance(sl_step, int):
raise TypeError("slice indices must be integers")
return sl_start, sl_stop, sl_step
def __getitem__(self, index):
"""Return the node at specified index or a subnodeset when a slice is
specified."""
if isinstance(index, slice):
inst = NodeSetBase()
sl_start, sl_stop, sl_step = self._extractslice(index)
sl_next = sl_start
if sl_stop <= sl_next:
return inst
length = 0
for pat, rangeset in sorted(self._patterns.items()):
if rangeset:
cnt = len(rangeset)
offset = sl_next - length
if offset < cnt:
num = min(sl_stop - sl_next, cnt - offset)
inst._add(pat, rangeset[offset:offset + num:sl_step])
else:
#skip until sl_next is reached
length += cnt
continue
else:
cnt = num = 1
if sl_next > length:
length += cnt
continue
inst._add(pat, None)
# adjust sl_next...
sl_next += num
if (sl_next - sl_start) % sl_step:
sl_next = sl_start + \
((sl_next - sl_start)//sl_step + 1) * sl_step
if sl_next >= sl_stop:
break
length += cnt
return inst
elif isinstance(index, int):
if index < 0:
length = len(self)
if index >= -length:
index = length + index # - -index
else:
raise IndexError("%d out of range" % index)
length = 0
for pat, rangeset in sorted(self._patterns.items()):
if rangeset:
cnt = len(rangeset)
if index < length + cnt:
# return a subrangeset of size 1 to manage padding
if rangeset.dim() == 1:
return pat % rangeset[index-length:index-length+1]
else:
sub = rangeset[index-length:index-length+1]
for rgvec in sub.vectors():
return pat % (tuple(rgvec))
else:
cnt = 1
if index == length:
return pat
length += cnt
raise IndexError("%d out of range" % index)
else:
raise TypeError("NodeSet indices must be integers")
def _rangeset_index(self, rangeset, orangeset):
"""Return the position of the single index held by `orangeset`
within `rangeset`, following the same order as iteration, or None
if the index is not contained in `rangeset`.
Both arguments are the RangeSet/RangeSetND/None objects respectively
associated to the same pattern in this nodeset and in the searched
single node.
"""
# unnumbered node (eg. 'server'): both must have no index
if rangeset is None or orangeset is None:
return 0 if rangeset is None and orangeset is None else None
try:
if isinstance(orangeset, RangeSetND):
# nD: orangeset holds a single index vector
return rangeset.index(next(iter(orangeset)))
# 1D: orangeset holds a single (possibly zero-padded) index
return rangeset.index(next(orangeset.striter()))
except ValueError:
return None
def index(self, other, start=0, stop=None):
"""Return the zero-based index in the nodeset of the node `other`.
This behaves like the ``index()`` method of the ``list`` type: it
returns the position of the node when iterating over the nodeset and
raises a :class:`ValueError` if the node is not present. The optional
`start` and `stop` arguments restrict the search to the matching
subsequence, and may be negative (counted from the end).
Unlike a naive linear search, this implementation does not expand the
whole nodeset: it only sums the size of the patterns that precede the
searched node and locates it within its own pattern.
Example:
>>> NodeSetBase('node%s', RangeSet('0-9,20')).index(
... NodeSetBase('node%s', RangeSet('20')))
10
"""
self._binary_sanity_check(other)
if len(other) != 1:
raise ValueError("index() argument must be a single node")
# extract the single (pattern, rangeset) of the searched node
opat, orangeset = list(other._patterns.items())[0]
# walk patterns in iteration order, summing sizes until we reach the
# pattern of the searched node
found = None
base = 0
for pat, rangeset in sorted(self._patterns.items()):
if pat == opat:
offset = self._rangeset_index(rangeset, orangeset)
if offset is not None:
found = base + offset
break
if rangeset:
base += len(rangeset)
else:
base += 1
if found is None:
raise ValueError("'%s' is not in nodeset" % other)
# honor optional start/stop search window (list.index() semantics)
if start != 0 or stop is not None:
length = len(self)
if start < 0:
start = max(0, length + start)
if stop is None:
stop = length
elif stop < 0:
stop = max(0, length + stop)
if not start <= found < stop:
raise ValueError("'%s' is not in nodeset" % other)
return found
def _add_new(self, pat, rangeset):
"""Add nodes from a (pat, rangeset) tuple.
Predicate: pattern does not exist in current set. RangeSet object is
referenced (not copied)."""
assert pat not in self._patterns
self._patterns[pat] = rangeset
def _add(self, pat, rangeset, copy_rangeset=True):
"""Add nodes from a (pat, rangeset) tuple.
`pat' may be an existing pattern and `rangeset' may be None.
RangeSet or RangeSetND objects are copied if re-used internally
when provided and if copy_rangeset flag is set.
"""
if pat in self._patterns:
# existing pattern: get RangeSet or RangeSetND entry...
pat_e = self._patterns[pat]
# sanity checks
if (pat_e is None) is not (rangeset is None):
raise NodeSetError("Invalid operation")
# entry may exist but set to None (single node)
if pat_e:
pat_e.update(rangeset)
else:
# new pattern...
if rangeset and copy_rangeset:
# default is to inherit rangeset autostep value
rangeset = rangeset.copy()
# but if set, self._autostep does override it
if self._autostep is not None:
# works with rangeset 1D or nD
rangeset.autostep = self._autostep
self._add_new(pat, rangeset)
def union(self, other):
"""
s.union(t) returns a new set with elements from both s and t.
"""
self_copy = self.copy()
self_copy.update(other)
return self_copy
def __or__(self, other):
"""
Implements the | operator. So s | t returns a new nodeset with
elements from both s and t.
"""
if not isinstance(other, NodeSetBase):
return NotImplemented
return self.union(other)
def add(self, other):
"""
Add node to NodeSet.
"""
self.update(other)
def update(self, other):
"""
s.update(t) updates nodeset s with elements added from t.
"""
for pat, rangeset in other._patterns.items():
self._add(pat, rangeset)
def updaten(self, others):
"""
s.updaten(list) updates nodeset s with elements added from given list.
"""
for other in others:
self.update(other)
def clear(self):
"""
Remove all nodes from this nodeset.
"""
self._patterns.clear()
def __ior__(self, other):
"""
Implements the ``|=`` operator. So ``s |= t`` returns nodeset s
with elements added from t. (Python version 2.5+ required)
"""
self._binary_sanity_check(other)
self.update(other)
return self
def intersection(self, other):
"""
s.intersection(t) returns a new set with elements common to s
and t.
"""
self_copy = self.copy()
self_copy.intersection_update(other)
return self_copy
def __and__(self, other):
"""
Implements the & operator. So ``s & t`` returns a new nodeset with
elements common to s and t.
"""
if not isinstance(other, NodeSet):
return NotImplemented
return self.intersection(other)
def intersection_update(self, other):
"""
``s.intersection_update(t)`` updates nodeset s keeping only
elements also found in t.
"""
if other is self:
return
tmp_ns = NodeSetBase()
for pat, irangeset in other._patterns.items():
rangeset = self._patterns.get(pat)
if rangeset:
irset = rangeset.intersection(irangeset)
# ignore pattern if empty rangeset
if len(irset) > 0:
tmp_ns._add(pat, irset, copy_rangeset=False)
elif not irangeset and pat in self._patterns:
# intersect two nodes with no rangeset
tmp_ns._add(pat, None)
# Substitute
self._patterns = tmp_ns._patterns
def __iand__(self, other):
"""
Implements the &= operator. So ``s &= t`` returns nodeset s keeping
only elements also found in t. (Python version 2.5+ required)
"""
self._binary_sanity_check(other)
self.intersection_update(other)
return self
def difference(self, other):
"""
``s.difference(t)`` returns a new NodeSet with elements in s but not
in t.
"""
self_copy = self.copy()
self_copy.difference_update(other)
return self_copy
def __sub__(self, other):
"""
Implement the - operator. So ``s - t`` returns a new nodeset with
elements in s but not in t.
"""
if not isinstance(other, NodeSetBase):
return NotImplemented
return self.difference(other)
def difference_update(self, other, strict=False):
"""
``s.difference_update(t)`` removes from s all the elements found in t.
:raises KeyError: an element cannot be removed (only if strict is
True)
"""
# the purge of each empty pattern is done afterward to allow self = ns
purge_patterns = []
# iterate first over exclude nodeset rangesets which is usually smaller
for pat, erangeset in other._patterns.items():
# if pattern is found, deal with it
rangeset = self._patterns.get(pat)
if rangeset:
# sub rangeset, raise KeyError if not found
rangeset.difference_update(erangeset, strict)
# check if no range left and add pattern to purge list
if len(rangeset) == 0:
purge_patterns.append(pat)
else:
# unnumbered node exclusion
if pat in self._patterns:
purge_patterns.append(pat)
elif strict:
raise KeyError(pat)
for pat in purge_patterns:
del self._patterns[pat]
def __isub__(self, other):
"""
Implement the -= operator. So ``s -= t`` returns nodeset s after
removing elements found in t. (Python version 2.5+ required)
"""
self._binary_sanity_check(other)
self.difference_update(other)
return self
def remove(self, 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
"""
self.difference_update(elem, True)
def symmetric_difference(self, 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.)
"""
self_copy = self.copy()
self_copy.symmetric_difference_update(other)
return self_copy
def __xor__(self, other):
"""
Implement the ^ operator. So ``s ^ t`` returns a new NodeSet with
nodes that are in exactly one of the nodesets.
"""
if not isinstance(other, NodeSet):
return NotImplemented
return self.symmetric_difference(other)
def symmetric_difference_update(self, other):
"""
``s.symmetric_difference_update(t)`` updates nodeset s keeping all
nodes that are in exactly one of the nodesets.
"""
purge_patterns = []
# iterate over our rangesets
for pat, rangeset in self._patterns.items():
brangeset = other._patterns.get(pat)
if brangeset:
rangeset.symmetric_difference_update(brangeset)
else:
if pat in other._patterns:
purge_patterns.append(pat)
# iterate over other's rangesets
for pat, brangeset in other._patterns.items():
rangeset = self._patterns.get(pat)
if not rangeset and not pat in self._patterns:
self._add(pat, brangeset)
# check for patterns cleanup
for pat, rangeset in self._patterns.items():
if rangeset is not None and len(rangeset) == 0:
purge_patterns.append(pat)
# cleanup
for pat in purge_patterns:
del self._patterns[pat]
def __ixor__(self, 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)
"""
self._binary_sanity_check(other)
self.symmetric_difference_update(other)
return self
def _strip_escape(nsstr):
"""
Helper to prepare a nodeset string for parsing: trim boundary
whitespaces and escape special characters.
"""
return nsstr.strip().replace('%', '%%')
def _rsets4nsb(rsets, autostep):
"""
Helper to convert a list of RangeSet objects into the proper object
for NodeSetBase: RangeSet, RangeSetND or None (no node index).
"""
if len(rsets) > 1:
return RangeSetND([rsets], None, autostep, copy_rangeset=False)
elif len(rsets) == 1:
return rsets[0]
class ParsingEngine(object):
"""
Class that is able to transform a source into a NodeSetBase.
"""
OP_CODES = {',': 'update',
'!': 'difference_update',
'&': 'intersection_update',
'^': 'symmetric_difference_update'}
OP_CODES_PAT = '[%s]' % re.escape(''.join(OP_CODES.keys()))
BRACKET_OPEN = '['
BRACKET_CLOSE = ']'
def __init__(self, group_resolver, node_wildcard_enable=True):
"""
Initialize Parsing Engine.
"""
self.group_resolver = group_resolver
self.base_node_re = re.compile(r"(\D*)(\d*)")
self.node_wc = node_wildcard_enable # node wildcard support
def parse(self, nsobj, autostep):
"""
Parse provided object if possible and return a NodeSetBase object.
"""
# passing None is supported
if nsobj is None:
return NodeSetBase()
# is nsobj a NodeSetBase instance?
if isinstance(nsobj, NodeSetBase):
return nsobj
# or is nsobj a string?
if isinstance(nsobj, basestring):
try:
return self.parse_string(str(nsobj), autostep)
except (NodeUtils.GroupSourceQueryFailed, RuntimeError) as exc:
raise NodeSetParseError(nsobj, str(exc))
raise TypeError("Unsupported NodeSet input %s" % type(nsobj))
def parse_string(self, nsstr, autostep, namespace=None):
"""Parse provided string in optional namespace.
This method parses string, resolves all node groups, and
computes set operations.
Return a NodeSetBase object.
"""
alln_cache = None # used to compute 'all nodes' only once
nodeset = NodeSetBase()
nsstr = _strip_escape(nsstr)
for opc, pat, rgnd in self._scan_string(nsstr, autostep):
# Parser main debugging:
#print "OPC %s PAT %s RANGESETS %s" % (opc, pat, rgnd)
if self.group_resolver and pat[0] == '@':
ns_group = NodeSetBase()
for nodegroup in NodeSetBase(pat, rgnd):
# parse/expand nodes group: get group string and namespace
ns_str_ext, ns_nsp_ext = self.parse_group_string(nodegroup,
namespace)
if ns_str_ext: # may still contain groups
# recursively parse and aggregate result
ns_group.update(self.parse_string(ns_str_ext,
autostep,
ns_nsp_ext))
# perform operation
getattr(nodeset, opc)(ns_group)
elif self.group_resolver and self.node_wc and ('*' in pat or
'?' in pat):
# We support ranges with wildcard mask by testing all nodes
# against each expanded mask (wcmasks).
wcmasks = (str(wcn) for wcn in NodeSetBase(pat, rgnd, False))
# Our reference set is 'all nodes', we need to build it from
# NodeSetBase to iterate over each individual node.
if alln_cache is None:
self.node_wc = False # avoid infinite recursion
try:
nsb = NodeSetBase()
for res in self.all_nodes(namespace):
nsb.update(self.parse_string(res, autostep,
namespace))
alln_cache = set(str(node) for node in nsb)
finally:
self.node_wc = True
alln = alln_cache.copy()
# A wildcarded nodeset can be seen as a single nodeset, so we
# compute the union of nodes matching the wildcard mask(s) and
# use the resulting NodeSetBase object as argument of the next
# operation (opc).
wcns = NodeSetBase()
for wcmask in wcmasks:
# Expand nodes matching any of the wildcard mask
for node in fnmatch.filter(alln, wcmask):
alln.remove(node) # remove matching node for next iter
wcp, wcr = self._scan_string_single(node, autostep)
wcrgnd = _rsets4nsb(wcr, autostep)
wcns.update(NodeSetBase(wcp, wcrgnd, False))
getattr(nodeset, opc)(wcns)
else:
getattr(nodeset, opc)(NodeSetBase(pat, rgnd, False))
return nodeset
def parse_string_single(self, nsstr, autostep):
"""Parse provided string and return a NodeSetBase object."""
pat, rangesets = self._scan_string_single(_strip_escape(nsstr),
autostep)
if len(rangesets) > 1:
rgobj = RangeSetND([rangesets], None, autostep, copy_rangeset=False)
elif len(rangesets) == 1:
rgobj = rangesets[0]
else: # non-indexed nodename
rgobj = None
return NodeSetBase(pat, rgobj, False)
def parse_group(self, group, namespace=None, autostep=None):
"""Parse provided single group name (without @ prefix)."""
assert self.group_resolver is not None
nodestr = self.group_resolver.group_nodes(group, namespace)
return self.parse(",".join(nodestr), autostep)
def parse_group_string(self, nodegroup, namespace=None):
"""Parse provided raw nodegroup string in optional namespace.
Warning: 1 pass only, may still return groups.
Return a tuple (grp_resolved_string, namespace).
"""
assert nodegroup[0] == '@'
assert self.group_resolver is not None
grpstr = group = nodegroup[1:]
if grpstr.find(':') >= 0:
# specified namespace does always override
namespace, group = grpstr.split(':', 1)
if group == '*': # @* or @source:* magic
reslist = self.all_nodes(namespace)
elif group.startswith('@'): # @@source group name list
reslist = self.grouplist(grpstr[1:])
else:
reslist = self.group_resolver.group_nodes(group, namespace)
return ','.join(reslist), namespace
def grouplist(self, namespace=None):
"""
Return a sorted list of groups from current resolver (in optional
group source / namespace).
"""
grpset = NodeSetBase()
for grpstr in self.group_resolver.grouplist(namespace):
# We scan each group string to expand any range seen...
grpstr = _strip_escape(grpstr)
for opc, pat, rgnd in self._scan_string(grpstr, None):
getattr(grpset, opc)(NodeSetBase(pat, rgnd, False))
return list(grpset)
def all_nodes(self, namespace=None):
"""Get all nodes from group resolver as a list of strings."""
# namespace is the optional group source
assert self.group_resolver is not None
alln = []
try:
# Ask resolver to provide all nodes.
alln = self.group_resolver.all_nodes(namespace)
except NodeUtils.GroupSourceNoUpcall:
try:
# As the resolver is not able to provide all nodes directly,
# failback to list + map(s) method:
for grp in self.grouplist(namespace):
alln += self.group_resolver.group_nodes(grp, namespace)
except NodeUtils.GroupSourceNoUpcall:
# We are not able to find "all" nodes, definitely.
msg = "Not enough working methods (all or map + list) to " \
"get all nodes"
raise NodeSetExternalError(msg)
except NodeUtils.GroupSourceQueryFailed as exc:
raise NodeSetExternalError("Failed to get all nodes: %s" % exc)
return alln
def _next_op(self, pat):
"""Opcode parsing subroutine."""
mobj = re.search(ParsingEngine.OP_CODES_PAT, pat)
if mobj:
return mobj.span()[0], mobj.group()
else:
return -1, None
def _scan_string_single(self, nsstr, autostep):
"""Single node scan, returns (pat, list of rangesets)"""
# single node parsing
pfx_nd = [mobj.groups() for mobj in self.base_node_re.finditer(nsstr)]
pfx_nd = pfx_nd[:-1]
if not pfx_nd:
raise NodeSetParseError(nsstr, "parse error")
pat = ""
rangesets = []
for pfx, idx in pfx_nd:
if idx:
# optimization: process single index padding directly
pad = 0
if int(idx) != 0:
idxs = idx.lstrip("0")
if len(idx) - len(idxs) > 0:
pad = len(idx)
idxint = int(idxs)
else:
if len(idx) > 1:
pad = len(idx)
idxint = 0
if idxint > 1e100:
raise NodeSetParseRangeError( \
RangeSetParseError(idx, "invalid rangeset index"))
# optimization: use numerical RangeSet constructor
pat += "%s%%s" % pfx
rangesets.append(RangeSet.fromone(idxint, pad, autostep))
else:
# undefined pad means no node index
pat += pfx
return pat, rangesets
def _scan_string(self, nsstr, autostep):
"""Parsing engine's string scanner method (iterator)."""
next_op_code = ',' # if no operator, default one is to update nodeset
while nsstr:
# Ignore whitespace(s) for convenience
nsstr = nsstr.lstrip()
rsets = []
op_code = next_op_code
op_idx, next_op_code = self._next_op(nsstr)
bracket_idx = nsstr.find(self.BRACKET_OPEN)
# Check if the operator is after the bracket, or if there
# is no operator at all but some brackets.
if bracket_idx >= 0 and (op_idx > bracket_idx or op_idx < 0):
# In this case, we have a pattern of potentially several
# nodes.
# Fill prefix, range and suffix from pattern
# eg. "forbin[3,4-10]-ilo" -> "forbin", "3,4-10", "-ilo"
newpat = ""
sfx = nsstr
while bracket_idx >= 0 and (op_idx > bracket_idx or op_idx < 0):
pfx, sfx = sfx.split(self.BRACKET_OPEN, 1)
try:
rng, sfx = sfx.split(self.BRACKET_CLOSE, 1)
except ValueError:
raise NodeSetParseError(nsstr, "missing bracket")
# illegal closing bracket checks
if pfx.find(self.BRACKET_CLOSE) > -1:
raise NodeSetParseError(pfx, "illegal closing bracket")
if len(sfx) > 0:
bra_end = sfx.find(self.BRACKET_CLOSE)
bra_start = sfx.find(self.BRACKET_OPEN)
if bra_start == -1:
bra_start = bra_end + 1
if bra_end >= 0 and bra_end < bra_start:
msg = "illegal closing bracket"
raise NodeSetParseError(sfx, msg)
pfxlen, sfxlen = len(pfx), len(sfx)
if sfxlen > 0:
try:
# amending trailing digits generates /steps
sfx, rng = self._amend_trailing_digits(sfx, rng)
except RangeSetParseError as ex:
raise NodeSetParseRangeError(ex)
if pfxlen > 0:
try:
# this method supports /steps
pfx, rng = self._amend_leading_digits(pfx, rng)
except RangeSetParseError as ex:
raise NodeSetParseRangeError(ex)
if pfx:
# scan any nonempty pfx as a single node (no bracket)
pfx, pfxrvec = self._scan_string_single(pfx, autostep)
rsets += pfxrvec
# readahead for sanity check
bracket_idx = sfx.find(self.BRACKET_OPEN,
bracket_idx - pfxlen)
op_idx, next_op_code = self._next_op(sfx)
if len(sfx) > 0 and sfx[0] == '[':
msg = "illegal reopening bracket"
raise NodeSetParseError(sfx, msg)
newpat += "%s%%s" % pfx
try:
rsets.append(RangeSet(rng, autostep))
except RangeSetParseError as ex:
raise NodeSetParseRangeError(ex)
# Check if we have a next op-separated node or pattern
op_idx, next_op_code = self._next_op(sfx)
if op_idx < 0:
nsstr = None
else:
sfx, nsstr = sfx.split(next_op_code, 1)
# Detected character operator so right operand is mandatory
if not nsstr:
msg = "missing nodeset operand with '%s' " \
"operator" % next_op_code
raise NodeSetParseError(None, msg)
# Ignore whitespace(s)
sfx = sfx.rstrip()
if sfx:
sfx, sfxrvec = self._scan_string_single(sfx, autostep)
newpat += sfx
rsets += sfxrvec
else:
# In this case, either there is no comma and no bracket,
# or the bracket is after the comma, then just return
# the node.
if op_idx < 0:
node = nsstr
nsstr = None # break next time
else:
node, nsstr = nsstr.split(next_op_code, 1)
# Detected character operator so both operands are mandatory
if not node or not nsstr:
msg = "missing nodeset operand with '%s' " \
"operator" % next_op_code
raise NodeSetParseError(node or nsstr, msg)
# Check for illegal closing bracket
if node.find(self.BRACKET_CLOSE) > -1:
raise NodeSetParseError(node, "illegal closing bracket")
# Ignore whitespace(s)
node = node.rstrip()
newpat, rsets = self._scan_string_single(node, autostep)
op = ParsingEngine.OP_CODES[op_code]
yield op, newpat, _rsets4nsb(rsets, autostep)
def _amend_leading_digits(self, outer, inner):
"""Helper to get rid of leading bracket digits.
Take a bracket outer prefix string and an inner range set string and
return amended strings.
"""
outerstrip = outer.rstrip(string.digits)
outerlen, outerstriplen = len(outer), len(outerstrip)
if outerstriplen < outerlen:
# get outer bracket leading digits
outerdigits = outer[outerstriplen:]
inner = ','.join(
'-'.join(outerdigits + bound for bound in elem.split('-'))
for elem in (str(subrng)
for subrng in RangeSet(inner).contiguous()))
return outerstrip, inner
def _amend_trailing_digits(self, outer, inner):
"""Helper to get rid of trailing bracket digits.
Take a bracket outer suffix string and an inner range set string and
return amended strings.
"""
outerstrip = outer.lstrip(string.digits)
outerlen, outerstriplen = len(outer), len(outerstrip)
if outerstriplen < outerlen:
# step syntax is not compatible with trailing digits
if '/' in inner:
msg = "illegal trailing digits after range with steps"
raise NodeSetParseError(outer, msg)
# get outer bracket trailing digits
outerdigits = outer[0:outerlen-outerstriplen]
outlen = len(outerdigits)
def shiftstep(orig, power):
"""Add needed step after shifting range indexes"""
if '-' in orig:
return orig + '/1' + '0' * power
return orig # do not use /step for single index
inner = ','.join(shiftstep(s, outlen) for s in
('-'.join(bound + outerdigits
for bound in elem.split('-'))
for elem in inner.split(',')))
return outerstrip, inner
[docs]
class NodeSet(NodeSetBase):
"""
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 accordingly.
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
"""
_VERSION = 2
[docs]
def __init__(self, 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
:class:`.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
:class:`.NodeUtils.GroupResolver` object, to the ``RESOLVER_NOGROUP``
constant to disable any group resolution, or to None (default) to use
standard NodeSet group resolver (see :func:`.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 suboptimal folding, this is because NodeSet algorithms are
optimized for folding along all axis (default behavior).
"""
NodeSetBase.__init__(self, autostep=autostep, fold_axis=fold_axis)
# Set group resolver.
if resolver in (RESOLVER_NOGROUP, RESOLVER_NOINIT):
self._resolver = None
else:
self._resolver = resolver or RESOLVER_STD_GROUP
# Initialize default parser.
if resolver == RESOLVER_NOINIT:
self._parser = None
else:
self._parser = ParsingEngine(self._resolver)
self.update(nodes)
@classmethod
def _fromlist1(cls, nodelist, autostep=None, resolver=None):
"""Class method that returns a new NodeSet with single nodes from
provided list (optimized constructor)."""
inst = NodeSet(autostep=autostep, resolver=resolver)
for single in nodelist:
inst.update(inst._parser.parse_string_single(single, autostep))
return inst
[docs]
@classmethod
def fromlist(cls, nodelist, autostep=None, resolver=None):
"""Class method that returns a new NodeSet with nodes from provided
list."""
inst = NodeSet(autostep=autostep, resolver=resolver)
inst.updaten(nodelist)
return inst
[docs]
@classmethod
def fromall(cls, groupsource=None, autostep=None, resolver=None):
"""Class method that returns a new NodeSet with all nodes from optional
groupsource."""
inst = NodeSet(autostep=autostep, resolver=resolver)
try:
if not inst._resolver:
raise NodeSetExternalError("Group resolver is not defined")
else:
# fill this nodeset with all nodes found by resolver
inst.updaten(inst._parser.all_nodes(groupsource))
except NodeUtils.GroupResolverError as exc:
errmsg = "Group source error (%s: %s)" % (exc.__class__.__name__,
exc)
raise NodeSetExternalError(errmsg)
return inst
[docs]
def __getstate__(self):
"""Called when pickling: remove references to group resolver."""
odict = self.__dict__.copy()
odict['_version'] = NodeSet._VERSION
del odict['_resolver']
del odict['_parser']
return odict
[docs]
def __setstate__(self, dic):
"""Called when unpickling: restore parser using non group
resolver."""
self.__dict__.update(dic)
self._resolver = None
self._parser = ParsingEngine(None)
if getattr(self, '_version', 1) <= 1:
self.fold_axis = None
# if setting state from first version, a conversion is needed to
# support native RangeSetND
old_patterns = self._patterns
self._patterns = {}
for pat, rangeset in sorted(old_patterns.items()):
if rangeset:
assert isinstance(rangeset, RangeSet)
rgs = str(rangeset)
if len(rangeset) > 1:
rgs = "[%s]" % rgs
self.update(pat % rgs)
else:
self.update(pat)
[docs]
def copy(self):
"""Return a shallow copy of a NodeSet."""
cpy = self.__class__(resolver=RESOLVER_NOINIT)
dic = {}
for pat, rangeset in self._patterns.items():
if rangeset is None:
dic[pat] = None
else:
dic[pat] = rangeset.copy()
cpy._patterns = dic
cpy.fold_axis = self.fold_axis
cpy._autostep = self._autostep
cpy._resolver = self._resolver
cpy._parser = self._parser
return cpy
__copy__ = copy # For the copy module
def _find_groups(self, node, namespace, allgroups):
"""Find groups of node by namespace."""
if allgroups:
# find node groups using in-memory allgroups
for grp, nodeset in allgroups.items():
if node in nodeset:
yield grp
else:
# find node groups using resolver
try:
for group in self._resolver.node_groups(node, namespace):
yield group
except NodeUtils.GroupSourceQueryFailed as exc:
msg = "Group source query failed: %s" % exc
raise NodeSetExternalError(msg)
def _groups2(self, groupsource=None, autostep=None):
"""Find node groups this nodeset belongs to. [private]"""
if not self._resolver:
raise NodeSetExternalError("No node group resolver")
try:
# Get all groups in specified group source.
allgrplist = self._parser.grouplist(groupsource)
except NodeUtils.GroupSourceError:
# If list query failed, we still might be able to regroup
# using reverse.
allgrplist = None
groups_info = {}
allgroups = {}
# Check for external reverse presence, and also use the
# following heuristic: external reverse is used only when number
# of groups is greater than the NodeSet size.
if self._resolver.has_node_groups(groupsource) and \
(not allgrplist or len(allgrplist) >= len(self)):
# use external reverse
pass
else:
if not allgrplist: # list query failed and no way to reverse!
return groups_info # empty
try:
# use internal reverse: populate allgroups
for grp in allgrplist:
nodelist = self._resolver.group_nodes(grp, groupsource)
allgroups[grp] = NodeSet(",".join(nodelist),
resolver=self._resolver)
except NodeUtils.GroupSourceQueryFailed as exc:
# External result inconsistency
raise NodeSetExternalError("Unable to map a group " \
"previously listed\n\tFailed command: %s" % exc)
# For each NodeSetBase in self, find its groups.
for node in self._iterbase():
for grp in self._find_groups(node, groupsource, allgroups):
if grp not in groups_info:
nodes = self._parser.parse_group(grp, groupsource, autostep)
groups_info[grp] = (1, nodes)
else:
i, nodes = groups_info[grp]
groups_info[grp] = (i + 1, nodes)
return groups_info
[docs]
def groups(self, 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.
"""
groups = self._groups2(groupsource, self._autostep)
result = {}
for grp, (_, nsb) in groups.items():
if groupsource and not noprefix:
key = "@%s:%s" % (groupsource, grp)
else:
key = "@" + grp
result[key] = (NodeSet(nsb, resolver=self._resolver),
self.intersection(nsb))
return result
[docs]
def regroup(self, 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()."""
groups = self._groups2(groupsource, autostep)
if not groups:
return str(self)
# Keep only groups that are full.
fulls = []
for k, (i, nodes) in groups.items():
assert i <= len(nodes)
if i == len(nodes):
fulls.append((i, k))
rest = NodeSet(self, resolver=RESOLVER_NOGROUP)
regrouped = NodeSet(resolver=RESOLVER_NOGROUP)
# Build regrouped NodeSet by selecting largest groups first.
for _, grp in sorted(fulls, key=lambda x: (-x[0], x[1])):
if not overlap and groups[grp][1] not in rest:
continue
if groupsource and not noprefix:
regrouped.update("@%s:%s" % (groupsource, grp))
else:
regrouped.update("@" + grp)
rest.difference_update(groups[grp][1])
if not rest:
return str(regrouped)
if regrouped:
return "%s,%s" % (regrouped, rest)
return str(rest)
[docs]
def issubset(self, other):
"""
Report whether another nodeset contains this nodeset.
"""
nodeset = self._parser.parse(other, self._autostep)
return NodeSetBase.issuperset(nodeset, self)
[docs]
def issuperset(self, other):
"""
Report whether this nodeset contains another nodeset.
"""
nodeset = self._parser.parse(other, self._autostep)
return NodeSetBase.issuperset(self, nodeset)
[docs]
def __getitem__(self, index):
"""
Return the node at specified index or a subnodeset when a slice
is specified.
"""
base = NodeSetBase.__getitem__(self, index)
if not isinstance(base, NodeSetBase):
return base
# return a real NodeSet
inst = NodeSet(autostep=self._autostep, resolver=self._resolver)
inst._patterns = base._patterns
return inst
[docs]
def index(self, other, start=0, stop=None):
"""Return the zero-based index in the nodeset of the node `other`.
Like the ``index()`` method of the ``list`` type, this returns the
position of `other` when iterating over the nodeset and raises a
:class:`ValueError` if the node is not present. The optional `start`
and `stop` arguments restrict the search and may be negative.
The `other` argument is a single node and may be provided as a string
(it is parsed, so node groups are resolved if any).
>>> NodeSet("node[0-9,20]").index("node20")
10
"""
nodeset = self._parser.parse(other, self._autostep)
return NodeSetBase.index(self, nodeset, start, stop)
[docs]
def split(self, 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
"""
assert(nbr > 0)
# We put the same number of element in each sub-nodeset.
slice_size = len(self) // nbr
left = len(self) % nbr
begin = 0
for i in range(0, min(nbr, len(self))):
length = slice_size + int(i < left)
yield self[begin:begin + length]
begin += length
[docs]
def update(self, other):
"""
s.update(t) returns nodeset s with elements added from t.
"""
nodeset = self._parser.parse(other, self._autostep)
NodeSetBase.update(self, nodeset)
[docs]
def intersection_update(self, other):
"""
s.intersection_update(t) returns nodeset s keeping only
elements also found in t.
"""
nodeset = self._parser.parse(other, self._autostep)
NodeSetBase.intersection_update(self, nodeset)
[docs]
def difference_update(self, 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.
"""
nodeset = self._parser.parse(other, self._autostep)
NodeSetBase.difference_update(self, nodeset, strict)
[docs]
def symmetric_difference_update(self, other):
"""
s.symmetric_difference_update(t) returns nodeset s keeping all
nodes that are in exactly one of the nodesets.
"""
nodeset = self._parser.parse(other, self._autostep)
NodeSetBase.symmetric_difference_update(self, nodeset)
[docs]
def expand(pat):
"""
Commodity function that expands a nodeset pattern into a list of nodes.
"""
return list(NodeSet(pat))
[docs]
def fold(pat):
"""
Commodity function that clean dups and fold provided pattern with ranges
and "/step" support.
"""
return str(NodeSet(pat))
[docs]
def 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 "@".
"""
return ParsingEngine(resolver or RESOLVER_STD_GROUP).grouplist(namespace)
[docs]
def std_group_resolver():
"""
Get the current resolver used for standard "@" group resolution.
"""
return RESOLVER_STD_GROUP
[docs]
def 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.
"""
global RESOLVER_STD_GROUP
RESOLVER_STD_GROUP = new_resolver or _DEF_RESOLVER_STD_GROUP
[docs]
def set_std_group_resolver_config(groupsconf, illegal_chars=None):
"""
Helper to create and set std group resolver from a config file path.
By default, the GroupResolverConfig object is created using
illegal_chars=NodeSet.ILLEGAL_GROUP_CHARS.
This method does nothing if groupsconf is not defined.
"""
if groupsconf:
if illegal_chars is None:
illegal_chars = ILLEGAL_GROUP_CHARS
group_resolver = NodeUtils.GroupResolverConfig(groupsconf,
illegal_chars)
set_std_group_resolver(group_resolver)