ion.utils¶

This module provides helper functions for configuration scripts. The non-obvious member is exec_generator(), which drives Python generators as coroutines on the compositor’s event loop - useful for animations and multi-step UI sequences that need to yield between steps.

Utility functions for spawning processes and file operations.

Functions¶

ion.utils.exec(argv)¶

Execute a command directly (no shell).

Arguments are passed as-is without shell quoting concerns.

Parameters:: argv (tuple[str, ...]) – Program and arguments.
Returns:: True if the process was spawned, False on immediate failure.
Return type:: bool

ion.utils.exec_generator(callback)¶

Run a Python generator as a coroutine driven by the compositor’s event loop.

The generator is advanced one step at a time, with compositor state updates processed between yields. Yield GeneratorStep to control scheduling:

def my_sequence():
    ion.utils.log("step 1")
    yield GeneratorStep()  # Resume on next event-loop iteration.
    ion.utils.log("step 2")
    yield GeneratorStep(time=500)  # Wait 500 ms.
    ion.utils.log("step 3")
    event = yield GeneratorStep(consume_event=True)  # Wait for input.
    if isinstance(event, EventPointer):
        ion.utils.log("clicked!")

ion.utils.exec_generator(my_sequence())

Parameters:: callback (Generator[GeneratorStep, Event, None]) – A generator object.
Return type:: None

ion.utils.home()¶

User’s home directory.

Return type:: str

ion.utils.log(message)¶

Log a message from Python.

Parameters:: message (str) – The message to log.

ion.utils.notify(message, title=None, urgency=None)¶

Send a desktop notification.

Parameters:

message (str) – The notification body text.
title (str | None) – Optional notification title.
urgency (Literal['low', 'normal', 'critical'] | None) – Optional urgency level.

ion.utils.shell(command)¶

Execute a shell command (spawn a detached process via sh -c).

Use this when the command string may contain shell features (pipes, redirects, variable expansion, etc.).

Parameters:: command (str) – Shell command to execute.
Returns:: True if the process was spawned, False on immediate failure.
Return type:: bool