Merge pull request #173 from plotly/overwrite_flag

documented overwrite argument in update_*

Author: nicolaskruchten

python/creating-and-updating-figures.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.1'
-      jupytext_version: 1.1.6
+      jupytext_version: 1.1.1
   kernelspec:
     display_name: Python 3
     language: python
@@ -30,8 +30,8 @@ jupyter:
     page_type: example_index
     permalink: python/creating-and-updating-figures/
     redirect_from:
-      - python/user-guide/
-      - python/user-g/
+    - python/user-guide/
+    - python/user-g/
     thumbnail: thumbnail/creating-and-updating-figures.png
 ---
 
@@ -436,6 +436,23 @@ fig.update_traces(
 fig.show()
 ```
 
+### Overwrite existing properties when using update methods
+
+`update_layout` and `update_traces` have an `overwrite` keyword argument, defaulting to False, in which case updates are applied recursively to the *existing* nested property structure. When set to True, the prior value of existing properties is overwritten with the provided value.
+
+In the example below, the red color of markers is overwritten when updating `marker` in `update_traces` with `overwrite=True`. Note that setting instead `marker_opacity` with the magic underscore would not overwrite `marker_color` because properties would be overwritten starting only at the level of `marker.opacity`. 
+
+```python
+import plotly.graph_objects as go
+fig = go.Figure(go.Bar(x=[1, 2, 3], y=[6, 4, 9], 
+                       marker_color="red")) # will be overwritten below
+fig.update_traces(
+    overwrite=True,
+    marker={"opacity": 0.4}
+                 )
+fig.show()
+```
+
 #### The for each trace method
 Suppose the updates that you want to make to a collection of traces depend on the current values of certain trace properties.  The `update_traces` method cannot handle this situation, but the `for_each_trace` method can.