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("Dictionary")
 263 def TDict(val):
 264   """Checks if the given value is a dictionary.
 265
 266   """
 267   return isinstance(val, dict)
 268
 269
 270 def TIsLength(size):
 271   """Check is the given container is of the given size.
 272
 273   """
 274   def fn(container):
 275     return len(container) == size
 276
 277   return WithDesc("Length %s" % (size, ))(fn)
 278
 279
 280 # Combinator types
 281 def TAnd(*args):
 282   """Combine multiple functions using an AND operation.
 283
 284   """
 285   def fn(val):
 286     return compat.all(t(val) for t in args)
 287
 288   return CombinationDesc("and", args, fn)
 289
 290
 291 def TOr(*args):
 292   """Combine multiple functions using an AND operation.
 293
 294   """
 295   def fn(val):
 296     return compat.any(t(val) for t in args)
 297
 298   return CombinationDesc("or", args, fn)
 299
 300
 301 def TMap(fn, test):
 302   """Checks that a modified version of the argument passes the given test.
 303
 304   """
 305   return WithDesc("Result of %s must be %s" %
 306                   (Parens(fn), Parens(test)))(lambda val: test(fn(val)))
 307
 308
 309 def TRegex(pobj):
 310   """Checks whether a string matches a specific regular expression.
 311
 312   @param pobj: Compiled regular expression as returned by C{re.compile}
 313
 314   """
 315   desc = WithDesc("String matching regex \"%s\"" %
 316                   pobj.pattern.encode("string_escape"))
 317
 318   return desc(TAnd(TString, pobj.match))
 319
 320
 321 def TMaybe(test):
 322   """Wrap a test in a TOr(TNone, test).
 323
 324   This makes it easier to define TMaybe* types.
 325
 326   """
 327   return TOr(TNone, test)
 328
 329
 330 def TMaybeValueNone(test):
 331   """Used for unsetting values.
 332
 333   """
 334   return TMaybe(TOr(TValueNone, test))
 335
 336
 337 # Type aliases
 338
 339 #: a non-empty string
 340 TNonEmptyString = WithDesc("NonEmptyString")(TAnd(TString, TTrue))
 341
 342 #: a maybe non-empty string
 343 TMaybeString = TMaybe(TNonEmptyString)
 344
 345 #: a maybe boolean (bool or none)
 346 TMaybeBool = TMaybe(TBool)
 347
 348 #: Maybe a dictionary (dict or None)
 349 TMaybeDict = TMaybe(TDict)
 350
 351 #: a non-negative integer (value >= 0)
 352 TNonNegativeInt = \
 353   TAnd(TInt, WithDesc("EqualOrGreaterThanZero")(lambda v: v >= 0))
 354
 355 #: a positive integer (value > 0)
 356 TPositiveInt = \
 357   TAnd(TInt, WithDesc("GreaterThanZero")(lambda v: v > 0))
 358
 359 #: a maybe positive integer (positive integer or None)
 360 TMaybePositiveInt = TMaybe(TPositiveInt)
 361
 362 #: a negative integer (value < 0)
 363 TNegativeInt = \
 364   TAnd(TInt, WithDesc("LessThanZero")(compat.partial(operator.gt, 0)))
 365
 366 #: a positive float
 367 TNonNegativeFloat = \
 368   TAnd(TFloat, WithDesc("EqualOrGreaterThanZero")(lambda v: v >= 0.0))
 369
 370 #: Job ID
 371 TJobId = WithDesc("JobId")(TOr(TNonNegativeInt,
 372                                TRegex(re.compile("^%s$" %
 373                                                  constants.JOB_ID_TEMPLATE))))
 374
 375 #: Number
 376 TNumber = TOr(TInt, TFloat)
 377
 378 #: Relative job ID
 379 TRelativeJobId = WithDesc("RelativeJobId")(TNegativeInt)
 380
 381
 382 def TInstanceOf(cls):
 383   """Checks if a given value is an instance of C{cls}.
 384
 385   @type cls: class
 386   @param cls: Class object
 387
 388   """
 389   name = "%s.%s" % (cls.__module__, cls.__name__)
 390
 391   desc = WithDesc("Instance of %s" % (Parens(name), ))
 392
 393   return desc(lambda val: isinstance(val, cls))
 394
 395
 396 def TListOf(my_type):
 397   """Checks if a given value is a list with all elements of the same type.
 398
 399   """
 400   desc = WithDesc("List of %s" % (Parens(my_type), ))
 401   return desc(TAnd(TList, lambda lst: compat.all(my_type(v) for v in lst)))
 402
 403
 404 TMaybeListOf = lambda item_type: TMaybe(TListOf(item_type))
 405
 406
 407 def TDictOf(key_type, val_type):
 408   """Checks a dict type for the type of its key/values.
 409
 410   """
 411   desc = WithDesc("Dictionary with keys of %s and values of %s" %
 412                   (Parens(key_type), Parens(val_type)))
 413
 414   def fn(container):
 415     return (compat.all(key_type(v) for v in container.keys()) and
 416             compat.all(val_type(v) for v in container.values()))
 417
 418   return desc(TAnd(TDict, fn))
 419
 420
 421 def _TStrictDictCheck(require_all, exclusive, items, val):
 422   """Helper function for L{TStrictDict}.
 423
 424   """
 425   notfound_fn = lambda _: not exclusive
 426
 427   if require_all and not frozenset(val.keys()).issuperset(items.keys()):
 428     # Requires items not found in value
 429     return False
 430
 431   return compat.all(items.get(key, notfound_fn)(value)
 432                     for (key, value) in val.items())
 433
 434
 435 def TStrictDict(require_all, exclusive, items):
 436   """Strict dictionary check with specific keys.
 437
 438   @type require_all: boolean
 439   @param require_all: Whether all keys in L{items} are required
 440   @type exclusive: boolean
 441   @param exclusive: Whether only keys listed in L{items} should be accepted
 442   @type items: dictionary
 443   @param items: Mapping from key (string) to verification function
 444
 445   """
 446   descparts = ["Dictionary containing"]
 447
 448   if exclusive:
 449     descparts.append(" none but the")
 450
 451   if require_all:
 452     descparts.append(" required")
 453
 454   if len(items) == 1:
 455     descparts.append(" key ")
 456   else:
 457     descparts.append(" keys ")
 458
 459   descparts.append(utils.CommaJoin("\"%s\" (value %s)" % (key, value)
 460                                    for (key, value) in items.items()))
 461
 462   desc = WithDesc("".join(descparts))
 463
 464   return desc(TAnd(TDict,
 465                    compat.partial(_TStrictDictCheck, require_all, exclusive,
 466                                   items)))
 467
 468
 469 def TItems(items):
 470   """Checks individual items of a container.
 471
 472   If the verified value and the list of expected items differ in length, this
 473   check considers only as many items as are contained in the shorter list. Use
 474   L{TIsLength} to enforce a certain length.
 475
 476   @type items: list
 477   @param items: List of checks
 478
 479   """
 480   assert items, "Need items"
 481
 482   text = ["Item", "item"]
 483   desc = WithDesc(utils.CommaJoin("%s %s is %s" %
 484                                   (text[int(idx > 0)], idx, Parens(check))
 485                                   for (idx, check) in enumerate(items)))
 486
 487   return desc(lambda value: compat.all(check(i)
 488                                        for (check, i) in zip(items, value)))