extend functionality

Author: chriddyp

plotly/widgets/graph_widget.py

@@ -669,3 +669,105 @@ def reorder_traces(self, current_indices, new_indices=None):
         if new_indices is not None:
             message['newIndices'] = new_indices
         self._handle_outgoing_message(message)
+
+    def extend_traces(self, update, indices, max_points=None):
+        """ Append data points to existing traces in the Plotly graph.
+
+        Args:
+            update (dict):
+                dict where keys are the graph attribute strings
+                and values are arrays of arrays with values to extend.
+
+                Each array in the array will extend a trace.
+
+                Valid keys include:
+                    'x', 'y', 'text,
+                    'marker.color', 'marker.size', 'marker.symbol',
+                    'marker.line.color', 'marker.line.width'
+
+            indices (list, int):
+                Specify which traces to apply the `update` dict to.
+                If indices are not given, the update will apply to
+                the traces in order.
+
+            max_points (int or dict, optional):
+                If specified, then only show the `max_points` most
+                recent points in the graph.
+                This is useful to prevent traces from becoming too
+                large (and slow) or for creating "windowed" graphs
+                in monitoring applications.
+
+                To set max_points to different values for each trace
+                or attribute, set max_points to a dict mapping keys
+                to max_points values. See the examples below.
+
+            Examples:
+                Initialization - Start each example below with this setup:
+                ```
+                from plotly.widgets import Graph
+                from IPython.display import display
+
+                graph = GraphWidget()
+                graph.plot([
+                    {'x': [], 'y': []},
+                    {'x': [], 'y': []}
+                ])
+
+                display(graph)
+                ```
+
+                Example 1 - Extend the first trace with x and y data
+                ```
+                graph.extend_traces({'x': [[1,2,3]], 'y': [[10,20,30]]}, [0])
+                ```
+
+                Example 2 - Extend the second trace with x and y data
+                ```
+                graph.extend_traces({'x': [[1,2,3]], 'y': [[10,20,30]]}, [1])
+                ```
+
+                Example 3 - Extend the first two traces with x and y data
+                ```
+                graph.extend_traces({
+                    'x': [[1,2,3], [2,3,4]],
+                    'y': [[10,20,30], [3,4,3]]
+                }, [0, 1])
+                ```
+
+                Example 4 - Extend the first trace with x and y data and
+                            limit the length of data in that trace to 50
+                            points.
+                ```
+
+                graph.extend_traces({
+                    'x': [range(100)],
+                    'y': [range(100)]
+                }, [0, 1], max_points=50)
+                ```
+
+                Example 5 - Extend the first and second trace with x and y data
+                            and limit the length of data in the first trace to
+                            25 points and the second trace to 50 points.
+                ```
+                new_points = range(100)
+                graph.extend_traces({
+                        'x': [new_points, new_points],
+                        'y': [new_points, new_points]
+                    },
+                    [0, 1],
+                    max_points={
+                        'x': [25, 50],
+                        'y': [25, 50]
+                    }
+                )
+                ```
+        """
+        message = {
+            'task': 'extendTraces',
+            'update': update,
+            'graphId': self._graphId,
+            'indices': indices
+        }
+        if max_points is not None:
+            message['maxPoints'] = max_points
+        self._handle_outgoing_message(message)