chartflow 0.1__py3-none-any.whl

chartflow/node/_node_interface.py

@@ -0,0 +1,426 @@
+"""
+节点项接口契约模块
+
+定义 INodeItem(Protocol) —— 节点项的对外类型契约。
+Protocol 仅用于静态类型检查与文档, 不参与运行时继承(不进入 MRO),
+因此可安全地与 QGraphicsEllipseItem 继承体系并存。
+
+INodeItem 声明了 NodeItem 对外暴露的全部公开属性与方法签名,
+是 _NodeCore 及其子类的"契约说明"。最终具体类 NodeItem 在运行时
+通过多层继承组合 _NodeCore/_NodePortMixin/_NodeInteractionMixin 实现
+该契约, 但并不显式继承 Protocol。
+
+约定: 本模块只含类型声明, 不得有运行时依赖, 以避免循环导入。
+"""
+
+from typing import Any, Dict, Optional, Protocol, runtime_checkable, TYPE_CHECKING
+
+from PyQt6.QtCore import QPointF, pyqtSignal
+from PyQt6.QtGui import QColor, QFont
+
+from chartflow.node.enums import NodeShape, NodeState
+from chartflow.node.styles import NodeStyle
+
+if TYPE_CHECKING:
+    from chartflow.node.port_item import QNodePortSpec
+
+
+@runtime_checkable
+class INodeItem(Protocol):
+    """节点项接口契约
+
+    声明一个节点项应具备的对外属性与方法。具体实现由 _NodeCore 及其
+    Mixin 子类逐层填充, 最终由 NodeItem 组合完成。
+
+    注: Protocol 不参与运行时继承, 实现类无需显式声明 ``class X(INodeItem)``;
+    只要结构(属性/方法签名)匹配即视为满足契约(结构子类型, duck typing)。
+
+    契约按职责分为若干组:
+
+    - **身份与状态**: ``name`` / ``nodeShape`` / ``state`` / ``radius`` / ``center``
+    - **数据与编辑器**: ``data`` / ``editorClass``
+    - **装饰器**: ``decorator``
+    - **端口**: ``ports`` / :meth:`setPorts`
+    - **字体与样式**: ``font`` / ``fontFamily`` / ``fontSize`` / ``strokeWidth`` /
+      ``fillColor`` / ``strokeColor`` / ``isEditingName`` / :meth:`setColor` /
+      :meth:`setBorder` / :meth:`setFont` / :meth:`setRadius` /
+      :meth:`setEdgeIndicatorVisible` / :meth:`isEdgeIndicatorVisible` /
+      :meth:`setConnectable` / :meth:`isConnectable`
+    - **标记与编辑窗口**: :meth:`setStartMarkerVisible` / :meth:`setSingleMarkerVisible` /
+      :meth:`setCustomMarkerVisible` / :meth:`setCustomMarkerStyle` /
+      :meth:`getCustomMarkerStyle` / :meth:`setEditWindowOpen`
+    - **信号**: ``editRequested`` / ``nameChanged``
+    - **几何与序列化**: :meth:`getEdgePoint` / :meth:`toDict` / :meth:`fromDict`
+
+    除 ``center`` / ``data`` / ``font`` 等显式标注只读的属性外, 凡带 setter 的
+    属性均可读可写; 写入即触发对应的重算/重绘(详见各成员文档)。
+
+    所有坐标默认为 **场景坐标(scene coordinate)**, 几何单位为像素。
+    """
+
+    # ---- 身份与状态 ----
+    @property
+    def name(self) -> str:
+        """节点显示名称(可读写)。
+
+        读取返回当前名称; 赋值会更新文本、重新居中并发出
+        :attr:`nameChanged` 信号。空串或纯空白会被忽略。
+        """
+        ...
+
+    @name.setter
+    def name(self, value: str) -> None: ...
+
+    @property
+    def nodeShape(self) -> NodeShape:
+        """节点形状(可读写), 取值见 :class:`~chartflow.node.enums.NodeShape`:
+
+        - ``ELLIPSE`` 椭圆/圆形(强制为宽高相等的标准圆)
+        - ``RECTANGLE`` 圆角矩形
+        - ``DIAMOND`` 菱形
+
+        赋值后若未设置自定义半径, 会按新形状重算尺寸; 切换到圆形时
+        端口会从轴向排布切换为沿侧弧径向排布。
+        """
+        ...
+
+    @nodeShape.setter
+    def nodeShape(self, value: NodeShape) -> None: ...
+
+    @property
+    def state(self) -> NodeState:
+        """节点交互状态(可读写), 取值见
+        :class:`~chartflow.node.enums.NodeState`: ``IDLE`` / ``HOVER`` /
+        ``SELECTED``。状态变化会驱动填充色与描边色的样式切换。
+        """
+        ...
+
+    @state.setter
+    def state(self, value: NodeState) -> None: ...
+
+    @property
+    def radius(self) -> float:
+        """节点半宽(半边长, 可读写)。
+
+        赋值等价于调用 :meth:`setRadius`: 以方形覆盖原尺寸, 小于
+        ``MIN_RADIUS`` 的值会被钳制为 ``MIN_RADIUS``。赋值会重排端口。
+        """
+        ...
+
+    @radius.setter
+    def radius(self, value: float) -> None: ...
+
+    @property
+    def center(self) -> QPointF:
+        """节点中心点的 **场景坐标**(只读), 取自 ``sceneBoundingRect().center()``。"""
+        ...
+
+    # ---- 数据与编辑器 ----
+    @property
+    def data(self) -> Dict[str, Any]:
+        """节点自定义数据字典(只读引用, 内容可改)。
+
+        返回内部 ``_data`` 字典本身而非副本, 调用方可直接增删键值。
+        会被 :meth:`toDict` / :meth:`fromDict` 序列化。
+        """
+        ...
+
+    @property
+    def editorClass(self) -> Optional[type]:
+        """节点编辑器类(可读写)。
+
+        设为某个 ``QWidget`` 子类 ``type`` 时, 双击节点或点击悬浮按钮会
+        通过 :attr:`editRequested` 信号请求由该类创建编辑面板;
+        ``None`` 表示该节点不绑定编辑器。
+        """
+        ...
+
+    @editorClass.setter
+    def editorClass(self, value: Optional[type]) -> None: ...
+
+    # ---- 装饰器 ----
+    @property
+    def decorator(self) -> Optional[str]:
+        """装饰器类型(可读写), 用于以特殊描边色标记节点语义。
+
+        支持 ``'recursive'`` / ``'behavior'`` / ``'sequence'`` /
+        ``'selector'`` / ``'parallel'``; ``None`` 表示无装饰器。
+        赋值后立即重绘以应用对应的边框颜色。
+        """
+        ...
+
+    @decorator.setter
+    def decorator(self, value: Optional[str]) -> None: ...
+
+    # ---- 端口 ----
+    @property
+    def ports(self) -> Dict[str, list]:
+        """端口配置(可读写), 形如 ``{"left": [...], "right": [...]}``。
+
+        仅识别 ``'left'`` 与 ``'right'`` 两个键; 列表元素可为
+        :class:`~chartflow.node.port_item.QNodePortSpec` 或 ``dict``(自动转换)。
+        赋值会重新规范化、重建端口渲染项并重排布局; 赋 ``None`` 清空端口。
+        """
+        ...
+
+    @ports.setter
+    def ports(self, value: Optional[Dict[str, list]]) -> None: ...
+
+    def setPorts(self, value: Optional[Dict[str, list]]) -> None:
+        """设置端口, 等价于直接赋值 ``self.ports = value``。
+
+        Args:
+            value: 端口配置字典, 见 :attr:`ports`; ``None`` 表示清空。
+        """
+        ...
+
+    # ---- 字体与样式 ----
+    @property
+    def font(self) -> QFont:
+        """节点名称文本所用的 :class:`~PyQt6.QtGui.QFont`(只读)。
+
+        如需修改字体请用 :meth:`setFont` —— 它会同步刷新端口文本字号
+        并在未设置自定义半径时按新字号重算节点尺寸。
+        """
+        ...
+
+    @property
+    def fontFamily(self) -> str:
+        """当前字体家族名(只读)。"""
+        ...
+
+    @property
+    def fontSize(self) -> int:
+        """当前字体点距大小 pointSize(只读)。"""
+        ...
+
+    @property
+    def strokeWidth(self) -> float:
+        """当前描边宽度(只读)。"""
+        ...
+
+    @property
+    def fillColor(self) -> QColor:
+        """当前 IDLE 填充色(只读)。通过 :meth:`setColor` 修改。"""
+        ...
+
+    @property
+    def strokeColor(self) -> QColor:
+        """当前 IDLE 描边色(只读)。通过 :meth:`setBorder` 修改。"""
+        ...
+
+    @property
+    def isEditingName(self) -> bool:
+        """是否正处于名称原位编辑状态(只读)。"""
+        ...
+
+    def setColor(self, color: QColor) -> None:
+        """设置节点填充色。
+
+        会写入自定义填充色并立即重绘; 该颜色会被 :meth:`toDict` 序列化、
+        由 :meth:`fromDict` 还原。
+
+        Args:
+            color: 新的填充色。
+        """
+        ...
+
+    def setBorder(self, width: int = 1, color: QColor = None) -> None:
+        """设置描边宽度与颜色。
+
+        Args:
+            width: 描边宽度, ``<= 0`` 表示移除描边(NoPen)。
+            color: 描边颜色, ``None`` 表示沿用默认/已有颜色。设为非 ``None``
+                时会同时作为选中态描边色。
+        """
+        ...
+
+    def setFont(self, family: str = None, size: int = None) -> None:
+        """设置节点文本字体家族与字号。
+
+        两个参数均可单独提供(只改其一); 字体变化后会重新居中文字、
+        刷新端口文本字号, 并在未设置自定义半径时重算节点尺寸。
+
+        Args:
+            family: 字体家族名, ``None`` 表示不改变。
+            size: 字体 pointSize, ``None`` 或 ``<= 0`` 表示不改变。
+        """
+        ...
+
+    def setRadius(self, radius: float) -> None:
+        """设置节点半径(以方形覆盖原尺寸)并重排端口。
+
+        Args:
+            radius: 新的半径值(半边长); 小于 ``MIN_RADIUS`` 时钳制为 ``MIN_RADIUS``。
+        """
+        ...
+
+    def setEdgeIndicatorVisible(self, visible: bool) -> None:
+        """设置节点外环(可连线边缘指示器)是否显示。
+
+        外环是绘制在节点边缘、提示可从此处拖拽创建连线的浅灰色环。
+        关闭后仅停止绘制, 边缘的连线命中判定(``node_canvas._is_on_node_edge``)
+        不受影响。该状态会被 :meth:`toDict` / :meth:`fromDict` 序列化。
+
+        Args:
+            visible: ``True`` 显示外环, ``False`` 隐藏。
+        """
+        ...
+
+    def isEdgeIndicatorVisible(self) -> bool:
+        """查询节点外环(可连线边缘指示器)当前是否显示。
+
+        Returns:
+            ``True`` 表示显示中, ``False`` 表示已隐藏。
+        """
+        ...
+
+    def setConnectable(self, connectable: bool) -> None:
+        """设置节点是否可参与连线。
+
+        设为 ``False`` 时:
+        - 清除该节点已有的全部连线(两端任一为本节点即删除);
+        - 软联动隐藏外环(此后用户仍可单独调用
+          :meth:`setEdgeIndicatorVisible` 重新开启, 不会被强制覆盖);
+        - 后续任何新建连线(边缘拖拽 / 箭头重连 / 导入)只要涉及本节点,
+          都会被 ``NodeCanvas.addConnection`` 拒绝。
+
+        设为 ``True`` 时仅恢复连线能力, 不重建已删连线, 也不自动恢复外环。
+        该状态会被 :meth:`toDict` / :meth:`fromDict` 以及
+        ``NodeCanvas.importData`` 序列化。
+
+        Args:
+            connectable: ``True`` 允许参与连线, ``False`` 禁止并清除已有连线。
+        """
+        ...
+
+    def isConnectable(self) -> bool:
+        """查询节点当前是否可参与连线。
+
+        Returns:
+            ``True`` 可参与连线(默认), ``False`` 已被禁止。
+        """
+        ...
+
+    # ---- 标记与编辑窗口 ----
+    def setStartMarkerVisible(self, visible: bool) -> None:
+        """显示或隐藏「起点(Start)」标记, 带淡入/淡出动画。
+
+        Args:
+            visible: ``True`` 显示, ``False`` 隐藏。
+        """
+        ...
+
+    def setSingleMarkerVisible(self, visible: bool) -> None:
+        """显示或隐藏「Single」标记, 带淡入/淡出动画。
+
+        Args:
+            visible: ``True`` 显示, ``False`` 隐藏。
+        """
+        ...
+
+    def setCustomMarkerVisible(self, visible: bool) -> None:
+        """显示或隐藏「Custom」自定义标记, 带淡入/淡出动画。
+
+        若标记尚未创建, 显示时会自动创建一个默认样式的 CustomMarker。
+
+        Args:
+            visible: ``True`` 显示, ``False`` 隐藏。
+        """
+        ...
+
+    def setCustomMarkerStyle(
+        self,
+        text: str = None,
+        bg_color: QColor = None,
+        fg_color: QColor = None,
+        border_color: QColor = None,
+        border_width: float = None,
+        radius: float = None,
+    ) -> None:
+        """配置「Custom」自定义标记的样式。
+
+        仅传入非 ``None`` 的参数会覆盖对应字段, 其余保持不变;
+        若标记尚未创建, 会先按这些参数创建一个 CustomMarker。
+
+        Args:
+            text: 显示的文本字符。
+            bg_color: 背景色。
+            fg_color: 前景(文本)色。
+            border_color: 边框色。
+            border_width: 边框厚度。
+            radius: 标记外接半径。
+        """
+        ...
+
+    def getCustomMarkerStyle(self) -> dict:
+        """获取「Custom」标记的当前样式配置。
+
+        Returns:
+            样式字典(text/bg_color/fg_color/border_color/border_width/radius);
+            若标记尚未创建则返回空字典 ``{}``。
+        """
+        ...
+
+    def setEditWindowOpen(self, open: bool) -> None:
+        """切换编辑窗口打开状态, 进而控制悬浮编辑按钮的显示。
+
+        设为打开时立即显示悬浮按钮(带淡入); 关闭时淡出隐藏。
+
+        Args:
+            open: ``True`` 表示编辑窗口已打开(显示按钮), ``False`` 关闭。
+        """
+        ...
+
+    # ---- 信号(只读属性, 返回 pyqtSignal) ----
+    @property
+    def editRequested(self) -> pyqtSignal:
+        """编辑请求信号(只读)。
+
+        双击节点或点击悬浮按钮时发射, 载荷为本节点实例本身; 供宿主
+        (如画布/窗口)据此弹出 ``editorClass`` 对应的编辑面板。
+        """
+        ...
+
+    @property
+    def nameChanged(self) -> pyqtSignal:
+        """名称变更信号(只读)。名称被修改时发射。"""
+        ...
+
+    # ---- 几何与序列化 ----
+    def getEdgePoint(self, target_pos: QPointF) -> QPointF:
+        """计算从节点中心指向 ``target_pos`` 方向、落在节点外轮廓上的交点。
+
+        依据当前 :attr:`nodeShape` 采用不同算法: 圆形用三角函数、
+        圆角矩形先求外接矩形交点再修正圆角、菱形用 L1 范数缩放。
+
+        Args:
+            target_pos: 目标位置(场景坐标)。
+
+        Returns:
+            边缘交点(场景坐标)。退化为重合时返回节点中心。
+        """
+        ...
+
+    def toDict(self) -> dict:
+        """将节点序列化为可持久化的字典。
+
+        包含字段: ``id`` / ``name`` / ``shape`` / ``position`` / ``data``;
+        若存在自定义样式、custom 标记配置或端口配置, 会分别追加
+        ``style`` / ``custom`` / ``ports`` 键。
+
+        Returns:
+            节点数据字典(深拷贝, 修改返回值不影响节点)。
+        """
+        ...
+
+    def fromDict(self, data: dict) -> None:
+        """从字典恢复/更新节点状态(增量合并, 忽略未知键)。
+
+        可识别的键与 :meth:`toDict` 一致; 样式应用完成后会重新排布端口。
+        传入的 ``data`` 缺失的键不会被清空。
+
+        Args:
+            data: 由 :meth:`toDict` 产生(或同构)的字典。
+        """
+        ...