cursus.api.dag.base_dag

class PipelineDAG(nodes=None, edges=None, strict=False)

Bases: object

Represents a pipeline topology as a directed acyclic graph (DAG). Each node is a step name; edges define dependencies.

Node declaration vs. auto-creation: a node is “declared” when it is passed in the nodes= constructor arg or added via add_node(). By default add_edge() auto-creates any endpoint that was not declared (lenient mode) — convenient, but it means a single typo in an edge name (add_edge("A", "TabularPreprocessing_traning")) silently spawns a phantom, unconfigured node and orphans the real one, and construction never raises. Two guards exist:

• validate_node_declarations() reports every edge endpoint that was never declared (always available, non-fatal) — call it to surface likely typos / forgotten add_node.

• strict=True turns the same condition into an immediate ValueError at add_edge (and constructor) time, so undeclared endpoints can never enter the graph.

add_node(node)

Add a single node to the DAG. This DECLARES the node (see class docstring).

add_edge(src, dst)

Add a directed edge from src to dst.

Lenient (default): auto-creates either endpoint if it is not yet a node — but does NOT mark it declared, so validate_node_declarations will still surface it as a likely typo. strict=True: raises ValueError if either endpoint was never declared via add_node.

validate_node_declarations()

Return edge endpoints that were never explicitly declared via add_node / the nodes= arg.

Because add_edge auto-creates missing endpoints (lenient mode), a typo in an edge name silently produces a phantom, unconfigured node — and the serializer’s dangling-edge check cannot catch it, since add_edge has already promoted the typo into nodes. This is the only reliable detector: it compares every edge endpoint against the DECLARED set. An empty list means every edge endpoint was declared; any member is a likely typo or a forgotten add_node. Non-fatal — strict=True turns the same condition into a raise at add_edge time.

get_dependencies(node)

Return immediate dependencies (parents) of a node.

topological_sort()

Return nodes in topological order.

Tolerates edges whose endpoints are not in nodes (dangling edges) by ignoring the unknown endpoints here rather than raising an opaque KeyError — structural problems like dangling edges are surfaced with clear messages by the serializer’s validation layer.