chartflow 0.1__py3-none-any.whl

chartflow/fsm/test_stage_spec.py

@@ -0,0 +1,448 @@
+"""
+Stage Execute/Handle 模块规范测试
+验证所有需求文档中的行为
+"""
+
+import pytest
+from chartflow.fsm import Stage
+from chartflow.fsm.decorators import sequence, selector, parallel, behavior
+
+
+class TestBasicExecution:
+    """基础执行流程测试"""
+
+    def test_state_transition_cycle(self):
+        """测试: 所有节点转换必须通过 _execute_state -> _handle -> _transition_to 周期"""
+        events = []
+
+        class TestStage(Stage):
+            NAME = "Test"
+
+            def onChanged(self, src, dst, inst):
+                events.append(("onChanged", src, dst))
+
+            def a(self, inst):
+                return "b"
+
+            def b(self, inst):
+                return True
+
+        stage = TestStage()
+        stage.goto("a")
+        stage.handleStage(log=False)
+
+        assert ("onChanged", "a", "b") in events
+        assert stage.current_state == "b"
+
+    def test_changed_event_only_in_transition_to(self):
+        """测试: changed事件仅在 _transition_to 中触发"""
+        changed_events = []
+        enter_events = []
+
+        class TestStage(Stage):
+            NAME = "Test"
+
+            def setup(self):
+                self.listenFor("changed", lambda e: changed_events.append((e["old"], e["new"])))
+                self.listenFor("enter", lambda e: enter_events.append(e["state"]))
+
+            def a(self, inst):
+                return "b"
+
+            def b(self, inst):
+                return True
+
+        stage = TestStage()
+        stage.setup()
+        stage.goto("a")
+
+        # Tick 1: a 执行并转换到 b —— changed 事件在 _transition_to 中触发
+        stage.handleStage(log=False)
+        assert ("a", "b") in changed_events
+
+        # Tick 2: b 被执行 —— enter 事件在 _execute_state 中触发。
+        # 引擎为每 tick 一个状态：a->b 转换后，b 在下一 tick 才执行并 enter。
+        stage.handleStage(log=False)
+        assert "b" in enter_events
+
+    def test_enter_event_only_in_execute_state(self):
+        """测试: enter事件仅在 _execute_state 中触发"""
+        enter_events = []
+
+        class TestStage(Stage):
+            NAME = "Test"
+
+            def setup(self):
+                self.listenFor("enter", lambda e: enter_events.append(e["state"]))
+
+            def a(self, inst):
+                return True
+
+        stage = TestStage()
+        stage.setup()
+        stage.goto("a")
+        stage.handleStage(log=False)
+
+        assert "a" in enter_events
+
+
+class TestBehaviorTreeEvents:
+    """行为树事件测试"""
+
+    def test_sequence_child_changed_events(self):
+        """测试: Sequence子节点触发changed事件"""
+        changed_events = []
+
+        class SeqStage(Stage):
+            NAME = "Seq"
+
+            def setup(self):
+                self.listenFor("changed", lambda e: changed_events.append((e["old"], e["new"])))
+
+            @sequence("s1", "s2", "s3")
+            def seq(self, inst):
+                return True
+
+            def s1(self, inst): return True
+            def s2(self, inst): return True
+            def s3(self, inst): return True
+
+        stage = SeqStage()
+        stage.setup()
+        stage.goto("seq")
+
+        # 执行多个tick完成序列
+        for _ in range(5):
+            stage.handleStage(log=False)
+
+        # 应该有 seq -> s1, s1 -> s2, s2 -> s3
+        assert ("seq", "s1") in changed_events
+        assert ("s1", "s2") in changed_events
+        assert ("s2", "s3") in changed_events
+
+    def test_selector_child_changed_events(self):
+        """测试: Selector子节点触发changed事件"""
+        changed_events = []
+
+        class SelStage(Stage):
+            NAME = "Sel"
+
+            def setup(self):
+                self.listenFor("changed", lambda e: changed_events.append((e["old"], e["new"])))
+
+            @selector("f1", "f2")
+            def sel(self, inst):
+                return True
+
+            def f1(self, inst): return False
+            def f2(self, inst): return True
+
+        stage = SelStage()
+        stage.setup()
+        stage.goto("sel")
+
+        stage.handleStage(log=False)
+
+        # 应该有 sel -> f1, sel -> f2
+        assert ("sel", "f1") in changed_events
+        assert ("sel", "f2") in changed_events
+
+    def test_parallel_child_changed_events(self):
+        """测试: Parallel子节点触发changed事件"""
+        changed_events = []
+
+        class ParaStage(Stage):
+            NAME = "Para"
+
+            def setup(self):
+                self.listenFor("changed", lambda e: changed_events.append((e["old"], e["new"])))
+
+            @parallel("a", "b")
+            def root(self, inst):
+                return True
+
+            def a(self, inst): return True
+            def b(self, inst): return True
+
+        stage = ParaStage()
+        stage.setup()
+        stage.goto("root")
+
+        stage.handleStage(log=False)
+
+        # 应该有 root -> a, root -> b
+        assert ("root", "a") in changed_events
+        assert ("root", "b") in changed_events
+
+    def test_break_no_duplicate_events(self):
+        """测试: BREAK不产生重复changed事件"""
+        changed_events = []
+
+        class TestStage(Stage):
+            NAME = "Test"
+
+            def setup(self):
+                self.listenFor("changed", lambda e: changed_events.append((e["old"], e["new"])))
+
+            @sequence("a", "b")
+            def seq(self, inst):
+                return True
+
+            def a(self, inst):
+                return "external"  # BREAK
+
+            def b(self, inst): return True
+
+            def external(self, inst):
+                return True
+
+        stage = TestStage()
+        stage.setup()
+        stage.goto("seq")
+
+        stage.handleStage(log=False)
+
+        # 应该只有 a -> external, 没有 seq -> external
+        assert ("a", "external") in changed_events
+        assert ("seq", "external") not in changed_events
+
+
+class TestAsyncSemantics:
+    """异步语义测试（RUN/None）"""
+
+    def test_run_pauses_execution(self):
+        """测试: RUN (None) 暂停执行，下一tick恢复"""
+        call_count = {"a": 0}
+
+        class TestStage(Stage):
+            NAME = "Test"
+
+            @sequence("a", "b")
+            def seq(self, inst):
+                return True
+
+            def a(self, inst):
+                call_count["a"] += 1
+                return None  # RUN
+
+            def b(self, inst):
+                return True
+
+        stage = TestStage()
+        stage.goto("seq")
+
+        # 第一个tick执行a，暂停
+        stage.handleStage(log=False)
+        assert call_count["a"] == 1
+        assert stage.current_state == "a"
+
+        # 第二个tick继续执行a，完成
+        stage.handleStage(log=False)
+        assert call_count["a"] == 2
+
+    def test_behavior_context_preserved_during_run(self):
+        """测试: RUN期间行为树上下文被保留"""
+        class TestStage(Stage):
+            NAME = "Test"
+
+            @sequence("a", "b")
+            def seq(self, inst):
+                return True
+
+            def a(self, inst):
+                return None  # RUN
+
+            def b(self, inst):
+                return True
+
+        stage = TestStage()
+        stage.goto("seq")
+
+        stage.handleStage(log=False)
+
+        # _bhead 和 _bhcontext 应该被保留
+        assert stage._bhead == "seq"
+        assert "seq" in stage._bhcontext
+
+
+class TestNestedBehaviors:
+    """嵌套行为树测试"""
+
+    def test_nested_sequence_events(self):
+        """测试: 嵌套序列正确触发所有事件"""
+        changed_events = []
+
+        class TestStage(Stage):
+            NAME = "Test"
+
+            def setup(self):
+                self.listenFor("changed", lambda e: changed_events.append((e["old"], e["new"])))
+
+            @parallel("worker_a", "worker_b")
+            def root(self, inst):
+                return True
+
+            @sequence("s1", "s2")
+            def worker_a(self, inst):
+                return True
+
+            @sequence("p1", "p2")
+            def worker_b(self, inst):
+                return True
+
+            def s1(self, inst): return True
+            def s2(self, inst): return True
+            def p1(self, inst): return True
+            def p2(self, inst): return True
+
+        stage = TestStage()
+        stage.setup()
+        stage.goto("root")
+
+        # 执行多个tick完成
+        for _ in range(10):
+            stage.handleStage(log=False)
+
+        # 应该有 root -> worker_a, root -> worker_b, worker_a -> s1, worker_b -> p1, 等
+        assert ("root", "worker_a") in changed_events
+        assert ("root", "worker_b") in changed_events
+
+    def test_nested_break_propagation(self):
+        """测试: 嵌套BREAK正确传播，不触发父级事件"""
+        changed_events = []
+
+        class TestStage(Stage):
+            NAME = "Test"
+
+            def setup(self):
+                self.listenFor("changed", lambda e: changed_events.append((e["old"], e["new"])))
+
+            @parallel("inner_a", "inner_b")
+            def outer(self, inst):
+                return True
+
+            @sequence("x", "y")
+            def inner_a(self, inst):
+                return True
+
+            def inner_b(self, inst):
+                return True
+
+            def x(self, inst):
+                return "exit"  # BREAK
+
+            def y(self, inst):
+                return True
+
+            def exit(self, inst):
+                return True
+
+        stage = TestStage()
+        stage.setup()
+        stage.goto("outer")
+
+        stage.handleStage(log=False)
+
+        # 应该只有 x -> exit, 没有 inner_a -> exit, outer -> exit
+        assert ("x", "exit") in changed_events
+        assert ("inner_a", "exit") not in changed_events
+        assert ("outer", "exit") not in changed_events
+
+
+class TestOutputFormat:
+    """输出格式测试"""
+
+    def test_no_duplicate_arrow_on_resume(self, capsys):
+        """测试: 恢复时不重复打印 -> child"""
+        class TestStage(Stage):
+            NAME = "Test"
+            LOG = True
+
+            @sequence("a", "b")
+            def seq(self, inst):
+                return True
+
+            def a(self, inst):
+                return None  # RUN
+
+            def b(self, inst):
+                return True
+
+        stage = TestStage()
+        stage.goto("seq")
+
+        # 第一个tick
+        stage.handleStage(log=True)
+        # 第二个tick（恢复）
+        stage.handleStage(log=True)
+
+        captured = capsys.readouterr()
+        # 应该只有一个 "-> a"
+        assert captured.out.count("-> a") == 1
+
+
+class TestEdgeCases:
+    """边界情况测试"""
+
+    def test_sequence_restart_after_completion(self):
+        """测试: 序列完成后重新进入应该从头开始"""
+        call_order = []
+
+        class TestStage(Stage):
+            NAME = "Test"
+
+            @sequence("a", "b")
+            def seq(self, inst):
+                call_order.append("seq")
+                return True
+
+            def a(self, inst):
+                call_order.append("a")
+                return True
+
+            def b(self, inst):
+                call_order.append("b")
+                return True
+
+        stage = TestStage()
+        stage.goto("seq")
+
+        # 完成第一次执行
+        for _ in range(5):
+            stage.handleStage(log=False)
+
+        assert "a" in call_order
+        assert "b" in call_order
+
+    def test_empty_behavior(self):
+        """测试: 空行为树处理"""
+        class TestStage(Stage):
+            NAME = "Test"
+
+            @sequence()
+            def empty(self, inst):
+                return True
+
+        stage = TestStage()
+        stage.goto("empty")
+        result = stage.handleStage(log=False)
+
+        # 应该正常完成
+        assert result is not None
+
+    def test_unknown_state_in_behavior(self):
+        """测试: 行为树中未知状态在类定义时抛出异常"""
+        with pytest.raises(TypeError):
+            class TestStage(Stage):
+                NAME = "Test"
+
+                @sequence("unknown", "a")
+                def seq(self, inst):
+                    return True
+
+                def a(self, inst):
+                    return True
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

chartflow/fsm/utils.py

@@ -0,0 +1,34 @@
+from efr import EventSystem as _EventSystem
+from efr import EventFramework
+
+__event_system__ = None
+
+
+class EventSystem(_EventSystem):
+    """Extended EventSystem with source filtering support."""
+
+    def pushEvent(self, event, data, *targets, source=None):
+        """
+        Push event with optional source information.
+
+        Args:
+            event: Event name
+            data: Event data dict
+            *targets: Target names
+            source: Source identifier (stored in data)
+        """
+        if source is not None:
+            if not isinstance(data, dict):
+                data = {"_data": data}
+            data = dict(data)
+            data["source"] = source
+        super().pushEvent(event, data, *targets)
+
+
+def GetES():
+    global __event_system__
+    if __event_system__ is None:
+        # Use standalone mode (synchronous) for predictable event handling
+        __event_system__ = EventSystem()
+    return __event_system__
+

chartflow/node/__init__.py

@@ -0,0 +1,66 @@
+"""
+qnode - A generic node graph canvas library based on PyQt6
+
+This library provides a generic node graph canvas widget that can be used
+for various node-based visual editing applications.
+
+Usage:
+    from chartflow.node import NodeCanvas, NodeItem, ConnectionItem
+    
+    canvas = NodeCanvas()
+    node1 = canvas.addNode("Start", QPointF(0, 0))
+    node2 = canvas.addNode("End", QPointF(200, 0))
+    canvas.addConnection(node1, node2)
+"""
+
+from chartflow.node.enums import NodeState, NodeShape, ArrowState, ConnectionType
+from chartflow.node.styles import NodeStyle, ConnectionStyle, ArrowStyle
+from chartflow.node.node_item import QNodeItem
+from chartflow.node.port_item import QNodePort, QNodePortSpec
+from chartflow.node._port_interface import IQNodePort
+from chartflow.node.connection_item import ConnectionItem
+from chartflow.node.arrow_item import ArrowItem
+from chartflow.node.selection_rect import SelectionRect
+from chartflow.node.style_panel import StylePanel
+from chartflow.node.node_canvas import QNodeCanvas
+from chartflow.node.main_window import NodeCanvasWindow
+from chartflow.node.qnode_editor import QNodeEditor
+from chartflow.node.popmenu import (
+    ICanvasPopMenu, QCanvasPopMenu,
+    INodePopMenu, QNodePopMenu,
+    ILinePopMenu, QLinePopMenu,
+)
+
+__version__ = "1.0.0"
+__author__ = "qnode"
+
+__all__ = [
+    # Enums
+    "NodeState",
+    "NodeShape",
+    "ArrowState",
+    "ConnectionType",
+    # Styles
+    "NodeStyle",
+    "ConnectionStyle",
+    "ArrowStyle",
+    # Items
+    "QNodeItem",
+    "QNodePort",
+    "QNodePortSpec",
+    "IQNodePort",
+    "ConnectionItem",
+    "ArrowItem",
+    "SelectionRect",
+    # UI Components
+    "StylePanel",
+    # Canvas and Window
+    "QNodeCanvas",
+    "NodeCanvasWindow",
+    # Editor
+    "QNodeEditor",
+    # Pop Menus
+    "ICanvasPopMenu", "QCanvasPopMenu",
+    "INodePopMenu", "QNodePopMenu",
+    "ILinePopMenu", "QLinePopMenu",
+]