Enhance Mode Activation Observability: Better Logs and Diagnostics

[fohrloop]

Closes: #411

• Add activation process related logs
• Improve the error text: ActivationResult.get_failure_text()
• Issue NoMethodsWarning if trying to activate a Mode with empty list of Methods

Examples

Test script:

import logging
import time

logging.basicConfig(
    level=logging.DEBUG, format="%(asctime)s - %(levelname)s - %(message)s"
)

from wakepy import keep

t0 = time.time()
with keep.presenting(
    methods=[
        "SetThreadExecutionState",
        "caffeinate",
        "org.gnome.SessionManager",
    ],
    on_fail="pass",
) as m:
    time.sleep(2)

When activation successful:

Shows clearly the different stages, the different methods to be used and the outcome. Both DEBUG and INFO level logs.

2025-07-10 12:12:10,084 - DEBUG - Creating wakepy mode "keep.presenting" with methods=['SetThreadExecutionState', 'caffeinate', 'org.gnome.SessionManager'], omit=None, methods_priority=None, on_fail=pass, dbus_adapter=None
2025-07-10 12:12:10,084 - DEBUG - Found 4 method(s) for mode "keep.presenting": [<class 'wakepy.methods.freedesktop.FreedesktopScreenSaverInhibit'>, <class 'wakepy.methods.gnome.GnomeSessionManagerNoIdle'>, <class 'wakepy.methods.macos.CaffeinateKeepPresenting'>, <class 'wakepy.methods.windows.WindowsKeepPresenting'>]
2025-07-10 12:12:10,085 - DEBUG - Selected 3 method(s) for mode "keep.presenting": [<class 'wakepy.methods.gnome.GnomeSessionManagerNoIdle'>, <class 'wakepy.methods.macos.CaffeinateKeepPresenting'>, <class 'wakepy.methods.windows.WindowsKeepPresenting'>]
2025-07-10 12:12:10,085 - DEBUG - 'WAKEPY_FAKE_SUCCESS' not set.
2025-07-10 12:12:10,086 - INFO - Activating wakepy mode "keep.presenting". Will try the following methods in this order: ['org.gnome.SessionManager', 'caffeinate', 'SetThreadExecutionState']
2025-07-10 12:12:10,150 - INFO - Activated wakepy mode "keep.presenting" with method: org.gnome.SessionManager

Example of failure

Shows which methods were tried, in what order, and why they failed

... (similar logs)
2025-07-10 12:13:53,389 - INFO - Activating wakepy mode "keep.presenting". Will try the following methods in this order: ['org.gnome.SessionManager', 'caffeinate', 'SetThreadExecutionState']
2025-07-10 12:13:53,440 - INFO - Could not activate wakepy Mode "keep.presenting"! Tried Methods (in the order of attempt): (#1, org.gnome.SessionManager, ACTIVATION, RuntimeError('Intentional failure here')), (#2, caffeinate, PLATFORM_SUPPORT, -), (#3, SetThreadExecutionState, PLATFORM_SUPPORT, -). The format of each item in the list is (index, method_name, failure_stage, failure_reason).

Example of the ActivationResult.get_failure_text()

>>> # Assuming the activation will fail for some reason
>>> with keep.presenting() as m:
>>>     # do stuff
>>>
>>> print(m.activation_result.get_failure_text())

which could print:

Could not activate wakepy Mode "keep.presenting"!

Tried Methods (in the order of attempt):
(#1, org.gnome.SessionManager, ACTIVATION, RuntimeError('Intentional failure here')),
(#2, caffeinate, PLATFORM_SUPPORT, -),
(#3, SetThreadExecutionState, PLATFORM_SUPPORT, -).
The format of each item in the list is (index, method_name, failure_stage, failure_reason).

Example of NoMethodsWarning

When running:

with keep.presenting(methods=[], on_fail="pass") as m:
    ...

example output:

2025-07-10 16:38:02,551 - DEBUG - Found 4 method(s) for mode "keep.presenting": [<class 'wakepy.methods.freedesktop.FreedesktopScreenSaverInhibit'>, <class 'wakepy.methods.gnome.GnomeSessionManagerNoIdle'>, <class 'wakepy.methods.macos.CaffeinateKeepPresenting'>, <class 'wakepy.methods.windows.WindowsKeepPresenting'>]
2025-07-10 16:38:02,552 - DEBUG - Selected 0 method(s) for mode "keep.presenting": []
/home/fohrloop/code/wakepy/bar.py:11: NoMethodsWarning: No methods selected for mode "keep.presenting"! This will lead to automatic failure of mode activation. To suppress this warning, select at least one of the available methods, which are: [<class 'wakepy.methods.freedesktop.FreedesktopScreenSaverInhibit'>, <class 'wakepy.methods.gnome.GnomeSessionManagerNoIdle'>, <class 'wakepy.methods.macos.CaffeinateKeepPresenting'>, <class 'wakepy.methods.windows.WindowsKeepPresenting'>]
  with keep.presenting(
2025-07-10 16:38:02,553 - DEBUG - 'WAKEPY_FAKE_SUCCESS' not set.
2025-07-10 16:38:02,554 - INFO - Activating wakepy mode "keep.presenting". Will try the following methods in this order: []
2025-07-10 16:38:02,596 - INFO - Could not activate wakepy Mode "keep.presenting"! Did not try any methods!