celestialflow 3.0.8__tar.gz → 3.1.0__tar.gz

{celestialflow-3.0.8 → celestialflow-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: celestialflow
-Version: 3.0.8
+Version: 3.1.0
 Summary: A flexible GRAPH-based task orchestration framework.
 Author-email: Mr-xiaotian <mingxiaomingtian@gmail.com>
 License: MIT
@@ -22,6 +22,7 @@ Requires-Dist: requests
 Requires-Dist: networkx
 Requires-Dist: redis
 Requires-Dist: jinja2
+Requires-Dist: celestialtree
 
 # CelestialFlow ——一个轻量级、可并行、基于图结构的 Python 任务调度框架
 
@@ -48,21 +49,30 @@ Requires-Dist: jinja2
 - 相比 Airflow/Dagster 更轻、更快开始
 - 相比 multiprocessing/threading 更结构化，可直接表达 loop / complete graph 等复杂依赖模式
 
-框架的基本单元为 **TaskStage**（由 `TaskManager` 派生），每个 stage 内部绑定一个独立的执行函数，并支持四种运行模式：
+框架的基本单元为 **TaskExecutor**，可独立运行，并支持四种执行模式：
 
 * **线性（serial）**
 * **多线程（thread）**
 * **多进程（process）**
 * **协程（async）**
 
-每个 stage 均可独立运行，也可作为节点互相连接，形成具有上游与下游依赖关系的任务图（**TaskGraph**）。下游 stage 会自动接收上游执行完成的结果作为输入，从而形成明确的数据流。
+TaskExecutor 实现了对任务的结果缓存，任务去重，进度条显示，多执行模式比较等功能，单独使用也很好用。
+
+但除去直接使用 TaskExecutor，更重要的是使用其子类**TaskStage**。TaskStage 可以互相连接，形成具有上游与下游依赖关系的任务图（**TaskGraph**）。下游 stage 会自动接收上游执行完成的结果作为输入，从而形成明确的数据流。
+
+TaskStage 的任务执行模式只有两种：
+
+* **线性（serial）**
+* **多线程（thread）**
 
 在图级别上，每个 Stage 支持两种上下文模式：
 
 * **线性执行（serial layout）**：当前节点执行完毕再启动下一节点（下游节点可提前接收任务但不会立即执行）。
 * **并行执行（process layout）**：当前节点启动后立刻前去启动下一节点。
 
-TaskGraph 能构建完整的 **有向图结构（Directed Graph）**，不仅支持传统的有向无环图（DAG），也能灵活表达 **树形（Tree）**、**环形（loop）** 乃至于 **完全图(Complete Graph)** 形式的任务依赖。
+TaskGraph 能构建完整的 **有向图结构（Directed Graph）**，不仅支持传统的有向无环图（DAG），也能灵活表达 **树形（Tree）**、**环形（loop）** 乃至于 **完全图（Complete Graph）** 形式的任务依赖。
+
+在执行与调度之外，CelestialFlow 进一步引入 **CelestialTree（简称: ctree） 事件追踪系统**，为每一个任务及其衍生行为（成功、失败、重试、拆分、路由等）记录明确的因果关系。借助 ctree，可以从任意一个初始任务出发，完整还原其在 TaskGraph 中的传播路径与执行轨迹，使任务系统可以进行完整的**追溯、分析、解释**。
 
 在此基础上，CelestialFlow 支持 Web 可视化监控，并可通过 Redis 实现跨进程、跨设备协作；同时引入基于 Go 的外部 worker（通过 Redis 通信），用于承载 CPU 密集型任务，弥补 Python 在该场景下的性能瓶颈。
 
@@ -80,30 +90,9 @@ flowchart LR
         S3[TaskStage C]
         S4[TaskStage D]
 
-        T1[Last Stage]
-        T2[Next Stage]
-
-        TS[[TaskSplitter]]
-        TRSI1[/TaskRedisSink/]
-        TRSI2[/TaskRedisSink/]
-        TRSO[/TaskRedisSource/]
-        TRA[/TaskRedisAck/]
-
-        RE1[(Redis)]
-        RE2[(Redis)]
-        G1((GoWorker))
-        G2((GoWorker))
-
         S1 --> S2 --> S3 --> S1
         S1 --> S4
 
-        T1 -->|1 task| TS
-        TS -->|N task| T2
-
-        TRSI1 -.-> RE1 -.->  TRSO
-        TRSI2 -.->|task| RE2 -.->|task| G1
-        G2 -.->|result| RE2 -.->|result| TRA
-
     end
 
     %% 美化 TaskGraph 外框
@@ -114,13 +103,6 @@ flowchart LR
 
     %% 美化 TaskStages
     class S1,S2,S3,S4 blueNode;
-    class T1,T2 blueNode;
-
-    %% 美化 特殊Stage
-    class TS,TRA,TRSI1,TRSI2,TRSO blueNode;
-
-    %% 美化 外部结构
-    class RE1,RE2,G1,G2 blueNode;
 
     %% ===== WebUI =====
     subgraph W[WebUI]
@@ -154,7 +136,7 @@ pip install celestialflow
 一个简单的可运行代码:
 
 ```python
-from celestialflow import TaskManager, TaskGraph
+from celestialflow import TaskStage, TaskGraph
 
 def add(x, y): 
     return x + y
@@ -164,8 +146,8 @@ def square(x):
 
 if __name__ == "__main__":
     # 定义两个任务节点
-    stage1 = TaskManager(add, execution_mode="thread", unpack_task_args=True)
-    stage2 = TaskManager(square, execution_mode="thread")
+    stage1 = TaskStage(add, execution_mode="thread", unpack_task_args=True)
+    stage2 = TaskStage(square, execution_mode="thread")
 
     # 构建任务图结构
     stage1.set_graph_context([stage2], stage_mode="process", stage_name="Adder")
@@ -190,8 +172,9 @@ if __name__ == "__main__":
 
 若你想了解框架的整体结构与核心组件，下面的参考文档会对你有帮助：
 
-- [🔧TaskManage/TaskStage概念](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/reference/task_manage.md)
-- [🌐TaskGrapg概念](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/reference/task_graph.md)
+- [🔧TaskExecutor概念](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/reference/task_executor.md)
+- [🔧TaskStage概念](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/reference/task_stage.md)
+- [🌐TaskGraph概念](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/reference/task_graph.md)
 - [📚Go Worker概念](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/reference/go_worker.md)
 
 推荐阅读顺序:
@@ -200,18 +183,18 @@ if __name__ == "__main__":
 flowchart TD
     classDef whiteNode fill:#ffffff,stroke:#000000,color:#000000;
 
-    TM[TaskManage] --> TG[TaskGraph]
-    TM --> TP[TaskProgress]
+    TM[TaskExecutor.md] --> TS[TaskStage.md] --> TG[TaskGraph.md]
+    TM --> TP[TaskProgress.md]
 
-    TG --> TQ[TaskQueue]
-    TG --> TN[TaskNodes]
-    TG --> TR[TaskReport]
-    TG --> TS[TaskStructure]
+    TG --> TQ[TaskQueue.md]
+    TG --> TN[TaskNodes.md]
+    TG --> TR[TaskReport.md]
+    TG --> TSR[TaskStructure.md]
 
-    TR --> TW[TaskWeb]
-    TN --> GW[Go Worker]
+    TR --> TW[TaskWeb.md]
+    TN --> GW[Go Worker.md]
 
-    class TM,TG,TP,TQ,TN,TR,TS,TW,GW whiteNode;
+    class TM,TG,TP,TQ,TN,TR,TS,TW,GW,TSR whiteNode;
 ```
 
 以下三篇可以作为补充阅读:
@@ -224,42 +207,49 @@ flowchart TD
 
 [📘案例教程](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/tutorial.md)
 
+如果你对3.0.7版本加入的ctree_client与其功能感兴趣, 可以看看这一篇:
+
+[📚CelestialTreeClient](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/reference/ctree_client.md)
+
 ## 环境要求（Requirements）
 
 **CelestialFlow** 基于 Python 3.8+，并依赖以下核心组件。  
 请确保你的环境能够正常安装这些依赖（`pip install celestialflow` 会自动安装）。
 
 | 依赖包           | 说明 |
-| ---------------- | ---- |
-| **Python ≥ 3.8** | 运行环境，建议使用 3.10 及以上版本 |
-| **tqdm**         | 控制台进度条显示，用于任务执行可视化 |
-| **loguru**       | 高性能日志系统，支持多进程安全输出 |
-| **fastapi**      | Web 服务接口框架（用于任务可视化与远程控制） |
-| **uvicorn**      | FastAPI 的高性能 ASGI 服务器 |
-| **requests**     | HTTP 客户端库，用于任务状态上报与远程调用 |
-| **networkx**     | 任务图（TaskGraph）结构与依赖分析 |
-| **redis**        | 可选组件，用于分布式任务通信（`TaskRedis*` 系列模块） |
-| **jinja2**       | FastAPI 模板引擎，用于 Web 可视化界面渲染 |
+| ----------------- | ---- |
+| **Python ≥ 3.8**  | 运行环境，建议使用 3.10 及以上版本 |
+| **tqdm**          | 控制台进度条显示，用于任务执行可视化 |
+| **loguru**        | 高性能日志系统，支持多进程安全输出 |
+| **fastapi**       | Web 服务接口框架（用于任务可视化与远程控制） |
+| **uvicorn**       | FastAPI 的高性能 ASGI 服务器 |
+| **requests**      | HTTP 客户端库，用于任务状态上报与远程调用 |
+| **networkx**      | 任务图（TaskGraph）结构与依赖分析 |
+| **jinja2**        | FastAPI 模板引擎，用于 Web 可视化界面渲染 |
+| **redis**         | 可选组件，用于分布式任务通信（`TaskRedis*` 系列模块） |
+| **celestialtree** | 可选组件，用于任务状态上报与远程调用（`ctree_client`） |
 
 ## 文件结构（File Structure）
 
 ```
-📁 CelestialFlow	(213MB 633KB 545B)
-    📁 docs         	(25KB 183B)
-        📁 reference	(20KB 175B)
+📁 CelestialFlow	(224MB 407KB 500B)
+    📁 docs         	(34KB 944B)
+        📁 reference	(29KB 995B)
+            📝 ctree_client.md  	(6KB 997B)
             📝 go_worker.md     	(6KB 378B)
             📝 task_graph.md    	(4KB 989B)
             📝 task_logging.md  	(0B)
-            📝 task_manage.md   	(7KB 7B)
-            📝 task_nodes.md    	(1KB 737B)
+            📝 task_manage.md   	(7KB 499B)
+            📝 task_nodes.md    	(4KB 68B)
             📝 task_progress.md 	(0B)
             📝 task_queue.md    	(0B)
             📝 task_report.md   	(0B)
+            📝 task_stage.md    	(0B)
             📝 task_structure.md	(112B)
             📝 task_tools.md    	(0B)
             📝 task_types.md    	(0B)
             📝 task_web.md      	(0B)
-        📝 quick_start.md	(5KB 8B)
+        📝 quick_start.md	(4KB 973B)
         📝 tutorial.md   	(0B)
     📁 experiments  	(15KB 111B)
         🐍 benchmark_datastructures.py	(6KB 52B)
@@ -282,64 +272,56 @@ flowchart TD
         📷 logo.png       	(122KB 747B)
         📷 web_display.png	(129KB 545B)
         🎞️ web_ui.gif     	(3MB 635KB 909B)
-    📁 src          	(1MB 920KB 171B)
-        📁 celestialflow         	(1MB 902KB 818B)
-            📁 adapters   	(13KB 837B)
-                📁 celestialtree	(13KB 681B)
-                    📁 [1项排除的目录]	(6KB 960B)
-                    🐍 client.py  	(5KB 486B)
-                    🐍 tools.py   	(1KB 182B)
-                    🐍 __init__.py	(77B)
-                📁 [1项排除的目录]	(156B)
-                🐍 __init__.py	(0B)
-            📁 static     	(1MB 417KB 101B)
-                📁 css	(31KB 410B)
-                    🎨 base.css     	(6KB 155B)
-                    🎨 dashboard.css	(7KB 277B)
-                    🎨 errors.css   	(5KB 168B)
+    📁 src          	(1MB 929KB 111B)
+        📁 celestialflow         	(1MB 911KB 486B)
+            📁 static     	(1MB 417KB 367B)
+                📁 css	(31KB 621B)
+                    🎨 base.css     	(6KB 181B)
+                    🎨 dashboard.css	(7KB 414B)
+                    🎨 errors.css   	(5KB 216B)
                     🎨 inject.css   	(12KB 834B)
-                📁 js 	(33KB 617B)
-                    📜 main.js          	(5KB 77B)
-                    📜 task_errors.js   	(4KB 550B)
-                    📜 task_injection.js	(8KB 491B)
-                    📜 task_statuses.js 	(8KB 63B)
-                    📜 task_structure.js	(4KB 668B)
+                📁 js 	(33KB 672B)
+                    📜 main.js          	(5KB 65B)
+                    📜 task_errors.js   	(4KB 595B)
+                    📜 task_injection.js	(8KB 484B)
+                    📜 task_statuses.js 	(8KB 51B)
+                    📜 task_structure.js	(4KB 709B)
                     📜 task_topology.js 	(1KB 375B)
                     📜 utils.js         	(1KB 441B)
                 ❓ favicon.ico	(1MB 352KB 98B)
-            📁 templates  	(13KB 150B)
-                🌐 index.html	(13KB 150B)
-            📁 [1项排除的目录]	(331KB 149B)
-            🐍 task_graph.py    	(23KB 835B)
-            🐍 task_logging.py  	(8KB 903B)
-            🐍 task_manage.py   	(33KB 577B)
-            🐍 task_nodes.py    	(10KB 922B)
+            📁 templates  	(13KB 174B)
+                🌐 index.html	(13KB 174B)
+            📁 [1项排除的目录]	(339KB 553B)
+            🐍 task_graph.py    	(26KB 700B)
+            🐍 task_logging.py  	(10KB 282B)
+            🐍 task_manage.py   	(36KB 110B)
+            🐍 task_nodes.py    	(10KB 814B)
             🐍 task_progress.py 	(1KB 477B)
-            🐍 task_queue.py    	(8KB 570B)
-            🐍 task_report.py   	(4KB 805B)
-            🐍 task_stage.py    	(5KB 511B)
-            🐍 task_structure.py	(5KB 996B)
-            🐍 task_tools.py    	(15KB 105B)
-            🐍 task_types.py    	(2KB 265B)
-            🐍 task_web.py      	(5KB 693B)
-            🐍 __init__.py      	(1KB 114B)
-        📁 [1项排除的目录]	(17KB 377B)
-    📁 tests        	(126KB 669B)
-        📁 [1项排除的目录]	(90KB 310B)
+            🐍 task_queue.py    	(10KB 948B)
+            🐍 task_report.py   	(4KB 828B)
+            🐍 task_stage.py    	(6KB 577B)
+            🐍 task_structure.py	(7KB 255B)
+            🐍 task_tools.py    	(17KB 19B)
+            🐍 task_types.py    	(2KB 269B)
+            🐍 task_web.py      	(6KB 235B)
+            🐍 __init__.py      	(1KB 22B)
+        📁 [1项排除的目录]	(17KB 649B)
+    📁 tests        	(126KB 724B)
+        📁 [1项排除的目录]	(90KB 464B)
+        🐍 conftest.py      	(49B)
         📝 README.md        	(6KB 324B)
-        🐍 test_graph.py    	(5KB 594B)
+        🐍 test_graph.py    	(5KB 547B)
         🐍 test_manage.py   	(3KB 90B)
-        🐍 test_nodes.py    	(11KB 272B)
-        🐍 test_structure.py	(10KB 103B)
-    📁 [6项排除的目录]	(199MB 931KB 238B)
+        🐍 test_nodes.py    	(11KB 218B)
+        🐍 test_structure.py	(10KB 56B)
+    📁 [6项排除的目录]	(210MB 685KB 450B)
     ❓ .env          	(88B)
     ❓ .gitignore    	(272B)
     ❓ LICENSE       	(1KB 65B)
     ❓ Makefile      	(501B)
-    ❓ pyproject.toml	(1KB 223B)
-    ⚙️ pytest.ini    	(254B)
-    📝 README.md     	(15KB 109B)
-(celestial-flow 3.0.8)
+    ❓ pyproject.toml	(1KB 594B)
+    📝 README.md     	(16KB 3B)
+(celestial-flow 3.0.9)
 ```
 
 (该视图由我的另一个项目[CelestialVault](https://github.com/Mr-xiaotian/CelestialVault)中inst_file.FileTree.print_tree()生成。)
@@ -361,8 +343,17 @@ flowchart TD
 - 3.0.4: 新增一个抽象结构TaskQueue, 用于表示节点的所有"入边"与"出边"; 恢复未消费任务的保存功能
 - 3.0.5: 删除原有的TaskRedisTransfer节点, 并增添三种新的redis交互节点TaskRedisSink TaskRedisSource TaskRedisAck, 用于跨语言 跨进程 跨设备处理任务; 并在Web页面添加展示拓扑信息的卡片
 - 3.0.6: 添加对[CelestialTree](https://github.com/Mr-xiaotian/CelestialTree)系统的支持, 现在可以追踪单个任务的流向
-- 3.0.7: 将TaskStage从TaskManager中单独抽出来作为一个子类; 增加新节点TaskRouter, 可以将传入的任务选择的传给不同的下游节点, 而不是进行广播
-- 3.0.8: 在ctree关系上将"任务重试"后的"任务成功/失败/重试"视为因果关系, 而非之前的并行关系; 重构错误搜集部分逻辑; 修复大量3.0.6与3.07版本引入的bug; 优化部分log表现
+- 3.0.7: 将TaskStage从TaskExecutor中单独抽出来作为一个子类; 增加新节点TaskRouter, 可以将传入的任务选择的传给不同的下游节点, 而不是进行广播
+- 3.0.8: 在ctree逻辑上将"任务重试"事件后的"任务成功/失败/重试"事件视为因果关系, 而非之前的并行关系; 重构错误搜集部分逻辑; 修复大量3.0.6与3.07版本引入的bug; 优化部分log表现
+- 3.0.9: 
+  - 更新前端mermaid显示中部分节点图标; 
+  - 对ctree_client进行匹配CelestialTree的大量修改; 
+  - 将ctree_client移出为单独的project; 
+  - 在前端中添加error_id的显示, 为之后显示provenance_tree做准备; 
+  - 增加大量warning与error, 用于提醒不规范设置; 
+  - 优化前后端中错误数据的传输方式, 在大量错误数据时减少内存消耗; 
+  - 优化TaskLogger中log队列的准入机制; 
+  - 修改部分Bug
 
 ## Star 历史趋势（Star History）
 
@@ -374,6 +365,6 @@ flowchart TD
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
 ## 作者（Author）
-Author: Mr-xiaotian 
-Email: mingxiaomingtian@gmail.com  
+Author: Mr-xiaotian
+Email: mingxiaomingtian@gmail.com
 Project Link: [https://github.com/Mr-xiaotian/CelestialFlow](https://github.com/Mr-xiaotian/CelestialFlow)