New percentage helper function.

Since we were converting brightness values (int, float, str and relative) to a percentage
in multiple places, it made sense to centralize it

Author: Crozzers

screen_brightness_control/__init__.py

@@ -8,7 +8,7 @@
 from ._debug import info as debug_info  # noqa: F401
 from ._version import __author__, __version__  # noqa: F401
 from .exceptions import NoValidDisplayError, format_exc
-from .helpers import MONITOR_MANUFACTURER_CODES  # noqa: F401
+from .helpers import MONITOR_MANUFACTURER_CODES, percentage  # noqa: F401
 from .helpers import BrightnessMethod, ScreenBrightnessError, logarithmic_range
 
 logger = logging.getLogger(__name__)
@@ -99,34 +99,32 @@ def set_brightness(
         ```
     '''
     if isinstance(value, str) and ('+' in value or '-' in value):
-        value = int(float(value))
-        monitors = filter_monitors(display=display, method=method)
-        if len(monitors) > 1:
-            output = []
-            for monitor in monitors:
-                identifier = Monitor.get_identifier(monitor)[1]
-                tmp = set_brightness(
-                    get_brightness(display=identifier)[0] + value,
-                    display=identifier,
-                    force=force,
-                    verbose_error=verbose_error,
-                    no_return=no_return
-                )
-                if isinstance(tmp, list):
-                    output += tmp
-                else:  # otherwise the output should be None
-                    output.append(tmp)
-            return output
-
-        value += get_brightness(display=Monitor.get_identifier(monitors[0])[1])[0]
-    else:
-        value = int(float(str(value)))
+        output = []
+        for monitor in filter_monitors(display=display, method=method):
+            identifier = Monitor.get_identifier(monitor)[1]
+            current_value = get_brightness(display=identifier)[0]
+            result = set_brightness(
+                # don't need to calculate lower bound here because it will be
+                # done by the other path in `set_brightness`
+                percentage(value, current=current_value),
+                display=identifier,
+                force=force,
+                verbose_error=verbose_error,
+                no_return=no_return
+            )
+            if result is None:
+                output.append(result)
+            else:
+                output += result
 
-    # make sure value is within bounds
-    value = max(min(100, value), 0)
+        return output
 
     if platform.system() == 'Linux' and not force:
-        value = max(1, value)
+        lower_bound = 1
+    else:
+        lower_bound = 0
+
+    value = percentage(value, lower_bound=lower_bound)
 
     return __brightness(
         value, display=display, method=method,
@@ -498,19 +496,18 @@ def set_brightness(self, value: Union[int, str], no_return: bool = True, force:
         # refresh display info, in case another display has been unplugged or something
         # which would change the index of this display
         self.get_info()
-        # min brightness value
+
+        # convert brightness value to percentage
         if platform.system() == 'Linux' and not force:
             lower_bound = 1
         else:
             lower_bound = 0
 
-        # changing string value to int
-        if isinstance(value, str) and ('+' in value or '-' in value):
-            value = int(float(value))
-            value += self.method.get_brightness(display=self.index)[0]
-        else:
-            value = int(float(str(value)))
-        value = max(lower_bound, min(value, 100))
+        value = percentage(
+            value,
+            current=lambda: self.method.get_brightness(display=self.index)[0],
+            lower_bound=lower_bound
+        )
         self.method.set_brightness(value, display=self.index)
         if no_return:
             return None

screen_brightness_control/helpers.py

@@ -8,7 +8,7 @@
 import time
 from abc import ABC, abstractclassmethod
 from functools import lru_cache
-from typing import List, Optional, Tuple, Union
+from typing import Callable, List, Optional, Tuple, Union
 
 from .exceptions import (EDIDParseError, MaxRetriesExceededError,  # noqa:F401
                          ScreenBrightnessError)
@@ -448,3 +448,30 @@ def _monitor_brand_lookup(search: str) -> Union[Tuple[str, str], None]:
         else:
             return None
     return keys[index], values[index]
+
+
+def percentage(value: Union[int, str], current: Union[int, Callable[[], int]] = None, lower_bound: int = 0) -> int:
+    '''
+    Convenience function to convert a brightness value into a percentage. Can handle
+    integers, floats and strings. Also can handle relative strings (eg: `'+10'` or `'-10'`)
+
+    Args:
+        value (int or str or float): the brightness value to convert
+        current (int or callable): the current brightness value or a function that returns the current brightness
+            value. Used when dealing with relative brightness values
+        lower_bound (int): the minimum value the brightness can be set to
+
+    Returns:
+        int: the new brightness percentage, between `lower_bound` and 100
+    '''
+    if isinstance(value, str) and ('+' in value or '-' in value):
+        if callable(current):
+            current = current()
+        value = int(float(value)) + int(float(str(current)))
+    else:
+        value = int(float(str(value)))
+
+    return min(
+        100,
+        max(lower_bound, value)
+    )

screen_brightness_control/windows.py

@@ -88,7 +88,8 @@ def get_display_info() -> List[dict]:
                 i.InstanceName
                 for i in wmi.WmiMonitorBrightness()
             ]
-        except wmi.x_wmi as e:
+        except Exception as e:
+            # don't do specific exception classes here because WMI does not play ball with it
             logger.warning(f'get_display_info: failed to gather list of laptop displays - {format_exc(e)}')
             laptop_displays = []
 

tests/test_helpers.py

@@ -96,6 +96,50 @@ def test_skip_intervals(self):
             self.assertGreaterEqual(l_range[0] - l_range[1], l_range[-2] - l_range[-1])
 
 
+class TestPercentage(unittest.TestCase):
+    def test_normal(self):
+        percentage = sbc.helpers.percentage
+
+        # int
+        self.assertEqual(percentage(100), 100)
+        self.assertEqual(percentage(50), 50)
+        self.assertEqual(percentage(0), 0)
+        # float
+        self.assertEqual(percentage(59.3), 59)
+        self.assertEqual(percentage(24.999), 24)
+        # str
+        self.assertEqual(percentage('99'), 99)
+        self.assertEqual(percentage('12.125'), 12)
+
+    def test_relative(self):
+        percentage = sbc.helpers.percentage
+
+        self.assertEqual(percentage('+10', current=10), 20)
+        self.assertEqual(percentage('-5', current=30), 25)
+        self.assertEqual(percentage('-21', current=lambda: 99), 78)
+        self.assertEqual(percentage('+50', current=lambda: 50), 100)
+        self.assertEqual(percentage('-10.5', current=100, lower_bound=10), 90)
+
+    def test_bounds(self):
+        percentage = sbc.helpers.percentage
+
+        self.assertEqual(percentage(101), 100)
+        self.assertEqual(percentage(1000), 100)
+        self.assertEqual(percentage(-1), 0)
+        self.assertEqual(percentage(-19999), 0)
+        self.assertEqual(percentage('-100', current=0), 0)
+        self.assertEqual(percentage('+1000000', current=0), 100)
+
+        self.assertEqual(percentage(0, lower_bound=1), 1)
+        self.assertEqual(percentage('-10', current=10, lower_bound=1), 1)
+
+    def test_abnormal(self):
+        percentage = sbc.helpers.percentage
+
+        self.assertRaises(ValueError, percentage, [123])
+        self.assertRaises(ValueError, percentage, '1{2!3')
+
+
 if __name__ == '__main__':
     if '--synthetic' in sys.argv:
         sys.argv.remove('--synthetic')