onsrap.graph module

class onsrap.graph.StageGraph(stages: list[~onsrap.stage.Stage] = <factory>)

Bases: object

Represents an order to run stages.

Holds an order that stages need to run in based on dependencies and logic.

Parameters:

stages (list of Stage class items)

classmethod from_stages(stages: Iterable[Stage]) → StageGraph

This is the primary constructor for StageGraph, which performs validation and normalization of the stage list.

Parameters:

stages (Iterable of Stage class instances)

Return type:

The stages parameter as a list.

stages: list[Stage]
topological_order() → list[Stage]

Return the stages in an order that respects their dependencies.

In graph terms, this is a topological sort: if stage B depends on stage A, then A will always appear before B in the returned list. The word “topological” here does not refer to geographic maps or terrain; it means we are arranging nodes in a dependency-safe order.

The implementation works by repeatedly selecting stages that currently have no unmet dependencies. Those stages are “ready” to run because nothing else needs to happen first. After a ready stage is placed in the output order, the algorithm removes it from the dependency lists of the stages that depend on it. That may free up more stages, which are then added to the ready list.

Returns:

  • A list of stages ordered in the way that they need to be run through the

  • pipeline.

Raises:

DependencyCycleError – If the algorithm cannot place every stage, the graph contains either a cycle or a dependency that could not be resolved.

validate() → None

Validate the stage graph for issues such as duplicate stage names, missing dependencies, and cycles.

Raises: