Python TopologicalSorter 的done为什么必须对应已就绪节点

如果把 TopologicalSorter 当成“任意节点都能报完成”的集合工具，最容易在 done() 这里遇到 ValueError。原因很明确：done(*nodes) 只接受当前已经被 get_ready() 返回、并且确实完成处理的节点。它不是提前声明任务完成的接口，而是依赖调度器收到 worker 回执后的确认点。

ready 集合与 done 的对应关系

官方接口把依赖图表示为“节点到前置节点”的映射。例如 D 依赖 B、C，B 和 C 又都依赖 A。第一次 get_ready() 只能返回 A；调用方把 A 交给 worker 后，必须等 A 的实际处理结束，再调用 done("A")。此时 B、C 才有资格成为下一批 ready，D 仍然不能提前确认。

因此，“已就绪”和“已完成”是两个时间点：前者是调度器允许你接手，后者是你的业务处理已经成功结束。把 get_ready() 的返回值保存下来，是避免把未就绪节点传给 done() 的关键。

把 done 放在真实完成点

串行场景可以直接在处理函数返回后确认；并行场景则应由 worker 把完成节点放入回执队列，主调度循环从队列取出节点后再调用 done()。下面的例子保留了这个边界，并用中文注释说明异常和资源状态。

from graphlib import TopologicalSorter, CycleError

graph = {
    "build": set(),
    "test": {"build"},
    "package": {"test"},
}

sorter = TopologicalSorter(graph)
try:
    # prepare 固定依赖图；成环时不要进入调度循环。
    sorter.prepare()
except CycleError as exc:
    # 生产代码应记录依赖链并终止本次调度。
    raise RuntimeError("依赖图存在循环") from exc

while sorter.is_active():
    ready_nodes = sorter.get_ready()
    for node in ready_nodes:
        # 这里代表真实业务处理；返回后才允许 done。
        print("处理节点:", node)
        sorter.done(node)

这个循环的语义是：先拿到一批 ready 节点，再逐个完成并确认。若把 sorter.done("test") 放在 build 确认之前，test 尚未被 get_ready() 返回，调用会直接失败；若同一个节点被确认两次，也会失败。

并行调度时不要把返回批次当成完成批次

get_ready() 返回的是一个元组，同一批节点可以交给不同 worker 并行处理，但主循环不能因为“已经派发”就立刻调用 done(*ready_nodes)。正确做法是分别等待完成回执，再确认已经完成的节点：

# ready_nodes 已经派发给 worker，但此时不能提前 done。
ready_nodes = sorter.get_ready()
for node in ready_nodes:
    task_queue.put(node)  # 注释：队列只表示已派发，不表示业务成功。

while pending_nodes:
    node, ok = finished_queue.get()  # 注释：只从完成回执队列取结果。
    pending_nodes.remove(node)
    if not ok:
        raise RuntimeError(f"节点处理失败: {node}")  # 注释：失败时不要伪造 done。
    sorter.done(node)  # 注释：确认后，后继节点才可能被 get_ready 返回。

官方文档对 is_active() 的定义也解释了这个设计：只要已经返回的节点中仍有未调用 done() 的节点，排序器就仍然可能继续推进。因此，派发计数和完成计数要分开维护。

异常、重复确认与正常收尾

调用前可以按三条规则排查：第一，节点必须来自本轮或之前某轮 get_ready()；第二，同一节点只能确认一次；第三，必须先 prepare()。遇到 CycleError 时，图中可能仍有一部分节点可以读取，但被循环阻塞的节点不能靠提前 done() 绕过依赖。

如果只是一次性的串行排序，不需要手动管理生命周期，可以使用 static_order()。它内部完成 prepare()、get_ready() 和 done() 的配对；此时不要再手动调用这三个接口。需要并行 worker、失败回执或细粒度调度时，再使用显式循环。

常见问题

为什么 get_ready 返回了节点却不能马上 done？因为返回只表示依赖已满足、节点可被处理；done() 表示处理确实结束。两者之间必须经过业务执行。

能不能只 done 一部分 ready 节点？可以。剩余节点继续保持未完成状态，is_active() 会维持调度活跃；完成的节点确认后，相关后继才会重新参与就绪判断。

节点处理失败后是否应该照样 done？通常不应该。done() 会向排序器宣布该节点完成并释放后继，失败重试、终止或补偿应由外层调度策略决定。

把 get_ready() 看作“领取许可”，把 done() 看作“完成回执”，就能准确理解这个 API 的边界：领取许可不等于任务完成，完成回执也不能替代真实处理。