User Guide

User Guide#

Wakepy main Python API is are the wakepy Modes, which are states that are activated and deactivated and which keep your system awake. The method for activating the mode depends on your platform (among other things) and is determined by the used Method. For example keep.presenting mode is implemented by org.gnome.SessionManager for Linux with GNOME DE, SetThreadExecutionState for Windows and caffeinate for MacOS. In most cases, wakepy does nothing but calls an executable (caffeinate), a DLL function call (SetThreadExecutionState) or a D-Bus method (org.gnome.SessionManager). Wakepy helps in this by providing a coherent API which should just work™ on any system. Or, at least that is the vision of wakepy.

Entering a wakepy.Mode#

The wakepy modes are implemented as context managers of type wakepy.Mode. The available convenience wrappers for creating a Mode are keep.running() and keep.presenting(). These are used with the with statement:

from wakepy import keep

with keep.running():
    # Do something that takes a long time. The system may start screensaver
    # / screenlock or blank the screen, but CPU will keep running.

When entering the context, a Mode instance (m) is returned:

with keep.running() as m:
    ...

The Mode has following important attributes:

Which wakepy Method was used?#

New in version 0.8.0.

When you would like to check how exactly did wakepy do what you asked it to, you can check the used method from the Mode instance.

Example

from wakepy import keep

with keep.running() as m:
    print('active_method:', m.active_method)
    print('used_method:', m.used_method)

print('--------')
print('active_method:', m.active_method)
print('used_method:', m.used_method)

Example output:

active_method: org.gnome.SessionManager
used_method: org.gnome.SessionManager
--------
active_method: None
used_method: org.gnome.SessionManager

See also

Mode.active_method, Mode.used_method

Controlling the on-fail action#

New in version 0.8.0.

Changed in version 0.10.0: on_fail defaults to “warn” instead of “error”. See: wakepy/#376.

The wakepy Modes (e.g. keep.running and keep.presenting) also take an on_fail input argument which may be used to alter the behavior. Example:

from wakepy import keep

with keep.running(on_fail="warn"):
    # do something

on-fail actions#

on_fail

What happens?

“warn” (default)

Issues an ActivationWarning

“error”

Raises an ActivationError

“pass”

Does nothing

Callable

The callable is called with one argument: the result of the activation which is
a instance of ActivationResult. The call occurs before the with block is entered.

See also

Mode.__init__() on_fail argument.

Example: Notify user with a custom callable#

This is what you could do if you want to inform the user that the activation of the mode was not successful, but still want to continue to run the task:

from wakepy import keep, ActivationResult

def react_on_failure(result: ActivationResult):
    print(f'Failed to keep system awake using {result.mode_name} mode')

def run_long_task():
    print('Running a long task')

with keep.running(methods=[], on_fail=react_on_failure):
    print('started')
    run_long_task()

  • The on_fail parameter to keep.running() is a callable which gets called with an ActivationResult when the activation of the mode fails.

  • Here we use empty list in methods to force failure

Example output:

Failed to keep system awake using keep.running mode
started
Running a long task

Example: Notify user and exit#

This is what you could do if you want to inform the user that the activation of the mode was not successful, and then exit from the with block:

from wakepy import keep, ActivationResult, ModeExit

def react_on_failure(result: ActivationResult):
    print(f'Failed to keep system awake using {result.mode_name} mode')

def run_long_task():
    print('Running a long task')

with keep.running(methods=[], on_fail=react_on_failure) as m:
    print('started')

    if not m.active:
        print('exiting')
        raise ModeExit

    run_long_task()

  • The difference to the previous example is the ModeExit which is used to exit the with block, if the Mode.active is not True.

Example output (notice that run_long_task was never called):

Failed to keep system awake using keep.running mode
started
exiting

Controlling the Methods to be tried#

New in version 0.8.0.

Wakepy tries in order a list of different Methods. By default this is of methods are all the Methods which implement the selected wakepy Mode. If you do not want to try all the methods, you can

  • Blacklist methods with the omit parameter

  • Whitelist methods with the methods parameter

Only either omit or methods may be given (not both).

Example: whitelisting methods#

This would try the methods called org.gnome.SessionManager and SomeOtherMethod, but never any other methods. Note that the order is not defined by the whitelist.

from wakepy import keep

with keep.running(methods=['org.gnome.SessionManager', 'SomeOtherMethod']):
    ...

Example: blacklisting methods#

This would never try the methods called org.gnome.SessionManager and SomeOtherMethod, but only any other methods implementing the selected Mode.

from wakepy import keep

with keep.running(omit=['org.gnome.SessionManager', 'SomeOtherMethod']):
    ...

See also

omit and methods parameter of Mode.from_name(), keep.running() and keep.presenting()

Controlling the order of Methods to be tried#

New in version 0.8.0.

To control the order of the methods to be tried, you may use the methods_priority argument. The argument should be a list of method names or sets of method names. Each item in the list is considered as “equal priority” and wakepy’s automatic logic will order the methods within the sets. An asterisk (*) may be used to denote “any other methods”.

Example: prioritizing methods#

This would put MethodA and MethodB to be in the highest priority group, and wakepy’s automatic prioritization logic would determine which one of the methods should be tried first. It would also put the MethodF to have the least priority and that method would only be tried after trying any other methods have failed.

from wakepy import keep

with keep.running(methods_priority=[{"MethodA", "MethodB"}, "*", "MethodF"]):
    ...

See also

methods_priority parameter of Mode.from_name(), keep.running() and keep.presenting()

experimental feature

The methods_priority is still an experimental feature and may change or be removed without further notice.

Contents