support pos args in to_images and write_images; rename plotly_install_chrome to plotly_get_chrome

Author: emilykl

plotly/io/_kaleido.py

@@ -6,7 +6,7 @@
 import warnings
 
 import plotly
-from plotly.io._utils import validate_coerce_fig_to_dict, as_individual_kwargs
+from plotly.io._utils import validate_coerce_fig_to_dict, as_individual_args
 
 ENGINE_SUPPORT_TIMELINE = "September 2025"
 
@@ -199,7 +199,7 @@ def to_image(
                 """
 
 Kaleido requires Google Chrome to be installed. Install it by running:
-    $ plotly_install_chrome
+    $ plotly_get_chrome
 """
             )
 
@@ -362,7 +362,7 @@ def write_image(
         path.write_bytes(img_data)
 
 
-def to_images(**kwargs):
+def to_images(*args, **kwargs):
     """
     Convert multiple figures to static images and return a list of image bytes
 
@@ -377,18 +377,18 @@ def to_images(**kwargs):
     list of bytes
         The image data
     """
-    individual_kwargs = as_individual_kwargs(**kwargs)
+    individual_args, individual_kwargs = as_individual_args(*args, **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]
+        return [to_image(*a, **kw) for a, kw in zip(individual_args, individual_kwargs)]
     else:
         # Kaleido v0, or orca
-        return [to_image(**kw) for kw in individual_kwargs]
+        return [to_image(*a, **kw) for a, kw in zip(individual_args, individual_kwargs)]
 
 
-def write_images(**kwargs):
+def write_images(*args, **kwargs):
     """
     Write multiple images to files or writeable objects. This is much faster than
     calling write_image() multiple times.
@@ -404,25 +404,18 @@ def write_images(**kwargs):
     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
-    ]
+    # Get individual arguments
+    individual_args, individual_kwargs = as_individual_args(*args, **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)
+        for a, kw in zip(individual_args, individual_kwargs):
+            write_image(**kw)
     else:
         # Kaleido v0, or orca
-        for f, kw in zip(files, individual_kwargs):
-            write_image(file=f, **kw)
+        for a, kw in zip(individual_args, individual_kwargs):
+            write_image(*a, **kw)
 
 
 def full_figure_for_development(fig, warn=True, as_dict=False):
@@ -494,10 +487,10 @@ def full_figure_for_development(fig, warn=True, as_dict=False):
         return go.Figure(fig, skip_invalid=True)
 
 
-def install_chrome():
+def get_chrome():
     """
     Install Google Chrome for Kaleido
-    This function can be run from the command line using the command `plotly_install_chrome`
+    This function can be run from the command line using the command `plotly_get_chrome`
     defined in pyproject.toml
     """
     if not kaleido_available or kaleido_major < 1:

plotly/io/_utils.py

@@ -43,40 +43,53 @@ def validate_coerce_output_type(output_type):
     return cls
 
 
-def as_individual_kwargs(**kwargs):
+def as_individual_args(*args, **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
+    Given one or more positional or keyword arguments which may be either a single value
+    or a list of values, return a list of lists and a list of dictionaries
     by expanding the single values into lists.
-    If more than one keyword is a list, all lists must be the same length.
+    If more than one item in the input is a list, all lists must be the same length.
 
     Parameters
     ----------
-    kwargs: dict
+    *args: list
+        The positional arguments
+    **kwargs: dict
         The keyword arguments
 
     Returns
     -------
+    list of lists
+        A list of lists
     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)]
+    list_lengths = [len(v) for v in args + tuple(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_args = [
+        [v] * list_length if not isinstance(v, list) else v for v in args
+    ]
     expanded_kwargs = {
         k: [v] * list_length if not isinstance(v, list) else v
         for k, v in kwargs.items()
     }
 
+    # Reshape into a list of lists
+    # Each list represents the positional arguments for a single function call
+    list_of_args = [[v[i] for v in expanded_args] for i in range(list_length)]
+
     # 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)]
+    # Each dictionary represents the keyword arguments for a single function call
+    list_of_kwargs = [{k: v[i] for k, v in expanded_kwargs.items()} for i in range(list_length)]
+
+    return list_of_args, list_of_kwargs
 
 
 def plotly_cdn_url(cdn_ver=get_plotlyjs_version()):

pyproject.toml

@@ -47,7 +47,7 @@ dependencies = [
 express = ["numpy"]
 
 [project.scripts]
-plotly_install_chrome = "plotly.io._kaleido:install_chrome"
+plotly_get_chrome = "plotly.io._kaleido:get_chrome"
 
 [tool.setuptools.packages.find]
 where = ["."]