full_figure_for_development

nicolaskruchten · nicolaskruchten · commit 732be17e7ac6 · 2020-08-31T22:18:43.000-04:00
diff --git a/packages/python/plotly/plotly/basedatatypes.py b/packages/python/plotly/plotly/basedatatypes.py
@@ -1104,7 +1104,7 @@ def _add_annotation_like(
             if refs[0].subplot_type != "xy":
                 raise ValueError(
                     """
-Cannot add {prop_singular} to subplot at position ({r}, {c}) because subplot 
+Cannot add {prop_singular} to subplot at position ({r}, {c}) because subplot
 is of type {subplot_type}.""".format(
                         prop_singular=prop_singular,
                         r=row,
@@ -2896,6 +2896,35 @@ def to_json(self, *args, **kwargs):
 
         return pio.to_json(self, *args, **kwargs)
 
+    def full_figure_for_development(self, warn=True, as_dict=False):
+        """
+        Compute default values for all attributes not specified in the input figure and
+        returns the output as a "full" figure. This function calls Plotly.js via Kaleido
+        to populate unspecified attributes. This function is intended for interactive use
+        during development to learn more about how Plotly.js computes default values and is
+        not generally necessary or recommended for production use.
+
+        Parameters
+        ----------
+        fig:
+            Figure object or dict representing a figure
+
+        warn: bool
+            If False, suppress warnings about not using this in production.
+
+        as_dict: bool
+            If True, output is a dict with some keys that go.Figure can't parse.
+            If False, output is a go.Figure with unparseable keys skipped.
+
+        Returns
+        -------
+        plotly.graph_objects.Figure or dict
+            The full figure
+        """
+        import plotly.io as pio
+
+        return pio.full_figure_for_development(self, warn, as_dict)
+
     def write_json(self, *args, **kwargs):
         """
         Convert a figure to JSON and write it to a file or writeable
diff --git a/packages/python/plotly/plotly/io/__init__.py b/packages/python/plotly/plotly/io/__init__.py
@@ -2,7 +2,7 @@
 import sys
 
 if sys.version_info < (3, 7):
-    from ._kaleido import to_image, write_image
+    from ._kaleido import to_image, write_image, full_figure_for_development
     from . import orca, kaleido
     from ._json import to_json, from_json, read_json, write_json
     from ._templates import templates, to_templated
@@ -25,6 +25,7 @@
         "renderers",
         "show",
         "base_renderers",
+        "full_figure_for_development",
     ]
 else:
     __all__, __getattr__, __dir__ = relative_import(
@@ -33,6 +34,7 @@
         [
             "._kaleido.to_image",
             "._kaleido.write_image",
+            "._kaleido.full_figure_for_development",
             "._json.to_json",
             "._json.from_json",
             "._json.read_json",
diff --git a/packages/python/plotly/plotly/io/_kaleido.py b/packages/python/plotly/plotly/io/_kaleido.py
@@ -1,6 +1,7 @@
 from __future__ import absolute_import
 from six import string_types
 import os
+import json
 import plotly
 from plotly.io._utils import validate_coerce_fig_to_dict
 
@@ -120,7 +121,7 @@ def to_image(
             """
 Image export using the "kaleido" engine requires the kaleido package,
 which can be installed using pip:
-    $ pip install -U kaleido 
+    $ pip install -U kaleido
 """
         )
 
@@ -260,4 +261,58 @@ def write_image(
         file.write(img_data)
 
 
-__all__ = ["to_image", "write_image", "scope"]
+def full_figure_for_development(fig, warn=True, as_dict=False):
+    """
+    Compute default values for all attributes not specified in the input figure and
+    returns the output as a "full" figure. This function calls Plotly.js via Kaleido
+    to populate unspecified attributes. This function is intended for interactive use
+    during development to learn more about how Plotly.js computes default values and is
+    not generally necessary or recommended for production use.
+
+    Parameters
+    ----------
+    fig:
+        Figure object or dict representing a figure
+
+    warn: bool
+        If False, suppress warnings about not using this in production.
+
+    as_dict: bool
+        If True, output is a dict with some keys that go.Figure can't parse.
+        If False, output is a go.Figure with unparseable keys skipped.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure or dict
+        The full figure
+    """
+
+    # Raise informative error message if Kaleido is not installed
+    if scope is None:
+        raise ValueError(
+            """
+Image export using the "kaleido" engine requires the kaleido package,
+which can be installed using pip:
+    $ pip install -U kaleido
+"""
+        )
+
+    if warn:
+        import warnings
+
+        warnings.warn(
+            "full_figure_for_development is not recommended or necessary for "
+            "production use in most circumstances. \n"
+            "To suppress this warning, set warn=False"
+        )
+
+    fig = json.loads(scope.transform(fig, format="json"))
+    if as_dict:
+        return fig
+    else:
+        import plotly.graph_objects as go
+
+        return go.Figure(fig, skip_invalid=True)
+
+
+__all__ = ["to_image", "write_image", "scope", "full_figure_for_development"]
