diff --git a/README.md b/README.md index 66f66a2..a81cd17 100644 --- a/README.md +++ b/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. diff --git a/darkdetect/__init__.py b/darkdetect/__init__.py index 73d92de..e2fa568 100644 --- a/darkdetect/__init__.py +++ b/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 diff --git a/darkdetect/__main__.py b/darkdetect/__main__.py index 1cb260b..3cb063e 100644 --- a/darkdetect/__main__.py +++ b/darkdetect/__main__.py @@ -6,4 +6,4 @@ import darkdetect -print('Current theme: {}'.format(darkdetect.theme())) +print(f"Current theme: {darkdetect.theme()}") diff --git a/darkdetect/_base_listener.py b/darkdetect/_base_listener.py new file mode 100644 index 0000000..a72667f --- /dev/null +++ b/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") diff --git a/darkdetect/_dummy.py b/darkdetect/_dummy.py index 1e82117..530a4be 100644 --- a/darkdetect/_dummy.py +++ b/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") diff --git a/darkdetect/_linux_detect.py b/darkdetect/_linux_detect.py index 0570e6a..e5f3621 100644 --- a/darkdetect/_linux_detect.py +++ b/darkdetect/_linux_detect.py @@ -5,41 +5,51 @@ #----------------------------------------------------------------------------- import subprocess +from typing import Optional -def theme(): +from ._base_listener import BaseListener + + +def theme() -> Optional[str]: try: #Using the freedesktop specifications for checking dark mode - out = subprocess.run( - ['gsettings', 'get', 'org.gnome.desktop.interface', 'color-scheme'], - capture_output=True) - stdout = out.stdout.decode() + stdout = subprocess.check_output(['gsettings', 'get', 'org.gnome.desktop.interface', 'color-scheme']) #If not found then trying older gtk-theme method if len(stdout)<1: - out = subprocess.run( - ['gsettings', 'get', 'org.gnome.desktop.interface', 'gtk-theme'], - capture_output=True) - stdout = out.stdout.decode() - except Exception: - return 'Light' + stdout = subprocess.check_output(['gsettings', 'get', 'org.gnome.desktop.interface', 'gtk-theme']) + except subprocess.SubprocessError: + return "Light" # we have a string, now remove start and end quote - theme = stdout.lower().strip()[1:-1] - if '-dark' in theme.lower(): - return 'Dark' - else: - return 'Light' - -def isDark(): - return theme() == 'Dark' - -def isLight(): - return theme() == 'Light' - -# def listener(callback: typing.Callable[[str], None]) -> None: -def listener(callback): - with subprocess.Popen( - ('gsettings', 'monitor', 'org.gnome.desktop.interface', 'gtk-theme'), - stdout=subprocess.PIPE, - universal_newlines=True, - ) as p: - for line in p.stdout: - callback('Dark' if '-dark' in line.strip().removeprefix("gtk-theme: '").removesuffix("'").lower() else 'Light') + theme_: bytes = stdout.lower().strip()[1:-1] + return "Dark" if b"-dark" in theme_.lower() else "Light" + + +class GnomeListener(BaseListener): + """ + A listener for Gnome on Linux + """ + + def _listen(self) -> None: + with subprocess.Popen( + ('gsettings', 'monitor', 'org.gnome.desktop.interface', 'gtk-theme'), + stdout=subprocess.PIPE, + universal_newlines=True, + ) as self._proc: + for line in self._proc.stdout: + self._invoke_callback( + 'Dark' if '-dark' in line.strip().removeprefix("gtk-theme: '").removesuffix("'").lower() + else 'Light' + ) + + def _initiate_shutdown(self) -> None: + self._proc.kill() + + def _wait_for_shutdown(self, timeout: Optional[int]) -> bool: + try: + self._proc.wait(timeout) + return True + except subprocess.TimeoutExpired: + return False + + +__all__ = ("theme", "GnomeListener",) diff --git a/darkdetect/_mac_detect.py b/darkdetect/_mac_detect.py index 8d44bc7..f1ab57f 100644 --- a/darkdetect/_mac_detect.py +++ b/darkdetect/_mac_detect.py @@ -1,5 +1,5 @@ #----------------------------------------------------------------------------- -# Copyright (C) 2019 Alberto Sottile +# Copyright (C) 2019 Alberto Sottile, Zachary Wimer # # Distributed under the terms of the 3-clause BSD License. #----------------------------------------------------------------------------- @@ -7,10 +7,14 @@ import ctypes import ctypes.util import subprocess +import signal import sys import os from pathlib import Path -from typing import Callable +from typing import Optional + +from ._base_listener import BaseListener + try: from Foundation import NSObject, NSKeyValueObservingOptionNew, NSKeyValueChangeNewKey, NSUserDefaults @@ -50,13 +54,13 @@ def n(name): def C(classname): return objc.objc_getClass(_utf8(classname)) -def theme(): +def theme() -> Optional[str]: NSAutoreleasePool = objc.objc_getClass('NSAutoreleasePool') pool = msg(NSAutoreleasePool, n('alloc')) pool = msg(pool, n('init')) - NSUserDefaults = C('NSUserDefaults') - stdUserDef = msg(NSUserDefaults, n('standardUserDefaults')) + NSUserDefaults_ = C('NSUserDefaults') + stdUserDef = msg(NSUserDefaults_, n('standardUserDefaults')) NSString = C('NSString') @@ -71,54 +75,70 @@ def theme(): msg(pool, n('release')) - if out is not None: - return out.decode('utf-8') - else: - return 'Light' - -def isDark(): - return theme() == 'Dark' - -def isLight(): - return theme() == 'Light' + return "Light" if out is None else out.decode('utf-8') -def _listen_child(): +class MacListener(BaseListener): """ - Run by a child process, install an observer and print theme on change + A listener class for macOS """ - import signal - signal.signal(signal.SIGINT, signal.SIG_IGN) - - OBSERVED_KEY = "AppleInterfaceStyle" - - class Observer(NSObject): - def observeValueForKeyPath_ofObject_change_context_( - self, path, object, changeDescription, context - ): - result = changeDescription[NSKeyValueChangeNewKey] - try: - print(f"{'Light' if result is None else result}", flush=True) - except IOError: - os._exit(1) - - observer = Observer.new() # Keep a reference alive after installing - defaults = NSUserDefaults.standardUserDefaults() - defaults.addObserver_forKeyPath_options_context_( - observer, OBSERVED_KEY, NSKeyValueObservingOptionNew, 0 - ) - - AppHelper.runConsoleEventLoop() - - -def listener(callback: Callable[[str], None]) -> None: - if not _can_listen: - raise NotImplementedError() - with subprocess.Popen( - (sys.executable, "-c", "import _mac_detect as m; m._listen_child()"), - stdout=subprocess.PIPE, - universal_newlines=True, - cwd=Path(__file__).parent, - ) as p: - for line in p.stdout: - callback(line.strip()) + + def _listen(self) -> None: + if not _can_listen: + raise NotImplementedError("Optional dependencies not found; fix this with: pip install darkdetect[macos-listener]") + cmd = "import darkdetect as d; d.MacListener._listen_child()" + if getattr(sys, "frozen", False): + # This arrangement allows compatibility with pyinstaller and such (it is what multiprocessing does) + args = ("-B", "-s", "-S", "-E","-c", "from multiprocessing.resource_tracker import main;" + cmd) + else: + args = ("-B", "-c", cmd) + with subprocess.Popen( + (sys.executable, *args), + stdout=subprocess.PIPE, + universal_newlines=True, + cwd=Path(__file__).parents[1], + ) as self._proc: + for line in self._proc.stdout: + self._invoke_callback(line.strip()) + + def _initiate_shutdown(self) -> None: + self._proc.kill() + + def _wait_for_shutdown(self, timeout: Optional[int]) -> bool: + try: + self._proc.wait(timeout) + return True + except subprocess.TimeoutExpired: + return False + + # Internal Methods + + @staticmethod + def _listen_child() -> None: + """ + Run by a child process, install an observer and print theme on change + """ + signal.signal(signal.SIGINT, signal.SIG_IGN) + + OBSERVED_KEY: str = "AppleInterfaceStyle" + + class Observer(NSObject): + def observeValueForKeyPath_ofObject_change_context_( + self, path, object_, changeDescription, context + ): + result = changeDescription[NSKeyValueChangeNewKey] + try: + print(f"{'Light' if result is None else result}", flush=True) + except IOError: + os._exit(1) + + observer = Observer.new() # Keep a reference alive after installing + defaults = NSUserDefaults.standardUserDefaults() + defaults.addObserver_forKeyPath_options_context_( + observer, OBSERVED_KEY, NSKeyValueObservingOptionNew, 0 + ) + + AppHelper.runConsoleEventLoop() + + +__all__ = ("theme", "MacListener") diff --git a/darkdetect/_windows_detect.py b/darkdetect/_windows_detect.py index 2363f18..83bc17f 100644 --- a/darkdetect/_windows_detect.py +++ b/darkdetect/_windows_detect.py @@ -1,7 +1,11 @@ from winreg import HKEY_CURRENT_USER as hkey, QueryValueEx as getSubkeyValue, OpenKey as getKey +import threading import ctypes import ctypes.wintypes +from typing import Optional + +from ._base_listener import BaseListener, ListenerState advapi32 = ctypes.windll.advapi32 @@ -55,7 +59,8 @@ ) advapi32.RegNotifyChangeKeyValue.restype = ctypes.wintypes.LONG -def theme(): + +def theme() -> Optional[str]: """ Uses the Windows Registry to detect if the user is using Dark Mode """ # Registry will return 0 if Windows is in Dark Mode and 1 if Windows is in Light Mode. This dictionary converts that output into the text that the program is expecting. valueMeaning = {0: "Dark", 1: "Light"} @@ -70,53 +75,73 @@ def theme(): return None return valueMeaning[subkey] -def isDark(): - if theme() is not None: - return theme() == 'Dark' - -def isLight(): - if theme() is not None: - return theme() == 'Light' - -#def listener(callback: typing.Callable[[str], None]) -> None: -def listener(callback): - hKey = ctypes.wintypes.HKEY() - advapi32.RegOpenKeyExA( - ctypes.wintypes.HKEY(0x80000001), # HKEY_CURRENT_USER - ctypes.wintypes.LPCSTR(b'SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Themes\\Personalize'), - ctypes.wintypes.DWORD(), - ctypes.wintypes.DWORD(0x00020019), # KEY_READ - ctypes.byref(hKey), - ) - - dwSize = ctypes.wintypes.DWORD(ctypes.sizeof(ctypes.wintypes.DWORD)) - queryValueLast = ctypes.wintypes.DWORD() - queryValue = ctypes.wintypes.DWORD() - advapi32.RegQueryValueExA( - hKey, - ctypes.wintypes.LPCSTR(b'AppsUseLightTheme'), - ctypes.wintypes.LPDWORD(), - ctypes.wintypes.LPDWORD(), - ctypes.cast(ctypes.byref(queryValueLast), ctypes.wintypes.LPBYTE), - ctypes.byref(dwSize), - ) - - while True: - advapi32.RegNotifyChangeKeyValue( - hKey, - ctypes.wintypes.BOOL(True), - ctypes.wintypes.DWORD(0x00000004), # REG_NOTIFY_CHANGE_LAST_SET - ctypes.wintypes.HANDLE(None), - ctypes.wintypes.BOOL(False), + +class WindowsListener(BaseListener): + """ + A listener class for Windows + """ + + def stop(self, timeout: Optional[int] = None) -> bool: + if timeout is None: + raise ValueError( + "WindowsListener does not currently support None as the wait time is indefinite." \ + "If None truly is necessary, consider something like stop(2**100)" + ) + return super().stop(timeout) + + def _listen(self) -> None: + hKey = ctypes.wintypes.HKEY() + advapi32.RegOpenKeyExA( + ctypes.wintypes.HKEY(0x80000001), # HKEY_CURRENT_USER + ctypes.wintypes.LPCSTR(b'SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Themes\\Personalize'), + ctypes.wintypes.DWORD(), + ctypes.wintypes.DWORD(0x00020019), # KEY_READ + ctypes.byref(hKey), ) + + dwSize = ctypes.wintypes.DWORD(ctypes.sizeof(ctypes.wintypes.DWORD)) + queryValueLast = ctypes.wintypes.DWORD() + queryValue = ctypes.wintypes.DWORD() advapi32.RegQueryValueExA( hKey, ctypes.wintypes.LPCSTR(b'AppsUseLightTheme'), ctypes.wintypes.LPDWORD(), ctypes.wintypes.LPDWORD(), - ctypes.cast(ctypes.byref(queryValue), ctypes.wintypes.LPBYTE), + ctypes.cast(ctypes.byref(queryValueLast), ctypes.wintypes.LPBYTE), ctypes.byref(dwSize), ) - if queryValueLast.value != queryValue.value: - queryValueLast.value = queryValue.value - callback('Light' if queryValue.value else 'Dark') + + self._lock = threading.Lock() + with self._lock: + while self._state == ListenerState.Listening: + advapi32.RegNotifyChangeKeyValue( + hKey, + ctypes.wintypes.BOOL(True), + ctypes.wintypes.DWORD(0x00000004), # REG_NOTIFY_CHANGE_LAST_SET + ctypes.wintypes.HANDLE(None), + ctypes.wintypes.BOOL(False), + ) + advapi32.RegQueryValueExA( + hKey, + ctypes.wintypes.LPCSTR(b'AppsUseLightTheme'), + ctypes.wintypes.LPDWORD(), + ctypes.wintypes.LPDWORD(), + ctypes.cast(ctypes.byref(queryValue), ctypes.wintypes.LPBYTE), + ctypes.byref(dwSize), + ) + if queryValueLast.value != queryValue.value: + queryValueLast.value = queryValue.value + self._invoke_callback('Light' if queryValue.value else 'Dark') + + def _initiate_shutdown(self) -> None: + pass # TODO: Interrupt the listener rather than permit it to die + + def _wait_for_shutdown(self, timeout: Optional[int]) -> bool: + try: + return self._lock.acquire(timeout=(-1 if timeout is None else timeout)) + except Exception: + self._lock.release() + raise + + +__all__ = ("theme", "WindowsListener",) diff --git a/darkdetect/py.typed b/darkdetect/py.typed new file mode 100644 index 0000000..99d7bf6 --- /dev/null +++ b/darkdetect/py.typed @@ -0,0 +1 @@ +PARTIAL diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..7773169 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,55 @@ +# `darkdetect` API + +The centerpiece of the API is the `Listener` class. +Members of this class are: + +### The constructor: `.__init__(callback: Optional[Callable[[str], None]])` + +The constructor simply sets `.callback` to the given callback argument + +### The callback: `.callback: Optional[Callable[[str], None]]` + +The callback function that the listener uses. +This function will be passed "Dark" or "Light" when the theme is changed. +It is safe to change this during program execution. +It is safe to set this value to `None`, while the listener will still be active, +theme changes will not invoke the callback; though running callbacks will not be interrupted. +This is useful if 'temporarily pausing' the listener is desired. + +### The listen function: `.listen()` + +This starts listening for theme changes, it will invoke +`self.callback(theme_name)` when a change is detected. + +After a listener is stopped successfully via `.stop` (the return value must be `True`), +it can be started again via `.listen()`. +New listeners may be constructed, should waiting for `.stop` not be desired. + +### The stop function: `.stop(timeout: Optional[int]) -> bool` + +This function initiates the listener stop sequence and +waits for the listener to stop for at most `timeout` seconds. +This function returns `True` if the listener successfully +stops before the timeout expires; otherwise `False`. +`timeout` may be any non-negative integer or `None`. +After `.stop` returns, regardless of the argument passed to it, +theme changes will no longer invoke the callback +Running callbacks will not be interrupted and may continue executing. + +`.stop` may safely be re-invoked any number of times. +Calling `.stop(None)` after `.stop(0)` will work as expected. + +In most cases `.stop(0)` should be sufficient as this will successfully +prevent future theme changes from generating callbacks. +The two primary use cases for `stop` with a timeout are: +1. Cleaning up listener resources (be that subprocesses or something else) +2. To restart the existing listener; a listener's `.listen()` function + may only be re-invoked if a call to `.stop` has returned `True`. + +--- + +## Wrapper Function + +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). diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 0000000..1510d58 --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,71 @@ +# `darkdetect` Examples + +### Listening with the `listener` method +```python +import threading +import darkdetect + +t = threading.Thread(target=darkdetect.listener, args=(print,), daemon=True) +t.start() +``` + +### Listening with the `Listener` class +```python +import threading +import darkdetect + +listener = darkdetect.Listener(print) +t = threading.Thread(target=listener.listen, daemon=True) +t.start() +``` + +### Stop on user input +```python +import threading +import darkdetect + +listener = darkdetect.Listener(print) +t = threading.Thread(target=listener.listen, daemon=True) +t.start() + +input() # Wait for user input +listener.stop(0) +``` + +### User adjustable callback +```python +import threading +import darkdetect +import time + +listener = darkdetect.Listener(print) +t = threading.Thread(target=listener.listen) +t.start() + +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!") +``` + +### Possible GUI app shutdown sequence +```python +def shutdown(self): + self.listener.stop(0) # Prevent callback from being invoked on theme changes + # Existing callbacks may still be running! + + self.other_shutdown_methods() # Stop other processes + + # Wait a bit longer for callbacks to complete and listener to clean up + if self.listener.stop(timeout=5) is False: + # Log that listener is still running but that we are quitting anyway + self.logger.exception("Failed to shutdown listener / running callbacks within 5 seconds, quitting anyway.") +``` diff --git a/pyproject.toml b/pyproject.toml index d1b6ebc..53bffda 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -42,6 +42,9 @@ macos-listener = [ "pyobjc-framework-Cocoa; platform_system == 'Darwin'" ] [tool.setuptools] include-package-data = true +[tool.setuptools.package-data] +darkdetect = ["py.typed"] + [tool.setuptools.dynamic.version] attr = "darkdetect.__version__"