celestialflow 3.2.6__tar.gz → 3.2.8__tar.gz

{celestialflow-3.2.6/src/celestialflow.egg-info → celestialflow-3.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: celestialflow
-Version: 3.2.6
+Version: 3.2.8
 Summary: A flexible GRAPH-based task orchestration framework.
 Author-email: Mr-xiaotian <mingxiaomingtian@gmail.com>
 License: MIT
@@ -14,7 +14,6 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: tqdm
 Requires-Dist: requests
 Dynamic: license-file
 
@@ -134,16 +133,27 @@ uv sync --group dev
 ```python
 from celestialflow import TaskStage, TaskGraph
 
-def add(x, y): 
+
+def add(x, y):
     return x + y
 
-def square(x): 
-    return x ** 2
+
+def square(x):
+    return x**2
+
 
 if __name__ == "__main__":
     # 定义两个任务节点
-    stage1 = TaskStage(name="Adder", func=add, stage_mode="thread", execution_mode="thread", unpack_task_args=True)
-    stage2 = TaskStage(name="Squarer", func=square, stage_mode="thread", execution_mode="thread")
+    stage1 = TaskStage(
+        name="Adder",
+        func=add,
+        stage_mode="thread",
+        execution_mode="thread",
+        unpack_task_args=True,
+    )
+    stage2 = TaskStage(
+        name="Squarer", func=square, stage_mode="thread", execution_mode="thread"
+    )
 
     # 构建任务图结构
     graph = TaskGraph(name="DemoGraph")
@@ -165,12 +175,12 @@ if __name__ == "__main__":
 - [TaskExecutor.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/stage/core_executor.md)
 - [TaskStage.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/stage/core_stage.md)
 - [TaskGraph.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/graph/core_graph.md)
-- [TaskProgress.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/observability/core_progress.md)
 - [TaskMetrics.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/core_metrics.md)
 - [TaskQueue.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/core_queue.md)
 - [TaskStages.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/stage/core_stages.md)
 - [TaskReport.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/observability/core_report.md)
 - [TaskStructure.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/graph/core_structure.md)
+- [BaseObserver.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/observability/core_observer.md)
 - [Go Worker.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/other/go_worker.md)
 
 推荐阅读顺序:
@@ -183,7 +193,7 @@ flowchart TD
     classDef execution fill:#f3e8ff,stroke:#a855f7,color:#581c87;
 
     TM[TaskExecutor.md] --> TS[TaskStage.md] --> TG[TaskGraph.md]
-    TM --> TP[TaskProgress.md]
+    TM --> OB[BaseObserver.md]
     TM --> TME[TaskMetrics.md]
 
     TG --> TQ[TaskQueue.md]
@@ -247,26 +257,126 @@ flowchart TD
 
 ## 文件结构（File Structure）
 
+```
+📁 CelestialFlow	(587MB 684KB 313B)
+    📁 bench           	(296KB 842B)
+        📁 [1项排除的目录]                  	(194KB 222B)
+        🐍 bench_datastructures.py          	(6KB 690B)
+        🐍 bench_execution_mode.py          	(2KB 831B)
+        🐍 bench_futures_memory.py          	(2KB 269B)
+        🐍 bench_gil_vs_nogil.py            	(10KB 7B)
+        🐍 bench_graph_mode.py              	(7KB 450B)
+        🐍 bench_hash.py                    	(7KB 67B)
+        🐍 bench_hash_container.py          	(3KB 1009B)
+        🐍 bench_hash_memory.py             	(3KB 642B)
+        🐍 bench_http_grpc.py               	(2KB 608B)
+        🐍 bench_ipc_queue.py               	(7KB 104B)
+        🐍 bench_lock_overhead.py           	(9KB 421B)
+        🐍 bench_mpqueue_vs_shared_memory.py	(13KB 127B)
+        🐍 bench_observer.py                	(7KB 860B)
+        🐍 bench_persistence_spout.py       	(4KB 279B)
+        🐍 bench_queue.py                   	(5KB 857B)
+        🐍 bench_requests.py                	(6KB 813B)
+        🐍 bench_tqdm.py                    	(1KB 235B)
+        🐍 bench_utils.py                   	(543B)
+    📁 demo            	(147KB 87B)
+        📁 [1项排除的目录]  	(100KB 9B)
+        🐍 demo_executor.py 	(1KB 495B)
+        🐍 demo_funnel.py   	(2KB 289B)
+        🐍 demo_graph.py    	(3KB 565B)
+        🐍 demo_network.py  	(3KB 879B)
+        🐍 demo_observer.py 	(4KB 270B)
+        🐍 demo_redis.py    	(9KB 144B)
+        🐍 demo_stages.py   	(4KB 336B)
+        🐍 demo_structure.py	(12KB 24B)
+        🐍 demo_utils.py    	(6KB 148B)
+    📁 dist            	(147KB 48B)
+        ❓ .gitignore                          	(1B)
+        ❓ celestialflow-3.2.7-py3-none-any.whl	(79KB 235B)
+        📦 celestialflow-3.2.7.tar.gz          	(67KB 836B)
+    📁 docs            	(1MB 722KB 21B)
+        📁 en[已折叠]   	(568KB 991B)
+        📁 ja[已折叠]   	(642KB 383B)
+        📁 zh-CN[已折叠]	(534KB 695B)
+    📁 experiments     	(2KB 1015B)
+        🐍 experiment_networkx.py	(1KB 878B)
+        🐍 experiment_tqdm.py    	(1KB 137B)
+    📁 img             	(5MB 871KB 242B)
+        📷 file_structure.svg  	(4MB 918KB 1000B)
+        📷 logo(old).png       	(836KB 542B)
+        📷 logo.png            	(122KB 747B)
+        📷 scc_condensation.svg	(17KB 1B)
+    📁 src             	(1MB 858KB 89B)
+        📁 celestialflow[已折叠]         	(1MB 839KB 629B)
+        📁 celestialflow.egg-info[已折叠]	(18KB 484B)
+    📁 tests           	(4MB 167KB 552B)
+        📁 benchmark[已折叠]    	(38KB 197B)
+        📁 funnel[已折叠]       	(96KB 363B)
+        📁 graph[已折叠]        	(721KB 564B)
+        📁 observability[已折叠]	(189KB 236B)
+        📁 persistence[已折叠]  	(388KB 426B)
+        📁 runtime[已折叠]      	(1MB 295KB 529B)
+        📁 stage[已折叠]        	(382KB 155B)
+        📁 utils[已折叠]        	(639KB 527B)
+        📁 [1项排除的目录]      	(487KB 589B)
+        🐍 conftest.py          	(1KB 38B)
+        🐍 __init__.py          	(0B)
+    📁 [12项排除的目录]	(573MB 420KB 160B)
+    ❓ .env            	(468B)
+    ❓ .gitignore      	(1KB 314B)
+    📝 AGENTS.md       	(1KB 173B)
+    ❓ LICENSE         	(1KB 65B)
+    ❓ Makefile        	(155B)
+    ⚙️ pyproject.toml  	(2KB 668B)
+    📝 README.md       	(19KB 24B)
+    🔒 uv.lock         	(97KB 510B)
+```
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Mr-xiaotian/CelestialFlow/main/img/file_structure.svg" alt="FileStructure" />
-  <br/>
-  <em>celestial-flow 3.2.6</em>
+  <em>celestial-flow 3.2.8</em>
 </p>
 
 (该视图由我的另一个项目[CelestialVault](https://github.com/Mr-xiaotian/CelestialVault)中inst_file.FileTree.print_tree()生成。转换为图片则借助[Carbon](https://carbon.now.sh)。)
 
 ## 版本日志（Version Log）
-- 3.2.6
+- 3.2.8
   - feat:
-    - 在 `graph` 与 `stage` 中添加直接读取db文件并重试/继续任务的方法
-      - 分别为 `start_graph_db` 与 `start_db`
+    - [IMPORTANT] 添加 `TaskGraph.run_async`, 现在可以直接进行图级别的异步
+      - 根据 `bench_graph_mode.py` 最新测试, 在I/O密集型任务中, `serial`+`async`（6.05s），比 `serial`+`serial`（69.04s）快 **11.4x**
+    - 在 `core_structure` 中添加报错校验
+    - 不再允许设置 `execution_mode=async` 时调用 `TashExecutor.start`(如今的`TashExecutor.run`), 只能调用 `TashExecutor.run_async`
+    - 另外调用 `TashExecutor.run_async` 时也会进行模式检查, 不是 `execution_mode=async` 就会抛出异常
+    - 在 `BaseObserver` 中添加 `observer_error`, 用于处理 `BaseObserver.on_*` 函数的报错
+    - 在 `TaskGraph._finish_start_graph` `TaskExecutor._finish_start` 中对所有执行步骤进行 `try-except`, 以使收尾步骤尽量全部完成
+    - 添加 `core_scope`, 用于独立控制 `funnel` 的生命周期, 并用于 `TaskGraph.run/run_async` `TaskExecutor.run/run_async`
   - refactor:
-    - **[IMPORTANT]** 将web部分移至单独项目 [celestialflow-web](https://github.com/Mr-xiaotian/celestialflow-web)
-      - 考虑许久的决定, 当前的web端代码与项目整体风格差异极大, 已经不再适合继续合并一处
-      - 当然这意味着 `celestialflow-web` 命令在当前项目下失效, 需要单独安装 `pip install celestialflow-web`
-  - chore:
-    - 全量更新文档, 并翻译为en/ja双语言
-    - 移除 docs/zh-CN 下的 `README.md`, 现在中文readme只保留根目录下的这一份
+    - [IMPORTANT] 原 `TaskGraph.start_graph/start_graph_async` `TaskExecutor.start/start_async` 已被重命名为 `TaskGraph.run/run_async` `TaskExecutor.run/run_async`
+      - 破坏性更新
+      - 其底层缘由是为了合并 `TaskStage.start_stage/start_stage_async` 与 `TaskExecutor.start/start_async` 而做出的一系列重构之一
+      - 现在的 `TaskGraph.start/start_async` `TaskExecutor.start/start_async` 不再接受任务, 而是专注于处理现有任务列表中的任务
+    - [IMPORTANT] 将funnel从 `TaskGraph` `TaskExecutor` 中的显性调用与显性传递, 改为所有使用端均从独立文件中import
+      - 一来是因为原先的传递链太丑了, 二来是为了简化 `TaskExecutor.start/start_async` 逻辑, 为其与 `TaskStage.start_stage/start_stage_async` 的合并做准备
+    - 移动部分文件以解决部分模块级的循环引用问题
+      - 原先并非文件级循环引用, 在使用上并无问题
+    - 修改 `TaskDispatch.dispatch_thread` 中处理已完成future的逻辑, 避免cpu浪费
+    - 删除 `util_errors` 中一些不必要的错误类
+    - 将 `TaskGraph._finalize_stages` 进行拆分, 删除不必要的机制, 将剩余机制移至其他方法
+    - 修改 `TaskGraph.set_reporter` 的逻辑, 使其与 `set_ctree` 保持一致
+    - 将 `TaskOutQueue` 中的 `queue_list|target_name|_name_to_idx` 改为 `_queues`, 并删除 `put_channel`
+      - 我有些困惑为什么最初我没有这么做
+    - 在 `TaskExecutor` 中合并 `_get_task_repr` and `_get_result_repr`
+      - 这两个方法原先差异巨大, 但后来经过多次其他部分的重构, 现在逻辑已经一致
+    - 将 `TaskStage` 中的 `_status` 交给 `TaskMetrics` 维护
+      - 依旧是为了合并 `TaskExecutor.start/start_async` 与 `TaskStage.start_stage/start_stage_async`
+    - 移除 `TaskGraph` 中的 `put_stage_queue`
+      - 任务输入完全使用 `TaskExecutor` 中的 `put_task` `put_signal` 方法
+  - fix:
+    - 在 `TaskDispatch.worker/worker_async` 中添加错误捕捉, 捕捉为 `CRITICAL` 级错误
+      - 避免 `worker` 级出错导致计数错误, 永远无法退出
+    - 在 `spout` 与 `reporter` 的 `stop` 操作中添加对于线程没有成功 `join` 的报错
+    - 修复 `TaskGraph.restore_db` 与 `TaskExecutor.restore_db` 中开启 `filter_by_error_type=Ture` 时跳过 `status=pending` 任务记录的问题
+    - 修复 `TaskGraph` 中部分 `get_*` 方法依赖 `_build_analysis` 的产物, 但 `_build_analysis` 未执行导致的问题
+    - 修复 `TaskMetrics` 中 `get_counts` 与 `is_tasks_finished` 中可能导致死锁的问题
+    - 修复 `TaskReporter` 中 `stop` 里进行的最后一次 `_refresh_all` 没有错误捕捉, 导致后续收尾未完成的问题
 
 更多过往日志可看:
 

{celestialflow-3.2.6 → celestialflow-3.2.8}/README.md

@@ -114,16 +114,27 @@ uv sync --group dev
 ```python
 from celestialflow import TaskStage, TaskGraph
 
-def add(x, y): 
+
+def add(x, y):
     return x + y
 
-def square(x): 
-    return x ** 2
+
+def square(x):
+    return x**2
+
 
 if __name__ == "__main__":
     # 定义两个任务节点
-    stage1 = TaskStage(name="Adder", func=add, stage_mode="thread", execution_mode="thread", unpack_task_args=True)
-    stage2 = TaskStage(name="Squarer", func=square, stage_mode="thread", execution_mode="thread")
+    stage1 = TaskStage(
+        name="Adder",
+        func=add,
+        stage_mode="thread",
+        execution_mode="thread",
+        unpack_task_args=True,
+    )
+    stage2 = TaskStage(
+        name="Squarer", func=square, stage_mode="thread", execution_mode="thread"
+    )
 
     # 构建任务图结构
     graph = TaskGraph(name="DemoGraph")
@@ -145,12 +156,12 @@ if __name__ == "__main__":
 - [TaskExecutor.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/stage/core_executor.md)
 - [TaskStage.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/stage/core_stage.md)
 - [TaskGraph.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/graph/core_graph.md)
-- [TaskProgress.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/observability/core_progress.md)
 - [TaskMetrics.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/core_metrics.md)
 - [TaskQueue.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/core_queue.md)
 - [TaskStages.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/stage/core_stages.md)
 - [TaskReport.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/observability/core_report.md)
 - [TaskStructure.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/graph/core_structure.md)
+- [BaseObserver.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/observability/core_observer.md)
 - [Go Worker.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/other/go_worker.md)
 
 推荐阅读顺序:
@@ -163,7 +174,7 @@ flowchart TD
     classDef execution fill:#f3e8ff,stroke:#a855f7,color:#581c87;
 
     TM[TaskExecutor.md] --> TS[TaskStage.md] --> TG[TaskGraph.md]
-    TM --> TP[TaskProgress.md]
+    TM --> OB[BaseObserver.md]
     TM --> TME[TaskMetrics.md]
 
     TG --> TQ[TaskQueue.md]
@@ -227,26 +238,126 @@ flowchart TD
 
 ## 文件结构（File Structure）
 
+```
+📁 CelestialFlow	(587MB 684KB 313B)
+    📁 bench           	(296KB 842B)
+        📁 [1项排除的目录]                  	(194KB 222B)
+        🐍 bench_datastructures.py          	(6KB 690B)
+        🐍 bench_execution_mode.py          	(2KB 831B)
+        🐍 bench_futures_memory.py          	(2KB 269B)
+        🐍 bench_gil_vs_nogil.py            	(10KB 7B)
+        🐍 bench_graph_mode.py              	(7KB 450B)
+        🐍 bench_hash.py                    	(7KB 67B)
+        🐍 bench_hash_container.py          	(3KB 1009B)
+        🐍 bench_hash_memory.py             	(3KB 642B)
+        🐍 bench_http_grpc.py               	(2KB 608B)
+        🐍 bench_ipc_queue.py               	(7KB 104B)
+        🐍 bench_lock_overhead.py           	(9KB 421B)
+        🐍 bench_mpqueue_vs_shared_memory.py	(13KB 127B)
+        🐍 bench_observer.py                	(7KB 860B)
+        🐍 bench_persistence_spout.py       	(4KB 279B)
+        🐍 bench_queue.py                   	(5KB 857B)
+        🐍 bench_requests.py                	(6KB 813B)
+        🐍 bench_tqdm.py                    	(1KB 235B)
+        🐍 bench_utils.py                   	(543B)
+    📁 demo            	(147KB 87B)
+        📁 [1项排除的目录]  	(100KB 9B)
+        🐍 demo_executor.py 	(1KB 495B)
+        🐍 demo_funnel.py   	(2KB 289B)
+        🐍 demo_graph.py    	(3KB 565B)
+        🐍 demo_network.py  	(3KB 879B)
+        🐍 demo_observer.py 	(4KB 270B)
+        🐍 demo_redis.py    	(9KB 144B)
+        🐍 demo_stages.py   	(4KB 336B)
+        🐍 demo_structure.py	(12KB 24B)
+        🐍 demo_utils.py    	(6KB 148B)
+    📁 dist            	(147KB 48B)
+        ❓ .gitignore                          	(1B)
+        ❓ celestialflow-3.2.7-py3-none-any.whl	(79KB 235B)
+        📦 celestialflow-3.2.7.tar.gz          	(67KB 836B)
+    📁 docs            	(1MB 722KB 21B)
+        📁 en[已折叠]   	(568KB 991B)
+        📁 ja[已折叠]   	(642KB 383B)
+        📁 zh-CN[已折叠]	(534KB 695B)
+    📁 experiments     	(2KB 1015B)
+        🐍 experiment_networkx.py	(1KB 878B)
+        🐍 experiment_tqdm.py    	(1KB 137B)
+    📁 img             	(5MB 871KB 242B)
+        📷 file_structure.svg  	(4MB 918KB 1000B)
+        📷 logo(old).png       	(836KB 542B)
+        📷 logo.png            	(122KB 747B)
+        📷 scc_condensation.svg	(17KB 1B)
+    📁 src             	(1MB 858KB 89B)
+        📁 celestialflow[已折叠]         	(1MB 839KB 629B)
+        📁 celestialflow.egg-info[已折叠]	(18KB 484B)
+    📁 tests           	(4MB 167KB 552B)
+        📁 benchmark[已折叠]    	(38KB 197B)
+        📁 funnel[已折叠]       	(96KB 363B)
+        📁 graph[已折叠]        	(721KB 564B)
+        📁 observability[已折叠]	(189KB 236B)
+        📁 persistence[已折叠]  	(388KB 426B)
+        📁 runtime[已折叠]      	(1MB 295KB 529B)
+        📁 stage[已折叠]        	(382KB 155B)
+        📁 utils[已折叠]        	(639KB 527B)
+        📁 [1项排除的目录]      	(487KB 589B)
+        🐍 conftest.py          	(1KB 38B)
+        🐍 __init__.py          	(0B)
+    📁 [12项排除的目录]	(573MB 420KB 160B)
+    ❓ .env            	(468B)
+    ❓ .gitignore      	(1KB 314B)
+    📝 AGENTS.md       	(1KB 173B)
+    ❓ LICENSE         	(1KB 65B)
+    ❓ Makefile        	(155B)
+    ⚙️ pyproject.toml  	(2KB 668B)
+    📝 README.md       	(19KB 24B)
+    🔒 uv.lock         	(97KB 510B)
+```
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Mr-xiaotian/CelestialFlow/main/img/file_structure.svg" alt="FileStructure" />
-  <br/>
-  <em>celestial-flow 3.2.6</em>
+  <em>celestial-flow 3.2.8</em>
 </p>
 
 (该视图由我的另一个项目[CelestialVault](https://github.com/Mr-xiaotian/CelestialVault)中inst_file.FileTree.print_tree()生成。转换为图片则借助[Carbon](https://carbon.now.sh)。)
 
 ## 版本日志（Version Log）
-- 3.2.6
+- 3.2.8
   - feat:
-    - 在 `graph` 与 `stage` 中添加直接读取db文件并重试/继续任务的方法
-      - 分别为 `start_graph_db` 与 `start_db`
+    - [IMPORTANT] 添加 `TaskGraph.run_async`, 现在可以直接进行图级别的异步
+      - 根据 `bench_graph_mode.py` 最新测试, 在I/O密集型任务中, `serial`+`async`（6.05s），比 `serial`+`serial`（69.04s）快 **11.4x**
+    - 在 `core_structure` 中添加报错校验
+    - 不再允许设置 `execution_mode=async` 时调用 `TashExecutor.start`(如今的`TashExecutor.run`), 只能调用 `TashExecutor.run_async`
+    - 另外调用 `TashExecutor.run_async` 时也会进行模式检查, 不是 `execution_mode=async` 就会抛出异常
+    - 在 `BaseObserver` 中添加 `observer_error`, 用于处理 `BaseObserver.on_*` 函数的报错
+    - 在 `TaskGraph._finish_start_graph` `TaskExecutor._finish_start` 中对所有执行步骤进行 `try-except`, 以使收尾步骤尽量全部完成
+    - 添加 `core_scope`, 用于独立控制 `funnel` 的生命周期, 并用于 `TaskGraph.run/run_async` `TaskExecutor.run/run_async`
   - refactor:
-    - **[IMPORTANT]** 将web部分移至单独项目 [celestialflow-web](https://github.com/Mr-xiaotian/celestialflow-web)
-      - 考虑许久的决定, 当前的web端代码与项目整体风格差异极大, 已经不再适合继续合并一处
-      - 当然这意味着 `celestialflow-web` 命令在当前项目下失效, 需要单独安装 `pip install celestialflow-web`
-  - chore:
-    - 全量更新文档, 并翻译为en/ja双语言
-    - 移除 docs/zh-CN 下的 `README.md`, 现在中文readme只保留根目录下的这一份
+    - [IMPORTANT] 原 `TaskGraph.start_graph/start_graph_async` `TaskExecutor.start/start_async` 已被重命名为 `TaskGraph.run/run_async` `TaskExecutor.run/run_async`
+      - 破坏性更新
+      - 其底层缘由是为了合并 `TaskStage.start_stage/start_stage_async` 与 `TaskExecutor.start/start_async` 而做出的一系列重构之一
+      - 现在的 `TaskGraph.start/start_async` `TaskExecutor.start/start_async` 不再接受任务, 而是专注于处理现有任务列表中的任务
+    - [IMPORTANT] 将funnel从 `TaskGraph` `TaskExecutor` 中的显性调用与显性传递, 改为所有使用端均从独立文件中import
+      - 一来是因为原先的传递链太丑了, 二来是为了简化 `TaskExecutor.start/start_async` 逻辑, 为其与 `TaskStage.start_stage/start_stage_async` 的合并做准备
+    - 移动部分文件以解决部分模块级的循环引用问题
+      - 原先并非文件级循环引用, 在使用上并无问题
+    - 修改 `TaskDispatch.dispatch_thread` 中处理已完成future的逻辑, 避免cpu浪费
+    - 删除 `util_errors` 中一些不必要的错误类
+    - 将 `TaskGraph._finalize_stages` 进行拆分, 删除不必要的机制, 将剩余机制移至其他方法
+    - 修改 `TaskGraph.set_reporter` 的逻辑, 使其与 `set_ctree` 保持一致
+    - 将 `TaskOutQueue` 中的 `queue_list|target_name|_name_to_idx` 改为 `_queues`, 并删除 `put_channel`
+      - 我有些困惑为什么最初我没有这么做
+    - 在 `TaskExecutor` 中合并 `_get_task_repr` and `_get_result_repr`
+      - 这两个方法原先差异巨大, 但后来经过多次其他部分的重构, 现在逻辑已经一致
+    - 将 `TaskStage` 中的 `_status` 交给 `TaskMetrics` 维护
+      - 依旧是为了合并 `TaskExecutor.start/start_async` 与 `TaskStage.start_stage/start_stage_async`
+    - 移除 `TaskGraph` 中的 `put_stage_queue`
+      - 任务输入完全使用 `TaskExecutor` 中的 `put_task` `put_signal` 方法
+  - fix:
+    - 在 `TaskDispatch.worker/worker_async` 中添加错误捕捉, 捕捉为 `CRITICAL` 级错误
+      - 避免 `worker` 级出错导致计数错误, 永远无法退出
+    - 在 `spout` 与 `reporter` 的 `stop` 操作中添加对于线程没有成功 `join` 的报错
+    - 修复 `TaskGraph.restore_db` 与 `TaskExecutor.restore_db` 中开启 `filter_by_error_type=Ture` 时跳过 `status=pending` 任务记录的问题
+    - 修复 `TaskGraph` 中部分 `get_*` 方法依赖 `_build_analysis` 的产物, 但 `_build_analysis` 未执行导致的问题
+    - 修复 `TaskMetrics` 中 `get_counts` 与 `is_tasks_finished` 中可能导致死锁的问题
+    - 修复 `TaskReporter` 中 `stop` 里进行的最后一次 `_refresh_all` 没有错误捕捉, 导致后续收尾未完成的问题
 
 更多过往日志可看:
 

{celestialflow-3.2.6 → celestialflow-3.2.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "celestialflow"
-version = "3.2.6"
+version = "3.2.8"
 description = "A flexible GRAPH-based task orchestration framework."
 readme = "README.md"
 license = { text = "MIT" }
@@ -13,7 +13,6 @@ keywords = ["workflow", "task", "graph", "async", "CelestialFlow"]
 requires-python = ">=3.12"
 
 dependencies = [
-    "tqdm",
     "requests",
 ]
 
@@ -28,6 +27,9 @@ classifiers = [
 "Homepage" = "https://github.com/Mr-xiaotian/CelestialFlow"
 "Bug Tracker" = "https://github.com/Mr-xiaotian/CelestialFlow/issues"
 
+[tool.uv]
+index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+
 [tool.pytest.ini_options]
 addopts = "-s"
 log_cli = true
@@ -54,12 +56,17 @@ dev = [
     "pyright>=1.1.409",
     "redis",
     "celestialtree>=0.1.3",
+    "tqdm",
 ]
 
+[tool.celestialflow]
+log_level = "INFO"
+
 [tool.pyright]
 include = ["src"]
 ignore = ["tests", "**/tests/**", "typings", "demo", "bench", "experiments", "examples", "temp"]
 
+pythonVersion = "3.14"
 typeCheckingMode = "strict"
 reportUnusedFunction = "none"
 reportImplicitOverride = "none"

{celestialflow-3.2.6 → celestialflow-3.2.8}/src/celestialflow/__init__.py

@@ -4,6 +4,7 @@
 提供任务图构建、执行调度、实时监控与持久化等核心能力。
 """
 
+from .benchmark.util_benchmark import benchmark_executor, benchmark_graph
 from .funnel import BaseInlet, BaseSpout
 from .graph import (
     TaskChain,
@@ -14,11 +15,12 @@ from .graph import (
     TaskLoop,
     TaskWheel,
 )
-from .observability import BaseObserver, TaskProgress
+from .observability import BaseObserver, TaskReporter
 from .persistence.util_sqlite import (
     load_records,
     load_tasks_grouped_by_stage,
 )
+from .runtime.util_format import format_table
 from .runtime.util_hash import make_hashable
 from .runtime.util_types import TerminationSignal
 from .stage import (
@@ -27,8 +29,6 @@ from .stage import (
     TaskSplitter,
     TaskStage,
 )
-from .utils.util_benchmark import benchmark_executor, benchmark_graph
-from .utils.util_format import format_table
 
 __all__ = [
     "BaseInlet",
@@ -41,7 +41,7 @@ __all__ = [
     "TaskGraph",
     "TaskGrid",
     "TaskLoop",
-    "TaskProgress",
+    "TaskReporter",
     "TaskRouter",
     "TaskSplitter",
     "TaskStage",

celestialflow-3.2.8/src/celestialflow/benchmark/__init__.py

@@ -0,0 +1,6 @@
+# benchmark/__init__.py
+"""CelestialFlow 基准测试与克隆工具模块。
+
+提供执行器/任务图的克隆（clone）与基准测试（benchmark）能力。
+该模块位于依赖链顶层，可依赖其他模块，但不应被其他模块依赖。
+"""

{celestialflow-3.2.6/src/celestialflow/utils → celestialflow-3.2.8/src/celestialflow/benchmark}/util_benchmark.py

@@ -1,4 +1,4 @@
-# utils/util_benchmark.py
+# benchmark/util_benchmark.py
 from __future__ import annotations
 
 import time
@@ -6,9 +6,9 @@ from collections.abc import Iterable, Mapping
 from typing import Any
 
 from ..graph import TaskGraph
+from ..runtime.util_format import format_table
 from ..stage import TaskExecutor
 from .util_clone import clone_executor, clone_graph
-from .util_format import format_table
 
 type AnyTaskExecutor = TaskExecutor[Any, Any]
 
@@ -41,7 +41,8 @@ async def benchmark_executor(
         cloned_executor.set_execution_mode(mode)
 
         start: float = time.perf_counter()
-        cloned_executor.start(task_list)
+        cloned_executor.put_tasks(task_list)
+        cloned_executor.start()
         use_time.append([time.perf_counter() - start])
         results.append(cloned_executor.get_success_pairs())
 
@@ -50,7 +51,8 @@ async def benchmark_executor(
         cloned_executor.set_execution_mode(mode)
 
         start = time.perf_counter()
-        await cloned_executor.start_async(task_list)
+        cloned_executor.put_tasks(task_list)
+        await cloned_executor.start_async()
         use_time.append([time.perf_counter() - start])
         results.append(cloned_executor.get_success_pairs())
 
@@ -68,7 +70,7 @@ async def benchmark_executor(
     }
 
 
-def benchmark_graph(
+async def benchmark_graph(
     sync_graph: TaskGraph,
     async_graph: TaskGraph,
     init_tasks_dict: Mapping[str, Iterable[Any]],
@@ -88,38 +90,39 @@ def benchmark_graph(
     :return: 包含测试结果的字典
     """
     stage_modes = stage_modes or ["serial", "thread"]
-    sync_modes = execution_sync_modes or ["serial", "thread"]
-    async_modes = execution_async_modes or ["async"]
+    execution_sync_modes = execution_sync_modes or ["serial", "thread"]
+    execution_async_modes = execution_async_modes or ["async"]
 
     base_tasks: dict[str, list[Any]] = {
         stage_name: list(tasks) for stage_name, tasks in init_tasks_dict.items()
     }
-    execution_modes: list[str] = sync_modes + async_modes
+    execution_modes: list[str] = execution_sync_modes + execution_async_modes
 
     test_table_list: list[list[float]] = []
 
     for stage_mode in stage_modes:
         time_list: list[float] = []
-        for execution_mode in sync_modes:
+
+        for execution_mode in execution_sync_modes:
             cloned_graph: TaskGraph = clone_graph(sync_graph)
             cloned_graph.set_graph_mode(stage_mode, execution_mode)
 
-            run_tasks: dict[str, list[Any]] = {
+            sync_run_tasks: dict[str, Iterable[Any]] = {
                 stage_name: list(tasks) for stage_name, tasks in base_tasks.items()
             }
             start_time: float = time.perf_counter()
-            cloned_graph.start_graph(run_tasks)
+            cloned_graph.run(sync_run_tasks)
             time_list.append(time.perf_counter() - start_time)
 
-        for execution_mode in async_modes:
+        for execution_mode in execution_async_modes:
             cloned_graph = clone_graph(async_graph)
             cloned_graph.set_graph_mode(stage_mode, execution_mode)
 
-            run_tasks = {
+            async_run_tasks: dict[str, Iterable[Any]] = {
                 stage_name: list(tasks) for stage_name, tasks in base_tasks.items()
             }
             start_time = time.perf_counter()
-            cloned_graph.start_graph(run_tasks)
+            await cloned_graph.run_async(async_run_tasks)
             time_list.append(time.perf_counter() - start_time)
 
         test_table_list.append(time_list)
@@ -128,12 +131,12 @@ def benchmark_graph(
         test_table_list,
         stage_modes,
         execution_modes,
-        r"stage\execution",
+        "stage/execution",
     )
     print(f"Time table:\n{time_table}")
     return {
         "table": time_table,
         "stage_modes": stage_modes,
-        "sync_modes": sync_modes,
-        "async_modes": async_modes if async_graph else [],
+        "sync_modes": execution_sync_modes,
+        "async_modes": execution_async_modes if async_graph else [],
     }