celestialflow 3.2.0__tar.gz → 3.2.2__tar.gz

{celestialflow-3.2.0 → celestialflow-3.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: celestialflow
-Version: 3.2.0
+Version: 3.2.2
 Summary: A flexible GRAPH-based task orchestration framework.
 Author-email: Mr-xiaotian <mingxiaomingtian@gmail.com>
 License: MIT
@@ -12,7 +12,7 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Framework :: FastAPI
 Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 Requires-Dist: tqdm
 Requires-Dist: fastapi
@@ -44,7 +44,7 @@ Requires-Dist: celestialtree>=0.1.2
 </p>
 
 <p align="center">
-  <a href="README.md">中文</a> | <a href="docs/en/README.md">English</a> | <a href="docs/ja/README.md">日本語</a>
+  <a href="https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/README.md">中文</a> | <a href="https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/en/README.md">English</a> | <a href="https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/ja/README.md">日本語</a>
 </p>
 
 **CelestialFlow** 是一个轻量级但功能完全的任务流框架，适合需要 **复杂依赖关系**、**灵活执行模型**、**跨设备运行**与**实时可视化监控** 的中/大型 Python 任务系统。
@@ -64,11 +64,10 @@ TaskExecutor 实现了对任务的结果缓存，任务去重，进度条显示
 
 TaskStage 的任务执行模式同样包含三种，与TaskExecutor中一致。
 
-在图级别上，每个 Stage 支持三种上下文模式：
+在图级别上，每个 Stage 支持两种上下文模式：
 
 * **线性执行（serial layout）**：当前节点执行完毕再启动下一节点（下游节点可提前接收任务但不会立即执行）。
 * **线程执行（thread layout）**：当前节点在主进程的独立线程中启动，适合 I/O 密集型任务和不可 pickle 的函数（如 lambda）。
-* **并行执行（process layout）**：当前节点启动后立刻前去启动下一节点。
 
 TaskGraph 能构建完整的 **有向图结构（Directed Graph）**，不仅支持传统的有向无环图（DAG），也能灵活表达 **树形（Tree）**、**环形（loop）** 乃至于 **完全图（Complete Graph）** 形式的任务依赖。
 
@@ -150,8 +149,8 @@ def square(x):
 
 if __name__ == "__main__":
     # 定义两个任务节点
-    stage1 = TaskStage(name="Adder", func=add, execution_mode="thread", unpack_task_args=True, stage_mode="process")
-    stage2 = TaskStage(name="Squarer"func=square, execution_mode="thread", stage_mode="process")
+    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()
@@ -159,7 +158,7 @@ if __name__ == "__main__":
     graph.connect([stage1], [stage2])
 
     # 初始化任务并启动
-    graph.start_graph({stage1.get_tag(): [(1, 2), (3, 4), (5, 6)]})
+    graph.start_graph({stage1.get_name(): [(1, 2), (3, 4), (5, 6)]})
 ```
 
 注意不要在.ipynb中运行。
@@ -213,7 +212,7 @@ flowchart TD
 
 以下三篇可以作为补充阅读:
 
-- [runtime/util_queue.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_queue.md)
+- [runtime/util_hash.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_hash.md)
 - [runtime/util_types.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_types.md)
 - [runtime/util_errors.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_errors.md)
 - [persistence/core_fail.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/persistence/core_fail.md)
@@ -229,24 +228,24 @@ flowchart TD
 
 你可以继续运行更多的演示代码，这里记录了各个演示文件与其中的演示函数说明：
 
-[🎮demo/](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/demo/)
+[🎮demo/](https://github.com/Mr-xiaotian/CelestialFlow/tree/main/docs/zh-CN/demo)
 
 ​如果你想运行测试代码, 可以先查看如下文档内容:
 
-[🧪tests/](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/tests/)
+[🧪tests/](https://github.com/Mr-xiaotian/CelestialFlow/tree/main/docs/zh-CN/tests)
 
 如果你想查看bench内容, 这里的数据成为框架中部分设计的决策依据:
 
-[⚡bench/](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/bench/)
+[⚡bench/](https://github.com/Mr-xiaotian/CelestialFlow/tree/main/docs/zh-CN/bench)
 
 ## 环境要求（Requirements）
 
-**CelestialFlow** 基于 Python 3.10+，并依赖以下核心组件。  
+**CelestialFlow** 基于 Python 3.11+，并依赖以下核心组件。
 请确保你的环境能够正常安装这些依赖（`pip install celestialflow` 会自动安装）。
 
 | 依赖包           | 说明 |
 | ----------------- | ---- |
-| **Python ≥ 3.10**  | 运行环境，建议使用 3.10 及以上版本 |
+| **Python ≥ 3.11**  | 运行环境，建议使用 3.11 及以上版本 |
 | **fastapi**       | Web 服务接口框架（用于任务可视化与远程控制） |
 | **uvicorn**       | FastAPI 的高性能 ASGI 服务器 |
 | **requests**      | HTTP 客户端库，用于任务状态上报与远程调用 |
@@ -261,35 +260,35 @@ flowchart TD
 <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.0</em>
+  <em>celestial-flow 3.2.2</em>
 </p>
 
 (该视图由我的另一个项目[CelestialVault](https://github.com/Mr-xiaotian/CelestialVault)中inst_file.FileTree.print_tree()生成。转换为图片则借助[Carbon](https://carbon.now.sh)。)
 
 ## 版本日志（Version Log）
-- 3.2.0
+- 3.2.2
   - feat:
-    - [Important] 彻底废弃 `stage_mode="process"`, 移除所有 multiprocessing 依赖(MPValue, MPQueue, multiprocessing.Process);
-      - bench_graph_mode 数据表明 process 模式在所有场景下均慢于 thread 模式, 且引入大量序列化开销和 pickle 限制;
-    - [Important] 删除原有set_stages中手动输入的`root_stages`参数, 取而代之为通过scc缩合图计算出的一组`source_stages`
-      - 重补了不少图论课
-    - 将graph/stage/executor的默认log level从`SUCCESS`改为`INFO`, 也就是默认只显示开启关闭信息与错误
-    - 在web页面中添加配置按钮
-      - 当前仅支持设置刷新间隔与历史长度, 之后可以进行更多设置
+    - `core_server` 中添加数据锁, 避免并发访问导致的错误状态
+    - 优化前端设置面板的显示, 现在只显示全局设置与当前页相关设置
+    - 在设置面板中添加全局设置中的 "是否自动更新" 选项与错误日志页面中的 "排序方式" 两项
   - refactor:
-    - 由于stage_mode中取消`process`, 框架中部分为了适配`process`而进行的设计进行删除或者重构  
-      - 例如将所有的MPValue和MPQueue改为int与Queue
-      - 尚未进行严格的bench测试, 但应该会带来一定的性能优化
-    - 重构networkx图的建立过程, 现在直接通过节点与出边进行建立, 不再依赖递归
-    - 在重试检测机制中计算bytes类型的hash, 而非原本的string类型
-      - 根据 bench_hash_memory, 节省内存约23%
-    - 将节点状态中的deltas数据放在web端由js计算, 减少不必要的通信数据
+    - 删除前后端通讯中的 `summary` , 节点的总体预期结束时间由各个节点的 `status` 分别传递, 并由前端计算整体的预期结束时间
+    - 修改 `structure_graph`(原 `structure_json`) 字段的内容, 现在更为简洁, 避免信息冗余, 同时方便后续拓展
   - fix:
-    - 删除InQueue.get中的错误捕获, 这会导致错过panic级error
+    - 修复指标折线图中指标选择失效的问题
+    - 修改 `report.stop` 中_refresh_all的执行顺序, 避免与thread中的刷新冲突
+    - 在 `graph._finalize_nodes` 中添加对thread未终止的防御性检查
+    - 修复 `stage` 中 `start_time` 在未定义前被 `report` 调用的问题
+    - 修复 `TaskRedisTransport._transport` 中使用 `id()` 来计算task_id导致的问题
+    - 修复部分任务无法被hash导致的panic问题
+  - chore:
+    - 删除所有的 `type: ignore`
+      - 好看不少
+    - 在 `start_*` 函数的doc-string中标注该函数为一次性调用函数
 
 更多过往日志可看:
 
-[change_log.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/change_log.md )
+[change_log.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/change_log.md )
 
 ## Star 历史趋势（Star History）
 

{celestialflow-3.2.0 → celestialflow-3.2.2}/README.md

@@ -19,7 +19,7 @@
 </p>
 
 <p align="center">
-  <a href="README.md">中文</a> | <a href="docs/en/README.md">English</a> | <a href="docs/ja/README.md">日本語</a>
+  <a href="https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/README.md">中文</a> | <a href="https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/en/README.md">English</a> | <a href="https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/ja/README.md">日本語</a>
 </p>
 
 **CelestialFlow** 是一个轻量级但功能完全的任务流框架，适合需要 **复杂依赖关系**、**灵活执行模型**、**跨设备运行**与**实时可视化监控** 的中/大型 Python 任务系统。
@@ -39,11 +39,10 @@ TaskExecutor 实现了对任务的结果缓存，任务去重，进度条显示
 
 TaskStage 的任务执行模式同样包含三种，与TaskExecutor中一致。
 
-在图级别上，每个 Stage 支持三种上下文模式：
+在图级别上，每个 Stage 支持两种上下文模式：
 
 * **线性执行（serial layout）**：当前节点执行完毕再启动下一节点（下游节点可提前接收任务但不会立即执行）。
 * **线程执行（thread layout）**：当前节点在主进程的独立线程中启动，适合 I/O 密集型任务和不可 pickle 的函数（如 lambda）。
-* **并行执行（process layout）**：当前节点启动后立刻前去启动下一节点。
 
 TaskGraph 能构建完整的 **有向图结构（Directed Graph）**，不仅支持传统的有向无环图（DAG），也能灵活表达 **树形（Tree）**、**环形（loop）** 乃至于 **完全图（Complete Graph）** 形式的任务依赖。
 
@@ -125,8 +124,8 @@ def square(x):
 
 if __name__ == "__main__":
     # 定义两个任务节点
-    stage1 = TaskStage(name="Adder", func=add, execution_mode="thread", unpack_task_args=True, stage_mode="process")
-    stage2 = TaskStage(name="Squarer"func=square, execution_mode="thread", stage_mode="process")
+    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()
@@ -134,7 +133,7 @@ if __name__ == "__main__":
     graph.connect([stage1], [stage2])
 
     # 初始化任务并启动
-    graph.start_graph({stage1.get_tag(): [(1, 2), (3, 4), (5, 6)]})
+    graph.start_graph({stage1.get_name(): [(1, 2), (3, 4), (5, 6)]})
 ```
 
 注意不要在.ipynb中运行。
@@ -188,7 +187,7 @@ flowchart TD
 
 以下三篇可以作为补充阅读:
 
-- [runtime/util_queue.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_queue.md)
+- [runtime/util_hash.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_hash.md)
 - [runtime/util_types.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_types.md)
 - [runtime/util_errors.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_errors.md)
 - [persistence/core_fail.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/persistence/core_fail.md)
@@ -204,24 +203,24 @@ flowchart TD
 
 你可以继续运行更多的演示代码，这里记录了各个演示文件与其中的演示函数说明：
 
-[🎮demo/](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/demo/)
+[🎮demo/](https://github.com/Mr-xiaotian/CelestialFlow/tree/main/docs/zh-CN/demo)
 
 ​如果你想运行测试代码, 可以先查看如下文档内容:
 
-[🧪tests/](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/tests/)
+[🧪tests/](https://github.com/Mr-xiaotian/CelestialFlow/tree/main/docs/zh-CN/tests)
 
 如果你想查看bench内容, 这里的数据成为框架中部分设计的决策依据:
 
-[⚡bench/](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/bench/)
+[⚡bench/](https://github.com/Mr-xiaotian/CelestialFlow/tree/main/docs/zh-CN/bench)
 
 ## 环境要求（Requirements）
 
-**CelestialFlow** 基于 Python 3.10+，并依赖以下核心组件。  
+**CelestialFlow** 基于 Python 3.11+，并依赖以下核心组件。
 请确保你的环境能够正常安装这些依赖（`pip install celestialflow` 会自动安装）。
 
 | 依赖包           | 说明 |
 | ----------------- | ---- |
-| **Python ≥ 3.10**  | 运行环境，建议使用 3.10 及以上版本 |
+| **Python ≥ 3.11**  | 运行环境，建议使用 3.11 及以上版本 |
 | **fastapi**       | Web 服务接口框架（用于任务可视化与远程控制） |
 | **uvicorn**       | FastAPI 的高性能 ASGI 服务器 |
 | **requests**      | HTTP 客户端库，用于任务状态上报与远程调用 |
@@ -236,35 +235,35 @@ flowchart TD
 <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.0</em>
+  <em>celestial-flow 3.2.2</em>
 </p>
 
 (该视图由我的另一个项目[CelestialVault](https://github.com/Mr-xiaotian/CelestialVault)中inst_file.FileTree.print_tree()生成。转换为图片则借助[Carbon](https://carbon.now.sh)。)
 
 ## 版本日志（Version Log）
-- 3.2.0
+- 3.2.2
   - feat:
-    - [Important] 彻底废弃 `stage_mode="process"`, 移除所有 multiprocessing 依赖(MPValue, MPQueue, multiprocessing.Process);
-      - bench_graph_mode 数据表明 process 模式在所有场景下均慢于 thread 模式, 且引入大量序列化开销和 pickle 限制;
-    - [Important] 删除原有set_stages中手动输入的`root_stages`参数, 取而代之为通过scc缩合图计算出的一组`source_stages`
-      - 重补了不少图论课
-    - 将graph/stage/executor的默认log level从`SUCCESS`改为`INFO`, 也就是默认只显示开启关闭信息与错误
-    - 在web页面中添加配置按钮
-      - 当前仅支持设置刷新间隔与历史长度, 之后可以进行更多设置
+    - `core_server` 中添加数据锁, 避免并发访问导致的错误状态
+    - 优化前端设置面板的显示, 现在只显示全局设置与当前页相关设置
+    - 在设置面板中添加全局设置中的 "是否自动更新" 选项与错误日志页面中的 "排序方式" 两项
   - refactor:
-    - 由于stage_mode中取消`process`, 框架中部分为了适配`process`而进行的设计进行删除或者重构  
-      - 例如将所有的MPValue和MPQueue改为int与Queue
-      - 尚未进行严格的bench测试, 但应该会带来一定的性能优化
-    - 重构networkx图的建立过程, 现在直接通过节点与出边进行建立, 不再依赖递归
-    - 在重试检测机制中计算bytes类型的hash, 而非原本的string类型
-      - 根据 bench_hash_memory, 节省内存约23%
-    - 将节点状态中的deltas数据放在web端由js计算, 减少不必要的通信数据
+    - 删除前后端通讯中的 `summary` , 节点的总体预期结束时间由各个节点的 `status` 分别传递, 并由前端计算整体的预期结束时间
+    - 修改 `structure_graph`(原 `structure_json`) 字段的内容, 现在更为简洁, 避免信息冗余, 同时方便后续拓展
   - fix:
-    - 删除InQueue.get中的错误捕获, 这会导致错过panic级error
+    - 修复指标折线图中指标选择失效的问题
+    - 修改 `report.stop` 中_refresh_all的执行顺序, 避免与thread中的刷新冲突
+    - 在 `graph._finalize_nodes` 中添加对thread未终止的防御性检查
+    - 修复 `stage` 中 `start_time` 在未定义前被 `report` 调用的问题
+    - 修复 `TaskRedisTransport._transport` 中使用 `id()` 来计算task_id导致的问题
+    - 修复部分任务无法被hash导致的panic问题
+  - chore:
+    - 删除所有的 `type: ignore`
+      - 好看不少
+    - 在 `start_*` 函数的doc-string中标注该函数为一次性调用函数
 
 更多过往日志可看:
 
-[change_log.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/change_log.md )
+[change_log.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/change_log.md )
 
 ## Star 历史趋势（Star History）
 

{celestialflow-3.2.0 → celestialflow-3.2.2}/pyproject.toml

@@ -3,14 +3,14 @@ requires = ["setuptools>=61.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
-name = "celestialflow"                   
-version = "3.2.0"
+name = "celestialflow"
+version = "3.2.2"
 description = "A flexible GRAPH-based task orchestration framework."
 readme = "README.md"
 license = { text = "MIT" }
 authors = [{ name = "Mr-xiaotian", email = "mingxiaomingtian@gmail.com" }]
 keywords = ["workflow", "task", "graph", "async", "CelestialFlow"]
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 
 dependencies = [
     "tqdm",
@@ -76,5 +76,40 @@ dev = [
 
 [tool.pyright]
 include = ["src"]
-strict = ["src/celestialflow/runtime", "src/celestialflow/stage", "src/celestialflow/graph", "src/celestialflow/persistence", "src/celestialflow/funnel", "src/celestialflow/observability", "src/celestialflow/utils"]
-stubsPath = "typings"
+ignore = ["tests", "**/tests/**", "typings", "demo", "bench", "experiments", "examples", "temp"]
+
+typeCheckingMode = "strict"
+reportExplicitAny = "none"
+reportAny = "none"
+reportUnannotatedClassAttribute = "none"
+reportUnusedFunction = "none"
+reportImplicitOverride = "none"
+
+[tool.ruff]
+target-version = "py311"
+exclude = ["tests", "typings", "demo", "bench", "experiments", "examples", "temp"]
+
+[tool.ruff.lint]
+select = [
+    "E", "F",      # pycodestyle errors + pyflakes
+    "I",           # isort (import order)
+    "UP",          # pyupgrade
+    "B",           # flake8-bugbear
+    "SIM",         # flake8-simplify
+    "C4",          # flake8-comprehensions
+    "RUF",         # ruff-specific rules
+]
+ignore = [
+    "E501",        # line too long（交给 formatter）
+    "RUF001",      # 字符串内 Unicode 字符（中文内容）
+    "RUF002",      # 中文标点（项目使用中文 docstring）
+    "RUF003",      # 中文注释标点
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+
+[tool.ruff.lint.isort]
+known-first-party = ["celestialflow"]

{celestialflow-3.2.0 → celestialflow-3.2.2}/src/celestialflow/__init__.py

@@ -1,4 +1,9 @@
 # __init__.py
+"""CelestialFlow — 基于图结构的轻量级异步任务编排框架。
+
+提供任务图构建、执行调度、实时监控、Web 可视化和持久化等核心能力。
+"""
+
 from .graph import (
     TaskChain,
     TaskComplete,
@@ -30,30 +35,30 @@ from .utils.util_format import format_table
 from .web import TaskWebServer
 
 __all__ = [
-    "TaskGraph",
+    "BaseObserver",
+    "CallbackObserver",
     "TaskChain",
-    "TaskLoop",
-    "TaskCross",
     "TaskComplete",
-    "TaskWheel",
+    "TaskCross",
+    "TaskExecutor",
+    "TaskGraph",
     "TaskGrid",
-    "BaseObserver",
-    "CallbackObserver",
+    "TaskLoop",
     "TaskProgress",
-    "TaskExecutor",
-    "TaskStage",
-    "TaskSplitter",
-    "TaskRedisTransport",
-    "TaskRedisSource",
     "TaskRedisAck",
+    "TaskRedisSource",
+    "TaskRedisTransport",
     "TaskRouter",
-    "TerminationSignal",
+    "TaskSplitter",
+    "TaskStage",
     "TaskWebServer",
+    "TaskWheel",
+    "TerminationSignal",
+    "benchmark_executor",
+    "benchmark_graph",
+    "format_table",
     "load_jsonl_logs",
-    "load_task_by_stage",
     "load_task_by_error",
+    "load_task_by_stage",
     "make_hashable",
-    "format_table",
-    "benchmark_graph",
-    "benchmark_executor",
 ]

{celestialflow-3.2.0 → celestialflow-3.2.2}/src/celestialflow/funnel/__init__.py

@@ -1,8 +1,8 @@
 # funnel/__init__.py
-from .core_spout import BaseSpout
 from .core_inlet import BaseInlet
+from .core_spout import BaseSpout
 
 __all__ = [
-    "BaseSpout",
     "BaseInlet",
+    "BaseSpout",
 ]

{celestialflow-3.2.0 → celestialflow-3.2.2}/src/celestialflow/funnel/core_inlet.py

@@ -1,22 +1,22 @@
-# funnel/core_inlet.py
-from __future__ import annotations
-
-from typing import Any
-
-
-class BaseInlet:
-    """数据收集器基类，负责将记录通过队列发送到对应的监听器。"""
-
-    def __init__(self, queue: Any) -> None:
-        """初始化收集器
-
-        :param queue: 记录队列
-        """
-        self.queue: Any = queue
-
-    def _funnel(self, record: Any) -> None:
-        """将记录放入队列
-
-        :param record: 待发送的记录
-        """
-        self.queue.put(record)
+# funnel/core_inlet.py
+from __future__ import annotations
+
+from typing import Any
+
+
+class BaseInlet:
+    """数据收集器基类，负责将记录通过队列发送到对应的监听器。"""
+
+    def __init__(self, queue: Any) -> None:
+        """初始化收集器
+
+        :param queue: 记录队列
+        """
+        self.queue: Any = queue
+
+    def _funnel(self, record: Any) -> None:
+        """将记录放入队列
+
+        :param record: 待发送的记录
+        """
+        self.queue.put(record)

{celestialflow-3.2.0 → celestialflow-3.2.2}/src/celestialflow/funnel/core_spout.py

@@ -1,10 +1,12 @@
 # funnel/core_spout.py
 from __future__ import annotations
 
+import traceback
 from queue import Empty, Queue
 from threading import Thread
 from typing import Any
 
+from ..runtime.util_errors import CelestialFlowError
 from ..runtime.util_types import TERMINATION_SIGNAL, TerminationSignal
 
 
@@ -17,12 +19,19 @@ class BaseSpout:
         self._thread: Thread | None = None
 
     def _before_start(self) -> None:
+        """在后台线程启动前调用，子类可覆写以做初始化（如打开文件、清空缓存）。"""
         return None
 
-    def _handle_record(self, record: Any) -> None:
-        raise NotImplementedError
+    def _handle_record(self, _record: Any) -> None:
+        """
+        处理单条队列记录，子类必须覆写。
+
+        :param _record: 队列中取出的记录
+        """
+        raise CelestialFlowError("_handle_record must be implemented by subclasses")
 
     def _after_stop(self) -> None:
+        """在后台线程停止后调用，子类可覆写以做清理（如关闭文件句柄）。"""
         return None
 
     def start(self) -> None:
@@ -33,6 +42,7 @@ class BaseSpout:
             self._thread.start()
 
     def _spout(self) -> None:
+        """后台线程主循环，持续从队列拉取记录并调用 _handle_record，收到终止信号时退出。"""
         while True:
             try:
                 record = self.queue.get(timeout=0.5)
@@ -41,8 +51,9 @@ class BaseSpout:
                 self._handle_record(record)
             except Empty:
                 continue
-            except Exception:  # ← 新增：防止线程崩溃
-                continue  # 或记录到 stderr，至少不丢后续记录
+            except Exception:
+                # 单条记录处理失败不致死线程
+                traceback.print_exc()
 
     def get_queue(self) -> Queue[Any]:
         """获取监听器的输入队列。"""
@@ -54,6 +65,7 @@ class BaseSpout:
             return
 
         self.queue.put(TERMINATION_SIGNAL)
-        self._thread.join()
+        if self._thread.is_alive():
+            self._thread.join(timeout=5)
         self._thread = None
         self._after_stop()

{celestialflow-3.2.0 → celestialflow-3.2.2}/src/celestialflow/graph/__init__.py

@@ -10,11 +10,11 @@ from .core_structure import (
 )
 
 __all__ = [
-    "TaskGraph",
     "TaskChain",
-    "TaskLoop",
-    "TaskCross",
     "TaskComplete",
-    "TaskWheel",
+    "TaskCross",
+    "TaskGraph",
     "TaskGrid",
+    "TaskLoop",
+    "TaskWheel",
 ]