t/moe/config.py

   1 """
   2 Lazy conditional string evaluation module for Moe configuration variables.
   3
   4 * Each variable has ordered list of operations (definitions), each defining operation either
   5   assigns (SET) or appends (APPEND) value of an expression to the variable. Each operation may be guarded by condition(s).
   6
   7 * Each condition is a formula (tree consisting of 'AND', 'OR', 'NOT' and '==', '!=' between two expressions.
   8
   9 * Expression is a list of strings and variables to be expanded.
  10
  11 .. note:: If no 'SET' applies, a variable is still undefined even if some 'APPEND' applies. This might change.
  12 .. note:: All expanded data should be (or is converted to) unicode
  13 .. todo:: (OPT) Cleanup of unused undefined variables.
  14 .. todo:: (OPT) Better variable name checking (no name '.'-structural prefix of another)
  15 .. todo:: (OPT) Implemet "subtree" listing.
  16 """
  17
  18 import types, itertools, re, bisect
  19 import logging as log
  20
  21 from moe import MoeError
  22
  23
  24 "Allowed depth of recursion - includes ALL recursive calls, so should quite high."
  25 c_maxdepth = 256
  26
  27 "Maximum attained depth of recursion - for debug/testing"
  28 debug_maxdepth = 0
  29
  30 "Variable name regexp, dots (separators) must be separated from edges and each other."
  31 re_VARNAME = re.compile(r'\A([A-Za-z0-9_-]+\.)*[A-Za-z0-9_-]+\Z')
  32
  33
  34 def check_depth(depth):
  35   "Helper to check for recursion depth."
  36   global debug_maxdepth
  37   if depth > c_maxdepth:
  38     raise CyclicConfigError('Too deep recursion in config evaluation (cyclic substitution?)')
  39   if depth > debug_maxdepth:
  40     debug_maxdepth = depth
  41
  42
  43 class ConfigError(MoeError):
  44   pass
  45
  46 class UndefinedError(ConfigError):
  47   pass
  48
  49 class VariableNameError(ConfigError):
  50   pass
  51
  52 class VariableFixedError(ConfigError):
  53   pass
  54
  55 class CyclicConfigError(ConfigError):
  56   pass
  57
  58
  59 class ConfigTree(object):
  60   """
  61   Configuration tree containing all the variables.
  62
  63   The variables in `self.variables` are referenced directly by the full name.
  64   """
  65
  66   def __init__(self):
  67     self.variables = {}
  68
  69   def lookup(self, key, create = True):
  70     """
  71     Lookup and return a variable.
  72     If not found and `create` set, check the name and transparently create a new one.
  73     """
  74     if key not in self.variables:
  75       if not re_VARNAME.match(key):
  76         raise VariableNameError('Invalid variable identifier %r in config', key)
  77       if not create:
  78         raise UndefinedError('Config variable %r undefined.', key)
  79       self.variables[key] = ConfigVar(key)
  80     return self.variables[key]
  81
  82   def __getitem__(self, key):
  83     """
  84     Return the value of an existing variable.
  85     """
  86     return self.lookup(key, create=False).value()
  87
  88   def dump(self, prefix=''):
  89     """
  90     Pretty printing of the tree.
  91     Returns an iterator of lines (strings).
  92     """
  93     return itertools.chain(*[
  94       self.variables[k].dump(prefix) for k in sorted(self.variables.keys())
  95       ])
  96
  97   def fix(self, keys):
  98     "Fix value of variable or list of variables. Fixing undefined variable raises `UndefinedError`."
  99     if isinstance(keys, types.StringTypes):
 100       keys = [keys]
 101     for key in keys:
 102       self.lookup(key, create=True).fix()
 103
 104   def parse(self, s, source=None, level=0):
 105     """Parse `s` (stream/string) into the tree, see `moe.confparser.ConfigParser` for details."""
 106     import moe.config_parser
 107     p = moe.config_parser.ConfigParser(s, self, source=source, level=level)
 108     p.parse()
 109
 110   def parse_file(self, filename, desc=None, level=0):
 111     """Parse an utf-8 file into the tree, see `moe.confparser.ConfigParser` for details.
 112     Names the source "`filename` <`desc`>". """
 113     with open(filename, 'rt') as f:
 114       if desc:
 115         filename += " <" + desc + ">"
 116       self.parse(f, source=filename, level=level)
 117
 118
 119 class ConfigElem(object):
 120   """
 121   Base class for cahed config elements - variables and conditions
 122   """
 123
 124   def __init__(self, name):
 125     # Full name with separators, definition for conditions
 126     self.name = name
 127     # Vars and conditions depending on value of this one
 128     self.dependants = set([])
 129     # Cached value (may be None in case of evaluation error)
 130     self.cached = False
 131     self.cached_val = None
 132
 133   def invalidate(self, depth=0):
 134     """
 135     Invalidate cached data and invalidate all dependants.
 136     Does nothing if not cached.
 137     """
 138     check_depth(depth)
 139     if self.cached:
 140       log.debug('invalidating %s', self)
 141       self.cached = False
 142       for d in self.dependants:
 143         d.invalidate(depth + 1)
 144
 145   def value(self, depth=0):
 146     "Caching helper calling self.evaluate(), returns a value or throws an exception."
 147     check_depth(depth)
 148     if not self.cached:
 149       self.cached_val = self.evaluate(depth=depth+1)
 150       self.cached = True
 151     if self.cached_val == None:
 152       raise UndefinedError("Unable to evaluate %r."%(self.name,))
 153     return self.cached_val
 154
 155   def __str__(self):
 156     return self.name
 157
 158
 159 class ConfigCondition(ConfigElem):
 160   """
 161   Condition using equality and logic operators.
 162   Clause is a tuple-tree in the following recursive form::
 163
 164     ('AND', c1, c1), ('OR', c1, c2), ('NOT', c1), ('==', e1, e2), ('!=', e1, e2)
 165
 166   where e1, e2 are `ConfigExpression`, c1, c2, `ConfigCondition`.
 167   """
 168
 169   def __init__(self, formula, text=None, parent=None):
 170     """
 171     Condition defined by `text` (informative), `formula` as in class definition,
 172     `parent` is the parent condition (if any).
 173     """
 174     if not text:
 175       text = self.formula_string(formula)
 176     super(ConfigCondition, self).__init__(text)
 177     self.formula = formula
 178     self.parent = parent
 179     # Setup dependencies on used variables (not on the parent condition)
 180     for v in self.variables():
 181       v.dependants.add(self)
 182     if self.parent:
 183       self.parent.dependants.add(self)
 184
 185   def variables(self, cl=None):
 186     "Return an iterator of variables used in formula `cl`"
 187     if not cl:
 188       cl = self.formula
 189     if cl[0] in ['==','!=']:
 190       return itertools.chain(cl[1].variables(), cl[2].variables())
 191     if cl[0] in ['AND','OR']:
 192       return itertools.chain(self.variables(cl[1]), self.variables(cl[2]))
 193     return self.variables(cl[1]) # only 'NOT' left
 194
 195   def remove_dependencies(self):
 196     "Remove self as a dependant from all used variables"
 197     for v in self.variables():
 198       v.dependants.discard(self)
 199     if self.parent:
 200       self.parent.dependants.discard(self)
 201
 202   def evaluate(self, cl=None, depth=0):
 203     """Evaluate formula `cl` (or the entire condition).
 204     Partial evaluation for AND and OR. Tests the parent condition first."""
 205     check_depth(depth)
 206     if not cl:
 207       cl = self.formula
 208     if self.parent and not self.parent.value():
 209       return False
 210     if cl[0] in ['==','!=']:
 211       v = cl[1].evaluate(depth=depth+1) == cl[2].evaluate(depth=depth+1)
 212       if cl[0] == '!=': v = not v
 213       return v
 214     v1 = self.evaluate(cl=cl[1], depth=depth+1)
 215     if cl[0] == 'NOT':
 216       return not v1
 217     if cl[0] == 'OR' and v1: return True
 218     if cl[0] == 'AND' and not v1: return False
 219     return self.evaluate(cl=cl[2], depth=depth+1)
 220
 221   def formula_string(self, formula):
 222     "Create a string representation of a formula."
 223     if formula[0] == 'AND':
 224       return itertools.chain(['('], self.formula_string(formula[1]), [' and '], self.formula_string(formula[2]),[')'])
 225     elif formula[0] == 'OR':
 226       return itertools.chain(['('], self.formula_string(formula[1]), [' or '], self.formula_string(formula[2]),[')'])
 227     elif formula[0] == 'NOT':
 228       return itertools.chain(['(not '], self.formula_string(formula[1]),[')'])
 229     elif formula[0] in ['==', '!=']:
 230       return itertools.chain(formula[1], formula[0], formula[2])
 231     return iter(['<invalid formula>'])
 232
 233   def str(self, parents=False):
 234     "Retur the defining expression, if `parents` set, then prefixed with parent conditions."
 235     if parents and self.parent:
 236       return self.parent.str(parents=True) + u' && ' + self.name
 237     return self.name
 238
 239   def __str__(self):
 240     return self.str(parents=False)
 241
 242
 243 class Operation(object):
 244   "Helper class for operation data. Must not be present in more variables or present multiple times."
 245
 246   def __init__(self, operation, condition, expression, level=0, source='?'):
 247     # operation is currently 'SET' and 'APPEND'
 248     self.operation = operation
 249     self.condition = condition
 250     self.expression = expression
 251     self.level = level
 252     self.source = source
 253
 254   def __str__(self):
 255     return "%s <%d, %s> [%s] %r" % ( {'SET':'=', 'APPEND':'+'}[self.operation], self.level, self.source,
 256       (self.condition and self.condition.str(parents=True)) or '', unicode(self.expression))
 257
 258
 259 class ConfigVar(ConfigElem):
 260
 261   def __init__(self, name):
 262     super(ConfigVar, self).__init__(name)
 263     # Ordered list of `Operations` (ascending by `level`)
 264     self.operations = []
 265     # Fixed to value (may be None)
 266     self.fixed = False
 267     self.fixed_val = None
 268
 269   def variables(self):
 270     "Return a set of variables used in the expressions"
 271     return set(sum([ list(op.expression.variables()) for op in self.operations ], []))
 272
 273   def fix(self):
 274     """
 275     Fixes the value of the variable. Exception is raised should the variable
 276     evaluate to a different value while fixed.
 277     """
 278     if self.fixed:
 279       return
 280     self.fixed_val = self.value()
 281     self.fixed = True
 282
 283   def unfix(self):
 284     "Make the variable modifiable again."
 285     self.fixed = False
 286
 287   def value(self, depth=0):
 288     "Handle the case when fixed, raise exc. on different evaluation"
 289     val = super(ConfigVar,self).value(depth)
 290     if self.fixed and self.fixed_val != val:
 291       raise VariableFixedError("value of var %r was fixed to %r but evaluated to %r", self.name, self.fixed_val, val)
 292     return val
 293
 294   def add_operation(self, operation):
 295     """
 296     Inserts an operation. The operations are sorted by `level` (ascending), new operation goes last among
 297     these with the same level.
 298     Adds the variable as a dependant of the conditions and variables used in the expressions.
 299     """
 300     # Invalidate cached value
 301     self.invalidate()
 302     # Add the operation
 303     pos = bisect.bisect_right([o.level for o in self.operations], operation.level)
 304     self.operations.insert(pos, operation)
 305     # Create dependencies
 306     for v in operation.expression.variables():
 307       v.dependants.add(self)
 308     if operation.condition:
 309       operation.condition.dependants.add(self)
 310
 311   def remove_operation(self, operation):
 312     """
 313     Remove the Operation.
 314     Also removes the variable as dependant from all conditions and variables used in this
 315     operation that are no longer used.
 316     """
 317     # Invalidate cached value
 318     self.invalidate()
 319     # Remove the operation
 320     self.operations.remove(operation)
 321     # Remove dependencies on variables unused in other operations
 322     vs = self.variables()
 323     for v in operation.expression.variables():
 324       if v not in vs:
 325         v.dependants.remove(self)
 326     # Remove the dependency on the conditions (if not used in another operation)
 327     if operation.condition and operation.condition not in [op.condition for op in self.operations]:
 328       operation.condition.dependants.remove(self)
 329
 330   def evaluate(self, depth=0):
 331     """
 332     Find the last 'SET' operation that applies and return the result of concatenating with all
 333     subsequent applicable 'APPEND' operations. The result is the same as performing the operations
 334     first-to-last.
 335     NOTE: undefined if some 'APPEND' apply but no 'SET' applies.
 336     """
 337     check_depth(depth)
 338     log.debug('evaluating var %r', self.name)
 339     # List of strings to be concatenated
 340     val = []
 341     # Scan for last applicable expression - try each starting from the end, concatenate extensions
 342     for i in range(len(self.operations)-1, -1, -1):
 343       op = self.operations[i]
 344       # Check the guarding condition
 345       if (not op.condition) or op.condition.value(depth+1):
 346         val.insert(0, op.expression.evaluate(depth=depth+1))
 347         if op.operation == 'SET':
 348           return u''.join(val)
 349     return None
 350
 351   def dump(self, prefix=''):
 352     """
 353     Pretty printing of the variable. Includes all operations.
 354     Returns iterator of lines (unicode strings).
 355     """
 356     # Try to evaluate the variable, but avoid undefined exceptions
 357     v = None
 358     try:
 359       v = self.value(depth=0)
 360     except ConfigError:
 361       pass
 362     yield prefix+u'%s = %r' % (self.name, v)
 363     for op in self.operations:
 364       #yield prefix+u'  %s [%s] %s' % (op.operation, op.condition and op.condition.str(parents=True), op.expression)
 365       yield prefix + u'  ' + unicode(op)
 366
 367
 368 class ConfigExpression(object):
 369   """
 370   String expression with some unexpanded config variables. Used in variable operations and conditions.
 371   Expression is given as a list of unicode strings and ConfigVar variables to be expanded.
 372   """
 373
 374   def __init__(self, exprlist, original = u'<unknown>'):
 375     self.exprlist = list(exprlist)
 376     # Original defining string
 377     self.original = original
 378     # Replace strings with unicode
 379     for i in range(len(self.exprlist)):
 380       e = self.exprlist[i]
 381       if isinstance(e, types.StringTypes):
 382         if not isinstance(e, unicode):
 383           self.exprlist[i] = unicode(e, 'ascii')
 384
 385   def variables(self):
 386     "Return an iterator of variables user in the expression"
 387     return itertools.ifilter(lambda e: isinstance(e, ConfigVar), self.exprlist)
 388
 389   def __str__(self):
 390     return self.original
 391
 392   def evaluate(self, depth):
 393     check_depth(depth)
 394     "Return unicode result of expansion of the variables."
 395     s = []
 396     for e in self.exprlist:
 397       if isinstance(e, ConfigVar):
 398         s.append(e.value(depth+1))
 399       elif isinstance(e, unicode):
 400         s.append(e)
 401       else:
 402         raise ConfigError('Invalid type %s in expression \'%s\'.'%(type(e), self))
 403     return u''.join(s)
 404
 405