screen_brightness_control.linux

   1import fcntl
   2import functools
   3import glob
   4import logging
   5import operator
   6import os
   7import re
   8import time
   9from typing import List, Optional, Tuple, Union
  10
  11from . import filter_monitors, get_methods
  12from .exceptions import I2CValidationError, NoValidDisplayError, format_exc
  13from .helpers import (EDID, BrightnessMethod, BrightnessMethodAdv, __Cache,
  14                      _monitor_brand_lookup, check_output)
  15
  16__cache__ = __Cache()
  17logger = logging.getLogger(__name__)
  18
  19
  20class SysFiles(BrightnessMethod):
  21    '''
  22    A way of getting display information and adjusting the brightness
  23    that does not rely on any 3rd party software.
  24
  25    This class works with displays that show up in the `/sys/class/backlight`
  26    directory (so usually laptop displays).
  27
  28    To set the brightness, your user will need write permissions for
  29    `/sys/class/backlight/*/brightness` or you will need to run the program
  30    as root.
  31    '''
  32    logger = logger.getChild('SysFiles')
  33
  34    @classmethod
  35    def get_display_info(cls, display: Optional[Union[int, str]] = None) -> List[dict]:
  36        '''
  37        Returns information about detected displays by reading files from the
  38        `/sys/class/backlight` directory
  39
  40        Args:
  41            display (str or int): The display to return info about.
  42                Pass in the serial number, name, model, interface, edid or index.
  43                This is passed to `filter_monitors`
  44
  45        Returns:
  46            list: list of dicts
  47
  48        Example:
  49            ```python
  50            import screen_brightness_control as sbc
  51
  52            # get info about all displays
  53            info = sbc.linux.SysFiles.get_display_info()
  54            # EG output: [{'name': 'edp-backlight', 'path': '/sys/class/backlight/edp-backlight', edid': '00ffff...'}]
  55
  56            # get info about the primary display
  57            primary_info = sbc.linux.SysFiles.get_display_info(0)[0]
  58
  59            # get info about a display called 'edp-backlight'
  60            edp_info = sbc.linux.SysFiles.get_display_info('edp-backlight')[0]
  61            ```
  62        '''
  63        subsystems = set()
  64        for folder in os.listdir('/sys/class/backlight'):
  65            if os.path.isdir(f'/sys/class/backlight/{folder}/subsystem'):
  66                subsystems.add(tuple(os.listdir(f'/sys/class/backlight/{folder}/subsystem')))
  67
  68        all_displays = {}
  69        index = 0
  70
  71        for subsystem in subsystems:
  72
  73            device = {
  74                'name': subsystem[0],
  75                'path': f'/sys/class/backlight/{subsystem[0]}',
  76                'method': cls,
  77                'index': index,
  78                'model': None,
  79                'serial': None,
  80                'manufacturer': None,
  81                'manufacturer_id': None,
  82                'edid': None,
  83                'scale': None
  84            }
  85
  86            for folder in subsystem:
  87                # subsystems like intel_backlight usually have an acpi_video0
  88                # counterpart, which we don't want so lets find the 'best' candidate
  89                try:
  90                    with open(os.path.join(f'/sys/class/backlight/{folder}/max_brightness')) as f:
  91                        scale = int(f.read().rstrip(' \n')) / 100
  92
  93                    # use the display with the highest resolution scale
  94                    if device['scale'] is None or scale > device['scale']:
  95                        device['name'] = folder
  96                        device['path'] = f'/sys/class/backlight/{folder}'
  97                        device['scale'] = scale
  98                except (FileNotFoundError, TypeError) as e:
  99                    cls.logger.error(
 100                        f'error getting highest resolution scale for {folder}'
 101                        f' - {format_exc(e)}'
 102                    )
 103                    continue
 104
 105            if os.path.isfile('%s/device/edid' % device['path']):
 106                device['edid'] = EDID.hexdump('%s/device/edid' % device['path'])
 107
 108                for key, value in zip(
 109                    ('manufacturer_id', 'manufacturer', 'model', 'name', 'serial'),
 110                    EDID.parse(device['edid'])
 111                ):
 112                    if value is None:
 113                        continue
 114                    device[key] = value
 115
 116            all_displays[device['edid']] = device
 117            index += 1
 118
 119        all_displays = list(all_displays.values())
 120        if display is not None:
 121            all_displays = filter_monitors(display=display, haystack=all_displays, include=['path'])
 122        return all_displays
 123
 124    @classmethod
 125    def get_brightness(cls, display: Optional[int] = None) -> List[int]:
 126        '''
 127        Gets the brightness for a display by reading the brightness files
 128        stored in `/sys/class/backlight/*/brightness`
 129
 130        Args:
 131            display (int): The specific display you wish to query.
 132
 133        Returns:
 134            list: list of ints (0 to 100)
 135
 136        Example:
 137            ```python
 138            import screen_brightness_control as sbc
 139
 140            # get the current display brightness
 141            current_brightness = sbc.linux.SysFiles.get_brightness()
 142
 143            # get the brightness of the primary display
 144            primary_brightness = sbc.linux.SysFiles.get_brightness(display = 0)[0]
 145
 146            # get the brightness of the secondary display
 147            secondary_brightness = sbc.linux.SysFiles.get_brightness(display = 1)[0]
 148            ```
 149        '''
 150        info = cls.get_display_info()
 151        if display is not None:
 152            info = [info[display]]
 153
 154        results = []
 155        for device in info:
 156            with open(os.path.join(device['path'], 'brightness'), 'r') as f:
 157                brightness = int(f.read().rstrip('\n'))
 158            results.append(int(brightness / device['scale']))
 159
 160        return results
 161
 162    @classmethod
 163    def set_brightness(cls, value: int, display: Optional[int] = None):
 164        '''
 165        Sets the brightness for a display by writing to the brightness files
 166        stored in `/sys/class/backlight/*/brightness`.
 167        This function requires permission to write to these files which is
 168        usually provided when it's run as root.
 169
 170        Args:
 171            value (int): Sets the brightness to this value
 172            display (int): The specific display you wish to adjust.
 173
 174        Example:
 175            ```python
 176            import screen_brightness_control as sbc
 177
 178            # set the brightness to 50%
 179            sbc.linux.SysFiles.set_brightness(50)
 180
 181            # set the primary display brightness to 75%
 182            sbc.linux.SysFiles.set_brightness(75, display = 0)
 183
 184            # set the secondary display brightness to 25%
 185            sbc.linux.SysFiles.set_brightness(25, display = 1)
 186            ```
 187        '''
 188        info = cls.get_display_info()
 189        if display is not None:
 190            info = [info[display]]
 191
 192        for device in info:
 193            with open(os.path.join(device['path'], 'brightness'), 'w') as f:
 194                f.write(str(int(value * device['scale'])))
 195
 196
 197class I2C(BrightnessMethod):
 198    '''
 199    In the same spirit as `SysFiles`, this class serves as a way of getting
 200    display information and adjusting the brightness without relying on any
 201    3rd party software.
 202
 203    Usage of this class requires read and write permission for `/dev/i2c-*`.
 204
 205    This class works over the I2C bus, primarily with desktop monitors as I
 206    haven't tested any e-DP displays yet.
 207
 208    Massive thanks to [siemer](https://github.com/siemer) for
 209    his work on the [ddcci.py](https://github.com/siemer/ddcci) project,
 210    which served as a my main reference for this.
 211
 212    References:
 213        * [ddcci.py](https://github.com/siemer/ddcci)
 214        * [DDCCI Spec](https://milek7.pl/ddcbacklight/ddcci.pdf)
 215    '''
 216    logger = logger.getChild('I2C')
 217
 218    # vcp commands
 219    GET_VCP_CMD = 0x01
 220    '''VCP command to get the value of a feature (eg: brightness)'''
 221    GET_VCP_REPLY = 0x02
 222    '''VCP feature reply op code'''
 223    SET_VCP_CMD = 0x03
 224    '''VCP command to set the value of a feature (eg: brightness)'''
 225
 226    # addresses
 227    DDCCI_ADDR = 0x37
 228    '''DDC packets are transmittred using this I2C address'''
 229    HOST_ADDR_R = 0x50
 230    '''Packet source address (the computer) when reading data'''
 231    HOST_ADDR_W = 0x51
 232    '''Packet source address (the computer) when writing data'''
 233    DESTINATION_ADDR_W = 0x6e
 234    '''Packet destination address (the monitor) when writing data'''
 235    I2C_SLAVE = 0x0703
 236    '''The I2C slave address'''
 237
 238    # timings
 239    WAIT_TIME = 0.05
 240    '''How long to wait between I2C commands'''
 241
 242    _max_brightness_cache: dict = {}
 243
 244    class I2CDevice():
 245        '''
 246        Class to read and write data to an I2C bus,
 247        based on the `I2CDev` class from [ddcci.py](https://github.com/siemer/ddcci)
 248        '''
 249        def __init__(self, fname: str, slave_addr: int):
 250            '''
 251            Args:
 252                fname (str): the I2C path, eg: `/dev/i2c-2`
 253                slave_addr (int): not entirely sure what this is meant to be
 254            '''
 255            self.device = os.open(fname, os.O_RDWR)
 256            # I2C_SLAVE address setup
 257            fcntl.ioctl(self.device, I2C.I2C_SLAVE, slave_addr)
 258
 259        def read(self, length: int) -> bytes:
 260            '''
 261            Read a certain number of bytes from the I2C bus
 262
 263            Args:
 264                length (int): the number of bytes to read
 265
 266            Returns:
 267                bytes
 268            '''
 269            return os.read(self.device, length)
 270
 271        def write(self, data: bytes) -> int:
 272            '''
 273            Writes data to the I2C bus
 274
 275            Args:
 276                data (bytes): the data to write
 277
 278            Returns:
 279                int: the number of bytes written
 280            '''
 281            return os.write(self.device, data)
 282
 283    class DDCInterface(I2CDevice):
 284        '''
 285        Class to send DDC (Display Data Channel) commands to an I2C device,
 286        based on the `Ddcci` and `Mccs` classes from [ddcci.py](https://github.com/siemer/ddcci)
 287        '''
 288
 289        PROTOCOL_FLAG = 0x80
 290
 291        def __init__(self, i2c_path: str):
 292            '''
 293            Args:
 294                i2c_path (str): the path to the I2C device, eg: `/dev/i2c-2`
 295            '''
 296            self.logger = logger.getChild(self.__class__.__name__).getChild(i2c_path)
 297            super().__init__(i2c_path, I2C.DDCCI_ADDR)
 298
 299        def write(self, *args) -> int:
 300            '''
 301            Write some data to the I2C device.
 302
 303            It is recommended to use `setvcp` to set VCP values on the DDC device
 304            instead of using this function directly.
 305
 306            Args:
 307                *args: variable length list of arguments. This will be put
 308                    into a `bytearray` and wrapped up in various flags and
 309                    checksums before being written to the I2C device
 310
 311            Returns:
 312                int: the number of bytes that were written
 313            '''
 314            time.sleep(I2C.WAIT_TIME)
 315
 316            ba = bytearray(args)
 317            ba.insert(0, len(ba) | self.PROTOCOL_FLAG)  # add length info
 318            ba.insert(0, I2C.HOST_ADDR_W)  # insert source address
 319            ba.append(functools.reduce(operator.xor, ba, I2C.DESTINATION_ADDR_W))  # checksum
 320
 321            return super().write(ba)
 322
 323        def setvcp(self, vcp_code: int, value: int) -> int:
 324            '''
 325            Set a VCP value on the device
 326
 327            Args:
 328                vcp_code (int): the VCP command to send, eg: `0x10` is brightness
 329                value (int): what to set the value to
 330
 331            Returns:
 332                int: the number of bytes written to the device
 333            '''
 334            return self.write(I2C.SET_VCP_CMD, vcp_code, *value.to_bytes(2, 'big'))
 335
 336        def read(self, amount: int) -> bytes:
 337            '''
 338            Reads data from the DDC device.
 339
 340            It is recommended to use `getvcp` to retrieve VCP values from the
 341            DDC device instead of using this function directly.
 342
 343            Args:
 344                amount (int): the number of bytes to read
 345
 346            Returns:
 347                bytes
 348
 349            Raises:
 350                ValueError: if the read data is deemed invalid
 351            '''
 352            time.sleep(I2C.WAIT_TIME)
 353
 354            ba = super().read(amount + 3)
 355
 356            # check the bytes read
 357            checks = {
 358                'source address': ba[0] == I2C.DESTINATION_ADDR_W,
 359                'checksum': functools.reduce(operator.xor, ba) == I2C.HOST_ADDR_R,
 360                'length': len(ba) >= (ba[1] & ~self.PROTOCOL_FLAG) + 3
 361            }
 362            if False in checks.values():
 363                self.logger.error('i2c read check failed: ' + repr(checks))
 364                raise I2CValidationError('i2c read check failed: ' + repr(checks))
 365
 366            return ba[2:-1]
 367
 368        def getvcp(self, vcp_code: int) -> Tuple[int, int]:
 369            '''
 370            Retrieves a VCP value from the DDC device.
 371
 372            Args:
 373                vcp_code (int): the VCP value to read, eg: `0x10` is brightness
 374
 375            Returns:
 376                tuple[int, int]: the current and maximum value respectively
 377
 378            Raises:
 379                ValueError: if the read data is deemed invalid
 380            '''
 381            self.write(I2C.GET_VCP_CMD, vcp_code)
 382            ba = self.read(8)
 383
 384            checks = {
 385                'is feature reply': ba[0] == I2C.GET_VCP_REPLY,
 386                'supported VCP opcode': ba[1] == 0,
 387                'answer matches request': ba[2] == vcp_code
 388            }
 389            if False in checks.values():
 390                self.logger.error('i2c read check failed: ' + repr(checks))
 391                raise I2CValidationError('i2c read check failed: ' + repr(checks))
 392
 393            # current and max values
 394            return int.from_bytes(ba[6:8], 'big'), int.from_bytes(ba[4:6], 'big')
 395
 396    @classmethod
 397    def get_display_info(cls, display: Optional[Union[int, str]] = None) -> List[dict]:
 398        '''
 399        Returns information about detected displays by querying the various I2C buses
 400
 401        Args:
 402            display (str or int): The display to return info about.
 403                Pass in the serial number, name, model, interface, edid or index.
 404                This is passed to `filter_monitors`
 405
 406        Returns:
 407            list: list of dicts
 408
 409        Example:
 410            ```python
 411            import screen_brightness_control as sbc
 412
 413            # get info about all displays
 414            info = sbc.linux.I2C.get_display_info()
 415            # EG output: [{'name': 'Benq GL2450H', 'model': 'GL2450H', 'manufacturer': 'BenQ', 'edid': '00ffff...'}]
 416
 417            # get info about the primary display
 418            primary_info = sbc.linux.I2C.get_display_info(0)[0]
 419
 420            # get info about a display called 'Benq GL2450H'
 421            benq_info = sbc.linux.I2C.get_display_info('Benq GL2450H')[0]
 422            ```
 423        '''
 424        all_displays = __cache__.get('i2c_display_info')
 425        if all_displays is None:
 426            all_displays = []
 427            index = 0
 428
 429            for i2c_path in glob.glob('/dev/i2c-*'):
 430                if not os.path.exists(i2c_path):
 431                    continue
 432
 433                try:
 434                    # open the I2C device using the host read address
 435                    device = cls.I2CDevice(i2c_path, cls.HOST_ADDR_R)
 436                    # read some 512 bytes from the device
 437                    data = device.read(512)
 438                except IOError as e:
 439                    cls.logger.error(f'IOError reading from device {i2c_path}: {e}')
 440                    continue
 441
 442                # search for the EDID header within our 512 read bytes
 443                start = data.find(bytes.fromhex('00 FF FF FF FF FF FF 00'))
 444                if start < 0:
 445                    continue
 446
 447                # grab 128 bytes of the edid
 448                edid = data[start: start + 128]
 449                # parse the EDID
 450                manufacturer_id, manufacturer, model, name, serial = EDID.parse(edid)
 451                # convert edid to hex string
 452                edid = ''.join(f'{i:02x}' for i in edid)
 453
 454                all_displays.append(
 455                    {
 456                        'name': name,
 457                        'model': model,
 458                        'manufacturer': manufacturer,
 459                        'manufacturer_id': manufacturer_id,
 460                        'serial': serial,
 461                        'method': cls,
 462                        'index': index,
 463                        'edid': edid,
 464                        'i2c_bus': i2c_path
 465                    }
 466                )
 467                index += 1
 468
 469            if all_displays:
 470                __cache__.store('i2c_display_info', all_displays, expires=2)
 471
 472        if display is not None:
 473            return filter_monitors(display=display, haystack=all_displays, include=['i2c_bus'])
 474        return all_displays
 475
 476    @classmethod
 477    def get_brightness(cls, display: Optional[int] = None) -> List[int]:
 478        '''
 479        Gets the brightness for a display by querying the I2C bus
 480
 481        Args:
 482            display (int): The specific display you wish to query.
 483
 484        Returns:
 485            list: list of ints (0 to 100)
 486
 487        Example:
 488            ```python
 489            import screen_brightness_control as sbc
 490
 491            # get the current display brightness
 492            current_brightness = sbc.linux.I2C.get_brightness()
 493
 494            # get the brightness of the primary display
 495            primary_brightness = sbc.linux.I2C.get_brightness(display = 0)[0]
 496
 497            # get the brightness of the secondary display
 498            secondary_brightness = sbc.linux.I2C.get_brightness(display = 1)[0]
 499            ```
 500        '''
 501        all_displays = cls.get_display_info()
 502        if display is not None:
 503            all_displays = [all_displays[display]]
 504
 505        results = []
 506        for device in all_displays:
 507            interface = cls.DDCInterface(device['i2c_bus'])
 508            value, max_value = interface.getvcp(0x10)
 509
 510            # make sure display's max brighness is cached
 511            cache_ident = '%s-%s-%s' % (device['name'], device['model'], device['serial'])
 512            if cache_ident not in cls._max_brightness_cache:
 513                cls._max_brightness_cache[cache_ident] = max_value
 514                cls.logger.info(f'{cache_ident} max brightness:{max_value} (current: {value})')
 515
 516            if max_value != 100:
 517                # if max value is not 100 then we have to adjust the scale to be
 518                # a percentage
 519                value = int((value / max_value) * 100)
 520
 521            results.append(value)
 522
 523        return results
 524
 525    @classmethod
 526    def set_brightness(cls, value: int, display: Optional[int] = None):
 527        '''
 528        Sets the brightness for a display by writing to the I2C bus
 529
 530        Args:
 531            value (int): Set the brightness to this value
 532            display (int): The specific display you wish to adjust.
 533
 534        Example:
 535            ```python
 536            import screen_brightness_control as sbc
 537
 538            # set the brightness to 50%
 539            sbc.linux.I2C.set_brightness(50)
 540
 541            # set the primary display brightness to 75%
 542            sbc.linux.I2C.set_brightness(75, display = 0)
 543
 544            # set the secondary display brightness to 25%
 545            sbc.linux.I2C.set_brightness(25, display = 1)
 546            ```
 547        '''
 548        all_displays = cls.get_display_info()
 549        if display is not None:
 550            all_displays = [all_displays[display]]
 551
 552        for device in all_displays:
 553            # make sure display brightness max value is cached
 554            cache_ident = '%s-%s-%s' % (device['name'], device['model'], device['serial'])
 555            if cache_ident not in cls._max_brightness_cache:
 556                cls.get_brightness(display=device['index'])
 557
 558            # scale the brightness value according to the max brightness
 559            max_value = cls._max_brightness_cache[cache_ident]
 560            if max_value != 100:
 561                value = int((value / 100) * max_value)
 562
 563            interface = cls.DDCInterface(device['i2c_bus'])
 564            interface.setvcp(0x10, value)
 565
 566
 567class Light(BrightnessMethod):
 568    '''collection of screen brightness related methods using the light executable'''
 569
 570    executable: str = 'light'
 571    '''the light executable to be called'''
 572
 573    @classmethod
 574    def get_display_info(cls, display: Optional[Union[int, str]] = None) -> List[dict]:
 575        '''
 576        Returns information about detected displays as reported by Light.
 577
 578        It works by taking the output of `SysFiles.get_display_info` and
 579        filtering out any displays that aren't supported by Light
 580
 581        Args:
 582            display (str or int): The display to return info about.
 583                Pass in the serial number, name, model, interface, edid or index.
 584                This is passed to `filter_monitors`
 585
 586        Returns:
 587            list: list of dicts
 588
 589        Example:
 590            ```python
 591            import screen_brightness_control as sbc
 592
 593            # get info about all displays
 594            info = sbc.linux.Light.get_display_info()
 595            # EG output: [{'name': 'edp-backlight', 'path': '/sys/class/backlight/edp-backlight', edid': '00ffff...'}]
 596
 597            # get info about the primary display
 598            primary_info = sbc.linux.Light.get_display_info(0)[0]
 599
 600            # get info about a display called 'edp-backlight'
 601            edp_info = sbc.linux.Light.get_display_info('edp-backlight')[0]
 602            ```
 603        '''
 604        light_output = check_output([cls.executable, '-L']).decode()
 605        displays = []
 606        index = 0
 607        for device in SysFiles.get_display_info():
 608            # SysFiles scrapes info from the same place that Light used to
 609            # so it makes sense to use that output
 610            if device['path'].replace('/sys/class', 'sysfs') in light_output:
 611                del device['scale']
 612                device['light_path'] = device['path'].replace('/sys/class', 'sysfs')
 613                device['method'] = cls
 614                device['index'] = index
 615
 616                displays.append(device)
 617                index += 1
 618
 619        if display is not None:
 620            displays = filter_monitors(display=display, haystack=displays, include=['path', 'light_path'])
 621        return displays
 622
 623    @classmethod
 624    def set_brightness(cls, value: int, display: Optional[int] = None):
 625        '''
 626        Sets the brightness for a display using the light executable
 627
 628        Args:
 629            value (int): Sets the brightness to this value
 630            display (int): The specific display you wish to query.
 631
 632        Example:
 633            ```python
 634            import screen_brightness_control as sbc
 635
 636            # set the brightness to 50%
 637            sbc.linux.Light.set_brightness(50)
 638
 639            # set the primary display brightness to 75%
 640            sbc.linux.Light.set_brightness(75, display = 0)
 641
 642            # set the secondary display brightness to 25%
 643            sbc.linux.Light.set_brightness(25, display = 1)
 644            ```
 645        '''
 646        info = cls.get_display_info()
 647        if display is not None:
 648            info = [info[display]]
 649
 650        for i in info:
 651            check_output(f'{cls.executable} -S {value} -s {i["light_path"]}'.split(" "))
 652
 653    @classmethod
 654    def get_brightness(cls, display: Optional[int] = None) -> List[int]:
 655        '''
 656        Gets the brightness for a display using the light executable
 657
 658        Args:
 659            display (int): The specific display you wish to query.
 660
 661        Returns:
 662            list: list of ints (0 to 100)
 663
 664        Example:
 665            ```python
 666            import screen_brightness_control as sbc
 667
 668            # get the current display brightness
 669            current_brightness = sbc.linux.Light.get_brightness()
 670
 671            # get the brightness of the primary display
 672            primary_brightness = sbc.linux.Light.get_brightness(display = 0)[0]
 673
 674            # get the brightness of the secondary display
 675            edp_brightness = sbc.linux.Light.get_brightness(display = 1)[0]
 676            ```
 677        '''
 678        info = cls.get_display_info()
 679        if display is not None:
 680            info = [info[display]]
 681
 682        results = []
 683        for i in info:
 684            results.append(
 685                check_output([cls.executable, '-G', '-s', i['light_path']])
 686            )
 687        results = [int(round(float(i.decode()), 0)) for i in results]
 688        return results
 689
 690
 691class XRandr(BrightnessMethodAdv):
 692    '''collection of screen brightness related methods using the xrandr executable'''
 693
 694    executable: str = 'xrandr'
 695    '''the xrandr executable to be called'''
 696
 697    @classmethod
 698    def _gdi(cls):
 699        '''
 700        .. warning:: Don't use this
 701           This function isn't final and I will probably make breaking changes to it.
 702           You have been warned
 703
 704        Gets all displays reported by XRandr even if they're not supported
 705        '''
 706        xrandr_output = check_output([cls.executable, '--verbose']).decode().split('\n')
 707
 708        display_count = 0
 709        tmp_display = {}
 710
 711        for line_index, line in enumerate(xrandr_output):
 712            if line == '':
 713                continue
 714
 715            if not line.startswith((' ', '\t')) and 'connected' in line and 'disconnected' not in line:
 716                if tmp_display:
 717                    yield tmp_display
 718
 719                tmp_display = {
 720                    'name': line.split(' ')[0],
 721                    'interface': line.split(' ')[0],
 722                    'method': cls,
 723                    'index': display_count,
 724                    'model': None,
 725                    'serial': None,
 726                    'manufacturer': None,
 727                    'manufacturer_id': None,
 728                    'edid': None,
 729                    'unsupported': line.startswith('XWAYLAND')
 730                }
 731                display_count += 1
 732
 733            elif 'EDID:' in line:
 734                # extract the edid from the chunk of the output that will contain the edid
 735                edid = ''.join(
 736                    i.replace('\t', '') for i in xrandr_output[line_index + 1: line_index + 9]
 737                )
 738                tmp_display['edid'] = edid
 739
 740                for key, value in zip(
 741                    ('manufacturer_id', 'manufacturer', 'model', 'name', 'serial'),
 742                    EDID.parse(tmp_display['edid'])
 743                ):
 744                    if value is None:
 745                        continue
 746                    tmp_display[key] = value
 747
 748            elif 'Brightness:' in line:
 749                tmp_display['brightness'] = int(float(line.replace('Brightness:', '')) * 100)
 750
 751        if tmp_display:
 752            yield tmp_display
 753
 754    @classmethod
 755    def get_display_info(cls, display: Optional[Union[int, str]] = None, brightness: bool = False) -> List[dict]:
 756        '''
 757        Returns info about all detected displays as reported by xrandr
 758
 759        Args:
 760            display (str or int): The display to return info about.
 761                Pass in the serial number, name, model, interface, edid or index.
 762                This is passed to `filter_monitors`
 763            brightness (bool): whether to include the current brightness
 764                in the returned info
 765
 766        Returns:
 767            list: list of dicts
 768
 769        Example:
 770            ```python
 771            import screen_brightness_control as sbc
 772
 773            info = sbc.linux.XRandr.get_display_info()
 774            for i in info:
 775                print('================')
 776                for key, value in i.items():
 777                    print(key, ':', value)
 778
 779            # get information about the first XRandr addressable display
 780            primary_info = sbc.linux.XRandr.get_display_info(0)[0]
 781
 782            # get information about a display with a specific name
 783            benq_info = sbc.linux.XRandr.get_display_info('BenQ GL2450HM')[0]
 784            ```
 785        '''
 786        valid_displays = []
 787        for item in cls._gdi():
 788            if item['unsupported']:
 789                continue
 790            if not brightness:
 791                del item['brightness']
 792            del item['unsupported']
 793            valid_displays.append(item)
 794        if display is not None:
 795            valid_displays = filter_monitors(display=display, haystack=valid_displays, include=['interface'])
 796        return valid_displays
 797
 798    @classmethod
 799    def get_brightness(cls, display: Optional[int] = None) -> List[int]:
 800        '''
 801        Returns the brightness for a display using the xrandr executable
 802
 803        Args:
 804            display (int): The specific display you wish to query.
 805
 806        Returns:
 807            list: list of integers (from 0 to 100)
 808
 809        Example:
 810            ```python
 811            import screen_brightness_control as sbc
 812
 813            # get the current brightness
 814            current_brightness = sbc.linux.XRandr.get_brightness()
 815
 816            # get the current brightness for the primary display
 817            primary_brightness = sbc.linux.XRandr.get_brightness(display=0)[0]
 818            ```
 819        '''
 820        monitors = cls.get_display_info(brightness=True)
 821        if display is not None:
 822            monitors = [monitors[display]]
 823        brightness = [i['brightness'] for i in monitors]
 824
 825        return brightness
 826
 827    @classmethod
 828    def set_brightness(cls, value: int, display: Optional[int] = None):
 829        '''
 830        Sets the brightness for a display using the xrandr executable
 831
 832        Args:
 833            value (int): Sets the brightness to this value
 834            display (int): The specific display you wish to query.
 835
 836        Example:
 837            ```python
 838            import screen_brightness_control as sbc
 839
 840            # set the brightness to 50
 841            sbc.linux.XRandr.set_brightness(50)
 842
 843            # set the brightness of the primary display to 75
 844            sbc.linux.XRandr.set_brightness(75, display=0)
 845            ```
 846        '''
 847        value = str(float(value) / 100)
 848        info = cls.get_display_info()
 849        if display is not None:
 850            info = [info[display]]
 851
 852        for i in info:
 853            check_output([cls.executable, '--output', i['interface'], '--brightness', value])
 854
 855
 856class DDCUtil(BrightnessMethodAdv):
 857    '''collection of screen brightness related methods using the ddcutil executable'''
 858    logger = logger.getChild('DDCUtil')
 859
 860    executable: str = 'ddcutil'
 861    '''the ddcutil executable to be called'''
 862    sleep_multiplier: float = 0.5
 863    '''how long ddcutil should sleep between each DDC request (lower is shorter).
 864    See [the ddcutil docs](https://www.ddcutil.com/performance_options/) for more info.'''
 865    cmd_max_tries: int = 10
 866    '''max number of retries when calling the ddcutil'''
 867    _max_brightness_cache: dict = {}
 868    '''Cache for displays and their maximum brightness values'''
 869
 870    @classmethod
 871    def _gdi(cls):
 872        '''
 873        .. warning:: Don't use this
 874           This function isn't final and I will probably make breaking changes to it.
 875           You have been warned
 876
 877        Gets all displays reported by DDCUtil even if they're not supported
 878        '''
 879        raw_ddcutil_output = str(
 880            check_output(
 881                [
 882                    cls.executable, 'detect', '-v', '--async',
 883                    f'--sleep-multiplier={cls.sleep_multiplier}'
 884                ], max_tries=cls.cmd_max_tries
 885            )
 886        )[2:-1].split('\\n')
 887        # Use -v to get EDID string but this means output cannot be decoded.
 888        # Or maybe it can. I don't know the encoding though, so let's assume it cannot be decoded.
 889        # Use str()[2:-1] workaround
 890
 891        # include "Invalid display" sections because they tell us where one displays metadata ends
 892        # and another begins. We filter out invalid displays later on
 893        ddcutil_output = [i for i in raw_ddcutil_output if i.startswith(('Invalid display', 'Display', '\t', ' '))]
 894        tmp_display = {}
 895        display_count = 0
 896
 897        for line_index, line in enumerate(ddcutil_output):
 898            if not line.startswith(('\t', ' ')):
 899                if tmp_display:
 900                    yield tmp_display
 901
 902                tmp_display = {
 903                    'method': cls,
 904                    'index': display_count,
 905                    'model': None,
 906                    'serial': None,
 907                    'bin_serial': None,
 908                    'manufacturer': None,
 909                    'manufacturer_id': None,
 910                    'edid': None,
 911                    'unsupported': 'invalid display' in line.lower()
 912                }
 913                display_count += 1
 914
 915            elif 'I2C bus' in line:
 916                tmp_display['i2c_bus'] = line[line.index('/'):]
 917                tmp_display['bus_number'] = int(tmp_display['i2c_bus'].replace('/dev/i2c-', ''))
 918
 919            elif 'Mfg id' in line:
 920                # Recently ddcutil has started reporting manufacturer IDs like
 921                # 'BNQ - UNK' or 'MSI - Microstep' so we have to split the line
 922                # into chunks of alpha chars and check for a valid mfg id
 923                for code in re.split(r'[^A-Za-z]', line.replace('Mfg id:', '').replace(' ', '')):
 924                    if len(code) != 3:
 925                        # all mfg ids are 3 chars long
 926                        continue
 927
 928                    try:
 929                        (
 930                            tmp_display['manufacturer_id'],
 931                            tmp_display['manufacturer']
 932                        ) = _monitor_brand_lookup(code)
 933                    except TypeError:
 934                        continue
 935                    else:
 936                        break
 937
 938            elif 'Model' in line:
 939                # the split() removes extra spaces
 940                name = line.replace('Model:', '').split()
 941                try:
 942                    tmp_display['model'] = name[1]
 943                except IndexError:
 944                    pass
 945                tmp_display['name'] = ' '.join(name)
 946
 947            elif 'Serial number' in line:
 948                tmp_display['serial'] = line.replace('Serial number:', '').replace(' ', '') or None
 949
 950            elif 'Binary serial number:' in line:
 951                tmp_display['bin_serial'] = line.split(' ')[-1][3:-1]
 952
 953            elif 'EDID hex dump:' in line:
 954                try:
 955                    tmp_display['edid'] = ''.join(
 956                        ''.join(i.split()[1:17]) for i in ddcutil_output[line_index + 2: line_index + 10]
 957                    )
 958                except Exception:
 959                    pass
 960
 961        if tmp_display:
 962            yield tmp_display
 963
 964    @classmethod
 965    def get_display_info(cls, display: Optional[Union[int, str]] = None) -> List[dict]:
 966        '''
 967        Returns information about all DDC compatible displays shown by DDCUtil
 968        Works by calling the command 'ddcutil detect' and parsing the output.
 969
 970        Args:
 971            display (int or str): The display to return info about.
 972                Pass in the serial number, name, model, i2c bus, edid or index.
 973                This is passed to `filter_monitors`
 974
 975        Returns:
 976            list: list of dicts
 977
 978        Example:
 979            ```python
 980            import screen_brightness_control as sbc
 981
 982            info = sbc.linux.DDCUtil.get_display_info()
 983            for i in info:
 984                print('================')
 985                for key, value in i.items():
 986                    print(key, ':', value)
 987
 988            # get information about the first DDCUtil addressable display
 989            primary_info = sbc.linux.DDCUtil.get_display_info(0)[0]
 990
 991            # get information about a display with a specific name
 992            benq_info = sbc.linux.DDCUtil.get_display_info('BenQ GL2450HM')[0]
 993            ```
 994        '''
 995        valid_displays = __cache__.get('ddcutil_monitors_info')
 996        if valid_displays is None:
 997            valid_displays = []
 998            for item in cls._gdi():
 999                if item['unsupported']:
1000                    continue
1001                del item['unsupported']
1002                valid_displays.append(item)
1003
1004            if valid_displays:
1005                __cache__.store('ddcutil_monitors_info', valid_displays)
1006
1007        if display is not None:
1008            valid_displays = filter_monitors(display=display, haystack=valid_displays, include=['i2c_bus'])
1009        return valid_displays
1010
1011    @classmethod
1012    def get_brightness(cls, display: Optional[int] = None) -> List[int]:
1013        '''
1014        Returns the brightness for a display using the ddcutil executable
1015
1016        Args:
1017            display (int): The specific display you wish to query.
1018
1019        Returns:
1020            list: list of ints (0 to 100)
1021
1022        Example:
1023            ```python
1024            import screen_brightness_control as sbc
1025
1026            # get the current brightness
1027            current_brightness = sbc.linux.DDCUtil.get_brightness()
1028
1029            # get the current brightness for the primary display
1030            primary_brightness = sbc.linux.DDCUtil.get_brightness(display=0)[0]
1031            ```
1032        '''
1033        monitors = cls.get_display_info()
1034        if display is not None:
1035            monitors = [monitors[display]]
1036
1037        res = []
1038        for monitor in monitors:
1039            value = __cache__.get(f'ddcutil_brightness_{monitor["index"]}')
1040            if value is None:
1041                cmd_out = check_output(
1042                    [
1043                        cls.executable,
1044                        'getvcp', '10', '-t',
1045                        '-b', str(monitor['bus_number']),
1046                        f'--sleep-multiplier={cls.sleep_multiplier}'
1047                    ], max_tries=cls.cmd_max_tries
1048                ).decode().split(' ')
1049
1050                value = int(cmd_out[-2])
1051                max_value = int(cmd_out[-1])
1052                if max_value != 100:
1053                    # if the max brightness is not 100 then the number is not a percentage
1054                    # and will need to be scaled
1055                    value = int((value / max_value) * 100)
1056
1057                # now make sure max brightness is recorded so set_brightness can use it
1058                cache_ident = '%s-%s-%s' % (monitor['name'], monitor['serial'], monitor['bin_serial'])
1059                if cache_ident not in cls._max_brightness_cache:
1060                    cls._max_brightness_cache[cache_ident] = max_value
1061                    cls.logger.debug(f'{cache_ident} max brightness:{max_value} (current: {value})')
1062
1063                __cache__.store(f'ddcutil_brightness_{monitor["index"]}', value, expires=0.5)
1064            res.append(value)
1065        return res
1066
1067    @classmethod
1068    def set_brightness(cls, value: int, display: Optional[int] = None):
1069        '''
1070        Sets the brightness for a display using the ddcutil executable
1071
1072        Args:
1073            value (int): Sets the brightness to this value
1074            display (int): The specific display you wish to query.
1075
1076        Example:
1077            ```python
1078            import screen_brightness_control as sbc
1079
1080            # set the brightness to 50
1081            sbc.linux.DDCUtil.set_brightness(50)
1082
1083            # set the brightness of the primary display to 75
1084            sbc.linux.DDCUtil.set_brightness(75, display=0)
1085            ```
1086        '''
1087        monitors = cls.get_display_info()
1088        if display is not None:
1089            monitors = [monitors[display]]
1090
1091        __cache__.expire(startswith='ddcutil_brightness_')
1092        for monitor in monitors:
1093            # check if monitor has a max brightness that requires us to scale this value
1094            cache_ident = '%s-%s-%s' % (monitor['name'], monitor['serial'], monitor['bin_serial'])
1095            if cache_ident not in cls._max_brightness_cache:
1096                cls.get_brightness(display=monitor['index'])
1097
1098            if cls._max_brightness_cache[cache_ident] != 100:
1099                value = int((value / 100) * cls._max_brightness_cache[cache_ident])
1100
1101            check_output(
1102                [
1103                    cls.executable, 'setvcp', '10', str(value),
1104                    '-b', str(monitor['bus_number']),
1105                    f'--sleep-multiplier={cls.sleep_multiplier}'
1106                ], max_tries=cls.cmd_max_tries
1107            )
1108
1109
1110def list_monitors_info(
1111    method: Optional[str] = None, allow_duplicates: bool = False, unsupported: bool = False
1112) -> List[dict]:
1113    '''
1114    Lists detailed information about all detected displays
1115
1116    Args:
1117        method (str): the method the display can be addressed by. See `screen_brightness_control.get_methods`
1118            for more info on available methods
1119        allow_duplicates (bool): whether to filter out duplicate displays (displays with the same EDID) or not
1120        unsupported (bool): include detected displays that are invalid or unsupported
1121
1122    Returns:
1123        list: list of dicts
1124
1125    Example:
1126        ```python
1127        import screen_brightness_control as sbc
1128
1129        displays = sbc.linux.list_monitors_info()
1130        for display in displays:
1131            print('=======================')
1132            # the manufacturer name plus the model OR a generic name for the display, depending on the method
1133            print('Name:', display['name'])
1134            # the general model of the display
1135            print('Model:', display['model'])
1136            # the serial of the display
1137            print('Serial:', display['serial'])
1138            # the name of the brand of the display
1139            print('Manufacturer:', display['manufacturer'])
1140            # the 3 letter code corresponding to the brand name, EG: BNQ -> BenQ
1141            print('Manufacturer ID:', display['manufacturer_id'])
1142            # the index of that display FOR THE SPECIFIC METHOD THE DISPLAY USES
1143            print('Index:', display['index'])
1144            # the method this display can be addressed by
1145            print('Method:', display['method'])
1146        ```
1147    '''
1148    all_methods = get_methods(method).values()
1149    haystack = []
1150    for method_class in all_methods:
1151        try:
1152            if unsupported and issubclass(method_class, BrightnessMethodAdv):
1153                haystack += method_class._gdi()
1154            else:
1155                haystack += method_class.get_display_info()
1156        except Exception as e:
1157            logger.warning(f'error grabbing display info from {method_class} - {format_exc(e)}')
1158            pass
1159
1160    if allow_duplicates:
1161        return haystack
1162
1163    try:
1164        # use filter_monitors to remove duplicates
1165        return filter_monitors(haystack=haystack)
1166    except NoValidDisplayError:
1167        return []

 21class SysFiles(BrightnessMethod):
 22    '''
 23    A way of getting display information and adjusting the brightness
 24    that does not rely on any 3rd party software.
 25
 26    This class works with displays that show up in the `/sys/class/backlight`
 27    directory (so usually laptop displays).
 28
 29    To set the brightness, your user will need write permissions for
 30    `/sys/class/backlight/*/brightness` or you will need to run the program
 31    as root.
 32    '''
 33    logger = logger.getChild('SysFiles')
 34
 35    @classmethod
 36    def get_display_info(cls, display: Optional[Union[int, str]] = None) -> List[dict]:
 37        '''
 38        Returns information about detected displays by reading files from the
 39        `/sys/class/backlight` directory
 40
 41        Args:
 42            display (str or int): The display to return info about.
 43                Pass in the serial number, name, model, interface, edid or index.
 44                This is passed to `filter_monitors`
 45
 46        Returns:
 47            list: list of dicts
 48
 49        Example:
 50            ```python
 51            import screen_brightness_control as sbc
 52
 53            # get info about all displays
 54            info = sbc.linux.SysFiles.get_display_info()
 55            # EG output: [{'name': 'edp-backlight', 'path': '/sys/class/backlight/edp-backlight', edid': '00ffff...'}]
 56
 57            # get info about the primary display
 58            primary_info = sbc.linux.SysFiles.get_display_info(0)[0]
 59
 60            # get info about a display called 'edp-backlight'
 61            edp_info = sbc.linux.SysFiles.get_display_info('edp-backlight')[0]
 62            ```
 63        '''
 64        subsystems = set()
 65        for folder in os.listdir('/sys/class/backlight'):
 66            if os.path.isdir(f'/sys/class/backlight/{folder}/subsystem'):
 67                subsystems.add(tuple(os.listdir(f'/sys/class/backlight/{folder}/subsystem')))
 68
 69        all_displays = {}
 70        index = 0
 71
 72        for subsystem in subsystems:
 73
 74            device = {
 75                'name': subsystem[0],
 76                'path': f'/sys/class/backlight/{subsystem[0]}',
 77                'method': cls,
 78                'index': index,
 79                'model': None,
 80                'serial': None,
 81                'manufacturer': None,
 82                'manufacturer_id': None,
 83                'edid': None,
 84                'scale': None
 85            }
 86
 87            for folder in subsystem:
 88                # subsystems like intel_backlight usually have an acpi_video0
 89                # counterpart, which we don't want so lets find the 'best' candidate
 90                try:
 91                    with open(os.path.join(f'/sys/class/backlight/{folder}/max_brightness')) as f:
 92                        scale = int(f.read().rstrip(' \n')) / 100
 93
 94                    # use the display with the highest resolution scale
 95                    if device['scale'] is None or scale > device['scale']:
 96                        device['name'] = folder
 97                        device['path'] = f'/sys/class/backlight/{folder}'
 98                        device['scale'] = scale
 99                except (FileNotFoundError, TypeError) as e:
100                    cls.logger.error(
101                        f'error getting highest resolution scale for {folder}'
102                        f' - {format_exc(e)}'
103                    )
104                    continue
105
106            if os.path.isfile('%s/device/edid' % device['path']):
107                device['edid'] = EDID.hexdump('%s/device/edid' % device['path'])
108
109                for key, value in zip(
110                    ('manufacturer_id', 'manufacturer', 'model', 'name', 'serial'),
111                    EDID.parse(device['edid'])
112                ):
113                    if value is None:
114                        continue
115                    device[key] = value
116
117            all_displays[device['edid']] = device
118            index += 1
119
120        all_displays = list(all_displays.values())
121        if display is not None:
122            all_displays = filter_monitors(display=display, haystack=all_displays, include=['path'])
123        return all_displays
124
125    @classmethod
126    def get_brightness(cls, display: Optional[int] = None) -> List[int]:
127        '''
128        Gets the brightness for a display by reading the brightness files
129        stored in `/sys/class/backlight/*/brightness`
130
131        Args:
132            display (int): The specific display you wish to query.
133
134        Returns:
135            list: list of ints (0 to 100)
136
137        Example:
138            ```python
139            import screen_brightness_control as sbc
140
141            # get the current display brightness
142            current_brightness = sbc.linux.SysFiles.get_brightness()
143
144            # get the brightness of the primary display
145            primary_brightness = sbc.linux.SysFiles.get_brightness(display = 0)[0]
146
147            # get the brightness of the secondary display
148            secondary_brightness = sbc.linux.SysFiles.get_brightness(display = 1)[0]
149            ```
150        '''
151        info = cls.get_display_info()
152        if display is not None:
153            info = [info[display]]
154
155        results = []
156        for device in info:
157            with open(os.path.join(device['path'], 'brightness'), 'r') as f:
158                brightness = int(f.read().rstrip('\n'))
159            results.append(int(brightness / device['scale']))
160
161        return results
162
163    @classmethod
164    def set_brightness(cls, value: int, display: Optional[int] = None):
165        '''
166        Sets the brightness for a display by writing to the brightness files
167        stored in `/sys/class/backlight/*/brightness`.
168        This function requires permission to write to these files which is
169        usually provided when it's run as root.
170
171        Args:
172            value (int): Sets the brightness to this value
173            display (int): The specific display you wish to adjust.
174
175        Example:
176            ```python
177            import screen_brightness_control as sbc
178
179            # set the brightness to 50%
180            sbc.linux.SysFiles.set_brightness(50)
181
182            # set the primary display brightness to 75%
183            sbc.linux.SysFiles.set_brightness(75, display = 0)
184
185            # set the secondary display brightness to 25%
186            sbc.linux.SysFiles.set_brightness(25, display = 1)
187            ```
188        '''
189        info = cls.get_display_info()
190        if display is not None:
191            info = [info[display]]
192
193        for device in info:
194            with open(os.path.join(device['path'], 'brightness'), 'w') as f:
195                f.write(str(int(value * device['scale'])))