Animations/Frames in Python API

plotly/graph_objs/graph_objs.py

@@ -836,6 +836,22 @@ def __init__(self, *args, **kwargs):
                                                   _parent_key='data')
     figure_class.__init__ = __init__
 
+    # TODO better integrate frames into Figure - #604
+    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()
+        # TODO better integrate frames into Figure - #604
+        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/grid_objs/grid_objs.py

@@ -118,29 +118,96 @@ class Grid(MutableSequence):
     py.plot([trace], filename='graph from grid')
     ```
     """
-    def __init__(self, iterable_of_columns):
+    def __init__(self, columns_or_json, grid_id=None):
         """
-        Initialize a grid with an iterable of
-        `plotly.grid_objs.Column objects
+        Initialize a grid with an iterable of `plotly.grid_objs.Column`
+        objects or a json/dict describing a grid. See second usage example
+        below for the necessary structure of the dict.
 
-        Usage example:
+        :param (str|bool) grid_id: should not be accessible to users. Default
+            is 'None' but if a grid is retrieved via `py.get_grid()` then the
+            retrieved grid response will contain the grid_id which will be
+            necessary to set `self.id` and `self._columns.id` below.
+
+        Example from iterable of columns:
         ```
         column_1 = Column([1, 2, 3], 'time')
         column_2 = Column([4, 2, 5], 'voltage')
         grid = Grid([column_1, column_2])
         ```
+        Example from json grid
+        ```
+        grid_json = {
+            'cols': {
+                'time': {'data': [1, 2, 3], 'order': 0, 'uid': '4cd7fc'},
+                'voltage': {'data': [4, 2, 5], 'order': 1, 'uid': u'2744be'}
+            }
+        }
+        grid = Grid(grid_json)
+        ```
         """
-
         # TODO: verify that columns are actually columns
+        if isinstance(columns_or_json, dict):
+            # check that grid_id is entered
+            if grid_id is None:
+                raise exceptions.PlotlyError(
+                    "If you are manually converting a raw json/dict grid "
+                    "into a Grid instance, you must ensure that make "
+                    "'grid_id' is set to your file ID. This looks like "
+                    "'username:187'."
+                )
+            # TODO: verify that grid_id is a correct fid if a string
+            self.id = grid_id
+
+            # check if 'cols' is a root key
+            if 'cols' not in columns_or_json:
+                raise exceptions.PlotlyError(
+                    "'cols' must be a root key in your json grid."
+                )
+
+            # check if 'data', 'order' and 'uid' are not in columns
+            grid_col_keys = ['data', 'order', 'uid']
+
+            for column_name in columns_or_json['cols']:
+                for key in grid_col_keys:
+                    if key not in columns_or_json['cols'][column_name]:
+                        raise exceptions.PlotlyError(
+                            "Each column name of your dictionary must have "
+                            "'data', 'order' and 'uid' as keys."
+                        )
+            # collect and sort all orders in case orders do not start
+            # at zero or there are jump discontinuities between them
+            all_orders = []
+            for column_name in columns_or_json['cols'].keys():
+                all_orders.append(columns_or_json['cols'][column_name]['order'])
+            all_orders.sort()
+
+            # put columns in order in a list
+            ordered_columns = []
+            for order in all_orders:
+                for column_name in columns_or_json['cols'].keys():
+                    if columns_or_json['cols'][column_name]['order'] == order:
+                        break
+
+                ordered_columns.append(Column(
+                    columns_or_json['cols'][column_name]['data'],
+                    column_name)
+                )
+            self._columns = ordered_columns
+
+            # fill in uids
+            for column in self:
+                column.id = self.id + ':' + columns_or_json['cols'][column.name]['uid']
 
-        column_names = [column.name for column in iterable_of_columns]
-        duplicate_name = utils.get_first_duplicate(column_names)
-        if duplicate_name:
-            err = exceptions.NON_UNIQUE_COLUMN_MESSAGE.format(duplicate_name)
-            raise exceptions.InputError(err)
+        else:
+            column_names = [column.name for column in columns_or_json]
+            duplicate_name = utils.get_first_duplicate(column_names)
+            if duplicate_name:
+                err = exceptions.NON_UNIQUE_COLUMN_MESSAGE.format(duplicate_name)
+                raise exceptions.InputError(err)
 
-        self._columns = list(iterable_of_columns)
-        self.id = ''
+            self._columns = list(columns_or_json)
+            self.id = ''
 
     def __repr__(self):
         return self._columns.__repr__()
@@ -187,3 +254,17 @@ def get_column(self, column_name):
         for column in self._columns:
             if column.name == column_name:
                 return column
+
+    def get_fid_uid(self, column_name):
+        """
+        Return uid of given column name in the grid by column name.
+
+        Returns an empty string if either the column name does not exist in
+        the grid or if the id of the specified column has the empty string id.
+        """
+        uid = ''
+        for column in self._columns:
+            if column.name == column_name:
+                uid = column.id
+                break
+        return uid

plotly/offline/offline.py

@@ -162,8 +162,16 @@ 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
+    # TODO - add validation for frames in call - #605
+    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 +193,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',
@@ -225,11 +235,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 '')

plotly/plotly/__init__.py

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

plotly/plotly/plotly.py

@@ -33,6 +33,7 @@
 from plotly.session import (sign_in, update_session_plot_options,
                             get_session_plot_options, get_session_credentials,
                             get_session_config)
+from plotly.grid_objs import Grid, Column
 
 __all__ = None
 
@@ -238,6 +239,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'])
@@ -383,6 +385,7 @@ def get_figure(file_owner_or_url, file_id=None, raw=False):
         raise exceptions.PlotlyError(
             "The 'file_id' argument must be a non-negative number."
         )
+
     response = requests.get(plotly_rest_url + resource,
                             headers=headers,
                             verify=get_config()['plotly_ssl_verification'])
@@ -938,6 +941,7 @@ def upload(cls, grid, filename,
 
         paths = filename.split('/')
         parent_path = '/'.join(paths[0:-1])
+
         filename = paths[-1]
 
         if parent_path != '':
@@ -958,6 +962,7 @@ def upload(cls, grid, filename,
             payload['parent_path'] = parent_path
 
         upload_url = _api_v2.api_url('grids')
+
         req = requests.post(upload_url, data=payload,
                             headers=_api_v2.headers(),
                             verify=get_config()['plotly_ssl_verification'])
@@ -1299,7 +1304,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:
@@ -1449,6 +1454,81 @@ def _send_to_plotly(figure, **plot_options):
     return r
 
 
+def get_grid(grid_url, raw=False):
+    """
+    Returns a JSON figure representation for the specified grid.
+
+    :param (bool) raw: if False, will output a Grid instance of the JSON grid
+    being retrieved. If True, raw JSON will be returned.
+    """
+    credentials = get_credentials()
+    validate_credentials(credentials)
+    username, api_key = credentials['username'], credentials['api_key']
+    headers = {'plotly-username': username,
+               'plotly-apikey': api_key,
+               'plotly-version': version.__version__,
+               'plotly-platform': 'python'}
+    upload_url = _api_v2.api_url('grids')
+
+    # extract path in grid url
+    url_path = six.moves.urllib.parse.urlparse(grid_url)[2][2:]
+    if url_path[-1] == '/':
+        url_path = url_path[0: -1]
+    url_path = url_path.replace('/', ':')
+
+    meta_get_url = upload_url + '/' + url_path
+    get_url = meta_get_url + '/content'
+
+    r = requests.get(get_url, headers=headers)
+    json_res = json.loads(r.text)
+
+    # make request to grab the grid id (fid)
+    r_meta = requests.get(meta_get_url, headers=headers)
+    json_res_meta = json.loads(r_meta.text)
+    retrieved_grid_id = json_res_meta['fid']
+
+    if raw is False:
+        return Grid(json_res, retrieved_grid_id)
+    else:
+        return json_res
+
+
+def create_animations(figure, filename=None, sharing='public'):
+    """
+    Put description here.
+
+    For parameter descriptions, see the doc string for `py.plot()`.
+    `private` is not supported currently for param 'sharing'. Returns the
+    url for the plot if response is ok.
+    """
+    credentials = get_credentials()
+    validate_credentials(credentials)
+    username, api_key = credentials['username'], credentials['api_key']
+    auth = HTTPBasicAuth(str(username), str(api_key))
+    headers = {'Plotly-Client-Platform': 'python'}
+
+    json = {
+        'figure': figure,
+        'world_readable': 'true'
+    }
+
+    # set filename if specified
+    if filename:
+        json['filename'] = filename
+
+    # set sharing
+    if sharing == 'public':
+        json['world_readable'] = 'true'
+    elif sharing == 'private':
+        json['world_readable'] = 'false'
+
+    api_url = _api_v2.api_url('plots')
+    r = requests.post(api_url, auth=auth, headers=headers, json=json)
+
+    json_r = json.loads(r.text)
+    return json_r['file']['web_url']
+
+
 def _open_url(url):
     try:
         from webbrowser import open as wbopen

plotly/tests/test_core/test_graph_objs/test_graph_objs.py

@@ -6,7 +6,7 @@
 OLD_CLASS_NAMES = ['AngularAxis', 'Annotation', 'Annotations', 'Area',
                    'Bar', 'Box', 'ColorBar', 'Contour', 'Contours',
                    'Data', 'ErrorX', 'ErrorY', 'ErrorZ', 'Figure',
-                   'Font', 'Heatmap', 'Histogram', 'Histogram2d',
+                   'Font', 'Frames', 'Heatmap', 'Histogram', 'Histogram2d',
                    'Histogram2dContour', 'Layout', 'Legend', 'Line',
                    'Margin', 'Marker', 'RadialAxis', 'Scatter',
                    'Scatter3d', 'Scene', 'Stream', 'Surface', 'Trace',