first round of changes towards doctesting

packages/python/plotly/plotly/basedatatypes.py

@@ -458,8 +458,9 @@ def update(self, dict1=None, overwrite=False, **kwargs):
         --------
         >>> import plotly.graph_objs as go
         >>> fig = go.Figure(data=[{'y': [1, 2, 3]}])
-        >>> fig.update(data=[{'y': [4, 5, 6]}])
-        >>> fig.to_plotly_json()
+        >>> fig.update(data=[{'y': [4, 5, 6]}]) #doctest: +ELLIPSIS
+        Figure(...)
+        >>> fig.to_plotly_json() # doctest: +SKIP
             {'data': [{'type': 'scatter',
                'uid': 'e86a7c7a-346a-11e8-8aa8-a0999b0c017b',
                'y': array([4, 5, 6], dtype=int32)}],
@@ -468,8 +469,9 @@ def update(self, dict1=None, overwrite=False, **kwargs):
         >>> fig = go.Figure(layout={'xaxis':
         ...                         {'color': 'green',
         ...                          'range': [0, 1]}})
-        >>> fig.update({'layout': {'xaxis': {'color': 'pink'}}})
-        >>> fig.to_plotly_json()
+        >>> fig.update({'layout': {'xaxis': {'color': 'pink'}}}) #doctest: +ELLIPSIS
+        Figure(...)
+        >>> fig.to_plotly_json() # doctest: +SKIP
             {'data': [],
              'layout': {'xaxis':
                         {'color': 'pink',
@@ -1128,6 +1130,8 @@ def plotly_restyle(self, restyle_data, trace_indexes=None, **kwargs):
             example, the following command would be used to update the 'x'
             property of the first trace to the list [1, 2, 3]
 
+            >>> import plotly.graph_objects as go
+            >>> fig = go.Figure(go.Scatter(x=[2, 4, 6]))
             >>> fig.plotly_restyle({'x': [[1, 2, 3]]}, 0)
 
         trace_indexes : int or list of int
@@ -1586,15 +1590,19 @@ def add_trace(self, trace, row=None, col=None, secondary_y=None):
         Add two Scatter traces to a figure
 
         >>> fig = go.Figure()
-        >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]))
-        >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]))
+        >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2])) #doctest: +ELLIPSIS
+        Figure(...)
+        >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2])) #doctest: +ELLIPSIS
+        Figure(...)
 
 
         Add two Scatter traces to vertically stacked subplots
 
         >>> fig = subplots.make_subplots(rows=2)
-        >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=1, col=1)
-        >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=2, col=1)
+        >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=1, col=1) #doctest: +ELLIPSIS
+        Figure(...)
+        >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=2, col=1) #doctest: +ELLIPSIS
+        Figure(...)
         """
         # Make sure we have both row and col or neither
         if row is not None and col is None:
@@ -1662,14 +1670,16 @@ def add_traces(self, data, rows=None, cols=None, secondary_ys=None):
 
         >>> fig = go.Figure()
         >>> fig.add_traces([go.Scatter(x=[1,2,3], y=[2,1,2]),
-        ...                 go.Scatter(x=[1,2,3], y=[2,1,2])])
+        ...                 go.Scatter(x=[1,2,3], y=[2,1,2])]) #doctest: +ELLIPSIS
+        Figure(...)
 
         Add two Scatter traces to vertically stacked subplots
 
         >>> fig = subplots.make_subplots(rows=2)
         >>> fig.add_traces([go.Scatter(x=[1,2,3], y=[2,1,2]),
         ...                 go.Scatter(x=[1,2,3], y=[2,1,2])],
-        ...                 rows=[1, 2], cols=[1, 1])
+        ...                 rows=[1, 2], cols=[1, 1]) #doctest: +ELLIPSIS
+        Figure(...)
         """
 
         # Validate traces
@@ -2152,11 +2162,12 @@ def _build_dispatch_plan(key_path_strs):
 
         Examples
         --------
+
         >>> key_path_strs = ['xaxis.rangeselector.font.color',
         ...                  'xaxis.rangeselector.bgcolor']
 
-        >>> BaseFigure._build_dispatch_plan(key_path_strs)
-            {(): {('xaxis',),
+        >>> BaseFigure._build_dispatch_plan(key_path_strs) #doctest: +SKIP
+            {(): {'xaxis',
                   ('xaxis', 'rangeselector'),
                   ('xaxis', 'rangeselector', 'bgcolor'),
                   ('xaxis', 'rangeselector', 'font'),
@@ -2589,7 +2600,7 @@ def batch_animate(self, duration=500, easing="cubic-in-out"):
         2) Animate a change in the size and color of the trace's markers
         over 2 seconds using the elastic-in-out easing method
 
-        >>> with fig.batch_update(duration=2000, easing='elastic-in-out'):
+        >>> with fig.batch_animate(duration=2000, easing='elastic-in-out'):
         ...     fig.data[0].marker.color = 'green'
         ...     fig.data[0].marker.size = 20
         """
@@ -4088,6 +4099,8 @@ def on_change(self, callback, *args, **kwargs):
         Register callback that prints out the range extents of the xaxis and
         yaxis whenever either either of them changes.
 
+        >>> import plotly.graph_objects as go
+        >>> fig = go.Figure(go.Scatter(x=[1, 2], y=[1, 0]))
         >>> fig.layout.on_change(
         ...   lambda obj, xrange, yrange: print("%s-%s" % (xrange, yrange)),
         ...   ('xaxis', 'range'), ('yaxis', 'range'))
@@ -4572,13 +4585,15 @@ def on_hover(self, callback, append=False):
         Examples
         --------
 
+        >>> import plotly.graph_objects as go
         >>> from plotly.callbacks import Points, InputDeviceState
         >>> points, state = Points(), InputDeviceState()
 
         >>> def hover_fn(trace, points, state):
         ...     inds = points.point_inds
         ...     # Do something
 
+        >>> trace = go.Scatter(x=[1, 2], y=[3, 0])
         >>> trace.on_hover(hover_fn)
 
         Note: The creation of the `points` and `state` objects is optional,
@@ -4632,13 +4647,15 @@ def on_unhover(self, callback, append=False):
         Examples
         --------
 
+        >>> import plotly.graph_objects as go
         >>> from plotly.callbacks import Points, InputDeviceState
         >>> points, state = Points(), InputDeviceState()
 
         >>> def unhover_fn(trace, points, state):
         ...     inds = points.point_inds
         ...     # Do something
 
+        >>> trace = go.Scatter(x=[1, 2], y=[3, 0])
         >>> trace.on_unhover(unhover_fn)
 
         Note: The creation of the `points` and `state` objects is optional,
@@ -4692,13 +4709,15 @@ def on_click(self, callback, append=False):
         Examples
         --------
 
+        >>> import plotly.graph_objects as go
         >>> from plotly.callbacks import Points, InputDeviceState
         >>> points, state = Points(), InputDeviceState()
 
         >>> def click_fn(trace, points, state):
         ...     inds = points.point_inds
         ...     # Do something
 
+        >>> trace = go.Scatter(x=[1, 2], y=[3, 0])
         >>> trace.on_click(click_fn)
 
         Note: The creation of the `points` and `state` objects is optional,
@@ -4751,13 +4770,15 @@ def on_selection(self, callback, append=False):
         Examples
         --------
 
+        >>> import plotly.graph_objects as go
         >>> from plotly.callbacks import Points
         >>> points = Points()
 
         >>> def selection_fn(trace, points, selector):
         ...     inds = points.point_inds
         ...     # Do something
 
+        >>> trace = go.Scatter(x=[1, 2], y=[3, 0])
         >>> trace.on_selection(selection_fn)
 
         Note: The creation of the `points` object is optional,
@@ -4817,13 +4838,15 @@ def on_deselect(self, callback, append=False):
         Examples
         --------
 
+        >>> import plotly.graph_objects as go
         >>> from plotly.callbacks import Points
         >>> points = Points()
 
         >>> def deselect_fn(trace, points):
         ...     inds = points.point_inds
         ...     # Do something
 
+        >>> trace = go.Scatter(x=[1, 2], y=[3, 0])
         >>> trace.on_deselect(deselect_fn)
 
         Note: The creation of the `points` object is optional,

packages/python/plotly/plotly/figure_factory/_2d_density.py

@@ -56,8 +56,7 @@ def create_2d_density(
 
     Example 1: Simple 2D Density Plot
 
-    >>> from plotly.figure_factory create_2d_density
-
+    >>> from plotly.figure_factory import create_2d_density
     >>> import numpy as np
 
     >>> # Make data points
@@ -66,14 +65,14 @@ def create_2d_density(
     >>> y = (t**6)+(0.3*np.random.randn(2000))
 
     >>> # Create a figure
-    >>> fig = create_2D_density(x, y)
+    >>> fig = create_2d_density(x, y)
 
     >>> # Plot the data
     >>> fig.show()
 
     Example 2: Using Parameters
 
-    >>> from plotly.figure_factory create_2d_density
+    >>> from plotly.figure_factory import create_2d_density
 
     >>> import numpy as np
 
@@ -87,7 +86,7 @@ def create_2d_density(
     ...              (1, 1, 0.2), (0.98,0.98,0.98)]
 
     >>> # Create a figure
-    >>> fig = create_2D_density(x, y, colorscale=colorscale,
+    >>> fig = create_2d_density(x, y, colorscale=colorscale,
     ...       hist_color='rgb(255, 237, 222)', point_size=3)
 
     >>> # Plot the data

packages/python/plotly/plotly/figure_factory/_annotated_heatmap.py

@@ -94,7 +94,6 @@ def create_annotated_heatmap(
 
     >>> fig = ff.create_annotated_heatmap(z)
     >>> fig.show()
-    ```
     """
 
     # Avoiding mutables in the call signature

packages/python/plotly/plotly/figure_factory/_candlestick.py

@@ -125,51 +125,32 @@ def create_candlestick(open, high, low, close, dates=None, direction="both", **k
 
     >>> from plotly.figure_factory import create_candlestick
     >>> from datetime import datetime
+    >>> import pandas as pd
 
-    >>> import pandas.io.data as web
-
-    >>> df = web.DataReader("aapl", 'yahoo', datetime(2007, 10, 1), datetime(2009, 4, 1))
-    >>> fig = create_candlestick(df.Open, df.High, df.Low, df.Close, dates=df.index)
+    >>> df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv')
+    >>> fig = create_candlestick(df['AAPL.Open'], df['AAPL.High'], df['AAPL.Low'], df['AAPL.Close'],
+    ...                          dates=df.index)
     >>> fig.show()
 
-    Example 2: Add text and annotations to the candlestick chart
-
-    >>> fig = create_candlestick(df.Open, df.High, df.Low, df.Close, dates=df.index)
-    >>> # Update the fig - all options here: https://plot.ly/python/reference/#Layout
-    >>> fig['layout'].update({
-        'title': 'The Great Recession',
-        'yaxis': {'title': 'AAPL Stock'},
-        'shapes': [{
-            'x0': '2007-12-01', 'x1': '2007-12-01',
-            'y0': 0, 'y1': 1, 'xref': 'x', 'yref': 'paper',
-            'line': {'color': 'rgb(30,30,30)', 'width': 1}
-        }],
-        'annotations': [{
-            'x': '2007-12-01', 'y': 0.05, 'xref': 'x', 'yref': 'paper',
-            'showarrow': False, 'xanchor': 'left',
-            'text': 'Official start of the recession'
-        }]
-    })
-    >>> fig.show()
+    Example 2: Customize the candlestick colors
 
-    Example 3: Customize the candlestick colors
-
     >>> from plotly.figure_factory import create_candlestick
     >>> from plotly.graph_objs import Line, Marker
     >>> from datetime import datetime
 
-    >>> import pandas.io.data as web
-
-    >>> df = web.DataReader("aapl", 'yahoo', datetime(2008, 1, 1), datetime(2009, 4, 1))
+    >>> import pandas as pd
+    >>> df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv')
 
     >>> # Make increasing candlesticks and customize their color and name
-    >>> fig_increasing = create_candlestick(df.Open, df.High, df.Low, df.Close, dates=df.index,
+    >>> fig_increasing = create_candlestick(df['AAPL.Open'], df['AAPL.High'], df['AAPL.Low'], df['AAPL.Close'],
+    ...     dates=df.index,
     ...     direction='increasing', name='AAPL',
     ...     marker=Marker(color='rgb(150, 200, 250)'),
     ...     line=Line(color='rgb(150, 200, 250)'))
 
     >>> # Make decreasing candlesticks and customize their color and name
-    >>> fig_decreasing = create_candlestick(df.Open, df.High, df.Low, df.Close, dates=df.index,
+    >>> fig_decreasing = create_candlestick(df['AAPL.Open'], df['AAPL.High'], df['AAPL.Low'], df['AAPL.Close'],
+    ...     dates=df.index,
     ...     direction='decreasing',
     ...     marker=Marker(color='rgb(128, 128, 128)'),
     ...     line=Line(color='rgb(128, 128, 128)'))
@@ -178,11 +159,11 @@ def create_candlestick(open, high, low, close, dates=None, direction="both", **k
     >>> fig = fig_increasing
 
     >>> # Add decreasing data with .extend()
-    >>> fig['data'].extend(fig_decreasing['data'])
+    >>> fig.add_trace(fig_decreasing['data']) # doctest: +SKIP
     >>> fig.show()
 
-    Example 4: Candlestick chart with datetime objects
-    
+    Example 3: Candlestick chart with datetime objects
+
     >>> from plotly.figure_factory import create_candlestick
 
     >>> from datetime import datetime
@@ -202,7 +183,6 @@ def create_candlestick(open, high, low, close, dates=None, direction="both", **k
     >>> fig = create_candlestick(open_data, high_data,
     ...     low_data, close_data, dates=dates)
     >>> fig.show()
-
     """
     if dates is not None:
         utils.validate_equal_length(open, high, low, close, dates)

packages/python/plotly/plotly/figure_factory/_dendrogram.py

@@ -58,7 +58,7 @@ def create_dendrogram(
     >>> X = np.random.rand(5,5)
     >>> names = ['Jack', 'Oxana', 'John', 'Chelsea', 'Mark']
     >>> dendro = create_dendrogram(X, orientation='right', labels=names)
-    >>> dendro['layout'].update({'width':700, 'height':500})
+    >>> dendro.update_layout({'width':700, 'height':500}) # doctest: +SKIP
     >>> dendro.show()
 
     Example 3: Dendrogram with Pandas

packages/python/plotly/plotly/figure_factory/_distplot.py

@@ -130,7 +130,7 @@ def create_distplot(
     ...     hist_data, group_labels, rug_text=rug_text_all, bin_size=.2)
 
     >>> # Add title
-    >>> fig['layout'].update(title='Dist Plot')
+    >>> fig.update_layout(title='Dist Plot') # doctest: +SKIP
     >>> fig.show()
 
 
@@ -159,7 +159,7 @@ def create_distplot(
     >>> import pandas as pd
 
     >>> df = pd.DataFrame({'2012': np.random.randn(200),
-    >>>                    '2013': np.random.randn(200)+1})
+    ...                    '2013': np.random.randn(200)+1})
     >>> fig = create_distplot([df[c] for c in df.columns], df.columns)
     >>> fig.show()
     """

packages/python/plotly/plotly/figure_factory/_facet_grid.py

@@ -754,7 +754,8 @@ def create_facet_grid(
 
     >>> import plotly.figure_factory as ff
     >>> import pandas as pd
-    >>> mpg = pd.read_table('https://raw.githubusercontent.com/plotly/datasets/master/mpg_2017.txt')
+    >>> mtcars = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/mtcars.csv')
+    >>> mtcars.cyl = mtcars.cyl.astype(str)
     >>> fig = ff.create_facet_grid(
     ...     mtcars,
     ...     x='mpg',
@@ -770,9 +771,10 @@ def create_facet_grid(
     >>> import plotly.figure_factory as ff
     >>> import pandas as pd
     >>> tips = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/tips.csv')
+    >>> tips.size = tips.size.astype(str)
 
     >>> fig = ff.create_facet_grid(
-    >>>     tips,
+    ...     tips,
     ...     x='total_bill',
     ...     y='tip',
     ...     facet_row='sex',