Add Kaleido image export support

CHANGELOG.md

@@ -2,6 +2,11 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [4.9.0] - ???
+
+### Added
+ - Added preview image export support using Kaleido. Kaleido support is enabled by installing the `kaleido` package from PyPI and setting the `kaleido_export` future flag before importing `plotly` ([#2613](https://github.com/plotly/plotly.py/pull/2613)).
+
 ## [4.8.2] - 2020-06-26
 
 ### Updated

packages/python/plotly/_plotly_future_/kaleido_export.py

@@ -0,0 +1,5 @@
+from __future__ import absolute_import
+from _plotly_future_ import _future_flags, _assert_plotly_not_imported
+
+_assert_plotly_not_imported()
+_future_flags.add("kaleido_export")

packages/python/plotly/plotly/io/__init__.py

@@ -1,9 +1,19 @@
 from _plotly_utils.importers import relative_import
+from _plotly_future_ import _future_flags
 import sys
 
 if sys.version_info < (3, 7):
-    from ._orca import to_image, write_image
-    from . import orca
+    if "kaleido_export" in _future_flags:
+        from .kaleido import to_image, write_image
+        from . import kaleido
+
+        extra_modules = ["kaleido"]
+    else:
+        from ._orca import to_image, write_image
+        from . import orca
+
+        extra_modules = ["orca"]
+
     from ._json import to_json, from_json, read_json, write_json
     from ._templates import templates, to_templated
     from ._html import to_html, write_html
@@ -13,7 +23,6 @@
     __all__ = [
         "to_image",
         "write_image",
-        "orca",
         "to_json",
         "from_json",
         "read_json",
@@ -25,14 +34,19 @@
         "renderers",
         "show",
         "base_renderers",
-    ]
+    ] + extra_modules
 else:
+    if "kaleido_export" in _future_flags:
+        extra_modules = [".kaleido"]
+        extra_objects = [".kaleido.to_image", ".kaleido.write_image"]
+    else:
+        extra_modules = [".orca"]
+        extra_objects = ["._orca.to_image", "._orca.write_image"]
+
     __all__, __getattr__, __dir__ = relative_import(
         __name__,
-        [".orca", ".base_renderers"],
+        [".base_renderers"] + extra_modules,
         [
-            "._orca.to_image",
-            "._orca.write_image",
             "._json.to_json",
             "._json.from_json",
             "._json.read_json",
@@ -43,7 +57,8 @@
             "._html.write_html",
             "._renderers.renderers",
             "._renderers.show",
-        ],
+        ]
+        + extra_objects,
     )
 
     # Set default template (for < 3.7 this is done in ploty/__init__.py)

packages/python/plotly/plotly/io/_kaleido.py

@@ -0,0 +1,183 @@
+from six import string_types
+import os
+from plotly.io._utils import validate_coerce_fig_to_dict
+
+try:
+    from kaleido.scopes.plotly import PlotlyScope
+
+    scope = PlotlyScope()
+except ImportError:
+    PlotlyScope = None
+    scope = None
+
+
+def to_image(fig, format=None, width=None, height=None, scale=None, validate=True):
+    """
+    Convert a figure to a static image bytes string
+
+    Parameters
+    ----------
+    fig:
+        Figure object or dict representing a figure
+
+    format: str or None
+        The desired image format. One of
+          - 'png'
+          - 'jpg' or 'jpeg'
+          - 'webp'
+          - 'svg'
+          - 'pdf'
+
+        If not specified, will default to `plotly.io.kaleido.scope.default_format`
+
+    width: int or None
+        The width of the exported image in layout pixels. If the `scale`
+        property is 1.0, this will also be the width of the exported image
+        in physical pixels.
+
+        If not specified, will default to `plotly.io.kaleido.scope.default_width`
+
+    height: int or None
+        The height of the exported image in layout pixels. If the `scale`
+        property is 1.0, this will also be the height of the exported image
+        in physical pixels.
+
+        If not specified, will default to `plotly.io.kaleido.scope.default_height`
+
+    scale: int or float or None
+        The scale factor to use when exporting the figure. A scale factor
+        larger than 1.0 will increase the image resolution with respect
+        to the figure's layout pixel dimensions. Whereas as scale factor of
+        less than 1.0 will decrease the image resolution.
+
+        If not specified, will default to `plotly.io.kaleido.scope.default_scale`
+
+    validate: bool
+        True if the figure should be validated before being converted to
+        an image, False otherwise.
+
+    Returns
+    -------
+    bytes
+        The image data
+    """
+    # Raise informative error message if Kaleido is not installed
+    if scope is None:
+        raise ValueError(
+            """
+Image export requires the kaleido package, which can be installed using pip:
+    $ pip install -U kaleido 
+"""
+        )
+
+    # Validate figure
+    # ---------------
+    fig_dict = validate_coerce_fig_to_dict(fig, validate)
+    img_bytes = scope.transform(
+        fig_dict, format=format, width=width, height=height, scale=scale
+    )
+
+    return img_bytes
+
+
+def write_image(
+    fig, file, format=None, scale=None, width=None, height=None, validate=True
+):
+    """
+    Convert a figure to a static image and write it to a file or writeable
+    object
+
+    Parameters
+    ----------
+    fig:
+        Figure object or dict representing a figure
+
+    file: str or writeable
+        A string representing a local file path or a writeable object
+        (e.g. an open file descriptor)
+
+    format: str or None
+        The desired image format. One of
+          - 'png'
+          - 'jpg' or 'jpeg'
+          - 'webp'
+          - 'svg'
+          - 'pdf'
+          - 'eps' (Requires the poppler library to be installed)
+
+        If not specified and `file` is a string then this will default to the
+        file extension. If not specified and `file` is not a string then this
+        will default to `plotly.io.config.default_format`
+
+    width: int or None
+        The width of the exported image in layout pixels. If the `scale`
+        property is 1.0, this will also be the width of the exported image
+        in physical pixels.
+
+        If not specified, will default to `plotly.io.config.default_width`
+
+    height: int or None
+        The height of the exported image in layout pixels. If the `scale`
+        property is 1.0, this will also be the height of the exported image
+        in physical pixels.
+
+        If not specified, will default to `plotly.io.config.default_height`
+
+    scale: int or float or None
+        The scale factor to use when exporting the figure. A scale factor
+        larger than 1.0 will increase the image resolution with respect
+        to the figure's layout pixel dimensions. Whereas as scale factor of
+        less than 1.0 will decrease the image resolution.
+
+        If not specified, will default to `plotly.io.config.default_scale`
+
+    validate: bool
+        True if the figure should be validated before being converted to
+        an image, False otherwise.
+
+    Returns
+    -------
+    None
+    """
+
+    # Check if file is a string
+    # -------------------------
+    file_is_str = isinstance(file, string_types)
+
+    # Infer format if not specified
+    # -----------------------------
+    if file_is_str and format is None:
+        _, ext = os.path.splitext(file)
+        if ext:
+            format = ext.lstrip(".")
+        else:
+            raise ValueError(
+                """
+Cannot infer image type from output path '{file}'.
+Please add a file extension or specify the type using the format parameter.
+For example:
+
+    >>> import plotly.io as pio
+    >>> pio.write_image(fig, file_path, format='png')
+""".format(
+                    file=file
+                )
+            )
+
+    # Request image
+    # -------------
+    # Do this first so we don't create a file if image conversion fails
+    img_data = to_image(
+        fig, format=format, scale=scale, width=width, height=height, validate=validate
+    )
+
+    # Open file
+    # ---------
+    if file_is_str:
+        with open(file, "wb") as f:
+            f.write(img_data)
+    else:
+        file.write(img_data)
+
+
+__all__ = ["to_image", "write_image", "scope"]

packages/python/plotly/plotly/io/kaleido.py

@@ -0,0 +1 @@
+from ._kaleido import to_image, write_image, scope