Big refactor of codegen and project output structure

 - plotly/datatypes package is gone
 - codegen object hierarchy directly into plotly/graph_objs.
 - Refactor codegen output hierarchy to be compatible with legacy Figure/Layout/Trace types. e.g. go.Figure, go.Layout, go.Scatter.
 - Codegen deprecated classes as dict/list subclasses with deprecation warnings that point users to which classes to use instead.
 - The entire legacy graph_objs directory is gone (PlotlyDict/PlotlyList/etc.)
 - _plotly_utils package introduced as a package to hold code that should be available during both code generation and runtime. Moved base validators to this package so we can reuse their descriptions in docstrings.  All of the order-dependency of code generation is now gone, and the plotly/ package is not imported. This makes code generation much less fragile to future extension.

Author: Jon M. Mease

.gitignore

@@ -22,7 +22,7 @@ plotly/api/v2/spectacle_presentations.py
 
 plotly/presentation_objs/
 
-plotly/datatypes
+plotly/graph_objs
 
 plotly/validators
 

_plotly_utils/README.md

@@ -0,0 +1,7 @@
+This package is for utilities that are used during code generation
+and at runtime.  The reason for not placing these under the main plotly/
+package is that this avoids the complications of importing the module
+we're generating code into during code generation.
+
+This module must be independent of (it must not import from) both
+plotly/ and codegen/

_plotly_utils/__init__.py

@@ -584,7 +584,8 @@ def numbers_allowed(self):
 
     def description(self):
 
-        named_clrs_str = '\n'.join(textwrap.wrap(', '.join(self.named_colors), width=80, subsequent_indent=' ' * 12))
+        named_clrs_str = '\n'.join(textwrap.wrap(', '.join(
+            self.named_colors), width=79, subsequent_indent=' ' * 12))
 
         valid_color_description = """\
     The '{plotly_name}' property is a color and may be specified as:  
@@ -1090,38 +1091,60 @@ def validate_coerce(self, v):
 class CompoundValidator(BaseValidator):
     def __init__(self, plotly_name, parent_name, data_class, data_docs):
         super().__init__(plotly_name=plotly_name, parent_name=parent_name)
-        self.data_class = data_class
+
+        # Save element class string
+        self.data_class_str = data_class
+        self._data_class = None
         self.data_docs = data_docs
+        self.module_str = CompoundValidator.compute_graph_obj_module_str(
+            self.data_class_str, parent_name)
 
     @staticmethod
-    def get_constructor_params_str(data_class):
-        params_match = re.search("Parameters\n\W*-+\n\W*(.*?)(Returns|$)",
-                                 str(data_class.__init__.__doc__),
-                                 flags=re.DOTALL)
-
-        if params_match is not None:
-            param_descs = params_match.groups()[0]
+    def import_graph_objs_class(data_class_str, module_str):
+        # Import class module
+        module = import_module(module_str)
 
-            # Increase indent by 4 spaces
-            param_descs_indented = ('\n' + ' ' * 4).join(param_descs.split('\n'))
+        # Get class reference
+        return getattr(module, data_class_str)
 
-            return param_descs_indented
+    @staticmethod
+    def compute_graph_obj_module_str(data_class_str, parent_name):
+        if parent_name == 'frame' and data_class_str in ['Data', 'Layout']:
+            # Special case. There are no graph_objs.frame.Data or
+            # graph_objs.frame.Layout classes. These are remapped to
+            # graph_objs.Data and graph_objs.Layout
+
+            parent_parts = parent_name.split('.')
+            module_str = '.'.join(['plotly.graph_objs'] + parent_parts[1:])
+        elif parent_name:
+            module_str = 'plotly.graph_objs.' + parent_name
         else:
-            return ''
+            module_str = 'plotly.graph_objs'
+
+        return  module_str
+
+    @property
+    def data_class(self):
+        if self._data_class is None:
+            self._data_class = CompoundValidator.import_graph_objs_class(
+                self.data_class_str, self.module_str)
+
+        return self._data_class
 
     def description(self):
 
         desc = ("""\
-    The '{plotly_name}' property is an instance of {data_class} 
+    The '{plotly_name}' property is an instance of {class_str} 
     that may be specified as:
-      - An instance of {data_class}
+      - An instance of {module_str}.{class_str}
       - A dict of string/value properties that will be passed to the 
-        {data_class} constructor
+        {class_str} constructor
       
         Supported dict properties:
             {constructor_params_str}"""
                 ).format(plotly_name=self.plotly_name,
-                         data_class=type_str(self.data_class),
+                         class_str=self.data_class_str,
+                         module_str=self.module_str,
                          constructor_params_str=self.data_docs)
 
         return desc
@@ -1150,29 +1173,44 @@ def validate_coerce(self, v):
 class CompoundArrayValidator(BaseValidator):
     def __init__(self, plotly_name, parent_name, element_class, element_docs):
         super().__init__(plotly_name=plotly_name, parent_name=parent_name)
-        self.data_class = element_class
+
+        # Save element class string
+        self.data_class_str = element_class
+        self._data_class = None
+
         self.data_docs = element_docs
+        self.module_str = CompoundValidator.compute_graph_obj_module_str(
+            self.data_class_str, parent_name)
 
     def description(self):
 
         desc = ("""\
-    The '{plotly_name}' property is a tuple of instances of {data_class} that may be specified as:
-      - A list or tuple of instances of {data_class}
-      - A list or tuple of dicts of string/value properties that will be passed to the {data_class} constructor
+    The '{plotly_name}' property is a tuple of instances of {class_str} that may be specified as:
+      - A list or tuple of instances of {module_str}.{class_str}
+      - A list or tuple of dicts of string/value properties that will be passed to the {class_str} constructor
 
         Supported dict properties:
             {constructor_params_str}"""
                 ).format(plotly_name=self.plotly_name,
-                         data_class=type_str(self.data_class),
+                         class_str=self.data_class_str,
+                         module_str=self.module_str,
                          constructor_params_str=self.data_docs)
 
         return desc
 
+    @property
+    def data_class(self):
+        if self._data_class is None:
+            self._data_class = CompoundValidator.import_graph_objs_class(
+                self.data_class_str, self.module_str)
+
+        return self._data_class
+
     def validate_coerce(self, v):
 
         if isinstance(self.data_class, str):
             raise ValueError("Invalid data_class of type 'string': {data_class}"
-                             .format(data_class = self.data_class))
+                             .format(data_class=self.data_class))
 
         if v is None:
             v = ()
@@ -1203,15 +1241,16 @@ def validate_coerce(self, v):
 class BaseDataValidator(BaseValidator):
     def __init__(self, class_map, plotly_name, parent_name):
         super().__init__(plotly_name=plotly_name, parent_name=parent_name)
-        self.class_map = class_map
+        self.class_strs_map = class_map
+        self._class_map = None
 
     def description(self):
 
-        trace_types = str(list(self.class_map.keys()))
+        trace_types = str(list(self.class_strs_map.keys()))
 
         trace_types_wrapped = '\n'.join(textwrap.wrap(trace_types,
                                                       subsequent_indent=' ' * 21,
-                                                      width=80 - 8))
+                                                      width=79 - 8))
 
         desc = ("""\
     The '{plotly_name}' property is a tuple of trace instances that may be specified as:
@@ -1228,6 +1267,20 @@ def description(self):
 
         return desc
 
+    @property
+    def class_map(self):
+        if self._class_map is None:
+
+            # Initialize class map
+            self._class_map = {}
+
+            # Import trace classes
+            trace_module = import_module('plotly.graph_objs')
+            for k, class_str in self.class_strs_map.items():
+                self._class_map[k] = getattr(trace_module, class_str)
+
+        return self._class_map
+
     def validate_coerce(self, v):
 
         if v is None: