Changelog

Changelog#

wakepy 1.0.0#

🗓️ 2026-02-07

🏆 Highlights#

Python API#

Decorator Syntax: You can now use keep.running and keep.presenting as decorators to prevent system sleep during function execution:

from wakepy import keep

@keep.running
def long_running_task():
    process_large_dataset()

@keep.presenting
def slideshow():
    display_presentation()

MethodInfo: Most references to a “method”, like

are instances of MethodInfo instead of str.

Enhanced CLI Experience#

wakepy -p: Make keep.presenting as the default mode. Can type simply wakepy instead of wakepy -p.

CLI banner update: The CLI now shows which Method and Mode are being used, making it easier to understand what’s happening:

                         _
                        | |
        __      __ __ _ | | __ ___  _ __   _   _
        \ \ /\ / // _` || |/ // _ \| '_ \ | | | |
         \ V  V /| (_| ||   <|  __/| |_) || |_| |
          \_/\_/  \__,_||_|\_\\___|| .__/  \__, |
         v.1.0.0                   | |      __/ |
                                   |_|     |___/ 
 ┏━━ Mode: keep.presenting ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
 ┃                                                      ┃
 ┃  [✔] Programs keep running                           ┃
 ┃  [✔] Display kept on, screenlock disabled            ┃
 ┃                                                      ┃
 ┃   Method: org.freedesktop.ScreenSaver                ┃
 ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Verbosity Flags: Get detailed insights into what wakepy is doing. You can for example see which Method wakepy tried in which order, and what were the outcomes

# Show detailed output
wakepy -v

# Even more details
wakepy -vv

New wakepy methods Command: for testing which Method work on your system:

# List all available methods for the default keep.presenting mode
$ wakepy methods
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                    keep.presenting
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  1. org.freedesktop.ScreenSaver              SUCCESS   
  2. org.gnome.SessionManager                 SUCCESS   
  3. caffeinate                               *         
  4. SetThreadExecutionState                  *         
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# List all available methods for the keep.running mode
$ wakepy methods -r
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                      keep.running
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  1. org.freedesktop.PowerManagement          FAIL      
  2. org.gnome.SessionManager                 SUCCESS   
  3. caffeinate                               *         
  4. SetThreadExecutionState                  *         
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

For a complete list of changes, including minor enhancements, bug fixes, documentation updates, and maintenance improvements, see the detailed changelog below.

✨ Features#

✨ Python API#

✨ wakepy CLI#

  • 🚨 Make keep.presenting mode the default for the wakepy CLI. Previously the default was keep.running mode (#576)

  • Update the wakepy CLI printout: Adds the used Method and activated Mode to the printout (#434)

  • Add wakepy methods CLI subcommand for listing all available Methods for a mode in priority order, showing which ones work on the current system (#566)

  • 🚨 Remove deprecated CLI flags -k and --presentation (deprecated in 0.10.0). Use -r/--keep-running and -p/--keep-presenting instead

✨ Improve observability#

  • Added -v (INFO) and -vv (DEBUG) verbosity flags for the wakepy CLI command. (#439)

  • Show summary of used and unused Methods with wakepy -v; Previously it was possible to see the list of associated wakepy Methods only in case of failure (#567)

  • Better error messages: When selected Method is not part of the selected Mode (#427) and when a D-Bus -based method fails (#438).

  • More human-readable output (ActivationWarning, ActivationError) if activation fails. Internally using get_failure_text() (#547, #430).

  • Enhance Mode Activation Observability. Add logging (DEBUG and INFO level) for different parts in the Mode activation process. Show which methods are to be tried, and log any success and failure of activating a Mode. Improved the ActivationResult.get_failure_text() output. Added NoMethodsWarning which is issued if trying to activate a Mode with an empty list of methods. (#411)

  • Add logging to every Method activation and deactivation step (#469)

  • Improve logging: org.gnome.Sessionmanager and freedesktop methods (#474)

  • Make ActivationWarning use proper stacklevel, so that issued warnings point to user code, and not into wakepy source code. (#432)

  • Add helper methods for formatting activation results: get_summary_text(), get_detailed_summary_text(), get_status_string(), and get_status_line() (#564, #568)

  • Improve CLI error messages (#577)

  • Add Mode.probe_all_methods() method and ProbingResults class for testing which Methods work on the current system without keeping them active (#564)

✨ Other#

  • Add WAKEPY_FORCE_FAILURE environment variable which can be used to force activation failure (for testing/development) (#542)

🐞 Bug fixes#

  • Terminate caffeinate process even if python process is killed abruptly (Thanks to basilevs for #572)

  • Fix ResourceWarning with caffeinate Method on macOS (#479)

  • Fix prioritized order of Methods (#429).

  • Raise ContextAlreadyEnteredError (subclass of RuntimeError) if trying to use context manager twice without exiting first (#476)

📖 Documentation#

👷 Development Experience & Tooling#

  • Switch to uv and remove tox (#499)

  • Replace invoke (tasks.py) with just (.justfile) (#509)

  • Switch from black to ruff (#523)

  • Switch from isort to ruff (Thanks to @honerop for #531)

  • Add more ruff checks (#524, #525, #526)

  • Add basic spellchecking using codespell (#539)

  • Split testing pipelines into Fast Tests 🚀 and Full Tests 🔬. Fast tests run on every push to PR, and Full tests run after merging to main and before creating a release. (#530)

  • Add AGENTS.md for AI coding assistants (#508)

  • Add devcontainer (#574)

  • Fix development environment setup instructions and requirements on Windows (#445)

  • Fix flaky tests on pypy+windows (#447)

  • Remove the AttributeError traceback when building docs on Windows/MacOS (#449)

  • PyPy3.11, CPython 3.14, CPython 3.14t, CPython 3.15 and CPython 3.15t (free-threaded) tests in pipelines (#482, #501)

  • Fix freezing of CLI when running pytest with –pdb on CPython 3.13.x and 3.14.0 (#512)

wakepy 0.10.2#

🗓️ 2025-04-21

🐞 Bug fixes#

  • Fix keep.running mode on KDE Plasma 6.x.x, when plasmashell --version output contained extra lines, such as “QThreadStorage: entry 3 destroyed before end of thread 0x61b4ee73d540” (#417). Thanks to @materemias for #415.

👷 Maintenance#

  • Fix CI pipelines for Python 3.7 on linux (#419)

  • Disallow TODO comments (#410)

  • Fix: Cannot install -r requirements/requirements-test.txt (#403)

📖 Documentation#

  • Add manual testing instructions for Xfce (#405)

  • Readme updates (#412 & #413)

wakepy 0.10.1#

🗓️ 2024-09-20

🐞 Bug fixes#

  • Fix the wakepy logo/text printed to CLI (#400)

wakepy 0.10.0#

🗓️ 2024-09-20

🏆 Highlights#

  • Wakepy has been available in conda-forge since 0.9.1. Now it’s also documented.

  • Warn instead of raise Exception by default if activating a Mode fails.

✨ Features#

  • Change default on_fail action to be “warn” instead of “error” (in keep.running and keep.presenting modes). (#388)

  • Add support for BSD and other non-Linux Unix-like FOSS desktop systems. All systems running a supported Desktop Environment (currently: KDE, Gnome + other freedesktop compliant DEs) should be supported. (#379, #385)

  • Add support for PyPy (#393, #396)

  • When running on an unknown platform, do not fail any Methods in the platform check phase anymore, but try to use each Method. This means for example that any system running GNOME that is not Linux (or BSD) could still use wakepy with the org.gnome.SessionManager (#379)

  • 🚨 CLI arguments: Change -k, --keep-running to be -r, --keep-running and -p, --presentation to be -p, --keep-presenting; Be more consistent with the naming of the Modes. The old alternatives are deprecated and will be removed in a future release. (#356)

  • 🚨 Renamed PlatformName to PlatformType and added new types: ANY, which means “any platform”, BSD, meaning “any BSD system” in the future, but currently just FreeBSD / GhostBSD, and UNIX_LIKE_FOSS, which means “Unix-like desktop environment, but FOSS”. Includes: Linux and BSD. Excludes: Android (mobile), MacOS (non-FOSS), ChromeOS (non-FOSS). Only affects you if you have created custom Method subclasses. (#379)

  • Improve warnings and errors if platform is not supported (#383)

👷 Maintenance#

  • Fixed GitHub Release pipeline: Creates releases only from tags. Added automatic titles. Cannot accidentally publish with “main” tag. (#328, #346)

  • Fixed: Tests failing on Fedora 40 (#381)

  • Update various development time dependencies (#389)

📖 Documentation#

  • Update Installing instructions. Wakepy is available in conda-forge starting from version 0.9.1. (#390 + Thanks to @thewchan for wakepy-feedstock)

  • Add Roadmap and improve the Supported Platforms docs (#365)

  • Add logos and banners (#370, #371)

wakepy 0.9.1#

🗓️ 2024-06-04

🐞 Bug fixes#

  • The SetThreadExecutionState Method may now have multiple modes (same or different) activated within the same python thread without them interfering with each other on activation or deactivation, as wakepy creates a separate worker thread for the single purpose of setting and keeping the thread execution flag each time you activate a mode with the SetThreadExecutionState wakepy.Method. (#342)

  • Importing wakepy (0.8.0 and 0.9.0) messed up logging. In particular, the logging level was changed to WARNING due to direct call to logging.debug() instead of logger.debug(). (#344). Thanks to @reidswanson for reporting it.

  • 👷 Fixed running the dev command inv test on Windows (#339, #341)

wakepy 0.9.0.post1#

🗓️ 2024-06-01

📖 Documentation#

  • Update docs and README after 0.8.0 & 0.9.0 releases (#331)

wakepy 0.9.0#

🗓️ 2024-05-31

✨ Features#

  • Support keep.running mode in KDE Plasma 5.12.90 and newer through the org.freedesktop.PowerManagement method. It may also be used on other DEs which implement this older freedesktop.org D-Bus interface (but not Xfce). (#324)

  • Cooler CLI spinner (#309, #323)

📖 Documentation#

  • Document that the org.freedesktop.ScreenSaver method for keep.presenting mode also supports KDE Plasma. (#324)

  • Update dev docs (#308)

  • Mention that shell should be restarted for wakepy CLI tool (#321)

  • Fix: Supported Platforms table background does not support dark mode (#316)

wakepy 0.8.0#

🗓️ 2024-05-26

🏆 Highlights#

  • This is a basically a complete rewrite of wakepy. It adds support for keep.running mode on Gnome, on-fail action, possibility to control the used methods and their priority, more information about the used methods and the activation process and possibility to exit the mode early. In addition, testing and CI pipelines were updated to ease maintenance.

✨ Features#

🚨 Backwards incompatible#

  • Removed set_keepawake and unset_keepawake functions and the keepawake context manager. These were deprecated in 0.7.0 and are replaced with the new api: keep.running() and keep.presenting() context managers. (#85)

  • Renamed the CLI argument -s, --keep-screen-awake to -p, --presentation. The old ones were deprecated in 0.7.0. (#179)

  • If Mode activation fails, raise ActivationError by default. Previously there was no “on fail” action, but users needed to check the result.success to make sure the activation was successful.

  • The org.freedesktop.ScreenSaver based method is not used on keep.running mode. Systems supporting org.freedesktop.ScreenSaver which are not running Gnome will have no keep.running method until it gets implemented. By default wakepy will raise a wakepy.ActivationError if keep.running is used on such system. Either use keep.preseting mode, or wait or provide a PR.

  • The WAKEPY_FAKE_SUCCESS check is done before trying any wakepy Methods (previously, it was used when all the tried methods have failed)

🐞 Bug fixes#

  • The org.freedesktop.ScreenSaver based method is only used in keep.presenting mode. Previously, it was used on keep.running mode on Linux. (#46, #136)

  • Still going to sleep - running Fedora 36 (#18)

📖 Documentation#

👷 Maintenance#

  • Made the CI tests mandatory for every PR (previously manual) (#191)

  • 100% test coverage + use branch coverage instead of line coverage + enforce 100% coverage (#221, #222)

  • Run black+isort+ruff also on tests (#224)

  • Run mypy also on tests + fix the new mypy issues (#227)

  • Add tests for Python 3.12 and 3.13. Now test all supported versions of python on linux, and oldest and newest supported versions on MacOS and Windows. (#160, #236, #273)

  • Pin docs and tests dependencies (#220)

  • Build docs in CI tests to prevent breaking docs (#211)

  • Run tox and pipeline tests against build wheel instead of the source tree (#231, #236)

  • Build both, sdist (tar.gz) and wheel (.whl). 0.7.x had just wheels and <=0.6.x just dist. Start using setuptools-scm and switch from flit to setuptools (#235).

  • Add invoke commands (#223)

  • Add automatic publishing GitHub workflow (#238)

  • Limit docstrings and comments to 79 characters (#207)

  • WakepyFakeSuccess Method (#152) instead of using some custom logic with WAKEPY_FAKE_SUCCESS.

  • Split package extras: dev, doc, test and check (was: doc, dev) (#213) and start using requirements-*.txt instead of misusing extras (#228)

  • Ruff: Update from 0.0.270 to 0.3.2 (#206), use --no-fix in tox (#208), Stricter ruff rules: W291 (#209)

  • Black: Update from 23.3.0 to 24.2.0 and reformat (#217)

  • Isort: Update from 5.12.0 to 5.13.2 (#218)

  • Mypy: Update from 1.3.0 to 1.9.0 (#219), stricter settings; disallow_untyped_defs = true (#242), disallow_any_unimported = true and warn_unused_ignores = true (#243)

  • Make wakepy statically typed: Add py.typed (PEP 561) to advertise that wakepy is a fully typed package (#232), add mypy checks on 3.7-3.12 (#265)

  • Other tox improvements (#233)

  • Convert from flat layout to src layout (#234)

  • Cleanup .gitignore (#237)

wakepy 0.7.2#

🗓️ 2023-09-27

🐞 Bug fixes#

  • The CLI API on python 3.7 and python 3.8. Thanks to Aymane11 for PR #50

wakepy 0.7.1#

🗓️ 2023-06-11

🐞 Bug fixes#

  • keep.running and keep.presenting return an object m with success value of True.

wakepy 0.7.0#

🗓️ 2023-06-11

✨ Features#

  • New API: keep.running() and keep.presenting() context managers. These are currently simple wrappers of the old methods but the internals will be re-written in a future version.

  • The context managers now return the result of the action, m. Users may check with m.success if changing the mode was successful.

  • Possibility to fake successful change of mode with WAKEPY_FAKE_SUCCESS (for CI / tests).

🐞 Bug fixes#

  • No exceptions anymore on import-time. All exceptions should be handled now gracefully, and user is informed if switching to a keep.running or keep.presenting mode failed.

⚠️ Deprecations#

  • Old Python API: The keepawake(), set_keepawake and unset_keepwake. These will be removed in a future version of wakepy. Use keep.running()or keep.presenting(), instead.

  • The -s, --keep-screen-awake option of the wakepy CLI command. Use -p, --presentation option, instead.

📖 Documentation#

  • Created Readthedocs pages

👷 Maintenance#

  • Added manual CI tests

  • Start using tox

  • Enforce pass in isort, black, ruff and mypy in tests

wakepy 0.6.0#

🗓️ 2023-02-27

✨ Features#

  • Support for using wakepy without sudo on linux! There are now D-bus solutions (1) using jeepney and (2) using dbus-python (libdbus). Thanks to Stehlampe2020 for the dbus-python based solution (PR #22) and NicoWeio for raising Issue #17.

  • Linux+systemd approach has sudo check. The program won’t start without SUDO_UID environment variable set.

wakepy 0.5.0#

🗓️ 2021-12-15

✨ Features#

  • wakepy ascii art text, version and options will be printed in console if wakepy launched with the CLI

  • The wakepy executable for CLI is installed when wakepy is installed with pip.

wakepy 0.4.4#

🗓️ 2021-08-30

🐞 Bug fixes#

wakepy 0.4.3#

🗓️ 2021-08-28

🐞 Bug fixes#

  • Raising TypeError: a bytes-like object is required, not 'str' if trying to use on MacOS (Python 3.9) (#11). Thanks to mikeckennedy for PR #12.

wakepy 0.4.2#

🗓️ 2021-08-10

🐞 Bug fixes#

  • Raising FileNotFoundError if trying to use on MacOS. Previous implementation had a bug (#9). Thanks to matacoder for PR #10.

wakepy 0.4.1#

🗓️ 2021-06-15

🐞 Bug fixes#

  • Raising NotImplementedError if trying to use on Linux without systemctl. Previous implementation had a bug. (#8)

wakepy 0.4.0#

🗓️ 2021-06-09

✨ Features#

wakepy 0.3.2#

🗓️ 2021-06-06

🐞 Bug fixes#

  • Raising NotImplementedError if trying to use on Linux without systemctl. (#3)

wakepy 0.3.1#

🗓️ 2021-06-02

🐞 Bug fixes#

  • The package in PyPI did not have any content

wakepy 0.3.0#

🗓️ 2021-05-05

✨ Features#

  • Linux & OSX support. Thanks for rileyyy.

Contents