merge from remote branch

Author: Kully

codegen/datatypes.py

@@ -185,13 +185,37 @@ def _prop_descriptions(self):
     buffer.write(f"""
     def __init__(self""")
 
-    add_constructor_params(buffer, subtype_nodes)
-    header = f"Construct a new {datatype_class} object"
-    add_docstring(buffer, node, header=header)
+    add_constructor_params(buffer,
+                           subtype_nodes,
+                           prepend_extras=['arg'])
+
+    # ### Constructor Docstring ###
+    header = f'Construct a new {datatype_class} object'
+    class_name = (f'plotly.graph_objs'
+                  f'{node.parent_dotpath_str}.'
+                  f'{node.name_datatype_class}')
+
+    extras = [(f'arg',
+               f'dict of properties compatible with this constructor '
+               f'or an instance of {class_name}')]
+
+    add_docstring(buffer, node, header=header, prepend_extras=extras)
 
     buffer.write(f"""
         super({datatype_class}, self).__init__('{node.name_property}')
 
+        # Validate arg
+        # ------------
+        if arg is None:
+            arg = {{}}
+        elif isinstance(arg, self.__class__):
+            arg = arg.to_plotly_json()
+        elif not isinstance(arg, dict):
+            raise ValueError(\"\"\"\\
+The first argument to the {class_name} 
+constructor must be a dict or 
+an instance of {class_name}\"\"\")
+                
         # Import validators
         # -----------------
         from plotly.validators{node.parent_dotpath_str} import (
@@ -210,8 +234,10 @@ def __init__(self""")
         # Populate data dict with properties
         # ----------------------------------""")
     for subtype_node in subtype_nodes:
+        name_prop = subtype_node.name_property
         buffer.write(f"""
-        self.{subtype_node.name_property} = {subtype_node.name_property}""")
+        v = arg.pop('{name_prop}', None)
+        self.{name_prop} = {name_prop} or v""")
 
     # ### Literals ###
     if literal_nodes:
@@ -233,7 +259,7 @@ def __init__(self""")
     
         # Process unknown kwargs
         # ----------------------
-        self._process_kwargs(**kwargs)    
+        self._process_kwargs(**dict(arg, **kwargs))
     """)
 
     # Return source string
@@ -266,7 +292,10 @@ def reindent_validator_description(validator, extra_indent):
         validator.description().strip().split('\n'))
 
 
-def add_constructor_params(buffer, subtype_nodes, extras=()):
+def add_constructor_params(buffer,
+                           subtype_nodes,
+                           prepend_extras=(),
+                           append_extras=()):
     """
     Write datatype constructor params to a buffer
 
@@ -276,17 +305,23 @@ def add_constructor_params(buffer, subtype_nodes, extras=()):
         Buffer to write to
     subtype_nodes : list of PlotlyNode
         List of datatype nodes to be written as constructor params
-    extras : list[str]
+    prepend_extras : list[str]
+        List of extra parameters to include at the beginning of the params
+    append_extras : list[str]
         List of extra parameters to include at the end of the params
     Returns
     -------
     None
     """
+    for extra in prepend_extras:
+        buffer.write(f""",
+            {extra}=None""")
+
     for i, subtype_node in enumerate(subtype_nodes):
         buffer.write(f""",
             {subtype_node.name_property}=None""")
 
-    for extra in extras:
+    for extra in append_extras:
         buffer.write(f""",
             {extra}=None""")
 
@@ -296,7 +331,7 @@ def add_constructor_params(buffer, subtype_nodes, extras=()):
         ):""")
 
 
-def add_docstring(buffer, node, header, extras=()):
+def add_docstring(buffer, node, header, prepend_extras=(), append_extras=()):
     """
     Write docstring for a compound datatype node
 
@@ -309,6 +344,12 @@ def add_docstring(buffer, node, header, extras=()):
     header :
         Top-level header for docstring that will preceded the input node's
         own description. Header should be < 71 characters long
+    prepend_extras :
+        List or tuple of propery name / description pairs that should be
+        included at the beginning of the docstring
+    append_extras :
+        List or tuple of propery name / description pairs that should be
+        included at the end of the docstring
     Returns
     -------
 
@@ -340,11 +381,23 @@ def add_docstring(buffer, node, header, extras=()):
 
     # Write parameter descriptions
     # ----------------------------
+    # Write any prepend extras
+    for p, v in prepend_extras:
+        v_wrapped = '\n'.join(textwrap.wrap(
+            v,
+            width=79 - 12,
+            initial_indent=' ' * 12,
+            subsequent_indent=' ' * 12))
+        buffer.write(f"""
+        {p}
+{v_wrapped}""")
+
+    # Write core docstring
     buffer.write(node.get_constructor_params_docstring(
         indent=8))
 
-    # Write any extras
-    for p, v in extras:
+    # Write any append extras
+    for p, v in append_extras:
         v_wrapped = '\n'.join(textwrap.wrap(
             v,
             width=79-12,

codegen/figure.py

@@ -91,8 +91,9 @@ def __init__(self, data=None, layout=None, frames=None):
     def add_{trace_node.plotly_name}(self""")
 
         # #### Function params####
-        add_constructor_params(buffer, trace_node.child_datatypes,
-                               ['row', 'col'])
+        add_constructor_params(buffer,
+                               trace_node.child_datatypes,
+                               append_extras=['row', 'col'])
 
         # #### Docstring ####
         header = f"Add a new {trace_node.name_datatype_class} trace"
@@ -106,7 +107,7 @@ def add_{trace_node.plotly_name}(self""")
                    'added. Only valid if figure was created using '
                    '`plotly.tools.make_subplots`'))
 
-        add_docstring(buffer, trace_node, header, extras=extras)
+        add_docstring(buffer, trace_node, header, append_extras=extras)
 
         # #### Function body ####
         buffer.write(f"""

plotly/basedatatypes.py

@@ -12,7 +12,7 @@
 from . import offline as pyo
 from _plotly_utils.basevalidators import (
     CompoundValidator, CompoundArrayValidator, BaseDataValidator,
-    BaseValidator
+    BaseValidator, LiteralValidator
 )
 from . import animation
 from .callbacks import (Points, BoxSelector, LassoSelector,
@@ -2734,7 +2734,7 @@ def _build_repr_for_class(props, class_name, parent_path_str=None):
             # complaint indent
             body = '   ' + pprint_res[1:-1].replace('\n', '\n   ')
 
-            repr_str = class_name + '(**{\n ' + body + '\n})'
+            repr_str = class_name + '({\n ' + body + '\n})'
 
         return repr_str
 
@@ -2743,8 +2743,18 @@ def __repr__(self):
         Customize object representation when displayed in the
         terminal/notebook
         """
+
+        # Get all properties
+        props = self._props if self._props is not None else {}
+
+        # Remove literals (These can't be specified in the constructor)
+        props = {p: v for p, v in props.items()
+                 if p in self._validators and
+                 not isinstance(self._validators[p], LiteralValidator)}
+
+        # Build repr string
         repr_str = BasePlotlyType._build_repr_for_class(
-            props=self._props if self._props is not None else {},
+            props=props,
             class_name=self.__class__.__name__,
             parent_path_str=self._parent_path_str)
 

plotly/graph_objs/_area.py

@@ -590,6 +590,7 @@ def _prop_descriptions(self):
 
     def __init__(
         self,
+        arg=None,
         customdata=None,
         customdatasrc=None,
         hoverinfo=None,
@@ -617,6 +618,9 @@ def __init__(
         
         Parameters
         ----------
+        arg
+            dict of properties compatible with this constructor or
+            an instance of plotly.graph_objs.Area
         customdata
             Assigns extra data each datum. This may be useful when
             listening to hover, click and selection events. Note
@@ -689,6 +693,20 @@ def __init__(
         """
         super(Area, self).__init__('area')
 
+        # Validate arg
+        # ------------
+        if arg is None:
+            arg = {}
+        elif isinstance(arg, self.__class__):
+            arg = arg.to_plotly_json()
+        elif not isinstance(arg, dict):
+            raise ValueError(
+                """\
+The first argument to the plotly.graph_objs.Area 
+constructor must be a dict or 
+an instance of plotly.graph_objs.Area"""
+            )
+
         # Import validators
         # -----------------
         from plotly.validators import (area as v_area)
@@ -718,26 +736,46 @@ def __init__(
 
         # Populate data dict with properties
         # ----------------------------------
-        self.customdata = customdata
-        self.customdatasrc = customdatasrc
-        self.hoverinfo = hoverinfo
-        self.hoverinfosrc = hoverinfosrc
-        self.hoverlabel = hoverlabel
-        self.ids = ids
-        self.idssrc = idssrc
-        self.legendgroup = legendgroup
-        self.marker = marker
-        self.name = name
-        self.opacity = opacity
-        self.r = r
-        self.rsrc = rsrc
-        self.selectedpoints = selectedpoints
-        self.showlegend = showlegend
-        self.stream = stream
-        self.t = t
-        self.tsrc = tsrc
-        self.uid = uid
-        self.visible = visible
+        v = arg.pop('customdata', None)
+        self.customdata = customdata or v
+        v = arg.pop('customdatasrc', None)
+        self.customdatasrc = customdatasrc or v
+        v = arg.pop('hoverinfo', None)
+        self.hoverinfo = hoverinfo or v
+        v = arg.pop('hoverinfosrc', None)
+        self.hoverinfosrc = hoverinfosrc or v
+        v = arg.pop('hoverlabel', None)
+        self.hoverlabel = hoverlabel or v
+        v = arg.pop('ids', None)
+        self.ids = ids or v
+        v = arg.pop('idssrc', None)
+        self.idssrc = idssrc or v
+        v = arg.pop('legendgroup', None)
+        self.legendgroup = legendgroup or v
+        v = arg.pop('marker', None)
+        self.marker = marker or v
+        v = arg.pop('name', None)
+        self.name = name or v
+        v = arg.pop('opacity', None)
+        self.opacity = opacity or v
+        v = arg.pop('r', None)
+        self.r = r or v
+        v = arg.pop('rsrc', None)
+        self.rsrc = rsrc or v
+        v = arg.pop('selectedpoints', None)
+        self.selectedpoints = selectedpoints or v
+        v = arg.pop('showlegend', None)
+        self.showlegend = showlegend or v
+        v = arg.pop('stream', None)
+        self.stream = stream or v
+        v = arg.pop('t', None)
+        self.t = t or v
+        v = arg.pop('tsrc', None)
+        self.tsrc = tsrc or v
+        v = arg.pop('uid', None)
+        self.uid = uid or v
+        v = arg.pop('visible', None)
+        self.visible = visible or v
 
         # Read-only literals
         # ------------------
@@ -749,4 +787,4 @@ def __init__(
 
         # Process unknown kwargs
         # ----------------------
-        self._process_kwargs(**kwargs)
+        self._process_kwargs(**dict(arg, **kwargs))