code.grnet.gr Git - ganeti-local/blob - lib/ht.py

   1 #
   2 #
   3
   4 # Copyright (C) 2010, 2011, 2012 Google Inc.
   5 #
   6 # This program is free software; you can redistribute it and/or modify
   7 # it under the terms of the GNU General Public License as published by
   8 # the Free Software Foundation; either version 2 of the License, or
   9 # (at your option) any later version.
  10 #
  11 # This program is distributed in the hope that it will be useful, but
  12 # WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 # General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with this program; if not, write to the Free Software
  18 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 # 02110-1301, USA.
  20
  21
  22 """Module implementing the parameter types code."""
  23
  24 import re
  25 import operator
  26
  27 from ganeti import compat
  28 from ganeti import utils
  29 from ganeti import constants
  30
  31
  32 _PAREN_RE = re.compile("^[a-zA-Z0-9_-]+$")
  33
  34
  35 def Parens(text):
  36   """Enclose text in parens if necessary.
  37
  38   @param text: Text
  39
  40   """
  41   text = str(text)
  42
  43   if _PAREN_RE.match(text):
  44     return text
  45   else:
  46     return "(%s)" % text
  47
  48
  49 class _WrapperBase(object):
  50   __slots__ = [
  51     "_fn",
  52     "_text",
  53     ]
  54
  55   def __init__(self, text, fn):
  56     """Initializes this class.
  57
  58     @param text: Description
  59     @param fn: Wrapped function
  60
  61     """
  62     assert text.strip()
  63
  64     self._text = text
  65     self._fn = fn
  66
  67   def __call__(self, *args):
  68     return self._fn(*args)
  69
  70
  71 class _DescWrapper(_WrapperBase):
  72   """Wrapper class for description text.
  73
  74   """
  75   def __str__(self):
  76     return self._text
  77
  78
  79 class _CommentWrapper(_WrapperBase):
  80   """Wrapper class for comment.
  81
  82   """
  83   def __str__(self):
  84     return "%s [%s]" % (self._fn, self._text)
  85
  86
  87 def WithDesc(text):
  88   """Builds wrapper class with description text.
  89
  90   @type text: string
  91   @param text: Description text
  92   @return: Callable class
  93
  94   """
  95   assert text[0] == text[0].upper()
  96
  97   return compat.partial(_DescWrapper, text)
  98
  99
 100 def Comment(text):
 101   """Builds wrapper for adding comment to description text.
 102
 103   @type text: string
 104   @param text: Comment text
 105   @return: Callable class
 106
 107   """
 108   assert not frozenset(text).intersection("[]")
 109
 110   return compat.partial(_CommentWrapper, text)
 111
 112
 113 def CombinationDesc(op, args, fn):
 114   """Build description for combinating operator.
 115
 116   @type op: string
 117   @param op: Operator as text (e.g. "and")
 118   @type args: list
 119   @param args: Operator arguments
 120   @type fn: callable
 121   @param fn: Wrapped function
 122
 123   """
 124   # Some type descriptions are rather long. If "None" is listed at the
 125   # end or somewhere in between it is easily missed. Therefore it should
 126   # be at the beginning, e.g. "None or (long description)".
 127   if __debug__ and TNone in args and args.index(TNone) > 0:
 128     raise Exception("TNone must be listed first")
 129
 130   if len(args) == 1:
 131     descr = str(args[0])
 132   else:
 133     descr = (" %s " % op).join(Parens(i) for i in args)
 134
 135   return WithDesc(descr)(fn)
 136
 137
 138 # Modifiable default values; need to define these here before the
 139 # actual LUs
 140
 141 @WithDesc(str([]))
 142 def EmptyList():
 143   """Returns an empty list.
 144
 145   """
 146   return []
 147
 148
 149 @WithDesc(str({}))
 150 def EmptyDict():
 151   """Returns an empty dict.
 152
 153   """
 154   return {}
 155
 156
 157 #: The without-default default value
 158 NoDefault = object()
 159
 160
 161 #: The no-type (value too complex to check it in the type system)
 162 NoType = object()
 163
 164
 165 # Some basic types
 166 @WithDesc("Anything")
 167 def TAny(_):
 168   """Accepts any value.
 169
 170   """
 171   return True
 172
 173
 174 @WithDesc("NotNone")
 175 def TNotNone(val):
 176   """Checks if the given value is not None.
 177
 178   """
 179   return val is not None
 180
 181
 182 @WithDesc("None")
 183 def TNone(val):
 184   """Checks if the given value is None.
 185
 186   """
 187   return val is None
 188
 189
 190 @WithDesc("ValueNone")
 191 def TValueNone(val):
 192   """Checks if the given value is L{constants.VALUE_NONE}.
 193
 194   """
 195   return val == constants.VALUE_NONE
 196
 197
 198 @WithDesc("Boolean")
 199 def TBool(val):
 200   """Checks if the given value is a boolean.
 201
 202   """
 203   return isinstance(val, bool)
 204
 205
 206 @WithDesc("Integer")
 207 def TInt(val):
 208   """Checks if the given value is an integer.
 209
 210   """
 211   # For backwards compatibility with older Python versions, boolean values are
 212   # also integers and should be excluded in this test.
 213   #
 214   # >>> (isinstance(False, int), isinstance(True, int))
 215   # (True, True)
 216   return isinstance(val, (int, long)) and not isinstance(val, bool)
 217
 218
 219 @WithDesc("Float")
 220 def TFloat(val):
 221   """Checks if the given value is a float.
 222
 223   """
 224   return isinstance(val, float)
 225
 226
 227 @WithDesc("String")
 228 def TString(val):
 229   """Checks if the given value is a string.
 230
 231   """
 232   return isinstance(val, basestring)
 233
 234
 235 @WithDesc("EvalToTrue")
 236 def TTrue(val):
 237   """Checks if a given value evaluates to a boolean True value.
 238
 239   """
 240   return bool(val)
 241
 242
 243 def TElemOf(target_list):
 244   """Builds a function that checks if a given value is a member of a list.
 245
 246   """
 247   def fn(val):
 248     return val in target_list
 249
 250   return WithDesc("OneOf %s" % (utils.CommaJoin(target_list), ))(fn)
 251
 252
 253 # Container types
 254 @WithDesc("List")
 255 def TList(val):
 256   """Checks if the given value is a list.
 257
 258   """
 259   return isinstance(val, list)
 260
 261
 262 @WithDesc("Tuple")
 263 def TTuple(val):
 264   """Checks if the given value is a tuple.
 265
 266   """
 267   return isinstance(val, tuple)
 268
 269
 270 @WithDesc("Dictionary")
 271 def TDict(val):
 272   """Checks if the given value is a dictionary.
 273
 274   """
 275   return isinstance(val, dict)
 276
 277
 278 def TIsLength(size):
 279   """Check is the given container is of the given size.
 280
 281   """
 282   def fn(container):
 283     return len(container) == size
 284
 285   return WithDesc("Length %s" % (size, ))(fn)
 286
 287
 288 # Combinator types
 289 def TAnd(*args):
 290   """Combine multiple functions using an AND operation.
 291
 292   """
 293   def fn(val):
 294     return compat.all(t(val) for t in args)
 295
 296   return CombinationDesc("and", args, fn)
 297
 298
 299 def TOr(*args):
 300   """Combine multiple functions using an AND operation.
 301
 302   """
 303   def fn(val):
 304     return compat.any(t(val) for t in args)
 305
 306   return CombinationDesc("or", args, fn)
 307
 308
 309 def TMap(fn, test):
 310   """Checks that a modified version of the argument passes the given test.
 311
 312   """
 313   return WithDesc("Result of %s must be %s" %
 314                   (Parens(fn), Parens(test)))(lambda val: test(fn(val)))
 315
 316
 317 def TRegex(pobj):
 318   """Checks whether a string matches a specific regular expression.
 319
 320   @param pobj: Compiled regular expression as returned by C{re.compile}
 321
 322   """
 323   desc = WithDesc("String matching regex \"%s\"" %
 324                   pobj.pattern.encode("string_escape"))
 325
 326   return desc(TAnd(TString, pobj.match))
 327
 328
 329 def TMaybe(test):
 330   """Wrap a test in a TOr(TNone, test).
 331
 332   This makes it easier to define TMaybe* types.
 333
 334   """
 335   return TOr(TNone, test)
 336
 337
 338 def TMaybeValueNone(test):
 339   """Used for unsetting values.
 340
 341   """
 342   return TMaybe(TOr(TValueNone, test))
 343
 344
 345 # Type aliases
 346
 347 #: a non-empty string
 348 TNonEmptyString = WithDesc("NonEmptyString")(TAnd(TString, TTrue))
 349
 350 #: a maybe non-empty string
 351 TMaybeString = TMaybe(TNonEmptyString)
 352
 353 #: a maybe boolean (bool or none)
 354 TMaybeBool = TMaybe(TBool)
 355
 356 #: Maybe a dictionary (dict or None)
 357 TMaybeDict = TMaybe(TDict)
 358
 359 #: a non-negative integer (value >= 0)
 360 TNonNegativeInt = \
 361   TAnd(TInt, WithDesc("EqualOrGreaterThanZero")(lambda v: v >= 0))
 362
 363 #: a positive integer (value > 0)
 364 TPositiveInt = \
 365   TAnd(TInt, WithDesc("GreaterThanZero")(lambda v: v > 0))
 366
 367 #: a maybe positive integer (positive integer or None)
 368 TMaybePositiveInt = TMaybe(TPositiveInt)
 369
 370 #: a negative integer (value < 0)
 371 TNegativeInt = \
 372   TAnd(TInt, WithDesc("LessThanZero")(compat.partial(operator.gt, 0)))
 373
 374 #: a positive float
 375 TNonNegativeFloat = \
 376   TAnd(TFloat, WithDesc("EqualOrGreaterThanZero")(lambda v: v >= 0.0))
 377
 378 #: Job ID
 379 TJobId = WithDesc("JobId")(TOr(TNonNegativeInt,
 380                                TRegex(re.compile("^%s$" %
 381                                                  constants.JOB_ID_TEMPLATE))))
 382
 383 #: Number
 384 TNumber = TOr(TInt, TFloat)
 385
 386 #: Relative job ID
 387 TRelativeJobId = WithDesc("RelativeJobId")(TNegativeInt)
 388
 389
 390 def TInstanceOf(cls):
 391   """Checks if a given value is an instance of C{cls}.
 392
 393   @type cls: class
 394   @param cls: Class object
 395
 396   """
 397   name = "%s.%s" % (cls.__module__, cls.__name__)
 398
 399   desc = WithDesc("Instance of %s" % (Parens(name), ))
 400
 401   return desc(lambda val: isinstance(val, cls))
 402
 403
 404 def TListOf(my_type):
 405   """Checks if a given value is a list with all elements of the same type.
 406
 407   """
 408   desc = WithDesc("List of %s" % (Parens(my_type), ))
 409   return desc(TAnd(TList, lambda lst: compat.all(my_type(v) for v in lst)))
 410
 411
 412 TMaybeListOf = lambda item_type: TMaybe(TListOf(item_type))
 413
 414
 415 def TDictOf(key_type, val_type):
 416   """Checks a dict type for the type of its key/values.
 417
 418   """
 419   desc = WithDesc("Dictionary with keys of %s and values of %s" %
 420                   (Parens(key_type), Parens(val_type)))
 421
 422   def fn(container):
 423     return (compat.all(key_type(v) for v in container.keys()) and
 424             compat.all(val_type(v) for v in container.values()))
 425
 426   return desc(TAnd(TDict, fn))
 427
 428
 429 def _TStrictDictCheck(require_all, exclusive, items, val):
 430   """Helper function for L{TStrictDict}.
 431
 432   """
 433   notfound_fn = lambda _: not exclusive
 434
 435   if require_all and not frozenset(val.keys()).issuperset(items.keys()):
 436     # Requires items not found in value
 437     return False
 438
 439   return compat.all(items.get(key, notfound_fn)(value)
 440                     for (key, value) in val.items())
 441
 442
 443 def TStrictDict(require_all, exclusive, items):
 444   """Strict dictionary check with specific keys.
 445
 446   @type require_all: boolean
 447   @param require_all: Whether all keys in L{items} are required
 448   @type exclusive: boolean
 449   @param exclusive: Whether only keys listed in L{items} should be accepted
 450   @type items: dictionary
 451   @param items: Mapping from key (string) to verification function
 452
 453   """
 454   descparts = ["Dictionary containing"]
 455
 456   if exclusive:
 457     descparts.append(" none but the")
 458
 459   if require_all:
 460     descparts.append(" required")
 461
 462   if len(items) == 1:
 463     descparts.append(" key ")
 464   else:
 465     descparts.append(" keys ")
 466
 467   descparts.append(utils.CommaJoin("\"%s\" (value %s)" % (key, value)
 468                                    for (key, value) in items.items()))
 469
 470   desc = WithDesc("".join(descparts))
 471
 472   return desc(TAnd(TDict,
 473                    compat.partial(_TStrictDictCheck, require_all, exclusive,
 474                                   items)))
 475
 476
 477 def TItems(items):
 478   """Checks individual items of a container.
 479
 480   If the verified value and the list of expected items differ in length, this
 481   check considers only as many items as are contained in the shorter list. Use
 482   L{TIsLength} to enforce a certain length.
 483
 484   @type items: list
 485   @param items: List of checks
 486
 487   """
 488   assert items, "Need items"
 489
 490   text = ["Item", "item"]
 491   desc = WithDesc(utils.CommaJoin("%s %s is %s" %
 492                                   (text[int(idx > 0)], idx, Parens(check))
 493                                   for (idx, check) in enumerate(items)))
 494
 495   return desc(lambda value: compat.all(check(i)
 496                                        for (check, i) in zip(items, value)))