framework/status.py

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