Improve frames support in graph_objs.py.

This does the following:

* Allow object-or-string in frames array
* Refuse `frames` in frame object if nested
* Loosely associate a frames entry with `Figure`
* Tests this functionality

Author: theengineear

plotly/graph_objs/graph_objs.py

@@ -787,7 +787,7 @@ def create(object_name, *args, **kwargs):
 
         # We patch Figure and Data, so they actually require the subclass.
         class_name = graph_reference.OBJECT_NAME_TO_CLASS_NAME.get(object_name)
-        if class_name in ['Figure', 'Data']:
+        if class_name in ['Figure', 'Data', 'Frames']:
             return globals()[class_name](*args, **kwargs)
         else:
             kwargs['_name'] = object_name
@@ -1097,7 +1097,7 @@ class Figure(PlotlyDict):
     """
     Valid attributes for 'figure' at path [] under parents ():
     
-        ['data', 'layout']
+        ['data', 'frames', 'layout']
     
     Run `<figure-object>.help('attribute')` on any of the above.
     '<figure-object>' is the object at []
@@ -1108,22 +1108,7 @@ class Figure(PlotlyDict):
     def __init__(self, *args, **kwargs):
         super(Figure, self).__init__(*args, **kwargs)
         if 'data' not in self:
-            self.data = GraphObjectFactory.create('data', _parent=self,
-                                                  _parent_key='data')
-
-    # 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, self).__setitem__(key, value, **kwargs)
-
-    def _get_valid_attributes(self):
-        super(Figure, 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
+            self.data = Data(_parent=self, _parent_key='data')
 
     def get_data(self, flatten=False):
         """
@@ -1241,8 +1226,45 @@ class Font(PlotlyDict):
     _name = 'font'
 
 
-class Frames(dict):
-    pass
+class Frames(PlotlyList):
+    """
+    Valid items for 'frames' at path [] under parents ():
+        ['Figure']
+
+    """
+    _name = 'frames'
+
+    def _value_to_graph_object(self, index, value, _raise=True):
+        if isinstance(value, six.string_types):
+            return value
+        return super(Frames, self)._value_to_graph_object(index, value,
+                                                          _raise=_raise)
+
+    def to_string(self, level=0, indent=4, eol='\n',
+                  pretty=True, max_chars=80):
+        """Get formatted string by calling `to_string` on children items."""
+        if not len(self):
+            return "{name}()".format(name=self._get_class_name())
+        string = "{name}([{eol}{indent}".format(
+            name=self._get_class_name(),
+            eol=eol,
+            indent=' ' * indent * (level + 1))
+        for index, entry in enumerate(self):
+            if isinstance(entry, six.string_types):
+                string += repr(entry)
+            else:
+                string += entry.to_string(level=level+1,
+                                          indent=indent,
+                                          eol=eol,
+                                          pretty=pretty,
+                                          max_chars=max_chars)
+            if index < len(self) - 1:
+                string += ",{eol}{indent}".format(
+                    eol=eol,
+                    indent=' ' * indent * (level + 1))
+        string += (
+            "{eol}{indent}])").format(eol=eol, indent=' ' * indent * level)
+        return string
 
 
 class Heatmap(PlotlyDict):

plotly/graph_reference.py

@@ -33,7 +33,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},
+    'Frames': {'object_name': 'frames', 'base_type': list},
     'Heatmap': {'object_name': 'heatmap', 'base_type': dict},
     'Histogram': {'object_name': 'histogram', 'base_type': dict},
     'Histogram2d': {'object_name': 'histogram2d', 'base_type': dict},
@@ -168,6 +168,10 @@ def get_valid_attributes(object_name, parent_object_names=()):
             if key not in GRAPH_REFERENCE['defs']['metaKeys']:
                 valid_attributes.add(key)
 
+    if object_name == 'figure' and parent_object_names:
+        # A frame cannot itself contain a frames array.
+        valid_attributes.remove('frames')
+
     return valid_attributes
 
 
@@ -410,8 +414,11 @@ def _patch_objects():
                          'attribute_paths': layout_attribute_paths,
                          'additional_attributes': {}}
 
-    figure_attributes = {'layout': {'role': 'object'},
-                         'data': {'role': 'object', '_isLinkedToArray': True}}
+    figure_attributes = {
+        'layout': {'role': 'object'},
+        'data': {'role': 'object', '_isLinkedToArray': True},
+        'frames': {'role': 'object', '_isLinkedToArray': True}
+    }
     OBJECTS['figure'] = {'meta_paths': [],
                          'attribute_paths': [],
                          'additional_attributes': figure_attributes}
@@ -446,6 +453,7 @@ def _get_arrays():
 def _patch_arrays():
     """Adds information on our eventual Data array."""
     ARRAYS['data'] = {'meta_paths': [('traces', )], 'items': list(TRACE_NAMES)}
+    ARRAYS['frames'] = {'meta_paths': [], 'items': ['figure']}
 
 
 def _get_classes():

plotly/tests/test_core/test_graph_objs/test_figure.py

@@ -0,0 +1,37 @@
+from __future__ import absolute_import
+
+from unittest import TestCase
+
+from plotly import exceptions
+from plotly.graph_objs import Figure
+
+
+class FigureTest(TestCase):
+
+    def test_instantiation(self):
+
+        native_figure = {
+            'data': [],
+            'layout': {},
+            'frames': []
+        }
+
+        Figure(native_figure)
+        Figure()
+
+    def test_access_top_level(self):
+
+        # Figure is special, we define top-level objects that always exist.
+
+        self.assertEqual(Figure().data, [])
+        self.assertEqual(Figure().layout, {})
+        self.assertEqual(Figure().frames, [])
+
+    def test_nested_frames(self):
+        with self.assertRaisesRegexp(exceptions.PlotlyDictKeyError, 'frames'):
+            Figure({'frames': [{'frames': []}]})
+
+        figure = Figure()
+        figure.frames = [{}]
+        with self.assertRaisesRegexp(exceptions.PlotlyDictKeyError, 'frames'):
+            figure.frames[0].frames = []

plotly/tests/test_core/test_graph_objs/test_frames.py

@@ -0,0 +1,39 @@
+from __future__ import absolute_import
+
+from unittest import TestCase
+
+from plotly import exceptions
+from plotly.graph_objs import Frames
+
+
+class FramesTest(TestCase):
+
+    def test_instantiation(self):
+
+        native_frames = [{}, {'data': []}, 'foo', {'data': [], 'layout': {}}]
+
+        Frames(native_frames)
+        Frames()
+
+    def test_string_frame(self):
+        frames = Frames()
+        frames.append({})
+        frames.append('foobar')
+        self.assertEqual(frames[1], 'foobar')
+        self.assertEqual(frames.to_string(),
+                         "Frames([\n"
+                         "    Figure(\n"
+                         "        data=Data()\n"
+                         "    ),\n"
+                         "    'foobar'\n"
+                         "])")
+
+    def test_non_string_frame(self):
+        frames = Frames()
+        frames.append({})
+
+        with self.assertRaises(exceptions.PlotlyListEntryError):
+            frames.append([])
+
+        with self.assertRaises(exceptions.PlotlyListEntryError):
+            frames.append(0)

update_graph_objs.py

@@ -1,3 +1,5 @@
+from __future__ import print_function
+
 from plotly.graph_objs import graph_objs_tools
 from plotly.graph_reference import ARRAYS, CLASSES
 
@@ -35,22 +37,7 @@ def print_figure_patch(f):
     def __init__(self, *args, **kwargs):
         super(Figure, self).__init__(*args, **kwargs)
         if 'data' not in self:
-            self.data = GraphObjectFactory.create('data', _parent=self,
-                                                  _parent_key='data')
-
-    # 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, self).__setitem__(key, value, **kwargs)
-
-    def _get_valid_attributes(self):
-        super(Figure, 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
+            self.data = Data(_parent=self, _parent_key='data')
 
     def get_data(self, flatten=False):
         """
@@ -221,6 +208,45 @@ def get_data(self, flatten=False):
     )
 
 
+def print_frames_patch(f):
+    """Print a patch to our Frames object into the given open file."""
+    print(
+        '''
+    def _value_to_graph_object(self, index, value, _raise=True):
+        if isinstance(value, six.string_types):
+            return value
+        return super(Frames, self)._value_to_graph_object(index, value,
+                                                          _raise=_raise)
+
+    def to_string(self, level=0, indent=4, eol='\\n',
+                  pretty=True, max_chars=80):
+        """Get formatted string by calling `to_string` on children items."""
+        if not len(self):
+            return "{name}()".format(name=self._get_class_name())
+        string = "{name}([{eol}{indent}".format(
+            name=self._get_class_name(),
+            eol=eol,
+            indent=' ' * indent * (level + 1))
+        for index, entry in enumerate(self):
+            if isinstance(entry, six.string_types):
+                string += repr(entry)
+            else:
+                string += entry.to_string(level=level+1,
+                                          indent=indent,
+                                          eol=eol,
+                                          pretty=pretty,
+                                          max_chars=max_chars)
+            if index < len(self) - 1:
+                string += ",{eol}{indent}".format(
+                    eol=eol,
+                    indent=' ' * indent * (level + 1))
+        string += (
+            "{eol}{indent}])").format(eol=eol, indent=' ' * indent * level)
+        return string
+''', file=f, end=''
+    )
+
+
 def print_class(name, f):
     class_dict = CLASSES[name]
     print('\n', file=f)
@@ -250,6 +276,8 @@ def print_class(name, f):
         print_figure_patch(f)
     elif name == 'Data':
         print_data_patch(f)
+    elif name == 'Frames':
+        print_frames_patch(f)
 
 copied_lines = get_non_generated_file_lines()
 with open('./plotly/graph_objs/graph_objs.py', 'w') as graph_objs_file: