Animations/Frames in Python API

plotly/graph_objs/graph_objs.py

@@ -836,6 +836,20 @@ def __init__(self, *args, **kwargs):
                                                   _parent_key='data')
     figure_class.__init__ = __init__
 
+    def __setitem__(self, key, value, **kwargs):
+        if key == 'frames':
+            super(PlotlyDict, self).__setitem__(key, value)
+        else:
+            super(figure_class, self).__setitem__(key, value, **kwargs)
+    figure_class.__setitem__ = __setitem__
+
+    def _get_valid_attributes(self):
+        super(figure_class, self)._get_valid_attributes()
+        if 'frames' not in self._valid_attributes:
+            self._valid_attributes.add('frames')
+        return self._valid_attributes
+    figure_class._get_valid_attributes = _get_valid_attributes
+
     def get_data(self, flatten=False):
         """
         Returns the JSON for the plot with non-data elements stripped.

plotly/graph_reference.py

@@ -38,6 +38,7 @@
     'ErrorZ': {'object_name': 'error_z', 'base_type': dict},
     'Figure': {'object_name': 'figure', 'base_type': dict},
     'Font': {'object_name': 'font', 'base_type': dict},
+    'Frames': {'object_name': 'frames', 'base_type': dict},
     'Heatmap': {'object_name': 'heatmap', 'base_type': dict},
     'Histogram': {'object_name': 'histogram', 'base_type': dict},
     'Histogram2d': {'object_name': 'histogram2d', 'base_type': dict},
@@ -87,7 +88,6 @@ def get_graph_reference():
 
     graph_reference_url = '{}{}?sha1={}'.format(plotly_api_domain,
                                                 GRAPH_REFERENCE_PATH, sha1)
-
     try:
         response = requests.get(graph_reference_url,
                                 timeout=GRAPH_REFERENCE_DOWNLOAD_TIMEOUT)
@@ -196,11 +196,9 @@ def get_valid_attributes(object_name, parent_object_names=()):
     # These are for documentation and quick lookups. They're just strings.
     valid_attributes = set()
     for attributes_dict in attributes.values():
-
         for key, val in attributes_dict.items():
             if key not in GRAPH_REFERENCE['defs']['metaKeys']:
                 valid_attributes.add(key)
-
         deprecated_attributes = attributes_dict.get('_deprecated', {})
         for key, val in deprecated_attributes.items():
             if key not in GRAPH_REFERENCE['defs']['metaKeys']:

plotly/offline/offline.py

@@ -162,8 +162,15 @@ def init_notebook_mode(connected=False):
 
 def _plot_html(figure_or_data, config, validate, default_width,
                default_height, global_requirejs):
-
-    figure = tools.return_figure_from_figure_or_data(figure_or_data, validate)
+    # force no validation if frames is in the call
+    if 'frames' in figure_or_data:
+        figure = tools.return_figure_from_figure_or_data(
+            figure_or_data, False
+        )
+    else:
+        figure = tools.return_figure_from_figure_or_data(
+            figure_or_data, validate
+        )
 
     width = figure.get('layout', {}).get('width', default_width)
     height = figure.get('layout', {}).get('height', default_height)
@@ -185,6 +192,8 @@ def _plot_html(figure_or_data, config, validate, default_width,
     plotdivid = uuid.uuid4()
     jdata = json.dumps(figure.get('data', []), cls=utils.PlotlyJSONEncoder)
     jlayout = json.dumps(figure.get('layout', {}), cls=utils.PlotlyJSONEncoder)
+    if 'frames' in figure_or_data:
+        jframes = json.dumps(figure.get('frames', {}), cls=utils.PlotlyJSONEncoder)
 
     configkeys = (
     'editable',
@@ -224,11 +233,30 @@ def _plot_html(figure_or_data, config, validate, default_width,
         link_text = link_text.replace('plot.ly', link_domain)
         config['linkText'] = link_text
 
-    script = 'Plotly.newPlot("{id}", {data}, {layout}, {config})'.format(
-        id=plotdivid,
-        data=jdata,
-        layout=jlayout,
-        config=jconfig)
+    if 'frames' in figure_or_data:
+        script = '''
+        Plotly.plot(
+            '{id}',
+            {data},
+            {layout},
+            {config}
+        ).then(function () {add_frames}).then(function(){animate})
+        '''.format(
+            id=plotdivid,
+            data=jdata,
+            layout=jlayout,
+            config=jconfig,
+            add_frames="{" + "return Plotly.addFrames('{id}',{frames}".format(
+                id=plotdivid, frames=jframes
+            ) + ");}",
+            animate="{" + "Plotly.animate('{id}');".format(id=plotdivid) + "}"
+        )
+    else:
+        script = 'Plotly.newPlot("{id}", {data}, {layout}, {config})'.format(
+            id=plotdivid,
+            data=jdata,
+            layout=jlayout,
+            config=jconfig)
 
     optional_line1 = ('require(["plotly"], function(Plotly) {{ '
                       if global_requirejs else '')
@@ -252,6 +280,7 @@ def _plot_html(figure_or_data, config, validate, default_width,
 
     return plotly_html_div, plotdivid, width, height
 
+
 def iplot(figure_or_data, show_link=True, link_text='Export to plot.ly',
           validate=True, image=None, filename='plot_image', image_width=800,
           image_height=600):
@@ -321,10 +350,10 @@ def iplot(figure_or_data, show_link=True, link_text='Export to plot.ly',
                              )
         # if image is given, and is a valid format, we will download the image
         script = get_image_download_script('iplot').format(format=image,
-                                                       width=image_width,
-                                                       height=image_height,
-                                                       filename=filename,
-                                                       plot_id=plotdivid)
+                                                           width=image_width,
+                                                           height=image_height,
+                                                           filename=filename,
+                                                           plot_id=plotdivid)
         # allow time for the plot to draw
         time.sleep(1)
         # inject code to download an image of the plot

plotly/plotly/__init__.py

@@ -21,5 +21,6 @@
     grid_ops,
     meta_ops,
     file_ops,
-    get_config
+    get_config,
+    create_animations
 )

plotly/plotly/plotly.py

@@ -210,7 +210,6 @@ def plot(figure_or_data, validate=True, **plot_options):
 
     """
     figure = tools.return_figure_from_figure_or_data(figure_or_data, validate)
-
     for entry in figure['data']:
         if ('type' in entry) and (entry['type'] == 'scattergl'):
             continue
@@ -239,6 +238,7 @@ def plot(figure_or_data, validate=True, **plot_options):
 
     plot_options = _plot_option_logic(plot_options)
     res = _send_to_plotly(figure, **plot_options)
+
     if res['error'] == '':
         if plot_options['auto_open']:
             _open_url(res['url'])
@@ -1300,7 +1300,7 @@ def response_handler(cls, response):
                     "Plotly On-Premise server to request against this endpoint or "
                     "this endpoint may not be available yet.\nQuestions? "
                     "Visit community.plot.ly, contact your plotly administrator "
-                    "or upgrade to a Pro account for 1-1 help: https://goo.gl/1YUVu9 " 
+                    "or upgrade to a Pro account for 1-1 help: https://goo.gl/1YUVu9 "
                     .format(url=get_config()['plotly_api_domain'])
                 )
             else:
@@ -1400,9 +1400,6 @@ def add_share_key_to_url(plot_url, attempt=0):
 
 
 def _send_to_plotly(figure, **plot_options):
-    """
-
-    """
     fig = tools._replace_newline(figure)  # does not mutate figure
     data = json.dumps(fig['data'] if 'data' in fig else [],
                       cls=utils.PlotlyJSONEncoder)
@@ -1414,8 +1411,7 @@ def _send_to_plotly(figure, **plot_options):
                              fileopt=plot_options['fileopt'],
                              world_readable=plot_options['world_readable'],
                              sharing=plot_options['sharing'],
-                             layout=fig['layout'] if 'layout' in fig
-                             else {}),
+                             layout=fig['layout'] if 'layout' in fig else {}),
                         cls=utils.PlotlyJSONEncoder)
 
     # TODO: It'd be cool to expose the platform for RaspPi and others
@@ -1427,12 +1423,15 @@ def _send_to_plotly(figure, **plot_options):
                    origin='plot',
                    kwargs=kwargs)
 
-    url = get_config()['plotly_domain'] + "/clientresp"
+    if 'frames' in fig:
+        r = create_animations(fig, kwargs, payload)
+    else:
+        url = get_config()['plotly_domain'] + "/clientresp"
 
-    r = requests.post(url, data=payload,
-                      verify=get_config()['plotly_ssl_verification'])
-    r.raise_for_status()
-    r = json.loads(r.text)
+        r = requests.post(url, data=payload,
+                          verify=get_config()['plotly_ssl_verification'])
+        r.raise_for_status()
+        r = json.loads(r.text)
 
     if 'error' in r and r['error'] != '':
         raise exceptions.PlotlyError(r['error'])
@@ -1454,6 +1453,129 @@ def _send_to_plotly(figure, **plot_options):
     return r
 
 
+def create_animations(fig, kwargs, payload):
+    """
+    Makes a post to GRIDS and PLOTS if frames is in the figure.
+
+    This function bypasses the current '/clientresp' route  of making a POST
+    request to return back a url. Instead, the V2 REST API is used if frames
+    is part of the figure's keys. Currently, 'error', 'message' and 'warning'
+    are hard codded to the empty string.
+    """
+    url_v2_plot = "https://api.plot.ly/v2/plots"
+    url_v2_grid = "https://api.plot.ly/v2/grids"
+    auth = HTTPBasicAuth(str(payload['un']), str(payload['key']))
+    headers = {'Plotly-Client-Platform': 'python'}
+
+    # add layout if not in fig
+    if 'layout' not in fig:
+        fig['layout'] = {}
+
+    # make a copy of fig
+    fig_with_uids = copy.deepcopy(fig)
+
+    # make grid
+    cols_dict = {}
+    frames_cols_dict = {}
+    counter = 0
+    trace_num = 0
+    for trace in fig['data']:
+        for var in ['x', 'y']:
+            if 'name' in trace:
+                cols_dict["{name}, {x_or_y}".format(name=trace['name'],
+                                                    x_or_y=var)] = {
+                    "data": list(trace[var]), "order": counter
+                }
+            else:
+                cols_dict["Trace {num}, {x_or_y}".format(num=trace_num,
+                                                         x_or_y=var)] = {
+                    "data": list(trace[var]), "order": counter
+                }
+            counter += 1
+        trace_num += 1
+
+    # add frames data to grid
+    for j in range(len(fig['frames'])):
+        for var in ['x', 'y']:
+            if 'name' in fig['frames'][j]['data']:
+                cols_dict["{name}, {x_or_y}".format(
+                    name=fig['frames'][j]['data'][0]['name'], x_or_y=var
+                    )] = {
+                    "data": list(fig['frames'][j]['data'][0][var]),
+                    "order": counter
+                }
+            else:
+                cols_dict["Trace {num}, {x_or_y}".format(
+                    num=trace_num, x_or_y=var
+                    )] = {
+                    "data": list(fig['frames'][j]['data'][0][var]),
+                    "order": counter
+                }
+            counter += 1
+        trace_num += 1
+
+    grid_info = {
+        "data": {"cols": cols_dict},
+        "world_readable": True
+    }
+
+    r = requests.post(url_v2_grid, auth=auth,
+                      headers=headers, json=grid_info)
+    r_dict = json.loads(r.text)
+
+    # make plot
+    fid = r_dict['file']['fid']
+    cols_index = 0
+    for trace in fig_with_uids['data']:
+        if 'x' in trace:
+            del trace['x']
+        if 'y' in trace:
+            del trace['y']
+
+        trace["xsrc"] = "{fid}:{idlocal}".format(
+            fid=fid, idlocal=r_dict['file']['cols'][cols_index]['uid']
+        )
+        trace["ysrc"] = "{fid}:{idlocal}".format(
+            fid=fid, idlocal=r_dict['file']['cols'][cols_index + 1]['uid']
+        )
+        cols_index += 2
+
+    # replace data in frames by grid ids
+    for j in range(len(fig['frames'])):
+        if 'x' in fig_with_uids['frames'][j]['data'][0]:
+            del fig_with_uids['frames'][j]['data'][0]['x']
+        if 'y' in fig_with_uids['frames'][j]['data'][0]:
+            del fig_with_uids['frames'][j]['data'][0]['y']
+
+        fig_with_uids['frames'][j]['data'][0]["xsrc"] = "{fid}:{idlocal}".format(
+            fid=fid, idlocal=r_dict['file']['cols'][cols_index]['uid']
+        )
+        fig_with_uids['frames'][j]['data'][0]["ysrc"] = "{fid}:{idlocal}".format(
+            fid=fid, idlocal=r_dict['file']['cols'][cols_index + 1]['uid']
+        )
+        cols_index += 2
+
+    plots_info = {
+        "figure": fig_with_uids,
+        "world_readable": json.loads(kwargs)['world_readable']
+    }
+
+    r = requests.post(url_v2_plot, auth=auth,
+                      headers=headers, json=plots_info)
+
+    r_json = json.loads(r.text)
+
+    r_dict = {
+        'error': '',
+        'filename': json.loads(kwargs)['filename'],
+        'message': '',
+        'url': r_json['file']['web_url'],
+        'warning': ''
+    }
+
+    return r_dict
+
+
 def _open_url(url):
     try:
         from webbrowser import open as wbopen