add write_images and to_images functions (not yet using shared Kaleid…

…o so they are not faster
plotly · emilykl · Apr 29, 2025 · Mar 4, 2025 · Mar 4, 2025 · Mar 4, 2025
commit a2b4f3c6801db5277798713fbd35e3d6b5b9b8a9
diff --git a/plotly/io/__init__.py b/plotly/io/__init__.py
@@ -3,7 +3,7 @@
 from typing import TYPE_CHECKING
 
 if sys.version_info < (3, 7) or TYPE_CHECKING:
-    from ._kaleido import to_image, write_image, full_figure_for_development
+    from ._kaleido import to_image, write_image, to_images, write_images, full_figure_for_development
     from . import orca, kaleido
     from . import json
     from ._json import to_json, from_json, read_json, write_json
@@ -15,6 +15,8 @@
     __all__ = [
         "to_image",
         "write_image",
+        "to_images",
+        "write_images",
         "orca",
         "json",
         "to_json",
@@ -37,6 +39,8 @@
         [
             "._kaleido.to_image",
             "._kaleido.write_image",
+            "._kaleido.to_images",
+            "._kaleido.write_images",
             "._kaleido.full_figure_for_development",
             "._json.to_json",
             "._json.from_json",

diff --git a/plotly/io/_kaleido.py b/plotly/io/_kaleido.py
@@ -6,7 +6,7 @@
 import warnings
 
 import plotly
-from plotly.io._utils import validate_coerce_fig_to_dict
+from plotly.io._utils import validate_coerce_fig_to_dict, as_individual_kwargs
 
 ENGINE_SUPPORT_TIMELINE = "September 2025"
 
@@ -29,6 +29,7 @@
             scope.mathjax = (
                 "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js"
             )
+
 except ImportError as e:
     kaleido_available = False
     kaleido_major = -1
@@ -37,7 +38,14 @@
 
 
 def to_image(
-    fig, format=None, width=None, height=None, scale=None, validate=True, engine=None
+    fig,
+    format=None,
+    width=None,
+    height=None,
+    scale=None,
+    validate=True,
+    engine=None,
+    kaleido_instance=None,
 ):
     """
     Convert a figure to a static image bytes string
@@ -87,6 +95,9 @@ def to_image(
     engine (deprecated): str
         No longer used. Kaleido is the only supported engine.
 
+    kaleido_instance: kaleido.Kaleido or None
+        An instance of the Kaleido class. If None, a new instance will be created.
+
     Returns
     -------
     bytes
@@ -162,15 +173,17 @@ def to_image(
         # Check if trying to export to EPS format, which is not supported in Kaleido v1
         if format == "eps":
             raise ValueError(
-                """
-EPS export is not supported with Kaleido v1.
-Please downgrade to Kaleido v0 to use EPS export:
-    $ pip install kaleido==0.2.1
+                f"""
+EPS export is not supported with Kaleido v1. Please use SVG or PDF instead.
+You can also downgrade to Kaleido v0, but support for v0 will be removed after {ENGINE_SUPPORT_TIMELINE}.
+To downgrade to Kaleido v0, run:
+    $ pip install kaleido<1.0.0
 """
             )
         import choreographer
 
         try:
+            # TODO: Actually use provided kaleido_instance here
             img_bytes = kaleido.calc_fig_sync(
                 fig_dict,
                 path=None,
@@ -204,35 +217,6 @@ def to_image(
     return img_bytes
 
 
-def install_chrome():
-    """
-    Install Google Chrome for Kaleido
-    This function can be run from the command line using the command plotly_install_chrome
-    defined in pyproject.toml
-    """
-    if not kaleido_available or kaleido_major < 1:
-        raise ValueError(
-            "This command requires Kaleido v1.0.0 or greater. Install it using `pip install kaleido`."
-        )
-    import choreographer
-    import sys
-
-    cli_yes = len(sys.argv) > 1 and sys.argv[1] == "-y"
-    if not cli_yes:
-        print(
-            "\nPlotly will install a copy of Google Chrome to be used for generating static images of plots.\n"
-        )
-        # TODO: Print path where Chrome will be installed
-        # print(f"Chrome will be installed at {chrome_download_path}\n")
-        response = input("Do you want to proceed? [y/n] ")
-        if not response or response[0].lower() != "y":
-            print("Cancelled")
-            return
-    print("Installing Chrome for Plotly...")
-    kaleido.get_chrome_sync()
-    print("Chrome installed successfully.")
-
-
 def write_image(
     fig,
     file,
@@ -242,6 +226,7 @@ def write_image(
     height=None,
     validate=True,
     engine="auto",
+    kaleido_instance=None,
 ):
     """
     Convert a figure to a static image and write it to a file or writeable
@@ -300,6 +285,9 @@ def write_image(
     engine (deprecated): str
         No longer used. Kaleido is the only supported engine.
 
+    kaleido_instance: kaleido.Kaleido or None
+        An instance of the Kaleido class. If None, a new instance will be created.
+
     Returns
     -------
     None
@@ -348,6 +336,7 @@ def write_image(
         height=height,
         validate=validate,
         engine=engine,
+        kaleido_instance=kaleido_instance,
     )
 
     # Open file
@@ -373,6 +362,69 @@ def write_image(
         path.write_bytes(img_data)
 
 
+def to_images(**kwargs):
+    """
+    Convert multiple figures to static images and return a list of image bytes
+
+    Parameters
+    ----------
+    Accepts the same parameters as pio.to_image(), but any parameter may be either
+    a single value or a list of values. If more than one parameter is a list,
+    all must be the same length.
+
+    Returns
+    -------
+    list of bytes
+        The image data
+    """
+    individual_kwargs = as_individual_kwargs(**kwargs)
+
+    if kaleido_available and kaleido_major > 0:
+        # Kaleido v1
+        # TODO: Use a single shared kaleido instance for all images
+        return [to_image(**kw) for kw in individual_kwargs]
+    else:
+        # Kaleido v0, or orca
+        return [to_image(**kw) for kw in individual_kwargs]
+
+
+def write_images(**kwargs):
+    """
+    Write multiple images to files or writeable objects. This is much faster than
+    calling write_image() multiple times.
+
+    Parameters
+    ----------
+    Accepts the same parameters as pio.write_image(), but any parameter may be either
+    a single value or a list of values. If more than one parameter is a list,
+    all must be the same length.
+
+    Returns
+    -------
+    None
+    """
+
+    if "file" not in kwargs:
+        raise ValueError("'file' argument is required")
+
+    # Get individual arguments, and separate out the 'file' argument
+    individual_kwargs = as_individual_kwargs(**kwargs)
+    files = [kw["file"] for kw in individual_kwargs]
+    individual_kwargs = [
+        {k: v for k, v in kw.items() if k != "file"} for kw in individual_kwargs
+    ]
+
+    if kaleido_available and kaleido_major > 0:
+        # Kaleido v1
+        # TODO: Use a single shared kaleido instance for all images
+        for f, kw in zip(files, individual_kwargs):
+            write_image(file=f, **kw)
+    else:
+        # Kaleido v0, or orca
+        for f, kw in zip(files, individual_kwargs):
+            write_image(file=f, **kw)
+
+
 def full_figure_for_development(fig, warn=True, as_dict=False):
     """
     Compute default values for all attributes not specified in the input figure and
@@ -442,4 +494,32 @@ def full_figure_for_development(fig, warn=True, as_dict=False):
         return go.Figure(fig, skip_invalid=True)
 
 
+def install_chrome():
+    """
+    Install Google Chrome for Kaleido
+    This function can be run from the command line using the command `plotly_install_chrome`
+    defined in pyproject.toml
+    """
+    if not kaleido_available or kaleido_major < 1:
+        raise ValueError(
+            "This command requires Kaleido v1.0.0 or greater. Install it using `pip install kaleido`."
+        )
+    import sys
+
+    cli_yes = len(sys.argv) > 1 and sys.argv[1] == "-y"
+    if not cli_yes:
+        print(
+            "\nPlotly will install a copy of Google Chrome to be used for generating static images of plots.\n"
+        )
+        # TODO: Print path where Chrome will be installed
+        # print(f"Chrome will be installed at {chrome_download_path}\n")
+        response = input("Do you want to proceed? [y/n] ")
+        if not response or response[0].lower() != "y":
+            print("Cancelled")
+            return
+    print("Installing Chrome for Plotly...")
+    kaleido.get_chrome_sync()
+    print("Chrome installed successfully.")
+
+
 __all__ = ["to_image", "write_image", "scope", "full_figure_for_development"]
diff --git a/plotly/io/_utils.py b/plotly/io/_utils.py
@@ -43,6 +43,42 @@ def validate_coerce_output_type(output_type):
     return cls
 
 
+def as_individual_kwargs(**kwargs):
+    """
+    Given one or more keyword arguments which may be either a single value or a list of values,
+    return a list of dictionaries where each dictionary has only single values for each keyword
+    by expanding the single values into lists.
+    If more than one keyword is a list, all lists must be the same length.
+
+    Parameters
+    ----------
+    kwargs: dict
+        The keyword arguments
+
+    Returns
+    -------
+    list of dicts
+        A list of dictionaries
+    """
+    # Check that all list arguments have the same length,
+    # and find out what that length is
+    # If there are no list arguments, length is 1
+    list_lengths = [len(v) for v in kwargs.values() if isinstance(v, list)]
+    if list_lengths and len(set(list_lengths)) > 1:
+        raise ValueError("All list arguments must have the same length.")
+    list_length = list_lengths[0] if list_lengths else 1
+
+    # Expand all arguments to lists of the same length
+    expanded_kwargs = {
+        k: [v] * list_length if not isinstance(v, list) else v
+        for k, v in kwargs.items()
+    }
+
+    # Reshape into a list of dictionaries
+    # Each dictionary represents the arguments for a single call to to_image
+    return [{k: v[i] for k, v in expanded_kwargs.items()} for i in range(list_length)]
+
+
 def plotly_cdn_url(cdn_ver=get_plotlyjs_version()):
     """Return a valid plotly CDN url."""
     return "https://cdn.plot.ly/plotly-{cdn_ver}.min.js".format(