add new figure.data section and other things

Author: Kully

CHANGELOG.md

@@ -20,7 +20,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ### Changed
 - Improved data validation covering the full API with clear, informative error messages. This means that incorrect properties and/or values now always raise a `ValueError` with a description of the error, the invalid property, and the available properties on the level that it was placed in the graph object. Eg. `go.Scatter(foo=123)` raises a validation error. See https://plot.ly/python/reference/ for a reference to all valid properties and values in the Python API.
 
-- Graph objs are no longer dicts, though they still provide many dict-like magic methods. Running a cell of a graph object now prints a dict-style representation of the object:
+- Graph objects are no longer dicts, though they still provide many dict-like magic methods. Running a cell of a graph object now prints a dict-style representation of the object:
 
 Eg. `plotly.graph_objs.Scatter()` prints
 

migration-guide.md

@@ -27,13 +27,34 @@ f.add_scatter(x=[1,2,3], y=[4,3,2])
 f
 ```
 
-## New __repr__ method
-plotly figures and graph objects now include the dict-like `__repr__` method that represents the object as a string
+## New Plotly Object Representation
+Plotly figures and objects now display a clean representation of the dict-like hierarchy of their structure. They also includes the dict-like `__repr__` method that represents the object as a string
+
+Eg. `plotly.graph_objs.Scatter()` prints
+
+```
+Scatter({
+    'type': 'scatter'
+})
+```
+
+## New Figure.data Assignment
+- Assignment to the `Figure.data` property must contain a permutation of a subset of the existing traces. Assignment can be used to reorder and remove traces, but cannot currently add new traces.
+
+Suppose a figure, fig, has 3 traces. The following command is valid and it will move the third trace to be the first, the first trace to be the second, and it will remove the second trace.
 
 ```
-f.__repr__()
+fig.data = [fig.data[2], fig.data[0]]
 ```
 
+However this is not valid:
+```
+fig.data = [fig.data[0], go.Scatter(y=[2, 3, 1])]
+```
+
+It's not valid because it's introducing a new trace during assignment. This trace would need to be added using `add_trace` instead.
+
+
 ## FigureWidget Subplot Example
 Let's create a subplot then turn it into a FigureWidget to display in the notebook. Note that `append_trace` is no deprecated. Use `add_trace` or `add_traces` instead.