celestialflow 3.2.0__tar.gz → 3.2.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: celestialflow
-Version: 3.2.0
+Version: 3.2.1
 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中运行。
@@ -241,12 +240,12 @@ flowchart TD
 
 ## 环境要求（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,61 @@ 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.1</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.1:
   - 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页面中添加配置按钮
-      - 当前仅支持设置刷新间隔与历史长度, 之后可以进行更多设置
+    - **[Important]** 大幅强化配置按钮功能
+      - 现在可以配置界面语言，并支持中、日、英三语言切换
+      - 可以配置错误日志每页日志条数
+      - 可以配置结构图中是否显示增量，不过现在样式上有点丑
+      - 以及最重要的，可以直接编辑仪表盘页的卡片布局
+      - 另外，所有设置保存成功后会有提示
+    - 折线图中可以选择数据类型
+      - 现在包括"数据累计"、"等待队列"和"数据变化率"
+    - 对 structure 的一些调整
+      - 所有 structure 的参数中添加 `stage_mode`，用于统一控制节点模式
+      - 对 struct 中节点不再重新命名
+    - 在部分 Spout 中增加缓冲机制
   - refactor:
-    - 由于stage_mode中取消`process`, 框架中部分为了适配`process`而进行的设计进行删除或者重构  
-      - 例如将所有的MPValue和MPQueue改为int与Queue
-      - 尚未进行严格的bench测试, 但应该会带来一定的性能优化
-    - 重构networkx图的建立过程, 现在直接通过节点与出边进行建立, 不再依赖递归
-    - 在重试检测机制中计算bytes类型的hash, 而非原本的string类型
-      - 根据 bench_hash_memory, 节省内存约23%
-    - 将节点状态中的deltas数据放在web端由js计算, 减少不必要的通信数据
+    - **[Important]** 删除 executor 中的 `tag` 属性，并全面使用 `name` 属性进行替代
+      - `tag` 的出现是为了适应早期无法区分节点而设计的，但现在 `name` 已经强制唯一性，继续使用冗长的 `tag` 会导致不便
+    - **[Important]** 将 executor 中 `task_queue` 与 `result_queue` 的定义提前到 `__init__` 中
+      - 对于 executor 来说区别不大，但对于 stage 而言这是更理想且优雅的形式，只是由于原先 `stage_mode="process"` 时不允许执行函数内带有 `MPQueue`，所以才使用 graph 中统一定义，然后通过 process 的 args 注入的形式
+    - **[Important]** 重构 `core_server`，将其分解出 `routes/` 与 `util_models`，实现结构优化
+    - 进一步地，将 `log_queue` 和 `fail_queue` 的注入也提前到 `graph.set_stages` 中，实现 `stage.start_stage` 完全无输入参数
+    - 同时在 executor 中添加 `put_task` 与 `put_signal`，并在 graph 中进行复用
+      - 之前不能这样做是因为 stage 中此时还没有定义 queue
+    - 移除 `core_graph` 中的 `StageRuntime`
+    - 将类型标注中的部分 `Any` 改为更明确的类型
+    - 删除 HTML 中的仪表盘部分的 card，现在交给 `web-config` 来定义
+    - 删除部分没必要的前后端通信，优化通信负载
+      - 移除后端传递的节点历史信息，由前端进行维护
+      - 移除总体统计中除"总剩余时间"的后端数据，由前端进行计算
+    - 优化错误存储的 JSONL 数据结构，现在保存更细致的错误信息
+    - 调整 pyright 规则，并实现 pyright 0 error / 0 warning
+    - 给 `web/` 下几乎所有 `.ts` 与 `.css` 文件重命名，并整理文件内容边界
+    - `util_error` 中添加更多错误类型，保证项目中所有主动 raise 的错误都在当前的错误体系下
+    - 删除前端代码中所有的 `onclick`，改用 `data-*` 属性
+    - 清简 `config.json` 中的部分字段
+    - 删除部分不必要的代码
   - fix:
-    - 删除InQueue.get中的错误捕获, 这会导致错过panic级error
+    - 对部分太宽泛的错误捕捉进行收窄
+  - chore:
+    - 添加更多测试代码，并整理 `tests/` 结构
+    - 修复 `bench/` 中的一些问题
+      - 主要是 `bench_execution_mode` 中的两种 Fibonacci 运算量级不同，无法正常进行模型 bench
+    - 添加 `.github/workflows`，实现 CI/CD
+    - 更新支持的 Python 版本为 3.11，以与部分库要求相符
+    - 添加两个 skill，分别用于更新文档与审查项目
 
 更多过往日志可看:
 
-[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.1}/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中运行。
@@ -216,12 +215,12 @@ flowchart TD
 
 ## 环境要求（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,61 @@ 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.1</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.1:
   - 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页面中添加配置按钮
-      - 当前仅支持设置刷新间隔与历史长度, 之后可以进行更多设置
+    - **[Important]** 大幅强化配置按钮功能
+      - 现在可以配置界面语言，并支持中、日、英三语言切换
+      - 可以配置错误日志每页日志条数
+      - 可以配置结构图中是否显示增量，不过现在样式上有点丑
+      - 以及最重要的，可以直接编辑仪表盘页的卡片布局
+      - 另外，所有设置保存成功后会有提示
+    - 折线图中可以选择数据类型
+      - 现在包括"数据累计"、"等待队列"和"数据变化率"
+    - 对 structure 的一些调整
+      - 所有 structure 的参数中添加 `stage_mode`，用于统一控制节点模式
+      - 对 struct 中节点不再重新命名
+    - 在部分 Spout 中增加缓冲机制
   - refactor:
-    - 由于stage_mode中取消`process`, 框架中部分为了适配`process`而进行的设计进行删除或者重构  
-      - 例如将所有的MPValue和MPQueue改为int与Queue
-      - 尚未进行严格的bench测试, 但应该会带来一定的性能优化
-    - 重构networkx图的建立过程, 现在直接通过节点与出边进行建立, 不再依赖递归
-    - 在重试检测机制中计算bytes类型的hash, 而非原本的string类型
-      - 根据 bench_hash_memory, 节省内存约23%
-    - 将节点状态中的deltas数据放在web端由js计算, 减少不必要的通信数据
+    - **[Important]** 删除 executor 中的 `tag` 属性，并全面使用 `name` 属性进行替代
+      - `tag` 的出现是为了适应早期无法区分节点而设计的，但现在 `name` 已经强制唯一性，继续使用冗长的 `tag` 会导致不便
+    - **[Important]** 将 executor 中 `task_queue` 与 `result_queue` 的定义提前到 `__init__` 中
+      - 对于 executor 来说区别不大，但对于 stage 而言这是更理想且优雅的形式，只是由于原先 `stage_mode="process"` 时不允许执行函数内带有 `MPQueue`，所以才使用 graph 中统一定义，然后通过 process 的 args 注入的形式
+    - **[Important]** 重构 `core_server`，将其分解出 `routes/` 与 `util_models`，实现结构优化
+    - 进一步地，将 `log_queue` 和 `fail_queue` 的注入也提前到 `graph.set_stages` 中，实现 `stage.start_stage` 完全无输入参数
+    - 同时在 executor 中添加 `put_task` 与 `put_signal`，并在 graph 中进行复用
+      - 之前不能这样做是因为 stage 中此时还没有定义 queue
+    - 移除 `core_graph` 中的 `StageRuntime`
+    - 将类型标注中的部分 `Any` 改为更明确的类型
+    - 删除 HTML 中的仪表盘部分的 card，现在交给 `web-config` 来定义
+    - 删除部分没必要的前后端通信，优化通信负载
+      - 移除后端传递的节点历史信息，由前端进行维护
+      - 移除总体统计中除"总剩余时间"的后端数据，由前端进行计算
+    - 优化错误存储的 JSONL 数据结构，现在保存更细致的错误信息
+    - 调整 pyright 规则，并实现 pyright 0 error / 0 warning
+    - 给 `web/` 下几乎所有 `.ts` 与 `.css` 文件重命名，并整理文件内容边界
+    - `util_error` 中添加更多错误类型，保证项目中所有主动 raise 的错误都在当前的错误体系下
+    - 删除前端代码中所有的 `onclick`，改用 `data-*` 属性
+    - 清简 `config.json` 中的部分字段
+    - 删除部分不必要的代码
   - fix:
-    - 删除InQueue.get中的错误捕获, 这会导致错过panic级error
+    - 对部分太宽泛的错误捕捉进行收窄
+  - chore:
+    - 添加更多测试代码，并整理 `tests/` 结构
+    - 修复 `bench/` 中的一些问题
+      - 主要是 `bench_execution_mode` 中的两种 Fibonacci 运算量级不同，无法正常进行模型 bench
+    - 添加 `.github/workflows`，实现 CI/CD
+    - 更新支持的 Python 版本为 3.11，以与部分库要求相符
+    - 添加两个 skill，分别用于更新文档与审查项目
 
 更多过往日志可看:
 
-[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.1}/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.1"
 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.1}/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.1}/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.1}/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.1}/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.1}/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",
 ]