Add "overwrite" kwarg to all update* figure methods. (#1726)

When True, update operations will overwrite the prior version of all
properties. When False (the default), updates are applied recursively
and prior properties are retained if not updated.

packages/python/plotly/codegen/figure.py

@@ -313,6 +313,7 @@ def update_{plural_name}(
             self,
             patch=None,
             selector=None,
+            overwrite=False,
             row=None, col=None{secondary_y_1},
             **kwargs):
         \"\"\"
@@ -330,6 +331,10 @@ def update_{plural_name}(
             properties corresponding to all of the dictionary's keys, with
             values that exactly match the supplied values. If None
             (the default), all {singular_name} objects are selected.
+        overwrite: bool
+            If True, overwrite existing properties. If False, apply updates
+            to existing properties recursively, preserving existing
+            properties that are not specified in the update operation.
         row, col: int or None (default None)
             Subplot row and column index of {singular_name} objects to select.
             To select {singular_name} objects by row and column, the Figure
@@ -348,7 +353,7 @@ def update_{plural_name}(
         \"\"\"
         for obj in self.select_{plural_name}(
                 selector=selector, row=row, col=col{secondary_y_2}):
-            obj.update(patch, **kwargs)
+            obj.update(patch, overwrite=overwrite, **kwargs)
 
         return self"""
         )

packages/python/plotly/plotly/basedatatypes.py

@@ -438,7 +438,7 @@ def _ipython_display_(self):
         else:
             print (repr(self))
 
-    def update(self, dict1=None, **kwargs):
+    def update(self, dict1=None, overwrite=False, **kwargs):
         """
         Update the properties of the figure with a dict and/or with
         keyword arguments.
@@ -450,6 +450,10 @@ def update(self, dict1=None, **kwargs):
         ----------
         dict1 : dict
             Dictionary of properties to be updated
+        overwrite: bool
+            If True, overwrite existing properties. If False, apply updates
+            to existing properties recursively, preserving existing
+            properties that are not specified in the update operation.
         kwargs :
             Keyword/value pair of properties to be updated
 
@@ -484,10 +488,11 @@ def update(self, dict1=None, **kwargs):
                 if d:
                     for k, v in d.items():
                         update_target = self[k]
-                        if update_target == ():
-                            # existing data or frames property is empty
-                            # In this case we accept the v as is.
+                        if update_target == () or overwrite:
                             if k == "data":
+                                # Overwrite all traces as special due to
+                                # restrictions on trace assignment
+                                self.data = ()
                                 self.add_traces(v)
                             else:
                                 # Accept v
@@ -843,7 +848,14 @@ def for_each_trace(self, fn, selector=None, row=None, col=None, secondary_y=None
         return self
 
     def update_traces(
-        self, patch=None, selector=None, row=None, col=None, secondary_y=None, **kwargs
+        self,
+        patch=None,
+        selector=None,
+        row=None,
+        col=None,
+        secondary_y=None,
+        overwrite=False,
+        **kwargs
     ):
         """
         Perform a property update operation on all traces that satisfy the
@@ -877,6 +889,10 @@ def update_traces(
             created using plotly.subplots.make_subplots. See the docstring
             for the specs argument to make_subplots for more info on
             creating subplots with secondary y-axes.
+        overwrite: bool
+            If True, overwrite existing properties. If False, apply updates
+            to existing properties recursively, preserving existing
+            properties that are not specified in the update operation.
         **kwargs
             Additional property updates to apply to each selected trace. If
             a property is specified in both patch and in **kwargs then the
@@ -890,10 +906,10 @@ def update_traces(
         for trace in self.select_traces(
             selector=selector, row=row, col=col, secondary_y=secondary_y
         ):
-            trace.update(patch, **kwargs)
+            trace.update(patch, overwrite=overwrite, **kwargs)
         return self
 
-    def update_layout(self, dict1=None, **kwargs):
+    def update_layout(self, dict1=None, overwrite=False, **kwargs):
         """
         Update the properties of the figure's layout with a dict and/or with
         keyword arguments.
@@ -905,6 +921,10 @@ def update_layout(self, dict1=None, **kwargs):
         ----------
         dict1 : dict
             Dictionary of properties to be updated
+        overwrite: bool
+            If True, overwrite existing properties. If False, apply updates
+            to existing properties recursively, preserving existing
+            properties that are not specified in the update operation.
         kwargs :
             Keyword/value pair of properties to be updated
 
@@ -913,7 +933,7 @@ def update_layout(self, dict1=None, **kwargs):
         BaseFigure
             The Figure object that the update_layout method was called on
         """
-        self.layout.update(dict1, **kwargs)
+        self.layout.update(dict1, overwrite=overwrite, **kwargs)
         return self
 
     def _select_layout_subplots_by_prefix(
@@ -2697,7 +2717,7 @@ def _is_dict_list(v):
         return isinstance(v, list) and len(v) > 0 and isinstance(v[0], dict)
 
     @staticmethod
-    def _perform_update(plotly_obj, update_obj):
+    def _perform_update(plotly_obj, update_obj, overwrite=False):
         """
         Helper to support the update() methods on :class:`BaseFigure` and
         :class:`BasePlotlyType`
@@ -2747,6 +2767,12 @@ def _perform_update(plotly_obj, update_obj):
             # ------------------------
             for key in update_obj:
                 val = update_obj[key]
+
+                if overwrite:
+                    # Don't recurse and assign property as-is
+                    plotly_obj[key] = val
+                    continue
+
                 validator = plotly_obj._get_prop_validator(key)
 
                 if isinstance(validator, CompoundValidator) and isinstance(val, dict):
@@ -3530,7 +3556,7 @@ def _raise_on_invalid_property_error(self, *args):
                 )
             )
 
-    def update(self, dict1=None, **kwargs):
+    def update(self, dict1=None, overwrite=False, **kwargs):
         """
         Update the properties of an object with a dict and/or with
         keyword arguments.
@@ -3542,6 +3568,10 @@ def update(self, dict1=None, **kwargs):
         ----------
         dict1 : dict
             Dictionary of properties to be updated
+        overwrite: bool
+            If True, overwrite existing properties. If False, apply updates
+            to existing properties recursively, preserving existing
+            properties that are not specified in the update operation.
         kwargs :
             Keyword/value pair of properties to be updated
 
@@ -3552,11 +3582,11 @@ def update(self, dict1=None, **kwargs):
         """
         if self.figure:
             with self.figure.batch_update():
-                BaseFigure._perform_update(self, dict1)
-                BaseFigure._perform_update(self, kwargs)
+                BaseFigure._perform_update(self, dict1, overwrite=overwrite)
+                BaseFigure._perform_update(self, kwargs, overwrite=overwrite)
         else:
-            BaseFigure._perform_update(self, dict1)
-            BaseFigure._perform_update(self, kwargs)
+            BaseFigure._perform_update(self, dict1, overwrite=overwrite)
+            BaseFigure._perform_update(self, kwargs, overwrite=overwrite)
 
         return self