Add set_node_caption convenience method

ref GDS-59

Author: FlorentinD

changelog.md

@@ -2,15 +2,15 @@
 
 ## Breaking changes
 
-* Removed `table` property from nodes and relationships returned from `from_snowflake`, the table is represented by the `caption` field.
-* Changed default value of `override` parameter in `VisualizationGraph.color_nodes()` from `False` to `True`. The method now overrides existing node colors by default. To preserve existing colors, explicitly pass `override=False`.
+- Removed `table` property from nodes and relationships returned from `from_snowflake`, the table is represented by the `caption` field.
+- Changed default value of `override` parameter in `VisualizationGraph.color_nodes()` from `False` to `True`. The method now overrides existing node colors by default. To preserve existing colors, explicitly pass `override=False`.
 
 ## New features
 
+- Added `set_node_captions()` convenience method to `VisualizationGraph` for setting node captions from a field or property.
 
 ## Bug fixes
 
 ## Improvements
 
-
 ## Other changes

docs/source/customizing.rst

@@ -20,6 +20,45 @@ If you have not yet created a ``VisualizationGraph`` object, please refer to one
    :backlinks: none
 
 
+Setting node captions
+---------------------
+
+Node captions are the text labels displayed on nodes in the visualization.
+
+The ``set_node_captions`` method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By calling the :meth:`neo4j_viz.VisualizationGraph.set_node_captions` method, you can set node captions based on a
+node field (like ``id``, ``size``, etc.) or a node property (members of the ``Node.properties`` map).
+
+The method accepts an ``override`` parameter (default ``True``) that controls whether to replace existing captions.
+If ``override=False``, only nodes without captions will be updated.
+
+Here's an example of setting node captions from a property:
+
+.. code-block:: python
+
+    # VG is a VisualizationGraph object with nodes that have a "name" property
+    VG.set_node_captions(property="name")
+
+You can also set captions from a node field, and choose not to override existing captions:
+
+.. code-block:: python
+
+    # VG is a VisualizationGraph object
+    VG.set_node_captions(field="id", override=False)
+
+For more complex scenarios where you need fallback logic or want to combine multiple properties, you can iterate over
+nodes directly:
+
+.. code-block:: python
+
+    # VG is a VisualizationGraph object
+    for node in VG.nodes:
+        caption = node.properties.get("name") or node.properties.get("title") or node.id
+        node.caption = str(caption)
+
+
 Coloring nodes
 --------------
 

python-wrapper/src/neo4j_viz/visualization_graph.py

@@ -194,6 +194,73 @@ def toggle_nodes_pinned(self, pinned: dict[NodeIdType, bool]) -> None:
 
             node.pinned = node_pinned
 
+    def set_node_captions(
+        self,
+        *,
+        field: Optional[str] = None,
+        property: Optional[str] = None,
+        override: bool = True,
+    ) -> None:
+        """
+        Set the caption for nodes in the graph based on either a node field or a node property.
+
+        Parameters
+        ----------
+        field:
+            The field of the nodes to use as the caption. Must be None if `property` is provided.
+        property:
+            The property of the nodes to use as the caption. Must be None if `field` is provided.
+        override:
+            Whether to override existing captions of the nodes, if they have any.
+
+        Examples
+        --------
+        Given a VisualizationGraph `VG`:
+
+        >>> nodes = [
+        ...    Node(id="0", properties={"name": "Alice", "age": 30}),
+        ...    Node(id="1", properties={"name": "Bob", "age": 25}),
+        ... ]
+        >>> VG = VisualizationGraph(nodes=nodes)
+
+        Set node captions from a property:
+
+        >>> VG.set_node_captions(property="name")
+
+        Set node captions from a field, only if not already set:
+
+        >>> VG.set_node_captions(field="id", override=False)
+
+        Set captions from multiple properties with fallback:
+
+        >>> for node in VG.nodes:
+        ...     caption = node.properties.get("name") or node.properties.get("title") or node.id
+        ...     if override or node.caption is None:
+        ...         node.caption = str(caption)
+        """
+        if not ((field is None) ^ (property is None)):
+            raise ValueError(
+                f"Exactly one of the arguments `field` (received '{field}') and `property` (received '{property}') must be provided"
+            )
+
+        if property:
+            # Use property
+            for node in self.nodes:
+                if not override and node.caption is not None:
+                    continue
+
+                value = node.properties.get(property, "")
+                node.caption = str(value)
+        else:
+            # Use field
+            attribute = to_snake(field)
+            for node in self.nodes:
+                if not override and node.caption is not None:
+                    continue
+
+                value = getattr(node, attribute, "")
+                node.caption = str(value)
+
     def resize_nodes(
         self,
         sizes: Optional[dict[NodeIdType, RealNumber]] = None,