framework/status.py

   1 # coding=utf-8
   2 # Copyright (c) 2013, 2015 Intel Corporation
   3 #
   4 # Permission is hereby granted, free of charge, to any person obtaining a
   5 # copy of this software and associated documentation files (the "Software"),
   6 # to deal in the Software without restriction, including without limitation
   7 # the rights to use, copy, modify, merge, publish, distribute, sublicense,
   8 # and/or sell copies of the Software, and to permit persons to whom the
   9 # Software is furnished to do so, subject to the following conditions:
  10 #
  11 # The above copyright notice and this permission notice (including the next
  12 # paragraph) shall be included in all copies or substantial portions of the
  13 # Software.
  14 #
  15 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  18 # THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  20 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  21 # IN THE SOFTWARE.
  22
  23 """ Provides classes that represent test statuses
  24
  25 These classes work similar to enums in other languages. They provide a limited
  26 set of attributes that are defined per status:
  27
  28 A name -- a string representation of the values
  29 An integer -- a value that allows classes to be compared using python's rich
  30 comparisons
  31 A tuple representing :
  32   [0] -- whether the test is considered a passing status
  33   [1] -- whether the test should be added to the total number of tests. This
  34          allows statuses like 'skip' to not affect the total percentage.
  35
  36
  37 Status ordering from best to worst:
  38
  39 pass
  40 warn
  41 dmesg-warn
  42 fail
  43 dmesg-fail
  44 timeout
  45 crash
  46 incomplete
  47
  48 SKIP and NOTRUN are not factored into regressions and fixes, they are counted
  49 separately. They also derive from a subclass of Status, which always returns
  50 False
  51
  52 The formula for determining regressions is:
  53   old_status < new_status
  54
  55 The formula for determining fixes is:
  56   old_status > new_status
  57
  58 """
  59
  60 from framework import exceptions
  61
  62 __all__ = ['NOTRUN',
  63            'PASS',
  64            'FAIL',
  65            'WARN',
  66            'CRASH',
  67            'DMESG_WARN',
  68            'DMESG_FAIL',
  69            'SKIP',
  70            'TIMEOUT',
  71            'INCOMPLETE',
  72            'ALL']
  73
  74
  75 def status_lookup(status):
  76     """ Provided a string return a status object instance
  77
  78     When provided a string that corresponds to a key in it's status_dict
  79     variable, this function returns a status object instance. If the string
  80     does not correspond to a key it will raise an exception
  81
  82     """
  83     # Don't go through this if what we've been passed already is a status, it's
  84     # very expensive
  85     if isinstance(status, Status):
  86         return status
  87
  88     try:
  89         return _STATUS_MAP[status]
  90     except KeyError:
  91         # Raise a StatusException rather than a key error
  92         raise StatusException(status)
  93
  94
  95 class StatusException(exceptions.PiglitInternalError):
  96     """ Raise this exception when a string is passed to status_lookup that
  97     doesn't exists
  98
  99     The primary reason to have a special exception is that otherwise
 100     status_lookup returns a KeyError, but there are many cases where it is
 101     desirable to except a KeyError and have an exception path. Using a custom
 102     Error class here allows for more fine-grained control.
 103
 104     """
 105     def __init__(self, status):
 106         self.__status = status
 107         super(StatusException, self).__init__(self)
 108
 109     def __str__(self):
 110         return u'Unknown status "{}"'.format(self.__status)
 111
 112
 113 class Status(object):
 114     """ A simple class for representing the output values of tests.
 115
 116     This class creatse the necessary magic values to use python's rich
 117     comparison methods. This allows two objects to be compared using common
 118     operators like <. >, ==, etc. It also allows them to be looked up in
 119     containers using ``for x in []`` syntax.
 120
 121     This class is meant to be immutable, it (ab)uses two tools to provide this
 122     psuedo-immutability: the property decorator, and the __slots__ attribute to
 123     1: make the three attributes getters, therefore unwritable, and 2: make
 124     adding additional attributes impossible
 125
 126     Arguments:
 127     name -- the name of the status
 128     value -- an int used to sort statuses from best to worst (0 -> inf)
 129     fraction -- a tuple with two ints representing
 130                 [0]: 1 if the status is 'passing', else 0
 131                 [1]: 1 if the status counts toward the total number of tests,
 132                      else 0
 133
 134     """
 135     __slots__ = ['__name', '__value', '__fraction']
 136
 137     def __init__(self, name, value, fraction=(0, 1)):
 138         assert isinstance(value, int), type(value)
 139         # The object is immutable, so calling self.foo = foo will raise a
 140         # TypeError. Using setattr from the parent object works around this.
 141         self.__name = str(name)
 142         self.__value = value
 143         self.__fraction = fraction
 144
 145     @property
 146     def name(self):
 147         """ Return the value of name """
 148         return self.__name
 149
 150     @property
 151     def value(self):
 152         """ Return the sorting value """
 153         return self.__value
 154
 155     @property
 156     def fraction(self):
 157         """ Return the totals of the test as a tuple: (<pass>. <total>) """
 158         return self.__fraction
 159
 160     def __repr__(self):
 161         return 'Status("{}", {}, {})'.format(
 162             self.name, self.value, self.fraction)
 163
 164     def __bytes__(self):
 165         return bytes(self.name, 'utf-8')
 166
 167     def __str__(self):
 168         return self.name
 169
 170     def __lt__(self, other):
 171         return not self.__ge__(other)
 172
 173     def __le__(self, other):
 174         return not self.__gt__(other)
 175
 176     def __eq__(self, other):
 177         # This must be int or status, since status comparisons are done using
 178         # the __int__ magic method
 179         if isinstance(other, (int, Status)):
 180             return int(self) == int(other)
 181         elif isinstance(other, str):
 182             return str(self) == other
 183         elif isinstance(other, bytes):
 184             return bytes(self) == other
 185         raise TypeError("Cannot compare type: {}".format(type(other)))
 186
 187     def __ne__(self, other):
 188         return not self == other
 189
 190     def __ge__(self, other):
 191         return self.fraction[1] > other.fraction[1] or (
 192             self.fraction[1] == other.fraction[1] and int(self) >= int(other))
 193
 194     def __gt__(self, other):
 195         return self.fraction[1] > other.fraction[1] or int(self) > int(other)
 196
 197     def __int__(self):
 198         return self.value
 199
 200     def __hash__(self):
 201         return hash(self.name)
 202
 203
 204 class NoChangeStatus(Status):
 205     """ Special subclass of status that overrides rich comparison methods
 206
 207     This special class of a Status is for use with NOTRUN and SKIP, it never
 208     returns that it is a pass or regression
 209
 210     """
 211     def __init__(self, name, value=0, fraction=(0, 0)):
 212         super(NoChangeStatus, self).__init__(name, value, fraction)
 213
 214     def __eq__(self, other):
 215         if isinstance(other, (str, Status)):
 216             return str(self) == str(other)
 217         raise TypeError("Cannot compare type: {}".format(type(other)))
 218
 219     def __ne__(self, other):
 220         if isinstance(other, (str, Status)):
 221             return str(self) != str(other)
 222         raise TypeError("Cannot compare type: {}".format(type(other)))
 223
 224     def __hash__(self):
 225         return hash(self.name)
 226
 227
 228 NOTRUN = NoChangeStatus('notrun')
 229
 230 SKIP = NoChangeStatus('skip')
 231
 232 PASS = Status('pass', 0, (1, 1))
 233
 234 WARN = Status('warn', 10)
 235
 236 DMESG_WARN = Status('dmesg-warn', 20)
 237
 238 FAIL = Status('fail', 30)
 239
 240 DMESG_FAIL = Status('dmesg-fail', 40)
 241
 242 TIMEOUT = Status('timeout', 50)
 243
 244 CRASH = Status('crash', 60)
 245
 246 INCOMPLETE = Status('incomplete', 100)
 247
 248 _STATUS_MAP = {
 249     'skip': SKIP,
 250     'pass': PASS,
 251     'warn': WARN,
 252     'fail': FAIL,
 253     'crash': CRASH,
 254     'dmesg-warn': DMESG_WARN,
 255     'dmesg-fail': DMESG_FAIL,
 256     'notrun': NOTRUN,
 257     'timeout': TIMEOUT,
 258     'incomplete': INCOMPLETE,
 259 }
 260
 261 # A tuple (ordered, immutable) of all statuses in this module
 262 ALL = (PASS, WARN, DMESG_WARN, FAIL, DMESG_FAIL, TIMEOUT, CRASH, INCOMPLETE,
 263        SKIP, NOTRUN)