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 OR 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 #: Maybe a list (list or None)
 360 TMaybeList = TMaybe(TList)
 361
 362 #: a non-negative integer (value >= 0)
 363 TNonNegativeInt = \
 364   TAnd(TInt, WithDesc("EqualOrGreaterThanZero")(lambda v: v >= 0))
 365
 366 #: a positive integer (value > 0)
 367 TPositiveInt = \
 368   TAnd(TInt, WithDesc("GreaterThanZero")(lambda v: v > 0))
 369
 370 #: a maybe positive integer (positive integer or None)
 371 TMaybePositiveInt = TMaybe(TPositiveInt)
 372
 373 #: a negative integer (value < 0)
 374 TNegativeInt = \
 375   TAnd(TInt, WithDesc("LessThanZero")(compat.partial(operator.gt, 0)))
 376
 377 #: a positive float
 378 TNonNegativeFloat = \
 379   TAnd(TFloat, WithDesc("EqualOrGreaterThanZero")(lambda v: v >= 0.0))
 380
 381 #: Job ID
 382 TJobId = WithDesc("JobId")(TOr(TNonNegativeInt,
 383                                TRegex(re.compile("^%s$" %
 384                                                  constants.JOB_ID_TEMPLATE))))
 385
 386 #: Number
 387 TNumber = TOr(TInt, TFloat)
 388
 389 #: Relative job ID
 390 TRelativeJobId = WithDesc("RelativeJobId")(TNegativeInt)
 391
 392
 393 def TInstanceOf(cls):
 394   """Checks if a given value is an instance of C{cls}.
 395
 396   @type cls: class
 397   @param cls: Class object
 398
 399   """
 400   name = "%s.%s" % (cls.__module__, cls.__name__)
 401
 402   desc = WithDesc("Instance of %s" % (Parens(name), ))
 403
 404   return desc(lambda val: isinstance(val, cls))
 405
 406
 407 def TListOf(my_type):
 408   """Checks if a given value is a list with all elements of the same type.
 409
 410   """
 411   desc = WithDesc("List of %s" % (Parens(my_type), ))
 412   return desc(TAnd(TList, lambda lst: compat.all(my_type(v) for v in lst)))
 413
 414
 415 TMaybeListOf = lambda item_type: TMaybe(TListOf(item_type))
 416
 417
 418 def TDictOf(key_type, val_type):
 419   """Checks a dict type for the type of its key/values.
 420
 421   """
 422   desc = WithDesc("Dictionary with keys of %s and values of %s" %
 423                   (Parens(key_type), Parens(val_type)))
 424
 425   def fn(container):
 426     return (compat.all(key_type(v) for v in container.keys()) and
 427             compat.all(val_type(v) for v in container.values()))
 428
 429   return desc(TAnd(TDict, fn))
 430
 431
 432 def _TStrictDictCheck(require_all, exclusive, items, val):
 433   """Helper function for L{TStrictDict}.
 434
 435   """
 436   notfound_fn = lambda _: not exclusive
 437
 438   if require_all and not frozenset(val.keys()).issuperset(items.keys()):
 439     # Requires items not found in value
 440     return False
 441
 442   return compat.all(items.get(key, notfound_fn)(value)
 443                     for (key, value) in val.items())
 444
 445
 446 def TStrictDict(require_all, exclusive, items):
 447   """Strict dictionary check with specific keys.
 448
 449   @type require_all: boolean
 450   @param require_all: Whether all keys in L{items} are required
 451   @type exclusive: boolean
 452   @param exclusive: Whether only keys listed in L{items} should be accepted
 453   @type items: dictionary
 454   @param items: Mapping from key (string) to verification function
 455
 456   """
 457   descparts = ["Dictionary containing"]
 458
 459   if exclusive:
 460     descparts.append(" none but the")
 461
 462   if require_all:
 463     descparts.append(" required")
 464
 465   if len(items) == 1:
 466     descparts.append(" key ")
 467   else:
 468     descparts.append(" keys ")
 469
 470   descparts.append(utils.CommaJoin("\"%s\" (value %s)" % (key, value)
 471                                    for (key, value) in items.items()))
 472
 473   desc = WithDesc("".join(descparts))
 474
 475   return desc(TAnd(TDict,
 476                    compat.partial(_TStrictDictCheck, require_all, exclusive,
 477                                   items)))
 478
 479
 480 def TItems(items):
 481   """Checks individual items of a container.
 482
 483   If the verified value and the list of expected items differ in length, this
 484   check considers only as many items as are contained in the shorter list. Use
 485   L{TIsLength} to enforce a certain length.
 486
 487   @type items: list
 488   @param items: List of checks
 489
 490   """
 491   assert items, "Need items"
 492
 493   text = ["Item", "item"]
 494   desc = WithDesc(utils.CommaJoin("%s %s is %s" %
 495                                   (text[int(idx > 0)], idx, Parens(check))
 496                                   for (idx, check) in enumerate(items)))
 497
 498   return desc(lambda value: compat.all(check(i)
 499                                        for (check, i) in zip(items, value)))