wakepy roadmap: 0.7.0 & 0.8.0

[fohrloop]

I've been working on this project for a while by doing some research on how I could improve wakepy. It's finally starting to be clear to me, and now it is time to start work on a update.

I was first thinking that the next version of wakepy would be called 1.0.0 (current is 0.6.0), but that would mean that things would have been somehow stable for some a while. But that's not the case as the next version will change a lot of things. Therefore, the next version will be 0.7.0. It will contain minimal viable product version of what I have in mind.

New API for wakepy

1) Modes

• The use case for wakepy is to keep your computer "awake" while you're doing something. The term "awake", however, can mean a lot of different things, like inhibiting automatic suspend, inhibiting display from turned off automatically, inhibiting screensaver, inhibiting automatic screenlock, inhibiting the automatic lid close actions (while on AC / while docked or connected to a monitor or otherwise), etc..
• The proposal is to have next version coming with pre-defined Modes, which will map 1:1 with a real-life use case. Use cases being
  • Long running task (prevent suspend but allow automatic screen lock for security)
  • Presentation mode (prevent suspend and prevent automatic screen lock for showing something)
  • Ignoring lid close (rarer use case, .. not part of 0.7.0)
• Modes are given as clearly named context managers
• Usage could then look like this:

from wakepy import keep

with keep.running() as m:
    # Do something that takes long time
    # but allows screen to be locked automatically

with keep.presenting() as m:
    # Do something that takes a long time and needs
    # to be shown to user; no automatic screen lock

Methods

Each Mode will consist of one or more different Methods which may be tried to accomplish entering the Mode. This is because:

• Every OS works differently
• Inside OSes (especially Linux), things may work differently depending on what init daemon (e.g systemd) you're using, if you have D-Bus in use, what Desktop Environment you're using (GNOME, KDE, Xfce, ..), what version of the Desktop Environment you're using, what other power management or screen locking related applications you have running or installed (e.g. xscreensaver) , etc. etc. There is no single solution of inhibiting suspend on Linux.
• Users should be able to control which method is tried (or not tried) to enter in a certain mode

[fohrloop]

Proposed Changes (0.6.0 -> 0.7.0 -> 0.8.0)

This is the list of proposed changes with their tasks.

New things

• (0.7.0) API / Modes: Write keep.running() and keep.presenting() context managers
• (0.8.0) API / Methods: Write basic methods for each mode, supporting Windows, MacOS, Linux (presentation: freedektop DBus, long task: GNOME support) --> moved this task to the list below

Non-functional features

• (0.7.0) Update wakepy CLI to use new API
• (0.7.0) Deprecate old methods (keepawake, set_keepawake, unset_keepawake).
• (0.7.0) Add unit tests for wakepy
• (0.7.0) Add CI (GitHub Actions)
• (0.7.0) Write clear documentation for v0.7.0 (Readthedocs)

Outcomes

• (0.7.0) Wakepy will not crash on import time, even if no methods available.
• (0.7.0) Wakepy will not crash when a mode cannot be changed. Instead, user will be given a chance to decide what to do.
• (0.8.0) Multiprocessing support. No more usage of global state, but each "lock" taken in a separate little bubble.
• (0.8.0) Support for heartbeat-like methods (no such methods yet, but could be.) pushed to a later release
• (0.8.0) Wakepy is easily extensible. New methods should be easy to be added.

Other

• (linux) Only jeepney supported as D-Bus method in 0.7.0
• Systemd mask based method probably removed. The reason is that it alters system-wide settings. Could also be added in set of unsafe methods. (changes not reverted if python process killed from outside). It is also not just preventing automatic suspend but removing the whole option to suspend.

Later versions (> 0.8.0)

• Add support for more (ideally all) Desktop Environments. Document well which versions are supported.
• Possible support for ignoring close lid action.
• Check if WSL can be supported
• Support for multiple different D-Bus libraries. Users should be able to decide what to use. Or, alternatively, small D-Bus subset of implementation in wakepy itself (minimize dependencies).

[fohrloop]

Decided to publish an intermediate version (0.7.0) with the new API and deprecation notice for keepawake, set_keepawake and unset_keepawake.

[fohrloop]

As a quick update: I have mostly rewritten wakepy on a local branch, but still have some work, testing and documentation to do for 0.8.0 release. For the timetable I first thought it would be done in the beginning of September, but now I'm starting to thing that more realistic target is a release during October 2023.

[fohrloop]

Update: I have now some days time to work on wakepy. I'm hoping to get to version 0.8.0 during October 2023 :)

[fohrloop]

Update: October is passing by so fast. It's starting to look like wakepy 0.8.0 would be more realistically released in December 2023. Let's see how it goes! I'm working on listing all the items needed for the 0.8.0 release so keeping track of the progress would be easier.

[fohrloop]

Update: Got just finished #136 which included the first method (org.gnome.SessionManager) which utilizes the new wakepy (0.8.0) machinery!

[fohrloop]

It's been a long time after the last comment. I thought I was close to release back then but since #136 I've merged about 120 PRs and still not released 0.8.0. Now I'm updating docs and making a release after #68 is done.

[fohrloop]

Released wakepy today 2024-05-26. There was also a release done yesterday, but that did the release only on GitHub Releases (PyPI release failed), so I removed it and re-released.

[fohrloop]

Wakepy 0.8.0 goals

1 Changes visible to user

Wakepy methods

The version 0.7.x supports: Windows, MacOS and a subset of Linux distributions. The Linux specific methods are org.freedesktop.ScreenSaver (dbus) and systemctl mask. The org.freedesktop.Screensaver only supports keep.presenting (the keep.running in 0.7.x incorrectly uses the org.freedesktop.ScreenSaver so that should be removed). Using D-Bbus based methods could be an optional alternative. The systemctl mask requires sudo and alters the system state and shoud be removed altogether in 0.8.0. In addition to org.freedesktop.Screensaver, there should be support for at least org.gnome.SessionManager (dbus), which supports both keep.presenting and keep.running modes.

1.1 New functionality

• Linux / GNOME methods using org.gnome.SessionManager (D-Bus) #136
• User may check which method (or methods) was used for setting a keepawake when it was successful, and which methods were tried when it was not successful. PR #57
• Prioritization of methods. #75
• Make it possible to select what happens in case of failure #29
• Make it possible for the user to select the used method #28

1.2 Other visible changes

• Remove the deprecated parts #67
• Update docs for 0.8.0 #68
• Consider new return value (mode.active instead of result.success?) #73

2 Changes not visible to user

2.1 New wakepy internal API

• Split responsibilities to Mode, Method, activate() and activate_using() (v. 0.8.0) #69. Done & split into new tickets.
• Function to activate "mode" with a single Method #107
• Function to activate mode using a list of methods #108
• Function to deactivate "mode" with a single Method #118
• ModeController class #120
• Windows Methods using the new API supporting the SetThreadExecutionState #60
• MacOS Method using the new API supporting the caffeinate #61
• Linux keep.presenting method using the new API supporting org.freedesktop.ScreenSaver (D-Bus) #62

2.2 Other changes (non-visible)

• Platform check instead of System check: #63
• Create general dbus interface class #45
• Add tests for the CLI #54
• Add mentions to docs/code that heartbeat -like methods are part of a subsequential release.
• Check Fedora 36 support (close #18)

For later ?

• Non-DBUS based methods on GNOME #64
• Consider making D-Bus support install optional #65