Run a program

An ExecutionSpec describes a command and its files. An Executor creates a runner; run() submits and waits, while submit() followed by wait() separates those steps. Commands are argument sequences, so shell expansion is not performed.

import sys
import tempfile
from pathlib import Path
from kkrunner import ExecutionSpec
from kkrunner.backends import LocalExecutor

workspace = tempfile.TemporaryDirectory()
directory = Path(workspace.name)
spec = ExecutionSpec(
    [sys.executable, "-c", "print(42)"],
    directory=directory,
    output_file="stdout.txt",
)
runner = LocalExecutor().create_run(spec)
outcome = runner.run()
print(outcome.return_code)
print(Path(outcome.output_file).read_text().strip())
0
42

File paths in the specification are relative to directory; here "stdout.txt" names the file inside the temporary working directory. Absolute paths can be used when a file belongs elsewhere.

outcome contains execution facts, including the backend return code and stream paths. It contains no application-specific parsed result. Required outputs must exist after a successful command; declare optional outputs with TaskFile as described in Declare the files a run uses.

create_run() alone does not submit the program. Output paths are opened at submission. Supplied streams remain the caller’s responsibility unless ownership is explicitly transferred with ExecutionResources and ResourceOwnedRunner.

For progress notifications, register runner.add_output_listener(callback) before submission. The callback receives (text, kind), where kind is "out" or "err". Output observers do not determine execution success; use the runner’s result and exception. A completion callback is a separate notification and must not be confused with application result processing.

Use RunManager instead of a raw runner when the process must be monitored again after the client exits. See Persistent runs and recovery.