ion.utils
=========

.. module:: ion.utils

.. include:: ../rst/ion.utils.rst

Utility functions for spawning processes and file operations.

Functions
---------

.. function:: exec(argv)

   Execute a command directly (no shell).

   Arguments are passed as-is without shell quoting concerns.

   :param argv: Program and arguments.
   :type argv: tuple[str, ...]
   :returns: True if the process was spawned, False on immediate failure.
   :rtype: bool

.. function:: 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 :class:`~ion.types.GeneratorStep`
   to control scheduling:

   .. code-block:: python

      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())

   :param callback: A generator object.
   :type callback: Generator[:class:`~ion.types.GeneratorStep`, :class:`~ion.types.Event`, None]
   :rtype: None

.. function:: home()

   User's home directory.

   :rtype: str

.. function:: log(message)

   Log a message from Python.

   :param message: The message to log.
   :type message: str

.. function:: notify(message, title=None, urgency=None)

   Send a desktop notification.

   :param message: The notification body text.
   :type message: str
   :param title: Optional notification title.
   :type title: str | None
   :param urgency: Optional urgency level.
   :type urgency: Literal['low', 'normal', 'critical'] | None

.. function:: 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.).

   :param command: Shell command to execute.
   :type command: str
   :returns: True if the process was spawned, False on immediate failure.
   :rtype: bool