Skip to main content

builder

Builder: combines parsing and validation into a single callable.

This module provides build_background_dag — the canonical entry point for converting a v9 FlowSpec into an executable BackgroundDAG. It gates the spec's declared version before delegating to parser.py for YAML-to-model conversion and validator.py for registry and reference-ordering checks.

Keeping the builder separate from parser.py and validator.py preserves testability: callers that want to test parsing or validation independently can import those modules directly.

Module​

Functions​

build_background_dag​

def build_background_dag(flow_spec: FlowSpec) ‑> BackgroundDAG:

Parse and validate a v9 FlowSpec into an executable BackgroundDAG.

This is the canonical entry point for building a background DAG. It combines parse_background_dag and validate_background_dag into a single call so callers do not need to orchestrate the two steps themselves.

Arguments

  • flow_spec: A deserialised FlowSpec (from bitfount.flows.schema). Must be a v9 flow — i.e. it must carry federation, roles, and worker fields.

Returns A BackgroundDAG ready to be passed to execute_dag.

Raises

  • FlowSpecVersionError: If flow_spec declares a task YAML version newer than this SDK knows, or one that cannot be parsed.
  • LegacyTaskYAMLError: If flow_spec is not a v9 flow.
  • StepNotFoundError: If any step's (task, version) is absent from the step registry.
  • ReferenceOrderError: If any FromRef input references a step declared later in the DAG (forward reference).
  • ValueError: If a step config cannot be validated against its Pydantic class.

build_interactive_dag​

def build_interactive_dag(    flow_spec: FlowSpec,) ‑> InteractiveDAG:

Parse and validate a v9 FlowSpec into an executable InteractiveDAG.

Canonical entry point for building the interactive (post-processing) DAG. Combines parse_interactive_dag and validate_interactive_dag.

Arguments

  • flow_spec: A deserialised v9 FlowSpec (must carry federation, roles, and worker).

Returns An InteractiveDAG ready to be executed (e.g. via build_flow, which runs any DAG-shaped object).

Raises

  • FlowSpecVersionError: If flow_spec declares a task YAML version newer than this SDK knows, or one that cannot be parsed.
  • LegacyTaskYAMLError: If flow_spec is not a v9 flow.
  • StepNotFoundError: If any step's (task, version) is absent from the step registry.
  • ReferenceOrderError: If any FromRef references a later interactive step (forward reference).
  • BackgroundStepNotFoundError: If any BackgroundRef references a step not declared in the background phase.
  • ValueError: If a step config cannot be validated against its Pydantic class.