nodeeditor-qtpy 0.8.1__tar.gz → 0.8.2__tar.gz

{nodeeditor_qtpy-0.8.1 → nodeeditor_qtpy-0.8.2}/HISTORY.rst

@@ -1,12 +1,98 @@
 History
 =======
 
-Release history for **qtpy-nodeeditor**.
+Release history for **nodeeditor-qtpy**.
 
 This file tracks releases of this project. For the pre-fork upstream
 `PyNodeEditor <https://github.com/benbyjones/PyQtNodeEditor>`_ lineage that
 this code started from, see `CHANGES.md <CHANGES.md>`_.
 
+0.8.2 - 2026-10-25
+------------------
+
+**Fixes**
+
+- A dragged node no longer leaves a stack of label plates behind it. Two
+  declared rectangles were smaller than what their items painted:
+  ``QDMGraphicsNodeLabel`` declared the text while painting a rounded box
+  padded by 6x3 px, and ``QDMGraphicsNode`` / ``QDMIconGraphicsNode`` declared
+  their body while the label floats above it. Qt repaints a moved item by the
+  rectangle it declared at the old position and dirties its children only at
+  the new one, so the old plate was never cleared. The label now declares its
+  plate, ``textRect()`` keeps the text rectangle for callers that position it,
+  the nodes expose ``labelRect()`` and include it in their own rectangle, and a
+  label that moves, changes text or is hidden by the level of detail re-indexes
+  its node with ``prepareGeometryChange()``.
+- ``QDMGraphicsCutline`` declared the bare polyline while stroking it with a
+  2px pen, so a moving cut line left the outer half of the stroke behind. Its
+  rectangle now accounts for the pen.
+
+**Tests**
+
+- Added ``tests/test_210_label_geometry.py``: the label declares its plate, a
+  node declares the label above it, hiding the label leaves the body alone, and
+  a node move dirties the plate's old position.
+- The suite now runs 121 tests.
+
+0.8.1 - 2026-10-21
+------------------
+
+**Features**
+
+- Added ``nodeeditor.node_graph``: graph algorithms over a ``Scene`` without a
+  third-party graph library. ``topological_order`` (Kahn's algorithm, scene
+  order as the tie-break, raising ``GraphCycleError``), ``descendants`` and
+  ``ancestors`` (breadth-first with a visited set), ``components`` (the
+  disconnected subgraphs, via union-find), ``cycles`` (one representative cycle
+  per cyclic region), and ``paths`` and ``shortest_path`` (parallel edges stay
+  distinct). Every algorithm is also a thin wrapper on ``Scene``, so
+  ``scene.shortest_path(a, b)`` works without importing the module, and
+  ``GraphCycleError`` is exported from the package.
+- Added a graph inspector panel to the calculator example, which runs the
+  algorithms on the active graph and selects the matching node on the canvas.
+- ``Node.markDescendantsDirty`` and ``markDescendantsInvalid`` now walk with
+  ``descendants()`` instead of recursing. The old walk raised
+  ``RecursionError`` on a cycle and on chains over 1000 nodes, and visited a
+  node once per path into it: a 42-node diamond graph took 4.5 s, now about
+  0.0002 s.
+
+**Packaging**
+
+- First release on PyPI, as ``nodeeditor-qtpy``. The import package stays
+  ``nodeeditor``.
+- Built with ``uv_build``; the ``hatchling`` configuration is kept as a
+  fallback and produces the same artifacts.
+- Dependencies are ``qtpy`` and ``orjson`` only. The bindings are optional
+  extras, ``pyqt6`` and ``pyside6``, and any binding QtPy supports keeps
+  working. Python 3.10 and newer.
+- The licence is an SPDX ``MIT`` expression and the licence file ships in the
+  wheel, with the upstream copyright retained.
+- Uploads run from GitHub Actions with PEP 740 attestations, so PyPI records
+  provenance instead of showing "without provenance".
+- ``nodeeditor.__version__`` now reports the version of the installed
+  distribution, and importing the package without a Qt binding raises an error
+  that names the extras to install.
+
+**Docs**
+
+- New documentation site at
+  https://azadkshitij.github.io/qtpy-nodeeditor/, built with MkDocs, the
+  Material theme and mkdocstrings. The API reference is generated from the
+  docstrings in the source, so it always matches the installed code.
+- Added pages for the installation, a quick start, the event system and node
+  groups, and the guides now carry screenshots.
+- Documented every public class, method and function in the package.
+- The site is redeployed whenever a commit pushed to ``main`` carries
+  "publish" in its message.
+
+**Tests**
+
+- Added ``tests/test_120_graph.py`` for the algorithms, the ``Scene`` wrappers
+  and the dirty walk.
+- Moved the hover colour test into ``tests/``, where it runs with the suite; it
+  was stranded in the repository root and never collected.
+- The suite now runs 90 tests.
+
 0.8 - 2026-10-21
 ----------------
 

{nodeeditor_qtpy-0.8.1 → nodeeditor_qtpy-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nodeeditor-qtpy
-Version: 0.8.1
+Version: 0.8.2
 Summary: Framework for building node editors and graph UIs in Qt, independent of the Qt binding (PyQt5/PyQt6/PySide2/PySide6 via QtPy)
 Keywords: node editor,nodeeditor,node graph,graph,visual programming,qt,qtpy,pyqt6,pyside6
 Author: Azad Kshitij
@@ -50,6 +50,7 @@ PyQt6 and PySide6.
 - support for implementing evaluation logic
 - hovering effects, dragging edges, cutting lines, snapping and more
 - node groups, multi-input nodes, custom socket shapes and color schemes
+- canvas comments (sticky notes) with inline editing and serialization
 - ready-made examples you can copy from
 
 ## Requirements
@@ -142,6 +143,7 @@ from nodeeditor import NodeEditorColorScheme, get_socket_shape
 from nodeeditor.node_scene import Scene
 from nodeeditor.node_node import Node
 from nodeeditor.node_edge import Edge
+from nodeeditor.node_comment import Comment
 ```
 
 ## Credits

{nodeeditor_qtpy-0.8.1 → nodeeditor_qtpy-0.8.2}/README.md

@@ -18,6 +18,7 @@ PyQt6 and PySide6.
 - support for implementing evaluation logic
 - hovering effects, dragging edges, cutting lines, snapping and more
 - node groups, multi-input nodes, custom socket shapes and color schemes
+- canvas comments (sticky notes) with inline editing and serialization
 - ready-made examples you can copy from
 
 ## Requirements
@@ -110,6 +111,7 @@ from nodeeditor import NodeEditorColorScheme, get_socket_shape
 from nodeeditor.node_scene import Scene
 from nodeeditor.node_node import Node
 from nodeeditor.node_edge import Edge
+from nodeeditor.node_comment import Comment
 ```
 
 ## Credits

nodeeditor_qtpy-0.8.2/docs/api/comment.md

@@ -0,0 +1,8 @@
+A `Comment` is a canvas note: a movable, selectable box that holds multi-line
+plain text. It is a visual item like a `Group`, not a `Node`. It has no sockets,
+never runs, and has no effect on evaluation.
+
+See [Canvas comments](../guides/comments.md) for usage, editing semantics and
+the serialized shape.
+
+::: nodeeditor.node_comment

{nodeeditor_qtpy-0.8.1 → nodeeditor_qtpy-0.8.2}/docs/api/index.md

@@ -16,6 +16,7 @@ The package re-exports the pieces most applications need:
 | [Scene](scene.md) | `node_scene`, `node_scene_clipboard`, `node_scene_history` |
 | [Node](node.md) | `node_node`, `node_multi_input_node` |
 | [Groups](group.md) | `node_group` |
+| [Comments](comment.md) | `node_comment` |
 | [Edge](edge.md) | `node_edge` and the edge interaction helpers |
 | [Socket](socket.md) | `node_socket` |
 | [Socket shapes](socket-shapes.md) | `node_socket_shapes` |

nodeeditor_qtpy-0.8.2/docs/guides/comments.md

@@ -0,0 +1,96 @@
+# Canvas comments
+
+A `Comment` is a canvas note: a movable, selectable box that holds multi-line
+plain text. It is a visual item like a `Group`, not a `Node`. It has no sockets,
+never runs, and has no effect on evaluation.
+
+Use `Scene.addComment()` as the short form:
+
+```python
+note = scene.addComment(
+    "Remember to tune this after the first run.",
+    x=40, y=25, width=260,
+)
+```
+
+Or construct one directly. Both forms register the note with the scene:
+
+```python
+from nodeeditor.node_comment import Comment
+
+note = Comment(scene, "text", x=40, y=25, width=260, height=120)
+```
+
+The note auto-sizes: its width is the requested width (at least
+`Comment.MIN_WIDTH`) and its height grows to fit the wrapped text, never below
+`Comment.MIN_HEIGHT`. `setSize(w, h)` changes the requested size and
+`setText()` replaces the text.
+
+## Editing
+
+Double-click the note, or call `begin_edit()`, to open the inline editor.
+Editing ends in one of these ways:
+
+- Focus leaves the editor (clicking elsewhere): the text is committed and a
+  `"Edited comment"` history entry is stored.
+- `Escape` is pressed: the edit is cancelled and the text from before the edit
+  is restored. No history entry is stored.
+- `Ctrl+Enter` is pressed, or `finish_edit()` is called: the text is committed.
+- `cancel_edit()` is called: the edit is cancelled explicitly.
+
+`setText(text, store_history=True)` also stores a history entry. The default
+`store_history=False` keeps generated text and scene loading out of the undo
+stack. History stamps snapshot the whole scene, and comments are part of that
+snapshot, so undo and redo restore comment text, position, size, colours and
+z-order.
+
+## Colours and order
+
+The defaults are theme-neutral, so the library does not read an application
+theme manager:
+
+```python
+note.setBackgroundColor("#fff8d6")
+note.setBorderColor((190, 175, 120))
+note.setTextColor("#222222")
+note.setColors(background="#e8f0ff", border="#8aa4c8")
+```
+
+Each setter accepts a `QColor`, a colour name or an RGB/RGBA tuple. Moving a
+note updates its scene position. `bringToFront()`, `sendToBack()` and
+`resetZValue()` change the stacking order; the z-value is saved with the note.
+
+## Selection and removal
+
+Notes are ordinary selectable items, so rubber-band selection and `Shift`
+selection work. `Scene.getSelectedComments()` returns the selected notes.
+`Delete` removes them through `QDMGraphicsView.deleteSelected()`, and the
+context menu offers edit, order and delete actions. `note.remove()` removes a
+note programmatically; the caller decides whether to store a history entry.
+
+## Serialization
+
+Comments are stored in the additive `Scene` key `"comments"`. Files written
+before comments existed have no such key and load unchanged.
+
+```json
+{
+  "id": 1234,
+  "type": "Comment",
+  "version": 1,
+  "text": "first line\nsecond line",
+  "x": 40.0,
+  "y": 25.0,
+  "w": 240.0,
+  "h": 110.0,
+  "z": 1.0,
+  "style": {
+    "background": [255, 248, 214, 232],
+    "border": [190, 175, 120, 255],
+    "text": [35, 35, 35, 255]
+  }
+}
+```
+
+`w` and `h` are the outer size after auto-sizing; `z` is the item z-value.
+Missing `style` or `z` keys fall back to the neutral defaults.

{nodeeditor_qtpy-0.8.1 → nodeeditor_qtpy-0.8.2}/examples/example_calculator/calc_window.py

@@ -135,6 +135,11 @@ class CalculatorWindow(NodeEditorWindow):
             triggered=self.showSelectedPath)
         self.actShortestPath.setShortcut(QKeySequence("Ctrl+Shift+P"))
 
+        self.actNewComment = QAction("&New Comment", self,
+                                     statusTip="Add a sticky note to the canvas",
+                                     triggered=self.onAddComment)
+        self.actNewComment.setShortcut(QKeySequence("Ctrl+Shift+N"))
+
     def getCurrentScene(self):
         """Shortcut for the `Scene` of the active tab, or ``None``."""
         active = self.getCurrentNodeEditorWidget()
@@ -214,6 +219,10 @@ class CalculatorWindow(NodeEditorWindow):
     def createMenus(self):
         super().createMenus()
 
+        # "New Comment" belongs next to the other Edit-menu editing actions.
+        self.editMenu.addSeparator()
+        self.editMenu.addAction(self.actNewComment)
+
         self.graphMenu = self.menuBar().addMenu("&Graph")
         self.graphMenu.addAction(self.actTopologicalOrder)
         self.graphMenu.addAction(self.actComponents)
@@ -255,6 +264,7 @@ class CalculatorWindow(NodeEditorWindow):
         self.actComponents.setEnabled(hasMdiChild)
         self.actCycles.setEnabled(hasMdiChild)
         self.actShortestPath.setEnabled(hasMdiChild)
+        self.actNewComment.setEnabled(hasMdiChild)
 
         self.updateEditMenu()
 
@@ -290,6 +300,26 @@ class CalculatorWindow(NodeEditorWindow):
         # gridAct.setChecked(self.scene.grScene.showGrid)
         # gridAct.triggered.connect(self.onShowGrid)
 
+    def onAddComment(self):
+        """Add a sticky note at the center of the active canvas and edit it."""
+        scene = self.getCurrentScene()
+        if scene is None:
+            self.statusBar().showMessage("Open a graph before adding a comment", 3000)
+            return
+
+        try:
+            view = self.getCurrentNodeEditorWidget().view
+            center = view.mapToScene(view.viewport().rect().center())
+            x, y = center.x(), center.y()
+        except Exception:
+            x, y = 0, 0
+
+        comment = scene.addComment("", x=x, y=y, width=240)
+        comment.begin_edit()
+        self.statusBar().showMessage(
+            "Comment added. Type your note, then click away or press Ctrl+Enter to save.",
+            4000)
+
     def onShowGrid(self, checked: bool) -> None:
         """
         Toggle the grid visibility for all subwindows

{nodeeditor_qtpy-0.8.1 → nodeeditor_qtpy-0.8.2}/mkdocs.yml

@@ -87,6 +87,7 @@ nav:
       - Events: events.md
   - Guides:
       - Group nodes: guides/group-nodes.md
+      - Canvas comments: guides/comments.md
       - Node grouping (reference): guides/node-grouping.md
       - Multi-input nodes: guides/multi-input-nodes.md
       - Graph algorithms: guides/graph-algorithms.md
@@ -99,6 +100,7 @@ nav:
       - Scene: api/scene.md
       - Node: api/node.md
       - Groups: api/group.md
+      - Comments: api/comment.md
       - Edge: api/edge.md
       - Socket: api/socket.md
       - Socket shapes: api/socket-shapes.md

{nodeeditor_qtpy-0.8.1 → nodeeditor_qtpy-0.8.2}/nodeeditor/__init__.py

@@ -9,7 +9,7 @@ __author__ = 'Azad Kshitij'
 try:
     __version__ = _dist_version("nodeeditor-qtpy")
 except PackageNotFoundError:  # running from a source checkout
-    __version__ = "0.8.1"
+    __version__ = "0.8.2"
 
 
 _QT_API_NAME, _QT_API_VERSION = None, None
@@ -74,6 +74,9 @@ from nodeeditor.node_socket_shapes import (
 # Export the graph algorithm exception
 from nodeeditor.node_graph import GraphCycleError
 
+# Export the canvas note item for convenient construction
+from nodeeditor.node_comment import Comment
+
 
 __all__ = [
     "NodeEditorColorScheme",
@@ -90,4 +93,5 @@ __all__ = [
     "get_socket_shape",
     "SOCKET_SHAPES",
     "GraphCycleError",
+    "Comment",
 ]