Implement Listener Class

README.md

@@ -8,10 +8,25 @@ This package allows to detect if the user is using Dark Mode on:
 
 The main application of this package is to detect the Dark mode from your GUI Python application (Tkinter/wx/pyqt/qt for python (pyside)/...) and apply the needed adjustments to your interface. Darkdetect is particularly useful if your GUI library **does not** provide a public API for this detection (I am looking at you, Qt). In addition, this package does not depend on other modules or packages that are not already included in standard Python distributions.
 
+## Install
 
-## Usage
+The preferred channel is PyPI:
+```bash
+pip install darkdetect
+```
+
+Alternatively, you are free to vendor directly a copy of Darkdetect in your app. Further information on vendoring can be found [here](https://medium.com/underdog-io-engineering/vendoring-python-dependencies-with-pip-b9eb6078b9c0).
+
+### macOS Listener Support
 
+To enable the macOS listener, additional components are required, these can be installed via:
+```bash
+pip install darkdetect[macos-listener]
 ```
+
+## Usage
+
+```python
 import darkdetect
 
 >>> darkdetect.theme()
@@ -25,39 +40,82 @@ False
 ```
 It's that easy.
 
-You can create a dark mode switch listener daemon thread with `darkdetect.listener` and pass a callback function. The function will be called with string "Dark" or "Light" when the OS switches the dark mode setting.
+### Listener
+
+`darkdetect` exposes a listener API which is far more efficient than busy waiting on `theme()` changes.
+This API is exposed primarily via a `Listener` class.
+Detailed API documentation can be found [here](docs/api.md).
+For a quick overview: the `darkdetect.Listener` class exposes the following methods / members:
+
+1. `.__init__(callback: Optional[Callable[[str], None]])`: The constructor simply sets `.callback` to the given callback argument
+1. `.callback: Optional[Callable[[str], None]]`: The settable callback function that the listener uses; it will be passed "Dark" or "Light" when the theme is changed.
+1. `.listen()`: This starts listening for theme changes, it will invoke
+`self.callback(theme_name)` when a change is detected.
+1. `.stop(timeout: Optional[int]) -> bool`: 
+This function attempts to stop the listener,
+waiting at most `timeout` seconds (`None` means infinite),
+returning `True` on success, `False` on timeout.
+Regardless of the result, after `.stop` returns, theme changes 
+will no longer trigger `callback`, though running callbacks will
+not be interrupted.
+`.stop` may safely be re-invoked any number of times, but must succeed at before re-calling `.listen()`.
+
+##### Wrapper Function
 
-``` python
+The simplest method of using this API is the `darkdetect.listener` function,
+which takes a callback function as an argument.
+This function is a small wrapper around `Listener(callback).listen()`.
+_In this mode, the listener cannot be stopped_; forceful stops may not clean up resources (such as subprocesses if applicable).
+
+### Examples
+
+Below are 2 examples of basic usage; additional examples can be found [here](docs/examples.md).
+
+##### A simple listener:
+```python
 import threading
 import darkdetect
 
-# def listener(callback: typing.Callable[[str], None]) -> None: ...
-
-t = threading.Thread(target=darkdetect.listener, args=(print,))
-t.daemon = True
+listener = darkdetect.Listener(print)
+t = threading.Thread(target=listener.listen, daemon=True)
+# OR: t = threading.Thread(target=darkdetect.listener, args=(print,), daemon=True)
 t.start()
 ```
 
-## Install
+##### User input controlling listener
+```python
+import threading
+import darkdetect
+import time
 
-The preferred channel is PyPI:
-```
-pip install darkdetect
-```
+listener = darkdetect.Listener(print)
+t = threading.Thread(target=listener.listen)
+t.start()
 
-Alternatively, you are free to vendor directly a copy of Darkdetect in your app. Further information on vendoring can be found [here](https://medium.com/underdog-io-engineering/vendoring-python-dependencies-with-pip-b9eb6078b9c0).
+txt = ""
+while txt != "quit":
+  txt = input()
+  if txt == "print":
+    listener.callback = print
+  elif txt == "verbose":
+    listener.callback = lambda x: print(f"The theme changed to {x} as {time.time()}")
+listener.stop(0)
+
+print("Waiting for running callbacks to complete and the listener to terminate")
+if not listener.stop(timeout=5):
+  print("Callbacks/listener are still running after 5 seconds!")
+```
 
-## Optional Installs
+## Known Issues
 
-To enable the macOS listener, additional components are required, these can be installed via:
-```bash
-pip install darkdetect[macos-listener]
-```
+1. On macOS, detection of the dark menu bar and dock option (available from macOS 10.10) is not supported.
+1. On macOS, using the listener API in a bundled app where `sys.executable` is not a python interpreter is not supported (though it may still work as it uses the same code path as `multiprocessing`).
+1. On Windows, the after `Listener.stop(None)` is not supported as it may not die until another theme change is detected.
+Future invocations of `callback` will not be made, but the listener itself will persist.
 
 ## Notes
 
 - This software is licensed under the terms of the 3-clause BSD License.
-- This package can be installed on any operative system, but it will always return `None` unless executed on a OS that supports Dark Mode, including older versions of macOS and Windows.
-- On macOS, detection of the dark menu bar and dock option (available from macOS 10.10) is not supported.
+- This package can be installed on any operative system, but `theme()`, `isDark()`, and `isLight()` will always return `None` unless executed on a OS that supports Dark Mode, including older versions of macOS and Windows.
 - [Details](https://stackoverflow.com/questions/25207077/how-to-detect-if-os-x-is-in-dark-mode) on the detection method used on macOS.
 - [Details](https://askubuntu.com/questions/1261366/detecting-dark-mode#comment2132694_1261366) on the experimental detection method used on Linux.

darkdetect/__init__.py

@@ -8,37 +8,70 @@
 
 import sys
 import platform
+from typing import Callable, Optional, Type
+
+from ._base_listener import BaseListener
+Listener: Type[BaseListener]
+
+#
+# Import correct the listener for the given OS
+#
 
 def macos_supported_version():
-    sysver = platform.mac_ver()[0] #typically 10.14.2 or 12.3
-    major = int(sysver.split('.')[0])
+    sysver: str = platform.mac_ver()[0]  # typically 10.14.2 or 12.3
+    major: int = int(sysver.split('.')[0])
     if major < 10:
         return False
-    elif major >= 11:
+    if major >= 11:
         return True
-    else:
-        minor = int(sysver.split('.')[1])
-        if minor < 14:
-            return False
-        else:
-            return True
-
-if sys.platform == "darwin":
-    if macos_supported_version():
-        from ._mac_detect import *
-    else:
-        from ._dummy import *
-elif sys.platform == "win32" and platform.release().isdigit() and int(platform.release()) >= 10:
-    # Checks if running Windows 10 version 10.0.14393 (Anniversary Update) OR HIGHER. The getwindowsversion method returns a tuple.
-    # The third item is the build number that we can use to check if the user has a new enough version of Windows.
-    winver = int(platform.version().split('.')[2])
-    if winver >= 14393:
-        from ._windows_detect import *
-    else:
-        from ._dummy import *
+    return int(sysver.split('.')[1]) >= 14
+
+if sys.platform == "darwin" and macos_supported_version():
+    from ._mac_detect import *
+    Listener = MacListener
+# If running Windows 10 version 10.0.14393 (Anniversary Update) OR HIGHER.
+elif sys.platform == "win32" and platform.release().isdigit() and int(platform.release()) >= 10 and \
+        int(platform.version().split('.')[2]) >= 14393:
+    from ._windows_detect import *
+    Listener = WindowsListener
 elif sys.platform == "linux":
     from ._linux_detect import *
+    Listener = GnomeListener
 else:
     from ._dummy import *
+    Listener = DummyListener
+
+#
+# Common shortcut functions
+#
+
+def isDark() -> Optional[bool]:
+    """
+    :return: True if the theme is Dark, False if not, None if there is no support for this OS
+    """
+    t: Optional[str] = theme()
+    return t if t is None else (t == "Dark")
+
+
+def isLight() -> Optional[bool]:
+    """
+    :return: True if the theme is Light, False if not, None if there is no support for this OS
+    """
+    t: Optional[str] = theme()
+    return t if t is None else (t == "Light")
+
+
+def listener(callback: Callable[[str], None]) -> None:
+    """
+    Listen for a theme change, on theme change, invoke callback(theme_name)
+    :param callback: The callback to invoke
+    """
+    l = Listener(callback)
+    try:
+        l.listen()
+    except KeyboardInterrupt:
+        l.stop(0)
+        raise
+
 
-del sys, platform
+del sys, platform, Callable, Type

darkdetect/__main__.py

@@ -6,4 +6,4 @@
 
 import darkdetect
 
-print('Current theme: {}'.format(darkdetect.theme()))
+print(f"Current theme: {darkdetect.theme()}")

darkdetect/_base_listener.py

@@ -0,0 +1,110 @@
+from typing import Callable, Optional
+from enum import Enum, auto
+
+
+class ListenerState(Enum):
+    """
+    A listener state
+    """
+    Listening = auto()
+    Stopping = auto()
+    Dead = auto()
+
+
+class BaseListener:
+    """
+    An abstract listener class
+    It is safe to call stop from a different thread than listen() was called in
+    provided multiple threads are not racing to call these methods
+    """
+
+    def __init__(self, callback: Optional[Callable[[str], None]]):
+        """
+        :param callback: The callback to use when the listener detects something
+        """
+        self._state: ListenerState = ListenerState.Dead
+        self.callback: Optional[Callable[[str], None]] = callback
+
+    def listen(self):
+        """
+        Start the listener if it is not already running
+        """
+        if self._state == ListenerState.Listening:
+            raise RuntimeError("Do not run .listen() from multiple threads concurrently")
+        if self._state == ListenerState.Stopping:
+            raise RuntimeError("Call .stop to wait for the previous listener to finish shutting down")
+        self._state = ListenerState.Listening
+        try:
+            self._listen()
+        except BaseException as e:
+            self._on_listen_fail(e)
+
+    def stop(self, timeout: Optional[int]) -> bool:
+        """
+        Initiate the listener stop sequence, wait at most timeout seconds for it to complete.
+        After this function returns, new theme changes will not invoke callbacks.
+        Running callbacks will not be interrupted.
+        May safely be called as many times as desired.
+        :param timeout: How many seconds to wait until the listener stops; None means infinite
+        :return: True if the listener completes before the timeout expires, else False
+        """
+        if timeout is not None and timeout < 0:
+            raise ValueError("timeout may not be negative")
+        if self._state == ListenerState.Listening:
+            self._initiate_shutdown()
+            self._state = ListenerState.Stopping
+        if self._state == ListenerState.Stopping:
+            if self._wait_for_shutdown(timeout):
+                self._state = ListenerState.Dead
+        return self._state == ListenerState.Dead
+
+    # Non-public helper methods
+
+    def _invoke_callback(self, value: str) -> None:
+        """
+        Invoke the stored callback if the state is listening
+        """
+        if self._state == ListenerState.Listening:
+            c: Optional[Callable[[str], None]] = self.callback
+            if c is not None:
+                c(value)
+
+    # Non-public methods
+
+    def _listen(self) -> None:
+        """
+        Start the listener
+        Will only be called if self._state is Dead
+        """
+        raise NotImplementedError()
+
+    def _initiate_shutdown(self) -> None:
+        """
+        Tell the listener to initiate shutdown
+        Will only be called if self._state is Listening
+        """
+        raise NotImplementedError()
+
+    def _wait_for_shutdown(self, timeout: Optional[int]) -> bool:
+        """
+        Wait for the listener to stop at most timeout seconds
+        Will only be called if self._state is Stopping
+        :param timeout: How many seconds to wait until the listener stops; None means infinite
+        :return: True if the listener completes before the timeout expires, else False
+        """
+        raise NotImplementedError()
+
+    def _on_listen_fail(self, why: BaseException) -> None:
+        """
+        Invoked by .listen on all failures; self._state is unknown
+        Note that .stop may still be called on a failed listener!
+        This function must handle BaseExceptions as well!
+        For example: Emergency cleanup when a user KeyboardInterrupts a program via Ctrl-C
+        :param why: The exception caught by _listen
+        """
+        if isinstance(why, (BaseException, NotImplementedError)):
+            raise why
+        raise RuntimeError("Listener.listen failed") from why
+
+
+__all__ = ("BaseListener", "ListenerState")

darkdetect/_dummy.py

@@ -4,16 +4,17 @@
 #  Distributed under the terms of the 3-clause BSD License.
 #-----------------------------------------------------------------------------
 
-import typing
+from ._base_listener import BaseListener
+
 
 def theme():
     return None
-
-def isDark():
-    return None
-
-def isLight():
-    return None
 
-def listener(callback: typing.Callable[[str], None]) -> None:
-    raise NotImplementedError()
+
+class DummyListener(BaseListener):
+    """
+    A dummy listener class that implements nothing the abstract class does not
+    """
+
+
+__all__ = ("theme", "DummyListener")