nodeeditor-qtpy 0.8.1__py3-none-any.whl

nodeeditor/__init__.py

@@ -0,0 +1,93 @@
+# -*- coding: utf-8 -*-
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _dist_version
+
+__name__ = 'Node Editor'
+__author__ = 'Azad Kshitij'
+
+try:
+    __version__ = _dist_version("nodeeditor-qtpy")
+except PackageNotFoundError:  # running from a source checkout
+    __version__ = "0.8.1"
+
+
+_QT_API_NAME, _QT_API_VERSION = None, None
+
+if _QT_API_NAME is None:
+    try:
+        from PyQt5.QtCore import PYQT_VERSION_STR  # type: ignore
+        _QT_API_NAME, _QT_API_VERSION = "pyqt5", PYQT_VERSION_STR
+    except ImportError:
+        pass
+
+if _QT_API_NAME is None:
+    try:
+        from PySide2 import __version__  # type: ignore
+        _QT_API_NAME, _QT_API_VERSION = "pyside2", __version__
+    except ImportError:
+        pass
+
+if _QT_API_NAME is None:
+    try:
+        from PyQt6.QtCore import PYQT_VERSION_STR
+        _QT_API_NAME, _QT_API_VERSION = "pyqt6", PYQT_VERSION_STR
+    except ImportError:
+        pass
+
+if _QT_API_NAME is None:
+    try:
+        from PySide6 import __version__  # type: ignore
+        _QT_API_NAME, _QT_API_VERSION = "pyside6", __version__
+    except ImportError:
+        pass
+
+if _QT_API_NAME is None:
+    raise ImportError(
+        "No Qt binding found. Install nodeeditor-qtpy with one, e.g. "
+        "'pip install nodeeditor-qtpy[pyqt6]' or "
+        "'pip install nodeeditor-qtpy[pyside6]', "
+        "or install PyQt5/PySide2/PyQt6/PySide6 directly."
+    )
+
+# Export color configuration classes for easier access
+from nodeeditor.node_colors_config import (
+    NodeEditorColorScheme,
+    EdgeColors,
+    SocketColors,
+    get_color_scheme,
+)
+
+# Export the socket shape system for easier access
+from nodeeditor.node_socket_shapes import (
+    SocketShape,
+    SocketShapeContext,
+    CircleShape,
+    SquareShape,
+    TriangleShape,
+    ChevronShape,
+    register_socket_shape,
+    get_socket_shape,
+    SOCKET_SHAPES,
+)
+
+# Export the graph algorithm exception
+from nodeeditor.node_graph import GraphCycleError
+
+
+__all__ = [
+    "NodeEditorColorScheme",
+    "EdgeColors",
+    "SocketColors",
+    "get_color_scheme",
+    "SocketShape",
+    "SocketShapeContext",
+    "CircleShape",
+    "SquareShape",
+    "TriangleShape",
+    "ChevronShape",
+    "register_socket_shape",
+    "get_socket_shape",
+    "SOCKET_SHAPES",
+    "GraphCycleError",
+]

nodeeditor/node_colors_config.py

@@ -0,0 +1,343 @@
+# -*- coding: utf-8 -*-
+"""
+A module for centralized color configuration for the Node Editor.
+
+This module provides a single point to manage and update all colors used in:
+- Edge graphics (default, selected, hovered, dragging)
+- Socket graphics (background colors per type, highlighting, outlines)
+"""
+
+from qtpy.QtGui import QColor
+from typing import Dict, List
+
+
+class BaseColors:
+    """Base class for color configurations
+    _Parameters:
+        - **_default**: Default color
+        - **_selected**: Selected color
+        - **_hovered**: Hovered color
+        - **_dragging**: Dragging color
+    """
+    def __init__(self):
+        """Initialize default colors
+        """
+        self._default: QColor = QColor("#B08848")
+        self._selected: QColor = QColor("#00ff00")
+        self._hovered: QColor = QColor("#FF37A6FF")
+        self._dragging: QColor = QColor("#333334")
+
+    @property
+    def default(self) -> QColor:
+        """Get default edge color"""
+        return QColor(self._default)
+
+    @default.setter
+    def default(self, color):
+        """Set default edge color"""
+        self._default = self._parse_color(color)
+
+    @property
+    def selected(self) -> QColor:
+        """Get selected edge color"""
+        return QColor(self._selected)
+
+    @selected.setter
+    def selected(self, color):
+        """Set selected edge color"""
+        self._selected = self._parse_color(color)
+
+    @property
+    def hovered(self) -> QColor:
+        """Get hovered edge color"""
+        return QColor(self._hovered)
+
+    @hovered.setter
+    def hovered(self, color):
+        """Set hovered edge color"""
+        self._hovered = self._parse_color(color)
+
+    @staticmethod
+    def _parse_color(color) -> QColor:
+        """Parse color from various formats to QColor"""
+        if isinstance(color, QColor):
+            return QColor(color)
+        elif isinstance(color, str):
+            return QColor(color)
+        elif isinstance(color, tuple) and len(color) >= 3:
+            # RGB or RGBA tuple
+            return QColor(*color)
+        else:
+            raise ValueError(f"Invalid color format: {color}")
+
+
+class EdgeColors(BaseColors):
+    """Configuration for Edge colors"""
+
+    def __init__(self):
+        """Initialize default edge colors"""
+        self._default = QColor("#B08848")
+        self._selected = QColor("#ff00d0")
+        self._hovered = QColor("#FF37A6FF")
+        self._dragging = QColor("#333334")
+
+    @property
+    def default(self) -> QColor:
+        """Get default edge color"""
+        return QColor(self._default)
+
+    @default.setter
+    def default(self, color):
+        """Set default edge color"""
+        self._default = self._parse_color(color)
+
+    @property
+    def selected(self) -> QColor:
+        """Get selected edge color"""
+        return QColor(self._selected)
+
+    @selected.setter
+    def selected(self, color):
+        """Set selected edge color"""
+        self._selected = self._parse_color(color)
+
+    @property
+    def hovered(self) -> QColor:
+        """Get hovered edge color"""
+        return QColor(self._hovered)
+
+    @hovered.setter
+    def hovered(self, color):
+        """Set hovered edge color"""
+        self._hovered = self._parse_color(color)
+
+    @property
+    def dragging(self) -> QColor:
+        """Get dragging edge color"""
+        return QColor(self._dragging)
+
+    @dragging.setter
+    def dragging(self, color):
+        """Set dragging edge color"""
+        self._dragging = self._parse_color(color)
+
+    def set_all(self, default=None, selected=None, hovered=None, dragging=None):
+        """Set all edge colors at once
+
+        :param default: Default edge color
+        :param selected: Selected edge color
+        :param hovered: Hovered edge color
+        :param dragging: Dragging edge color
+        """
+        if default is not None:
+            self.default = default
+        if selected is not None:
+            self.selected = selected
+        if hovered is not None:
+            self.hovered = hovered
+        if dragging is not None:
+            self.dragging = dragging
+
+
+class SocketColors(BaseColors):
+    """Configuration for Socket colors"""
+
+    def __init__(self):
+        """Initialize default socket colors"""
+        self._socket_type_colors = [
+            QColor("#FFFF7700"),  # Orange
+            QColor("#FF52e220"),  # Green
+            QColor("#FF0056a6"),  # Blue
+            QColor("#FFa86db1"),  # Purple
+            QColor("#FFb54747"),  # Red
+            QColor("#FFdbe220"),  # Yellow
+            QColor("#FF888888"),  # Gray
+            QColor("#FFFF7700"),  # Orange (duplicate)
+            QColor("#FF52e220"),  # Green (duplicate)
+            QColor("#FF0056a6"),  # Blue (duplicate)
+            QColor("#FFa86db1"),  # Purple (duplicate)
+            QColor("#FFb54747"),  # Red (duplicate)
+            QColor("#FFdbe220"),  # Yellow (duplicate)
+            QColor("#FF888888"),  # Gray (duplicate)
+        ]
+        self._outline = QColor("#FF000000")
+        self._highlight = QColor("#FF37A6FF")
+
+    @property
+    def outline(self) -> QColor:
+        """Get socket outline color"""
+        return QColor(self._outline)
+
+    @outline.setter
+    def outline(self, color):
+        """Set socket outline color"""
+        self._outline = self._parse_color(color)
+
+    @property
+    def highlight(self) -> QColor:
+        """Get socket highlight color"""
+        return QColor(self._highlight)
+
+    @highlight.setter
+    def highlight(self, color):
+        """Set socket highlight color"""
+        self._highlight = self._parse_color(color)
+
+    def get_type_color(self, socket_type: int) -> QColor:
+        """Get color for a specific socket type
+
+        :param socket_type: Socket type index
+        :return: QColor for the socket type
+        """
+        if isinstance(socket_type, int):
+            return QColor(self._socket_type_colors[socket_type % len(self._socket_type_colors)])
+        elif isinstance(socket_type, str):
+            return QColor(socket_type)
+        return QColor(0, 0, 0, 0)
+
+    def set_type_color(self, socket_type: int, color):
+        """Set color for a specific socket type
+
+        :param socket_type: Socket type index
+        :param color: Color to set
+        """
+        self._socket_type_colors[socket_type] = self._parse_color(color)
+
+    def set_type_colors(self, colors: List) -> None:
+        """Set all socket type colors at once
+
+        :param colors: List of colors
+        """
+        self._socket_type_colors = [self._parse_color(c) for c in colors]
+
+    def get_all_type_colors(self) -> List[QColor]:
+        """Get all socket type colors
+
+        :return: List of QColor objects
+        """
+        return [QColor(c) for c in self._socket_type_colors]
+
+    def set_all(self, outline=None, highlight=None, type_colors=None):
+        """Set all socket colors at once
+
+        :param outline: Socket outline color
+        :param highlight: Socket highlight color
+        :param type_colors: List of socket type colors
+        """
+        if outline is not None:
+            self.outline = outline
+        if highlight is not None:
+            self.highlight = highlight
+        if type_colors is not None:
+            self.set_type_colors(type_colors)
+
+class NodesColors(BaseColors):
+    """Configuration for Node colors
+
+    This class reuses the EdgeColors structure to define colors for nodes.
+    """
+
+    def __init__(self):
+        """Initialize default node colors"""
+        super().__init__()
+
+
+class NodeEditorColorScheme:
+    """Global color scheme configuration for Node Editor
+
+    This class provides a centralized way to manage and update all colors
+    used in the node editor, including edge colors and socket colors.
+
+    Example:
+        >>> scheme = NodeEditorColorScheme()
+        >>> scheme.edges.default = "#FF0000"  # Red edges
+        >>> scheme.sockets.highlight = "#00FF00"  # Green highlights
+    """
+
+    _instance = None
+
+    def __new__(cls):
+        """Singleton pattern - ensure only one instance exists"""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self):
+        """Initialize color scheme (only once)"""
+        if self._initialized:
+            return
+
+        self.edges = EdgeColors()
+        self.sockets = SocketColors()
+        self.nodes = NodesColors()  # Reusing EdgeColors for node colors
+        self._initialized = True
+
+    @classmethod
+    def get_instance(cls) -> 'NodeEditorColorScheme':
+        """Get the singleton instance of the color scheme
+
+        :return: NodeEditorColorScheme instance
+        """
+        return cls()
+
+    def reset_to_defaults(self):
+        """Reset all colors to their default values"""
+        self.edges = EdgeColors()
+        self.sockets = SocketColors()
+        self.nodes = NodesColors()
+
+    def to_dict(self) -> Dict:
+        """Export current color scheme to dictionary
+
+        :return: Dictionary representation of the color scheme
+        """
+        return {
+            'edges': {
+                'default': self.edges.default.name(),
+                'selected': self.edges.selected.name(),
+                'hovered': self.edges.hovered.name(),
+                'dragging': self.edges.dragging.name(),
+            },
+            'sockets': {
+                'outline': self.sockets.outline.name(),
+                'highlight': self.sockets.highlight.name(),
+                'type_colors': [c.name() for c in self.sockets.get_all_type_colors()],
+            }
+        }
+
+    def from_dict(self, config: Dict):
+        """Import color scheme from dictionary
+
+        :param config: Dictionary with color configuration
+        """
+        if 'edges' in config:
+            edge_config = config['edges']
+            self.edges.set_all(
+                default=edge_config.get('default'),
+                selected=edge_config.get('selected'),
+                hovered=edge_config.get('hovered'),
+                dragging=edge_config.get('dragging')
+            )
+
+        if 'sockets' in config:
+            socket_config = config['sockets']
+            self.sockets.set_all(
+                outline=socket_config.get('outline'),
+                highlight=socket_config.get('highlight'),
+                type_colors=socket_config.get('type_colors')
+            )
+
+# Global singleton instance
+_global_scheme = None
+
+
+def get_color_scheme() -> NodeEditorColorScheme:
+    """Get the global color scheme instance
+
+    :return: NodeEditorColorScheme instance
+    """
+    global _global_scheme
+    if _global_scheme is None:
+        _global_scheme = NodeEditorColorScheme()
+    return _global_scheme

nodeeditor/node_content_widget.py

@@ -0,0 +1,129 @@
+# -*- coding: utf-8 -*-
+"""A module containing the base class for the Node's content graphical representation. It also contains an example of
+an overridden Text Widget, which can pass a notification to it's parent about being modified."""
+from collections import OrderedDict
+from nodeeditor.node_serializable import Serializable
+from qtpy.QtWidgets import QWidget, QLabel, QVBoxLayout, QTextEdit
+from qtpy.QtGui import QFocusEvent
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from nodeeditor.node_node import Node
+
+
+class QDMNodeContentWidget(QWidget, Serializable):
+    """Base class for representation of the Node's graphics content. This class also provides layout
+    for other widgets inside of a :py:class:`~nodeeditor.node_node.Node`"""
+
+    def __init__(self, node: 'Node', parent: QWidget = None) -> None:
+        """
+        :param node: reference to the :py:class:`~nodeeditor.node_node.Node`
+        :type node: :py:class:`~nodeeditor.node_node.Node`
+        :param parent: parent widget
+        :type parent: QWidget
+
+        :Instance Attributes:
+            - **node** - reference to the :class:`~nodeeditor.node_node.Node`
+            - **layout** - ``QLayout`` container
+        """
+        self.node = node
+        super().__init__(parent)
+
+        self.initUI()
+
+    def initUI(self) -> None:
+        """Sets up layouts and widgets to be rendered in :py:class:`~nodeeditor.node_graphics_node.QDMGraphicsNode` class.
+        """
+        self.layout = QVBoxLayout()
+        self.layout.setContentsMargins(0, 0, 0, 0)
+        self.setLayout(self.layout)
+
+        self.wdg_label = QLabel("Some Title")
+        self.layout.addWidget(self.wdg_label)
+        self.layout.addWidget(QDMTextEdit("foo"))
+
+    def setEditingFlag(self, value: bool) -> None:
+        """
+        .. note::
+
+            If you are handling keyPress events by default Qt Window's shortcuts and ``QActions``, you will not
+             need to use this method.
+
+        Helper function which sets editingFlag inside :py:class:`~nodeeditor.node_graphics_view.QDMGraphicsView` class.
+
+        This is a helper function to handle keys inside nodes with ``QLineEdits`` or ``QTextEdits`` (you can
+        use overridden :py:class:`QDMTextEdit` class) and with QGraphicsView class method ``keyPressEvent``.
+
+        :param value: new value for editing flag
+        """
+        self.node.scene.getView().editingFlag = value
+
+    def serialize(self) -> OrderedDict:
+        """Serialization method to serialize this class data into ``OrderedDict``.
+
+        The content widget holds no state of its own, so there is nothing to store.
+
+        :return: data serialized in ``OrderedDict``
+        :rtype: ``OrderedDict``
+        """
+        return OrderedDict([
+        ])
+
+    def deserialize(self, data: dict, hashmap: dict = {}, restore_id: bool = True) -> bool:
+        """Deserialization method which takes data in python ``dict`` format.
+
+        The content widget holds no state of its own, so there is nothing to
+        restore and the call always succeeds.
+
+        :param data: Dictionary containing serialized data
+        :type data: ``dict``
+        :param hashmap: Helper dictionary containing references (by id == key) to existing objects
+        :type hashmap: ``dict``
+        :param restore_id: True if we are creating new objects. False is useful when loading existing
+            objects of which we want to keep the existing object's `id`.
+        :type restore_id: bool
+        :return: ``True`` if deserialization was successful, otherwise ``False``
+        :rtype: ``bool``
+        """
+        return True
+
+    # NOTE: deliberately no `history_stamp_callback` here. SceneHistory's
+    # dispatch resolves the hook with getattr and tolerates its absence, and
+    # defining a no-op base would shadow the real implementation in any
+    # content class whose MRO puts this Qt base ahead of its own mixin.
+
+
+class QDMTextEdit(QTextEdit):
+    """
+        .. note::
+
+            This class is an example of a ``QTextEdit`` modification that handles the `Delete` key event with an overridden
+            Qt's ``keyPressEvent`` (when not using ``QActions`` in menu or toolbar)
+
+        Overridden ``QTextEdit`` which sends a notification about being edited to its parent's container :py:class:`QDMNodeContentWidget`
+    """
+
+    def focusInEvent(self, event: QFocusEvent | None) -> None:
+        """Example of an overridden focusInEvent to mark the start of editing
+
+        :param event: Qt's focus event
+        :type event: QFocusEvent
+        """
+        parent = self.parentWidget()
+        if isinstance(parent, QDMNodeContentWidget):
+            parent.setEditingFlag(True)
+
+        super().focusInEvent(event)
+
+    def focusOutEvent(self, event: QFocusEvent | None) -> None:
+        """Example of an overridden focusOutEvent to mark the end of editing
+
+        :param event: Qt's focus event
+        :type event: QFocusEvent
+        """
+        parent = self.parentWidget()
+        if isinstance(parent, QDMNodeContentWidget):
+            parent.setEditingFlag(False)
+
+        super().focusOutEvent(event)

nodeeditor/node_decorators.py

@@ -0,0 +1,65 @@
+"""
+A module containing the decorator which marks classes as automatically serializable
+"""
+from typing import Any, Callable, Optional, Type, Dict, TypeVar, List, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from nodeeditor.node_scene import Scene
+
+
+T = TypeVar('T')
+
+
+class MakeSerializable:
+    """Registry for classes that should be automatically serialized"""
+    _registry: Dict[str, Type] = {}
+    _instances: Dict[str, List['Scene']] = {}  # Track instances per scene
+
+    @classmethod
+    def register(cls, key: str = "") -> Callable[[Type[T]], Type[T]]:
+        """Class decorator to mark a class as automatically serializable"""
+        def decorator(wrapped_class: Type[T]) -> Type[T]:
+            # Use class name as key if none provided
+            serialize_key = key or wrapped_class.__name__.lower()
+
+            # Ensure the class has required methods
+            if not hasattr(wrapped_class, 'serialize') or not hasattr(wrapped_class, 'deserialize'):
+                raise TypeError(
+                    f"Class {wrapped_class.__name__} must implement serialize and deserialize methods")
+
+            # Store the original __init__
+            original_init = wrapped_class.__init__
+
+            # Create new __init__ that registers with scene
+            def new_init(self, scene: 'Scene', *args, **kwargs):
+                original_init(self, scene, *args, **kwargs)
+                # Auto-register with scene
+                if serialize_key not in cls._instances:
+                    cls._instances[serialize_key] = []
+                cls._instances[serialize_key].append(scene)
+                # Force scene to register serializers
+                scene._register_auto_serializers()
+
+            wrapped_class.__init__ = new_init
+            cls._registry[serialize_key] = wrapped_class
+            return wrapped_class
+        return decorator
+
+    @classmethod
+    def get_registered(cls) -> Dict[str, Type]:
+        """Get all classes registered as automatically serializable
+
+        :return: mapping of serialize keys to the registered classes
+        :rtype: ``dict``
+        """
+        return cls._registry
+
+    @classmethod
+    def get_instance(cls, key: str, scene: 'Scene') -> Optional[Any]:
+        """Get instance for given key and scene"""
+        if key in cls._instances:
+            scenes = cls._instances[key]
+            if scene in scenes:
+                return next((obj for obj in scene.__dict__.values()
+                             if isinstance(obj, cls._registry[key])), None)
+        return None