----------------------------------------------------------------------
This is the API documentation for the gdtest_sphinx_rich library.
----------------------------------------------------------------------


## Functions

Public functions


execute(command: str, timeout: int = 30) -> str

Execute a shell command and return its output.

Runs the given command string in a subprocess and captures
the standard output. The command is subject to a timeout
to prevent hangs.

.. note::

    The command is executed in a new subprocess. Environment
    variables from the parent process are inherited.

.. warning::

    Never pass untrusted input directly as the command string.
    This function does not sanitize inputs.

**Examples**::

>>> execute("echo hello")
'hello'

>>> execute("sleep 5", timeout=2)
TimeoutError: Command timed out after 2 seconds

:param command: The shell command to execute.
:type command: str
:param timeout: Maximum seconds to wait for the command
    to complete. Defaults to 30.
:type timeout: int
:returns: The captured standard output from the command.
:rtype: str
:raises OSError: If the command cannot be found or executed.
:raises TimeoutError: If the command exceeds the timeout.
:raises RuntimeError: If the command exits with a non-zero
    return code.

schedule(task: str, delay: float = 0.0) -> bool

Schedule a task for later execution.

Registers the given task identifier to be executed after
the specified delay. Returns whether the scheduling was
successful.

.. note::

    Tasks are identified by their string name. Scheduling
    the same task twice will return False the second time.

**Examples**::

>>> schedule("cleanup")
True

>>> schedule("backup", delay=60.0)
True

>>> schedule("cleanup")
False

:param task: The task identifier string to schedule.
:type task: str
:param delay: Number of seconds to wait before executing.
    Must be non-negative. Defaults to ``0.0``.
:type delay: float
:returns: True if the task was successfully scheduled,
    False if the task is already scheduled.
:rtype: bool
:raises ValueError: If ``delay`` is negative.
:raises TypeError: If ``task`` is not a string.