onsrap.loader module

onsrap.loader.discover_python_entrypoint(path: Path) → str | None

Inspect a Python stage file and return the preferred callable entrypoint name.

onsrap stages are intentionally lightweight: a stage can be a plain Python file, but the execution layer still needs a concrete function to call when one is available. This helper does a shallow AST scan for the project’s preferred entrypoints, run, main, and execute, without importing the module. That keeps discovery fast and avoids running stage code just to learn how it should be invoked.

Parameters:

path (Path) – File path for the stage being run.

Returns:

• String item containing the name of the PREFERRED_ENTRYPOINTS item relevant

• for the stages.

• None when the file exists but does not define a preferred

• callable, which signals to the executor that it should treat the file as a

• script-style stage instead.

Raises:

StageConfigurationError – If the file path requested for the Stage does not exist.

onsrap.loader.load_historical_run(run_dir: Path) → PipelineRun

Load a previously executed pipeline run from a YAML file.

Returns:

An instance of PipelineRun representing the historical run.

Return type:

PipelineRun

onsrap.loader.load_python_callable(path: Path, entrypoint: str) → Any

Import a stage module and return the named callable from it.

This is the bridge from the declarative stage model to execution. Once the pipeline has chosen a stage source and entrypoint, the runtime uses this helper to import the module exactly once and retrieve the function that will receive the execution context. It is kept separate from module loading so the executor can reuse the same import path for multiple runtime strategies.

Parameters:

• path (Path) – The file path for the stage being run.

• entrypoint (str) – The name of the entrypoint function defined in the stage script.

Raises:

• StageConfigurationError –

• If the chosen entrypoint does not exist or is not callable, because that means –

• the stage definition and the executable surface no longer agree. –

Returns:

The entrypoint attribute of the module called to run the stage.

Return type:

target

onsrap.loader.load_python_module(path: Path) → ModuleType

Import a Python stage file as an isolated module object.

The architecture treats stage files as user-owned execution units, not as part of the package’s own import graph. To preserve that boundary, this helper loads the file under a generated module name instead of importing it by package path. That lets onsrap execute local stage code without requiring the user to restructure it into an installed module.

The generated name is derived from the file path so repeated loads of the same stage remain stable during a run, while still avoiding collisions with other Python modules.

Parameters:

path (Path) – The path for the stage.

Returns:

The set of code being run for the stage.

Return type:

module

Raises:

StageLoadError – If the file is unable to be imported so callers can report a stage-specific problem rather than a raw import exception.