Module Runner Utility

A helper that executes Python scripts or modules the way the interpreter does, with controlled arguments, search paths, and inline evaluation.

Capabilities

Execute script files

• Running a script file that prints its received CLI arguments returns exit code 0 and captures those arguments in stdout @test
• Running a script file that raises an exception returns a non-zero exit code and includes the traceback text in stderr @test

Execute modules as scripts

• Running a package module with a __main__ entrypoint executes it as a script, returning its printed message in stdout and exit code 0 @test

Evaluate inline code

• Evaluating a single expression string like x + y with provided globals returns the computed value @test

Search path override

• When a working directory is provided, the runner prepends that path so module imports in executed code resolve relative to it @test

Implementation

@generates

API

from dataclasses import dataclass
from typing import Any, Iterable, Mapping, Optional

@dataclass
class RunResult:
    exit_code: int
    stdout: str
    stderr: str

def run_file(script_path: str, args: Optional[Iterable[str]] = None, workdir: Optional[str] = None) -> RunResult:
    ...

def run_module(module_name: str, args: Optional[Iterable[str]] = None, workdir: Optional[str] = None) -> RunResult:
    ...

def eval_snippet(source: str, globals_ns: Optional[Mapping[str, Any]] = None, locals_ns: Optional[Mapping[str, Any]] = None) -> Any:
    ...

Dependencies { .dependencies }

python { .dependency }

Provides interpreter runtime for executing files, modules, and dynamic code evaluation. @satisfied-by