celestialflow 3.0.8__tar.gz → 3.0.9__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. {celestialflow-3.0.8 → celestialflow-3.0.9}/PKG-INFO +97 -107
  2. {celestialflow-3.0.8 → celestialflow-3.0.9}/README.md +95 -106
  3. {celestialflow-3.0.8 → celestialflow-3.0.9}/pyproject.toml +17 -2
  4. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/__init__.py +2 -3
  5. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/static/css/base.css +1 -0
  6. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/static/css/dashboard.css +9 -5
  7. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/static/css/errors.css +4 -0
  8. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/static/js/main.js +3 -3
  9. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/static/js/task_errors.js +8 -7
  10. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/static/js/task_injection.js +3 -3
  11. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/static/js/task_statuses.js +3 -3
  12. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/static/js/task_structure.js +5 -4
  13. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/task_graph.py +162 -75
  14. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/task_logging.py +50 -10
  15. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/task_manage.py +171 -83
  16. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/task_nodes.py +22 -22
  17. celestialflow-3.0.9/src/celestialflow/task_queue.py +325 -0
  18. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/task_report.py +11 -7
  19. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/task_stage.py +42 -13
  20. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/task_structure.py +34 -8
  21. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/task_tools.py +126 -67
  22. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/task_types.py +4 -3
  23. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/task_web.py +33 -22
  24. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/templates/index.html +2 -1
  25. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow.egg-info/PKG-INFO +97 -107
  26. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow.egg-info/SOURCES.txt +0 -4
  27. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow.egg-info/requires.txt +1 -0
  28. {celestialflow-3.0.8 → celestialflow-3.0.9}/tests/test_graph.py +0 -2
  29. {celestialflow-3.0.8 → celestialflow-3.0.9}/tests/test_nodes.py +4 -6
  30. {celestialflow-3.0.8 → celestialflow-3.0.9}/tests/test_structure.py +0 -2
  31. celestialflow-3.0.8/src/celestialflow/adapters/__init__.py +0 -0
  32. celestialflow-3.0.8/src/celestialflow/adapters/celestialtree/__init__.py +0 -2
  33. celestialflow-3.0.8/src/celestialflow/adapters/celestialtree/client.py +0 -201
  34. celestialflow-3.0.8/src/celestialflow/adapters/celestialtree/tools.py +0 -41
  35. celestialflow-3.0.8/src/celestialflow/task_queue.py +0 -248
  36. {celestialflow-3.0.8 → celestialflow-3.0.9}/setup.cfg +0 -0
  37. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/static/css/inject.css +0 -0
  38. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/static/favicon.ico +0 -0
  39. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/static/js/task_topology.js +0 -0
  40. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/static/js/utils.js +0 -0
  41. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow/task_progress.py +0 -0
  42. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow.egg-info/dependency_links.txt +0 -0
  43. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow.egg-info/entry_points.txt +0 -0
  44. {celestialflow-3.0.8 → celestialflow-3.0.9}/src/celestialflow.egg-info/top_level.txt +0 -0
  45. {celestialflow-3.0.8 → celestialflow-3.0.9}/tests/test_manage.py +0 -0
{celestialflow-3.0.8 → celestialflow-3.0.9}/PKG-INFO RENAMED
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: celestialflow
3
- Version: 3.0.8
3
+ Version: 3.0.9
4
4
  Summary: A flexible GRAPH-based task orchestration framework.
5
5
  Author-email: Mr-xiaotian <mingxiaomingtian@gmail.com>
6
6
  License: MIT
@@ -22,6 +22,7 @@ Requires-Dist: requests
22
22
  Requires-Dist: networkx
23
23
  Requires-Dist: redis
24
24
  Requires-Dist: jinja2
25
+ Requires-Dist: celestialtree
25
26
 
26
27
  # CelestialFlow ——一个轻量级、可并行、基于图结构的 Python 任务调度框架
27
28
 
@@ -48,21 +49,30 @@ Requires-Dist: jinja2
48
49
  - 相比 Airflow/Dagster 更轻、更快开始
49
50
  - 相比 multiprocessing/threading 更结构化，可直接表达 loop / complete graph 等复杂依赖模式
50
51
 
51
- 框架的基本单元为 **TaskStage**（由 `TaskManager` 派生），每个 stage 内部绑定一个独立的执行函数，并支持四种运行模式：
52
+ 框架的基本单元为 **TaskManager**，可独立运行，并支持四种执行模式：
52
53
 
53
54
  * **线性（serial）**
54
55
  * **多线程（thread）**
55
56
  * **多进程（process）**
56
57
  * **协程（async）**
57
58
 
58
- 每个 stage 均可独立运行，也可作为节点互相连接，形成具有上游与下游依赖关系的任务图（**TaskGraph**）。下游 stage 会自动接收上游执行完成的结果作为输入，从而形成明确的数据流。
59
+ TaskManager 实现了对任务的结果缓存，任务去重，进度条显示，多执行模式比较等功能，单独使用也很好用。
60
+
61
+ 但除去直接使用 TaskManager，更重要的是使用其子类**TaskStage**。TaskStage 可以互相连接，形成具有上游与下游依赖关系的任务图（**TaskGraph**）。下游 stage 会自动接收上游执行完成的结果作为输入，从而形成明确的数据流。
62
+
63
+ TaskStage 的任务执行模式只有两种：
64
+
65
+ * **线性（serial）**
66
+ * **多线程（thread）**
59
67
 
60
68
  在图级别上，每个 Stage 支持两种上下文模式：
61
69
 
62
70
  * **线性执行（serial layout）**：当前节点执行完毕再启动下一节点（下游节点可提前接收任务但不会立即执行）。
63
71
  * **并行执行（process layout）**：当前节点启动后立刻前去启动下一节点。
64
72
 
65
- TaskGraph 能构建完整的 **有向图结构（Directed Graph）**，不仅支持传统的有向无环图（DAG），也能灵活表达 **树形（Tree）**、**环形（loop）** 乃至于 **完全图(Complete Graph)** 形式的任务依赖。
73
+ TaskGraph 能构建完整的 **有向图结构（Directed Graph）**，不仅支持传统的有向无环图（DAG），也能灵活表达 **树形（Tree）**、**环形（loop）** 乃至于 **完全图（Complete Graph）** 形式的任务依赖。
74
+
75
+ 在执行与调度之外，CelestialFlow 进一步引入 **CelestialTree（简称: ctree） 事件追踪系统**，为每一个任务及其衍生行为（成功、失败、重试、拆分、路由等）记录明确的因果关系。借助 ctree，可以从任意一个初始任务出发，完整还原其在 TaskGraph 中的传播路径与执行轨迹，使任务系统可以进行完整的**追溯、分析、解释**。
66
76
 
67
77
  在此基础上，CelestialFlow 支持 Web 可视化监控，并可通过 Redis 实现跨进程、跨设备协作；同时引入基于 Go 的外部 worker（通过 Redis 通信），用于承载 CPU 密集型任务，弥补 Python 在该场景下的性能瓶颈。
68
78
 
@@ -80,30 +90,9 @@ flowchart LR
80
90
  S3[TaskStage C]
81
91
  S4[TaskStage D]
82
92
 
83
- T1[Last Stage]
84
- T2[Next Stage]
85
-
86
- TS[[TaskSplitter]]
87
- TRSI1[/TaskRedisSink/]
88
- TRSI2[/TaskRedisSink/]
89
- TRSO[/TaskRedisSource/]
90
- TRA[/TaskRedisAck/]
91
-
92
- RE1[(Redis)]
93
- RE2[(Redis)]
94
- G1((GoWorker))
95
- G2((GoWorker))
96
-
97
93
  S1 --> S2 --> S3 --> S1
98
94
  S1 --> S4
99
95
 
100
- T1 -->|1 task| TS
101
- TS -->|N task| T2
102
-
103
- TRSI1 -.-> RE1 -.-> TRSO
104
- TRSI2 -.->|task| RE2 -.->|task| G1
105
- G2 -.->|result| RE2 -.->|result| TRA
106
-
107
96
  end
108
97
 
109
98
  %% 美化 TaskGraph 外框
@@ -114,13 +103,6 @@ flowchart LR
114
103
 
115
104
  %% 美化 TaskStages
116
105
  class S1,S2,S3,S4 blueNode;
117
- class T1,T2 blueNode;
118
-
119
- %% 美化 特殊Stage
120
- class TS,TRA,TRSI1,TRSI2,TRSO blueNode;
121
-
122
- %% 美化 外部结构
123
- class RE1,RE2,G1,G2 blueNode;
124
106
 
125
107
  %% ===== WebUI =====
126
108
  subgraph W[WebUI]
@@ -200,18 +182,18 @@ if __name__ == "__main__":
200
182
  flowchart TD
201
183
  classDef whiteNode fill:#ffffff,stroke:#000000,color:#000000;
202
184
 
203
- TM[TaskManage] --> TG[TaskGraph]
204
- TM --> TP[TaskProgress]
185
+ TM[TaskManage.md] --> TS[TaskStage.md] --> TG[TaskGraph.md]
186
+ TM --> TP[TaskProgress.md]
205
187
 
206
- TG --> TQ[TaskQueue]
207
- TG --> TN[TaskNodes]
208
- TG --> TR[TaskReport]
209
- TG --> TS[TaskStructure]
188
+ TG --> TQ[TaskQueue.md]
189
+ TG --> TN[TaskNodes.md]
190
+ TG --> TR[TaskReport.md]
191
+ TG --> TSR[TaskStructure.md]
210
192
 
211
- TR --> TW[TaskWeb]
212
- TN --> GW[Go Worker]
193
+ TR --> TW[TaskWeb.md]
194
+ TN --> GW[Go Worker.md]
213
195
 
214
- class TM,TG,TP,TQ,TN,TR,TS,TW,GW whiteNode;
196
+ class TM,TG,TP,TQ,TN,TR,TS,TW,GW,TSR whiteNode;
215
197
  ```
216
198
 
217
199
  以下三篇可以作为补充阅读:
@@ -224,42 +206,49 @@ flowchart TD
224
206
 
225
207
  [📘案例教程](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/tutorial.md)
226
208
 
209
+ 如果你对3.0.7版本加入的ctree_client与其功能感兴趣, 可以看看这一篇:
210
+
211
+ [📚CelestialTreeClient](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/reference/ctree_client.md)
212
+
227
213
  ## 环境要求（Requirements）
228
214
 
229
215
  **CelestialFlow** 基于 Python 3.8+，并依赖以下核心组件。
230
216
  请确保你的环境能够正常安装这些依赖（`pip install celestialflow` 会自动安装）。
231
217
 
232
218
  | 依赖包 | 说明 |
233
- | ---------------- | ---- |
234
- | **Python ≥ 3.8** | 运行环境，建议使用 3.10 及以上版本 |
235
- | **tqdm** | 控制台进度条显示，用于任务执行可视化 |
236
- | **loguru** | 高性能日志系统，支持多进程安全输出 |
237
- | **fastapi** | Web 服务接口框架（用于任务可视化与远程控制） |
238
- | **uvicorn** | FastAPI 的高性能 ASGI 服务器 |
239
- | **requests** | HTTP 客户端库，用于任务状态上报与远程调用 |
240
- | **networkx** | 任务图（TaskGraph）结构与依赖分析 |
241
- | **redis** | 可选组件，用于分布式任务通信（`TaskRedis*` 系列模块） |
242
- | **jinja2** | FastAPI 模板引擎，用于 Web 可视化界面渲染 |
219
+ | ----------------- | ---- |
220
+ | **Python ≥ 3.8** | 运行环境，建议使用 3.10 及以上版本 |
221
+ | **tqdm** | 控制台进度条显示，用于任务执行可视化 |
222
+ | **loguru** | 高性能日志系统，支持多进程安全输出 |
223
+ | **fastapi** | Web 服务接口框架（用于任务可视化与远程控制） |
224
+ | **uvicorn** | FastAPI 的高性能 ASGI 服务器 |
225
+ | **requests** | HTTP 客户端库，用于任务状态上报与远程调用 |
226
+ | **networkx** | 任务图（TaskGraph）结构与依赖分析 |
227
+ | **jinja2** | FastAPI 模板引擎，用于 Web 可视化界面渲染 |
228
+ | **redis** | 可选组件，用于分布式任务通信（`TaskRedis*` 系列模块） |
229
+ | **celestialtree** | 可选组件，用于任务状态上报与远程调用（`ctree_client`） |
243
230
 
244
231
  ## 文件结构（File Structure）
245
232
 
246
233
  ```
247
- 📁 CelestialFlow (213MB 633KB 545B)
248
- 📁 docs (25KB 183B)
249
- 📁 reference (20KB 175B)
234
+ 📁 CelestialFlow (224MB 407KB 500B)
235
+ 📁 docs (34KB 944B)
236
+ 📁 reference (29KB 995B)
237
+ 📝 ctree_client.md (6KB 997B)
250
238
  📝 go_worker.md (6KB 378B)
251
239
  📝 task_graph.md (4KB 989B)
252
240
  📝 task_logging.md (0B)
253
- 📝 task_manage.md (7KB 7B)
254
- 📝 task_nodes.md (1KB 737B)
241
+ 📝 task_manage.md (7KB 499B)
242
+ 📝 task_nodes.md (4KB 68B)
255
243
  📝 task_progress.md (0B)
256
244
  📝 task_queue.md (0B)
257
245
  📝 task_report.md (0B)
246
+ 📝 task_stage.md (0B)
258
247
  📝 task_structure.md (112B)
259
248
  📝 task_tools.md (0B)
260
249
  📝 task_types.md (0B)
261
250
  📝 task_web.md (0B)
262
- 📝 quick_start.md (5KB 8B)
251
+ 📝 quick_start.md (4KB 973B)
263
252
  📝 tutorial.md (0B)
264
253
  📁 experiments (15KB 111B)
265
254
  🐍 benchmark_datastructures.py (6KB 52B)
@@ -282,64 +271,56 @@ flowchart TD
282
271
  📷 logo.png (122KB 747B)
283
272
  📷 web_display.png (129KB 545B)
284
273
  🎞️ web_ui.gif (3MB 635KB 909B)
285
- 📁 src (1MB 920KB 171B)
286
- 📁 celestialflow (1MB 902KB 818B)
287
- 📁 adapters (13KB 837B)
288
- 📁 celestialtree (13KB 681B)
289
- 📁 [1项排除的目录] (6KB 960B)
290
- 🐍 client.py (5KB 486B)
291
- 🐍 tools.py (1KB 182B)
292
- 🐍 __init__.py (77B)
293
- 📁 [1项排除的目录] (156B)
294
- 🐍 __init__.py (0B)
295
- 📁 static (1MB 417KB 101B)
296
- 📁 css (31KB 410B)
297
- 🎨 base.css (6KB 155B)
298
- 🎨 dashboard.css (7KB 277B)
299
- 🎨 errors.css (5KB 168B)
274
+ 📁 src (1MB 929KB 111B)
275
+ 📁 celestialflow (1MB 911KB 486B)
276
+ 📁 static (1MB 417KB 367B)
277
+ 📁 css (31KB 621B)
278
+ 🎨 base.css (6KB 181B)
279
+ 🎨 dashboard.css (7KB 414B)
280
+ 🎨 errors.css (5KB 216B)
300
281
  🎨 inject.css (12KB 834B)
301
- 📁 js (33KB 617B)
302
- 📜 main.js (5KB 77B)
303
- 📜 task_errors.js (4KB 550B)
304
- 📜 task_injection.js (8KB 491B)
305
- 📜 task_statuses.js (8KB 63B)
306
- 📜 task_structure.js (4KB 668B)
282
+ 📁 js (33KB 672B)
283
+ 📜 main.js (5KB 65B)
284
+ 📜 task_errors.js (4KB 595B)
285
+ 📜 task_injection.js (8KB 484B)
286
+ 📜 task_statuses.js (8KB 51B)
287
+ 📜 task_structure.js (4KB 709B)
307
288
  📜 task_topology.js (1KB 375B)
308
289
  📜 utils.js (1KB 441B)
309
290
  ❓ favicon.ico (1MB 352KB 98B)
310
- 📁 templates (13KB 150B)
311
- 🌐 index.html (13KB 150B)
312
- 📁 [1项排除的目录] (331KB 149B)
313
- 🐍 task_graph.py (23KB 835B)
314
- 🐍 task_logging.py (8KB 903B)
315
- 🐍 task_manage.py (33KB 577B)
316
- 🐍 task_nodes.py (10KB 922B)
291
+ 📁 templates (13KB 174B)
292
+ 🌐 index.html (13KB 174B)
293
+ 📁 [1项排除的目录] (339KB 553B)
294
+ 🐍 task_graph.py (26KB 700B)
295
+ 🐍 task_logging.py (10KB 282B)
296
+ 🐍 task_manage.py (36KB 110B)
297
+ 🐍 task_nodes.py (10KB 814B)
317
298
  🐍 task_progress.py (1KB 477B)
318
- 🐍 task_queue.py (8KB 570B)
319
- 🐍 task_report.py (4KB 805B)
320
- 🐍 task_stage.py (5KB 511B)
321
- 🐍 task_structure.py (5KB 996B)
322
- 🐍 task_tools.py (15KB 105B)
323
- 🐍 task_types.py (2KB 265B)
324
- 🐍 task_web.py (5KB 693B)
325
- 🐍 __init__.py (1KB 114B)
326
- 📁 [1项排除的目录] (17KB 377B)
327
- 📁 tests (126KB 669B)
328
- 📁 [1项排除的目录] (90KB 310B)
299
+ 🐍 task_queue.py (10KB 948B)
300
+ 🐍 task_report.py (4KB 828B)
301
+ 🐍 task_stage.py (6KB 577B)
302
+ 🐍 task_structure.py (7KB 255B)
303
+ 🐍 task_tools.py (17KB 19B)
304
+ 🐍 task_types.py (2KB 269B)
305
+ 🐍 task_web.py (6KB 235B)
306
+ 🐍 __init__.py (1KB 22B)
307
+ 📁 [1项排除的目录] (17KB 649B)
308
+ 📁 tests (126KB 724B)
309
+ 📁 [1项排除的目录] (90KB 464B)
310
+ 🐍 conftest.py (49B)
329
311
  📝 README.md (6KB 324B)
330
- 🐍 test_graph.py (5KB 594B)
312
+ 🐍 test_graph.py (5KB 547B)
331
313
  🐍 test_manage.py (3KB 90B)
332
- 🐍 test_nodes.py (11KB 272B)
333
- 🐍 test_structure.py (10KB 103B)
334
- 📁 [6项排除的目录] (199MB 931KB 238B)
314
+ 🐍 test_nodes.py (11KB 218B)
315
+ 🐍 test_structure.py (10KB 56B)
316
+ 📁 [6项排除的目录] (210MB 685KB 450B)
335
317
  ❓ .env (88B)
336
318
  ❓ .gitignore (272B)
337
319
  ❓ LICENSE (1KB 65B)
338
320
  ❓ Makefile (501B)
339
- ❓ pyproject.toml (1KB 223B)
340
- ⚙️ pytest.ini (254B)
341
- 📝 README.md (15KB 109B)
342
- (celestial-flow 3.0.8)
321
+ ❓ pyproject.toml (1KB 594B)
322
+ 📝 README.md (16KB 3B)
323
+ (celestial-flow 3.0.9)
343
324
  ```
344
325
 
345
326
  (该视图由我的另一个项目[CelestialVault](https://github.com/Mr-xiaotian/CelestialVault)中inst_file.FileTree.print_tree()生成。)
@@ -362,7 +343,16 @@ flowchart TD
362
343
  - 3.0.5: 删除原有的TaskRedisTransfer节点, 并增添三种新的redis交互节点TaskRedisSink TaskRedisSource TaskRedisAck, 用于跨语言 跨进程 跨设备处理任务; 并在Web页面添加展示拓扑信息的卡片
363
344
  - 3.0.6: 添加对[CelestialTree](https://github.com/Mr-xiaotian/CelestialTree)系统的支持, 现在可以追踪单个任务的流向
364
345
  - 3.0.7: 将TaskStage从TaskManager中单独抽出来作为一个子类; 增加新节点TaskRouter, 可以将传入的任务选择的传给不同的下游节点, 而不是进行广播
365
- - 3.0.8: 在ctree关系上将"任务重试"后的"任务成功/失败/重试"视为因果关系, 而非之前的并行关系; 重构错误搜集部分逻辑; 修复大量3.0.6与3.07版本引入的bug; 优化部分log表现
346
+ - 3.0.8: 在ctree逻辑上将"任务重试"事件后的"任务成功/失败/重试"事件视为因果关系, 而非之前的并行关系; 重构错误搜集部分逻辑; 修复大量3.0.6与3.07版本引入的bug; 优化部分log表现
347
+ - 3.0.9: 1/23/2026
348
+ - 更新前端mermaid显示中部分节点图标;
349
+ - 对ctree_client的大量修改;
350
+ - 将ctree_client移出为单独的project;
351
+ - 在前端中添加error_id的显示, 为之后显示provenance_tree做准备;
352
+ - 增加大量warning与error, 用于提醒不规范设置;
353
+ - 优化前后端中错误数据的传输方式, 在大量错误数据时减少内存消耗;
354
+ - 优化TaskLogger中log队列的准入机制;
355
+ - 修改部分Bug
366
356
 
367
357
  ## Star 历史趋势（Star History）
368
358
 
@@ -374,6 +364,6 @@ flowchart TD
374
364
  This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
375
365
 
376
366
  ## 作者（Author）
377
- Author: Mr-xiaotian
378
- Email: mingxiaomingtian@gmail.com
367
+ Author: Mr-xiaotian
368
+ Email: mingxiaomingtian@gmail.com
379
369
  Project Link: [https://github.com/Mr-xiaotian/CelestialFlow](https://github.com/Mr-xiaotian/CelestialFlow)
{celestialflow-3.0.8 → celestialflow-3.0.9}/README.md RENAMED
@@ -23,21 +23,30 @@
23
23
  - 相比 Airflow/Dagster 更轻、更快开始
24
24
  - 相比 multiprocessing/threading 更结构化，可直接表达 loop / complete graph 等复杂依赖模式
25
25
 
26
- 框架的基本单元为 **TaskStage**（由 `TaskManager` 派生），每个 stage 内部绑定一个独立的执行函数，并支持四种运行模式：
26
+ 框架的基本单元为 **TaskManager**，可独立运行，并支持四种执行模式：
27
27
 
28
28
  * **线性（serial）**
29
29
  * **多线程（thread）**
30
30
  * **多进程（process）**
31
31
  * **协程（async）**
32
32
 
33
- 每个 stage 均可独立运行，也可作为节点互相连接，形成具有上游与下游依赖关系的任务图（**TaskGraph**）。下游 stage 会自动接收上游执行完成的结果作为输入，从而形成明确的数据流。
33
+ TaskManager 实现了对任务的结果缓存，任务去重，进度条显示，多执行模式比较等功能，单独使用也很好用。
34
+
35
+ 但除去直接使用 TaskManager，更重要的是使用其子类**TaskStage**。TaskStage 可以互相连接，形成具有上游与下游依赖关系的任务图（**TaskGraph**）。下游 stage 会自动接收上游执行完成的结果作为输入，从而形成明确的数据流。
36
+
37
+ TaskStage 的任务执行模式只有两种：
38
+
39
+ * **线性（serial）**
40
+ * **多线程（thread）**
34
41
 
35
42
  在图级别上，每个 Stage 支持两种上下文模式：
36
43
 
37
44
  * **线性执行（serial layout）**：当前节点执行完毕再启动下一节点（下游节点可提前接收任务但不会立即执行）。
38
45
  * **并行执行（process layout）**：当前节点启动后立刻前去启动下一节点。
39
46
 
40
- TaskGraph 能构建完整的 **有向图结构（Directed Graph）**，不仅支持传统的有向无环图（DAG），也能灵活表达 **树形（Tree）**、**环形（loop）** 乃至于 **完全图(Complete Graph)** 形式的任务依赖。
47
+ TaskGraph 能构建完整的 **有向图结构（Directed Graph）**，不仅支持传统的有向无环图（DAG），也能灵活表达 **树形（Tree）**、**环形（loop）** 乃至于 **完全图（Complete Graph）** 形式的任务依赖。
48
+
49
+ 在执行与调度之外，CelestialFlow 进一步引入 **CelestialTree（简称: ctree） 事件追踪系统**，为每一个任务及其衍生行为（成功、失败、重试、拆分、路由等）记录明确的因果关系。借助 ctree，可以从任意一个初始任务出发，完整还原其在 TaskGraph 中的传播路径与执行轨迹，使任务系统可以进行完整的**追溯、分析、解释**。
41
50
 
42
51
  在此基础上，CelestialFlow 支持 Web 可视化监控，并可通过 Redis 实现跨进程、跨设备协作；同时引入基于 Go 的外部 worker（通过 Redis 通信），用于承载 CPU 密集型任务，弥补 Python 在该场景下的性能瓶颈。
43
52
 
@@ -55,30 +64,9 @@ flowchart LR
55
64
  S3[TaskStage C]
56
65
  S4[TaskStage D]
57
66
 
58
- T1[Last Stage]
59
- T2[Next Stage]
60
-
61
- TS[[TaskSplitter]]
62
- TRSI1[/TaskRedisSink/]
63
- TRSI2[/TaskRedisSink/]
64
- TRSO[/TaskRedisSource/]
65
- TRA[/TaskRedisAck/]
66
-
67
- RE1[(Redis)]
68
- RE2[(Redis)]
69
- G1((GoWorker))
70
- G2((GoWorker))
71
-
72
67
  S1 --> S2 --> S3 --> S1
73
68
  S1 --> S4
74
69
 
75
- T1 -->|1 task| TS
76
- TS -->|N task| T2
77
-
78
- TRSI1 -.-> RE1 -.-> TRSO
79
- TRSI2 -.->|task| RE2 -.->|task| G1
80
- G2 -.->|result| RE2 -.->|result| TRA
81
-
82
70
  end
83
71
 
84
72
  %% 美化 TaskGraph 外框
@@ -89,13 +77,6 @@ flowchart LR
89
77
 
90
78
  %% 美化 TaskStages
91
79
  class S1,S2,S3,S4 blueNode;
92
- class T1,T2 blueNode;
93
-
94
- %% 美化 特殊Stage
95
- class TS,TRA,TRSI1,TRSI2,TRSO blueNode;
96
-
97
- %% 美化 外部结构
98
- class RE1,RE2,G1,G2 blueNode;
99
80
 
100
81
  %% ===== WebUI =====
101
82
  subgraph W[WebUI]
@@ -175,18 +156,18 @@ if __name__ == "__main__":
175
156
  flowchart TD
176
157
  classDef whiteNode fill:#ffffff,stroke:#000000,color:#000000;
177
158
 
178
- TM[TaskManage] --> TG[TaskGraph]
179
- TM --> TP[TaskProgress]
159
+ TM[TaskManage.md] --> TS[TaskStage.md] --> TG[TaskGraph.md]
160
+ TM --> TP[TaskProgress.md]
180
161
 
181
- TG --> TQ[TaskQueue]
182
- TG --> TN[TaskNodes]
183
- TG --> TR[TaskReport]
184
- TG --> TS[TaskStructure]
162
+ TG --> TQ[TaskQueue.md]
163
+ TG --> TN[TaskNodes.md]
164
+ TG --> TR[TaskReport.md]
165
+ TG --> TSR[TaskStructure.md]
185
166
 
186
- TR --> TW[TaskWeb]
187
- TN --> GW[Go Worker]
167
+ TR --> TW[TaskWeb.md]
168
+ TN --> GW[Go Worker.md]
188
169
 
189
- class TM,TG,TP,TQ,TN,TR,TS,TW,GW whiteNode;
170
+ class TM,TG,TP,TQ,TN,TR,TS,TW,GW,TSR whiteNode;
190
171
  ```
191
172
 
192
173
  以下三篇可以作为补充阅读:
@@ -199,42 +180,49 @@ flowchart TD
199
180
 
200
181
  [📘案例教程](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/tutorial.md)
201
182
 
183
+ 如果你对3.0.7版本加入的ctree_client与其功能感兴趣, 可以看看这一篇:
184
+
185
+ [📚CelestialTreeClient](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/reference/ctree_client.md)
186
+
202
187
  ## 环境要求（Requirements）
203
188
 
204
189
  **CelestialFlow** 基于 Python 3.8+，并依赖以下核心组件。
205
190
  请确保你的环境能够正常安装这些依赖（`pip install celestialflow` 会自动安装）。
206
191
 
207
192
  | 依赖包 | 说明 |
208
- | ---------------- | ---- |
209
- | **Python ≥ 3.8** | 运行环境，建议使用 3.10 及以上版本 |
210
- | **tqdm** | 控制台进度条显示，用于任务执行可视化 |
211
- | **loguru** | 高性能日志系统，支持多进程安全输出 |
212
- | **fastapi** | Web 服务接口框架（用于任务可视化与远程控制） |
213
- | **uvicorn** | FastAPI 的高性能 ASGI 服务器 |
214
- | **requests** | HTTP 客户端库，用于任务状态上报与远程调用 |
215
- | **networkx** | 任务图（TaskGraph）结构与依赖分析 |
216
- | **redis** | 可选组件，用于分布式任务通信（`TaskRedis*` 系列模块） |
217
- | **jinja2** | FastAPI 模板引擎，用于 Web 可视化界面渲染 |
193
+ | ----------------- | ---- |
194
+ | **Python ≥ 3.8** | 运行环境，建议使用 3.10 及以上版本 |
195
+ | **tqdm** | 控制台进度条显示，用于任务执行可视化 |
196
+ | **loguru** | 高性能日志系统，支持多进程安全输出 |
197
+ | **fastapi** | Web 服务接口框架（用于任务可视化与远程控制） |
198
+ | **uvicorn** | FastAPI 的高性能 ASGI 服务器 |
199
+ | **requests** | HTTP 客户端库，用于任务状态上报与远程调用 |
200
+ | **networkx** | 任务图（TaskGraph）结构与依赖分析 |
201
+ | **jinja2** | FastAPI 模板引擎，用于 Web 可视化界面渲染 |
202
+ | **redis** | 可选组件，用于分布式任务通信（`TaskRedis*` 系列模块） |
203
+ | **celestialtree** | 可选组件，用于任务状态上报与远程调用（`ctree_client`） |
218
204
 
219
205
  ## 文件结构（File Structure）
220
206
 
221
207
  ```
222
- 📁 CelestialFlow (213MB 633KB 545B)
223
- 📁 docs (25KB 183B)
224
- 📁 reference (20KB 175B)
208
+ 📁 CelestialFlow (224MB 407KB 500B)
209
+ 📁 docs (34KB 944B)
210
+ 📁 reference (29KB 995B)
211
+ 📝 ctree_client.md (6KB 997B)
225
212
  📝 go_worker.md (6KB 378B)
226
213
  📝 task_graph.md (4KB 989B)
227
214
  📝 task_logging.md (0B)
228
- 📝 task_manage.md (7KB 7B)
229
- 📝 task_nodes.md (1KB 737B)
215
+ 📝 task_manage.md (7KB 499B)
216
+ 📝 task_nodes.md (4KB 68B)
230
217
  📝 task_progress.md (0B)
231
218
  📝 task_queue.md (0B)
232
219
  📝 task_report.md (0B)
220
+ 📝 task_stage.md (0B)
233
221
  📝 task_structure.md (112B)
234
222
  📝 task_tools.md (0B)
235
223
  📝 task_types.md (0B)
236
224
  📝 task_web.md (0B)
237
- 📝 quick_start.md (5KB 8B)
225
+ 📝 quick_start.md (4KB 973B)
238
226
  📝 tutorial.md (0B)
239
227
  📁 experiments (15KB 111B)
240
228
  🐍 benchmark_datastructures.py (6KB 52B)
@@ -257,64 +245,56 @@ flowchart TD
257
245
  📷 logo.png (122KB 747B)
258
246
  📷 web_display.png (129KB 545B)
259
247
  🎞️ web_ui.gif (3MB 635KB 909B)
260
- 📁 src (1MB 920KB 171B)
261
- 📁 celestialflow (1MB 902KB 818B)
262
- 📁 adapters (13KB 837B)
263
- 📁 celestialtree (13KB 681B)
264
- 📁 [1项排除的目录] (6KB 960B)
265
- 🐍 client.py (5KB 486B)
266
- 🐍 tools.py (1KB 182B)
267
- 🐍 __init__.py (77B)
268
- 📁 [1项排除的目录] (156B)
269
- 🐍 __init__.py (0B)
270
- 📁 static (1MB 417KB 101B)
271
- 📁 css (31KB 410B)
272
- 🎨 base.css (6KB 155B)
273
- 🎨 dashboard.css (7KB 277B)
274
- 🎨 errors.css (5KB 168B)
248
+ 📁 src (1MB 929KB 111B)
249
+ 📁 celestialflow (1MB 911KB 486B)
250
+ 📁 static (1MB 417KB 367B)
251
+ 📁 css (31KB 621B)
252
+ 🎨 base.css (6KB 181B)
253
+ 🎨 dashboard.css (7KB 414B)
254
+ 🎨 errors.css (5KB 216B)
275
255
  🎨 inject.css (12KB 834B)
276
- 📁 js (33KB 617B)
277
- 📜 main.js (5KB 77B)
278
- 📜 task_errors.js (4KB 550B)
279
- 📜 task_injection.js (8KB 491B)
280
- 📜 task_statuses.js (8KB 63B)
281
- 📜 task_structure.js (4KB 668B)
256
+ 📁 js (33KB 672B)
257
+ 📜 main.js (5KB 65B)
258
+ 📜 task_errors.js (4KB 595B)
259
+ 📜 task_injection.js (8KB 484B)
260
+ 📜 task_statuses.js (8KB 51B)
261
+ 📜 task_structure.js (4KB 709B)
282
262
  📜 task_topology.js (1KB 375B)
283
263
  📜 utils.js (1KB 441B)
284
264
  ❓ favicon.ico (1MB 352KB 98B)
285
- 📁 templates (13KB 150B)
286
- 🌐 index.html (13KB 150B)
287
- 📁 [1项排除的目录] (331KB 149B)
288
- 🐍 task_graph.py (23KB 835B)
289
- 🐍 task_logging.py (8KB 903B)
290
- 🐍 task_manage.py (33KB 577B)
291
- 🐍 task_nodes.py (10KB 922B)
265
+ 📁 templates (13KB 174B)
266
+ 🌐 index.html (13KB 174B)
267
+ 📁 [1项排除的目录] (339KB 553B)
268
+ 🐍 task_graph.py (26KB 700B)
269
+ 🐍 task_logging.py (10KB 282B)
270
+ 🐍 task_manage.py (36KB 110B)
271
+ 🐍 task_nodes.py (10KB 814B)
292
272
  🐍 task_progress.py (1KB 477B)
293
- 🐍 task_queue.py (8KB 570B)
294
- 🐍 task_report.py (4KB 805B)
295
- 🐍 task_stage.py (5KB 511B)
296
- 🐍 task_structure.py (5KB 996B)
297
- 🐍 task_tools.py (15KB 105B)
298
- 🐍 task_types.py (2KB 265B)
299
- 🐍 task_web.py (5KB 693B)
300
- 🐍 __init__.py (1KB 114B)
301
- 📁 [1项排除的目录] (17KB 377B)
302
- 📁 tests (126KB 669B)
303
- 📁 [1项排除的目录] (90KB 310B)
273
+ 🐍 task_queue.py (10KB 948B)
274
+ 🐍 task_report.py (4KB 828B)
275
+ 🐍 task_stage.py (6KB 577B)
276
+ 🐍 task_structure.py (7KB 255B)
277
+ 🐍 task_tools.py (17KB 19B)
278
+ 🐍 task_types.py (2KB 269B)
279
+ 🐍 task_web.py (6KB 235B)
280
+ 🐍 __init__.py (1KB 22B)
281
+ 📁 [1项排除的目录] (17KB 649B)
282
+ 📁 tests (126KB 724B)
283
+ 📁 [1项排除的目录] (90KB 464B)
284
+ 🐍 conftest.py (49B)
304
285
  📝 README.md (6KB 324B)
305
- 🐍 test_graph.py (5KB 594B)
286
+ 🐍 test_graph.py (5KB 547B)
306
287
  🐍 test_manage.py (3KB 90B)
307
- 🐍 test_nodes.py (11KB 272B)
308
- 🐍 test_structure.py (10KB 103B)
309
- 📁 [6项排除的目录] (199MB 931KB 238B)
288
+ 🐍 test_nodes.py (11KB 218B)
289
+ 🐍 test_structure.py (10KB 56B)
290
+ 📁 [6项排除的目录] (210MB 685KB 450B)
310
291
  ❓ .env (88B)
311
292
  ❓ .gitignore (272B)
312
293
  ❓ LICENSE (1KB 65B)
313
294
  ❓ Makefile (501B)
314
- ❓ pyproject.toml (1KB 223B)
315
- ⚙️ pytest.ini (254B)
316
- 📝 README.md (15KB 109B)
317
- (celestial-flow 3.0.8)
295
+ ❓ pyproject.toml (1KB 594B)
296
+ 📝 README.md (16KB 3B)
297
+ (celestial-flow 3.0.9)
318
298
  ```
319
299
 
320
300
  (该视图由我的另一个项目[CelestialVault](https://github.com/Mr-xiaotian/CelestialVault)中inst_file.FileTree.print_tree()生成。)
@@ -337,7 +317,16 @@ flowchart TD
337
317
  - 3.0.5: 删除原有的TaskRedisTransfer节点, 并增添三种新的redis交互节点TaskRedisSink TaskRedisSource TaskRedisAck, 用于跨语言 跨进程 跨设备处理任务; 并在Web页面添加展示拓扑信息的卡片
338
318
  - 3.0.6: 添加对[CelestialTree](https://github.com/Mr-xiaotian/CelestialTree)系统的支持, 现在可以追踪单个任务的流向
339
319
  - 3.0.7: 将TaskStage从TaskManager中单独抽出来作为一个子类; 增加新节点TaskRouter, 可以将传入的任务选择的传给不同的下游节点, 而不是进行广播
340
- - 3.0.8: 在ctree关系上将"任务重试"后的"任务成功/失败/重试"视为因果关系, 而非之前的并行关系; 重构错误搜集部分逻辑; 修复大量3.0.6与3.07版本引入的bug; 优化部分log表现
320
+ - 3.0.8: 在ctree逻辑上将"任务重试"事件后的"任务成功/失败/重试"事件视为因果关系, 而非之前的并行关系; 重构错误搜集部分逻辑; 修复大量3.0.6与3.07版本引入的bug; 优化部分log表现
321
+ - 3.0.9: 1/23/2026
322
+ - 更新前端mermaid显示中部分节点图标;
323
+ - 对ctree_client的大量修改;
324
+ - 将ctree_client移出为单独的project;
325
+ - 在前端中添加error_id的显示, 为之后显示provenance_tree做准备;
326
+ - 增加大量warning与error, 用于提醒不规范设置;
327
+ - 优化前后端中错误数据的传输方式, 在大量错误数据时减少内存消耗;
328
+ - 优化TaskLogger中log队列的准入机制;
329
+ - 修改部分Bug
341
330
 
342
331
  ## Star 历史趋势（Star History）
343
332
 
@@ -349,6 +338,6 @@ flowchart TD
349
338
  This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
350
339
 
351
340
  ## 作者（Author）
352
- Author: Mr-xiaotian
353
- Email: mingxiaomingtian@gmail.com
341
+ Author: Mr-xiaotian
342
+ Email: mingxiaomingtian@gmail.com
354
343
  Project Link: [https://github.com/Mr-xiaotian/CelestialFlow](https://github.com/Mr-xiaotian/CelestialFlow)
{celestialflow-3.0.8 → celestialflow-3.0.9}/pyproject.toml RENAMED
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "celestialflow"
7
- version = "3.0.8"
7
+ version = "3.0.9"
8
8
  description = "A flexible GRAPH-based task orchestration framework."
9
9
  readme = "README.md"
10
10
  license = { text = "MIT" }
@@ -21,6 +21,7 @@ dependencies = [
21
21
  "networkx",
22
22
  "redis",
23
23
  "jinja2",
24
+ "celestialtree",
24
25
  ]
25
26
 
26
27
  classifiers = [
@@ -42,4 +43,18 @@ celestialflow-web = "celestialflow.task_web:main_entry"
42
43
  license-files = []
43
44
 
44
45
  [tool.setuptools.package-data]
45
- "celestialflow" = ["templates/*.html", "static/**/*"]
46
+ "celestialflow" = ["templates/*.html", "static/**/*"]
47
+
48
+ [tool.pytest.ini_options]
49
+ addopts = "-s"
50
+ log_cli = true
51
+ log_cli_level = "INFO"
52
+ log_cli_format = "%(asctime)s [%(levelname)s] %(message)s"
53
+ log_cli_date_format = "%Y-%m-%d %H:%M:%S"
54
+
55
+ filterwarnings = [
56
+ "ignore::DeprecationWarning",
57
+ "ignore::pytest.PytestDeprecationWarning",
58
+ ]
59
+
60
+ asyncio_default_fixture_loop_scope = "function"