chartflow 0.1__py3-none-any.whl

chartflow/showcase.py

@@ -0,0 +1,528 @@
+"""
+chartflow.showcase — one small but complete multi-page demo.
+
+A single application that tours every chartflow subpackage on its own page,
+unified by the central :mod:`chartflow.theme` dark stylesheet:
+
+    1. 状态机 (fsm)   — a traffic-light Stage you can step through
+    2. 节点图 (node)  — an interactive node-graph canvas
+    3. 流程图 (flow)  — a QFlowChart running a live state machine
+    4. 编辑器 (edit)  — the PythonEditor with syntax highlighting
+    5. IP端口 (ports) — IP-core modules rendered as nodes with QNodePortSpec ports
+
+Run it::
+
+    python -m chartflow.showcase
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+import sys
+from pathlib import Path
+from typing import Optional
+
+from PyQt6.QtCore import Qt, QPointF, QSize, QTimer
+from PyQt6.QtWidgets import (
+    QApplication, QMainWindow, QWidget, QVBoxLayout, QHBoxLayout,
+    QListWidget, QListWidgetItem, QStackedWidget, QLabel,
+    QPushButton, QTextEdit, QFrame,
+)
+
+from chartflow.theme import applyTheme, PALETTE
+from chartflow.fsm import Stage
+from chartflow.node import QNodeCanvas, NodeShape, QNodePortSpec
+from chartflow.node.layout_utils import ViewportFitter
+from chartflow.flow.qchart import QFlowChart
+from chartflow.flow.chart import ChartNode, ChartEdge
+from chartflow.fsm.logic import Logic
+from chartflow.edit import PythonEditor
+
+
+# ---------------------------------------------------------------------------
+# Page 1 — FSM: a hand-stepped traffic-light state machine
+# ---------------------------------------------------------------------------
+class _TrafficLight(Stage):
+    """red -> green -> yellow -> red ..."""
+
+    NAME = "TrafficLight"
+
+    def onChanged(self, src, dst, inst):  # type: ignore[override]
+        # Forward transitions to the bound UI page, if any.
+        cb = getattr(self, "_on_change", None)
+        if cb is not None:
+            cb(src, dst)
+
+    def red(self, inst):     return "green"
+    def green(self, inst):   return "yellow"
+    def yellow(self, inst):  return "red"
+
+
+_LIGHT_COLORS = {"red": "#ff6b6b", "green": "#7ee787", "yellow": "#f0c040"}
+_LIGHT_LABELS = {"red": "红灯 · 停", "green": "绿灯 · 行", "yellow": "黄灯 · 等待"}
+
+
+class FSMPage(QWidget):
+    """Step a Stage state machine and watch it transition."""
+
+    def __init__(self, parent: Optional[QWidget] = None) -> None:
+        super().__init__(parent)
+        self._fsm = _TrafficLight()
+        self._fsm.goto("red")
+        self._fsm._on_change = self._onTransition  # type: ignore[attr-defined]
+
+        root = QVBoxLayout(self)
+        root.setContentsMargins(24, 24, 24, 24)
+        root.setSpacing(16)
+
+        title = QLabel("有限状态机 · chartflow.fsm")
+        title.setStyleSheet(f"font-size: 18px; font-weight: 600; color: {PALETTE.text};")
+        root.addWidget(title)
+        root.addWidget(self._hint("一个 Stage，每个状态返回下一状态名。点击「单步」推进一个 tick。"))
+
+        # The traffic light itself
+        self._lamp = QLabel("红灯 · 停")
+        self._lamp.setAlignment(Qt.AlignmentFlag.AlignCenter)
+        self._lamp.setFixedHeight(120)
+        self._lamp.setStyleSheet(
+            f"background-color: {_LIGHT_COLORS['red']}; color: #1a1a22;"
+            " border-radius: 12px; font-size: 22px; font-weight: 700;"
+        )
+        root.addWidget(self._lamp)
+
+        row = QHBoxLayout()
+        self._btn_step = QPushButton("单步推进")
+        self._btn_step.setObjectName("primary")
+        self._btn_step.setCursor(Qt.CursorShape.PointingHandCursor)
+        self._btn_step.clicked.connect(self._step)
+        self._btn_reset = QPushButton("重置")
+        self._btn_reset.setCursor(Qt.CursorShape.PointingHandCursor)
+        self._btn_reset.clicked.connect(self._reset)
+        row.addWidget(self._btn_step)
+        row.addWidget(self._btn_reset)
+        row.addStretch()
+        root.addLayout(row)
+
+        root.addWidget(self._hint("转换日志（onChanged 回调）："))
+        self._log = QTextEdit()
+        self._log.setReadOnly(True)
+        self._log.setStyleSheet(
+            f"background-color: {PALETTE.code_bg}; color: {PALETTE.code_text};"
+            f" border: 1px solid {PALETTE.border}; border-radius: 9px;"
+            " font-family: 'JetBrains Mono', Consolas, Monaco, monospace; padding: 9px 12px;"
+        )
+        root.addWidget(self._log, stretch=1)
+
+        self._log.append("初始状态: red")
+        self._refresh("red")
+
+    def _step(self) -> None:
+        self._fsm.handleStage(log=False)  # transitions fire onChanged -> _onTransition
+
+    def _reset(self) -> None:
+        self._fsm.goto("red")
+        self._log.clear()
+        self._log.append("初始状态: red")
+        self._refresh("red")
+
+    def _onTransition(self, src, dst) -> None:
+        self._log.append(f"{src} -> {dst}")
+        self._refresh(dst)
+
+    def _refresh(self, state: str) -> None:
+        color = _LIGHT_COLORS.get(state, PALETTE.surface)
+        self._lamp.setText(_LIGHT_LABELS.get(state, state))
+        self._lamp.setStyleSheet(
+            f"background-color: {color}; color: #1a1a22;"
+            " border-radius: 12px; font-size: 22px; font-weight: 700;"
+        )
+
+    @staticmethod
+    def _hint(text: str) -> QLabel:
+        lbl = QLabel(text)
+        lbl.setStyleSheet(f"color: {PALETTE.text_dim}; font-size: 12px;")
+        lbl.setWordWrap(True)
+        return lbl
+
+
+# ---------------------------------------------------------------------------
+# Page 2 — Node canvas: an interactive node graph
+# ---------------------------------------------------------------------------
+class NodePage(QWidget):
+    def __init__(self, parent: Optional[QWidget] = None) -> None:
+        super().__init__(parent)
+
+        root = QVBoxLayout(self)
+        root.setContentsMargins(0, 0, 0, 0)
+        root.setSpacing(0)
+
+        header = QFrame()
+        header.setStyleSheet(f"background-color: {PALETTE.panel}; border: none;"
+                             f" border-bottom: 1px solid {PALETTE.border};")
+        hlay = QVBoxLayout(header)
+        hlay.setContentsMargins(24, 14, 24, 14)
+        hlay.setSpacing(2)
+        title = QLabel("节点图画布 · chartflow.node")
+        title.setStyleSheet(f"font-size: 18px; font-weight: 600; color: {PALETTE.text};")
+        hint = QLabel("拖拽节点 · 从节点边缘拖出连接 · 右键连接切换类型 · 中键/空格/Alt+左键平移 · Alt悬停节点=调整大小光标 · 滚轮缩放")
+        hint.setStyleSheet(f"color: {PALETTE.text_dim}; font-size: 12px;")
+        hlay.addWidget(title)
+        hlay.addWidget(hint)
+        root.addWidget(header)
+
+        self._canvas = QNodeCanvas()
+        root.addWidget(self._canvas, stretch=1)
+        self._seed()
+
+    def _seed(self) -> None:
+        c = self._canvas
+        start = c.addNode("开始", QPointF(0, 0), NodeShape.ELLIPSE)
+        read = c.addNode("读取数据", QPointF(220, -120), NodeShape.RECTANGLE)
+        proc = c.addNode("处理", QPointF(440, 0), NodeShape.RECTANGLE)
+        check = c.addNode("校验?", QPointF(660, 0), NodeShape.DIAMOND)
+        ok = c.addNode("成功", QPointF(880, -120), NodeShape.RECTANGLE)
+        bad = c.addNode("失败", QPointF(880, 120), NodeShape.RECTANGLE)
+        end = c.addNode("结束", QPointF(1100, 0), NodeShape.ELLIPSE)
+
+        c.addConnection(start, read)
+        c.addConnection(read, proc)
+        c.addConnection(proc, check)
+        c.addConnection(check, ok)
+        c.addConnection(check, bad)
+        c.addConnection(ok, end)
+        c.addConnection(bad, read)   # 失败重试
+        c.startNode = start
+
+
+# ---------------------------------------------------------------------------
+# Page 3 — Flow chart: a QFlowChart running a live state machine
+# ---------------------------------------------------------------------------
+class _PipelineLogic(Logic):
+    """A small linear pipeline visualized by QFlowChart."""
+
+    NAME = "PipelineLogic"
+
+    def entry(self, inst):   return "fetch"
+    def fetch(self, inst):   return "parse"
+    def parse(self, inst):   return "validate"
+    def validate(self, inst): return "done"
+    def done(self, inst):    return None   # terminal
+
+
+class FlowPage(QWidget):
+    def __init__(self, parent: Optional[QWidget] = None) -> None:
+        super().__init__(parent)
+
+        root = QVBoxLayout(self)
+        root.setContentsMargins(24, 24, 24, 24)
+        root.setSpacing(12)
+
+        title = QLabel("流程图执行 · chartflow.flow")
+        title.setStyleSheet(f"font-size: 18px; font-weight: 600; color: {PALETTE.text};")
+        root.addWidget(title)
+        root.addWidget(self._hint(
+            "QFlowChart 绑定一个 Stage/Logic，节点与状态一一对应。"
+            "点击「Next Step」单步执行，活跃状态会高亮。"))
+
+        self._chart = QFlowChart(_PipelineLogic(), show_controls=True)
+        # Build the graph that mirrors the logic's states.
+        for nid, name, shape in [
+            ("entry", "Entry", "ellipse"),
+            ("fetch", "Fetch", "rectangle"),
+            ("parse", "Parse", "rectangle"),
+            ("validate", "Validate", "diamond"),
+            ("done", "Done", "ellipse"),
+        ]:
+            self._chart.addNode(ChartNode(nid=nid, name=name, ntype="state", shape=shape))
+        for i, (src, dst) in enumerate(
+            [("entry", "fetch"), ("fetch", "parse"),
+             ("parse", "validate"), ("validate", "done")]
+        ):
+            self._chart.addEdge(ChartEdge(eid=f"e{i}", src=src, dst=dst, etype="flow"))
+        self._chart.startnode = "entry"
+
+        root.addWidget(self._chart, stretch=1)
+
+    @staticmethod
+    def _hint(text: str) -> QLabel:
+        lbl = QLabel(text)
+        lbl.setStyleSheet(f"color: {PALETTE.text_dim}; font-size: 12px;")
+        lbl.setWordWrap(True)
+        return lbl
+
+
+# ---------------------------------------------------------------------------
+# Page 4 — Code editor
+# ---------------------------------------------------------------------------
+_SAMPLE_CODE = '''"""欢迎使用 chartflow.edit 代码编辑器。"""
+
+from chartflow import Stage, Logic, Scheduler
+from chartflow.fsm.decorators import sequence, parallel
+
+
+class Counter(Logic):
+    """一个会数到 3 然后结束的状态机。"""
+
+    NAME = "Counter"
+
+    def entry(self, inst):
+        inst.count = 0
+        return "tick"
+
+    def tick(self, inst):
+        inst.count += 1
+        print(f"tick #{inst.count}")
+        if inst.count >= 3:
+            return "done"
+        return "tick"
+
+    def done(self, inst):
+        print("完成！")
+        return None
+
+
+if __name__ == "__main__":
+    scheduler = Scheduler()
+    Counter()                # 自动注册到调度器
+    for _ in range(10):
+        scheduler.handle()
+'''
+
+
+class EditorPage(QWidget):
+    def __init__(self, parent: Optional[QWidget] = None) -> None:
+        super().__init__(parent)
+
+        root = QVBoxLayout(self)
+        root.setContentsMargins(0, 0, 0, 0)
+        root.setSpacing(0)
+
+        header = QFrame()
+        header.setStyleSheet(f"background-color: {PALETTE.panel}; border: none;"
+                             f" border-bottom: 1px solid {PALETTE.border};")
+        hlay = QVBoxLayout(header)
+        hlay.setContentsMargins(24, 14, 24, 14)
+        hlay.setSpacing(2)
+        title = QLabel("Python 编辑器 · chartflow.edit")
+        title.setStyleSheet(f"font-size: 18px; font-weight: 600; color: {PALETTE.text};")
+        hint = QLabel("语法高亮 · 代码折叠 · 行号 · 小地图 · 自动补全")
+        hint.setStyleSheet(f"color: {PALETTE.text_dim}; font-size: 12px;")
+        hlay.addWidget(title)
+        hlay.addWidget(hint)
+        root.addWidget(header)
+
+        self._editor = PythonEditor()
+        self._editor.set_code(_SAMPLE_CODE)
+        root.addWidget(self._editor, stretch=1)
+
+
+# ---------------------------------------------------------------------------
+# Page 5 — IP-core ports: render .ipc.json modules as nodes with QNodePortSpec
+# ---------------------------------------------------------------------------
+_DATA_DIR = Path(__file__).parent / "showcase_data"
+
+
+def _parse_bit_width(width) -> int:
+    """ipc.json 的 width 字段 → 位宽: null -> 1, '[15:0]' -> 16, '8' -> 8"""
+    if width is None:
+        return 1
+    s = str(width).strip()
+    m = re.match(r"^\[(\d+):(\d+)\]$", s)
+    if m:
+        return max(1, int(m.group(1)) - int(m.group(2)) + 1)
+    try:
+        return max(1, int(float(s)))
+    except ValueError:
+        return 1
+
+
+def _shape_and_size_for_bits(bits: int):
+    """根据位宽选择 dot 的 shape 与 size
+
+    1 bit -> triangle(单线信号); 2~8 bit -> circle; >=9 bit -> trapezoid(总线，
+    尺寸随位宽增长)。
+    """
+    if bits <= 1:
+        return "triangle", 10
+    if bits <= 8:
+        return "circle", 10 + min(bits - 1, 6)
+    return "trapezoid", 10 + math.ceil((bits - 8) / 2)
+
+
+def _ports_from_module(module_list):
+    """把一个 ipc.json 模块的端口列表转成 QNodePortSpec 的 {'left':..., 'right':...}
+
+    规则:
+      - direction output -> right(橙), 其余(input/inout) -> left(绿)
+      - shape/size 由位宽决定
+      - 位宽>1 时 hit = 位宽数字; 位宽==1 时 hit 为空
+      - label = 端口名 + 位宽文本(如 cmp[15:0]); 无位宽时仅为端口名
+    """
+    left, right = [], []
+    for p in module_list:
+        name = p.get("name", "")
+        direction = p.get("direction", "input")
+        width = p.get("width", None)
+        bits = _parse_bit_width(width)
+        shape, size = _shape_and_size_for_bits(bits)
+        hit = str(bits) if bits > 1 else ""
+        width_str = width if (isinstance(width, str) and width) else ""
+        label = f"{name}{width_str}" if width_str else name
+        port = QNodePortSpec(name=name, shape=shape, size=size, hit=hit,
+                         label=label, outline=2)
+        if direction == "output":
+            right.append(port)
+        else:
+            left.append(port)
+    return {"left": left, "right": right}
+
+
+def _load_ipc_module(path: Path):
+    """读取 ipc.json，返回 (节点显示名, 端口列表)"""
+    with open(path, encoding="utf-8") as f:
+        spec = json.load(f)
+    info = spec.get("info", {}) or {}
+    modules = spec.get("modules", {}) or {}
+    mod_name = (info.get("module_final") or info.get("module_initial")
+                or info.get("name") or "")
+    ports_list = modules.get(mod_name)
+    if ports_list is None and modules:
+        ports_list = next(iter(modules.values()))
+    ports_list = ports_list or []
+    display_name = info.get("name") or mod_name or "IP"
+    return display_name, ports_list
+
+
+class PortsPage(QWidget):
+    """读取 showcase_data 下的 .ipc.json，把 IP 核渲染成带端口的节点。"""
+
+    def __init__(self, parent: Optional[QWidget] = None) -> None:
+        super().__init__(parent)
+
+        root = QVBoxLayout(self)
+        root.setContentsMargins(0, 0, 0, 0)
+        root.setSpacing(0)
+
+        header = QFrame()
+        header.setStyleSheet(f"background-color: {PALETTE.panel}; border: none;"
+                             f" border-bottom: 1px solid {PALETTE.border};")
+        hlay = QVBoxLayout(header)
+        hlay.setContentsMargins(24, 14, 24, 14)
+        hlay.setSpacing(2)
+        title = QLabel("IP 核端口 · chartflow.node.QNodePortSpec")
+        title.setStyleSheet(f"font-size: 18px; font-weight: 600; color: {PALETTE.text};")
+        hint = QLabel("读取 .ipc.json · 按位宽选择 dot 形状/尺寸 · 位宽>1 显示在 hit · "
+                      "hover 节点>0.5s 或 hover 端口显示 label · dot hover 时 DodgerBlue 描边")
+        hint.setStyleSheet(f"color: {PALETTE.text_dim}; font-size: 12px;")
+        hlay.addWidget(title)
+        hlay.addWidget(hint)
+        root.addWidget(header)
+
+        self._canvas = QNodeCanvas()
+        # self._canvas.linkables["right->left"] = False
+        root.addWidget(self._canvas, stretch=1)
+        self._seed()
+
+        # 视口就绪后适配显示两个节点
+        QTimer.singleShot(120, self._fit)
+
+    def _seed(self) -> None:
+        files = ["counter-n.ipc.json", "pwmx.ipc.json"]
+        span = 460.0
+        for i, fname in enumerate(files):
+            path = _DATA_DIR / fname
+            if not path.exists():
+                continue
+            display_name, ports_list = _load_ipc_module(path)
+            x = (i - (len(files) - 1) / 2.0) * span
+            node = self._canvas.addNode(display_name, QPointF(x, 0),
+                                        NodeShape.RECTANGLE)
+            node.selfrefs["left->right"] = False
+            node.selfrefs["node->port"] = True
+            node.selfrefs["port->node"] = True
+            node.selfrefs["port->port"] = True
+            node.setFont(size=13)
+            node.ports = _ports_from_module(ports_list)
+
+    def _fit(self) -> None:
+        try:
+            ViewportFitter(self._canvas).fitViewport(margin=60)
+        except Exception:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Shell: sidebar navigation + stacked pages
+# ---------------------------------------------------------------------------
+_PAGES = [
+    ("状态机", "fsm",  FSMPage),
+    ("节点图", "node", NodePage),
+    ("流程图", "flow", FlowPage),
+    ("编辑器", "edit", EditorPage),
+    ("IP端口", "ports", PortsPage),
+]
+
+
+class ShowcaseWindow(QMainWindow):
+    def __init__(self) -> None:
+        super().__init__()
+        self.setWindowTitle("chartflow 全功能演示")
+        self.resize(1240, 820)
+
+        central = QWidget()
+        self.setCentralWidget(central)
+        layout = QHBoxLayout(central)
+        layout.setContentsMargins(0, 0, 0, 0)
+        layout.setSpacing(0)
+
+        # Left navigation
+        self._nav = QListWidget()
+        self._nav.setFixedWidth(190)
+        self._nav.setIconSize(QSize(1, 1))
+        self._nav.setSpacing(2)
+        self._nav.setCurrentRow(0)
+        self._nav.currentRowChanged.connect(self._onNav)
+        layout.addWidget(self._nav)
+
+        # Vertical separator
+        sep = QFrame()
+        sep.setFixedWidth(1)
+        sep.setStyleSheet(f"background-color: {PALETTE.border};")
+        layout.addWidget(sep)
+
+        # Right stacked pages
+        self._stack = QStackedWidget()
+        layout.addWidget(self._stack, stretch=1)
+
+        for label, _key, page_cls in _PAGES:
+            item = QListWidgetItem(label)
+            item.setSizeHint(QSize(0, 44))
+            self._nav.addItem(item)
+            self._stack.addWidget(page_cls())
+
+        self._buildStatus()
+
+    def _buildStatus(self) -> None:
+        bar = self.statusBar()
+        bar.showMessage("就绪 · 在左侧选择一个模块")
+
+    def _onNav(self, row: int) -> None:
+        if 0 <= row < len(_PAGES):
+            label, key, _ = _PAGES[row]
+            self._stack.setCurrentIndex(row)
+            self.statusBar().showMessage(f"当前页面：{label}  ·  chartflow.{key}")
+
+
+def main() -> None:
+    app = QApplication(sys.argv)
+    app.setStyle("Fusion")
+    applyTheme(app)
+    win = ShowcaseWindow()
+    win.show()
+    sys.exit(app.exec())
+
+
+if __name__ == "__main__":
+    main()