Support Kaleido v1 in Plotly.py

.circleci/config.yml

@@ -114,6 +114,35 @@ commands:
             source .venv/bin/activate
             python -m pytest -x test_init/test_lazy_imports.py
 
+  test_io_kaleido_v0:
+    steps:
+      - checkout
+      - browser-tools/install-chrome
+      - browser-tools/install-chromedriver
+      - run:
+          name: Install dependencies
+          command: |
+            curl -LsSf https://astral.sh/uv/install.sh | sh
+            uv venv
+            source .venv/bin/activate
+            uv pip install .
+            uv pip install -r ./test_requirements/requirements_optional.txt
+            # Install Kaleido v0 instead of the v1 specified in requirements_optional.txt
+            uv pip uninstall kaleido
+            uv pip install kaleido==0.2.1
+      - run:
+          name: List installed packages and python version
+          command: |
+            source .venv/bin/activate
+            uv pip list
+            python --version
+      - run:
+          name: Test plotly.io image output with Kaleido v0
+          command: |
+            source .venv/bin/activate
+            python -m pytest tests/test_optional/test_kaleido
+          no_output_timeout: 20m
+
 jobs:
   check-code-formatting:
     docker:
@@ -163,6 +192,17 @@ jobs:
           pandas_version: <<parameters.pandas_version>>
           numpy_version: <<parameters.numpy_version>>
 
+  test_kaleido_v0:
+    parameters:
+      python_version:
+        default: "3.12"
+        type: string
+    executor:
+      name: docker-container
+      python_version: <<parameters.python_version>>
+    steps:  
+      - test_io_kaleido_v0
+
   # Percy
   python_311_percy:
     docker:
@@ -435,5 +475,10 @@ workflows:
           python_version: "3.9"
           pandas_version: "1.2.4"
           numpy_version: "1.26.4"
+      - test_kaleido_v0:
+          matrix:
+            parameters:
+              python_version:
+                - "3.12"
       - python_311_percy
       - build-doc

CHANGELOG.md

@@ -2,10 +2,15 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
-## Unreleased
+## [6.1.0b0] - 2025-03-31
+
+### Updated
+- Add support for Kaleido >= v1.0.0 for image generation, and deprecate support for Kaleido<1 and Orca [[#5062](https://github.com/plotly/plotly.py/pull/5062)]
 
 ### Fixed
-- Fix third-party widget display issues in v6 [[#5102]https://github.com/plotly/plotly.py/pull/5102]
+- Fix third-party widget display issues in v6 [[#5102](https://github.com/plotly/plotly.py/pull/5102)]
+- Add handling for case where `jupyterlab` or `notebook` is not installed [[#5104](https://github.com/plotly/plotly.py/pull/5104/files)]
+- Fix issue causing Plotly.js script to be embedded multiple times in Jupyter notebooks [[#5112](https://github.com/plotly/plotly.py/pull/5112)]
 
 ## [6.0.1] - 2025-03-14
 

plotly/basedatatypes.py

@@ -3740,48 +3740,77 @@ def to_image(self, *args, **kwargs):
               - 'webp'
               - 'svg'
               - 'pdf'
-              - 'eps' (Requires the poppler library to be installed)
+              - 'eps' (deprecated) (Requires the poppler library to be installed)
 
-            If not specified, will default to `plotly.io.config.default_format`
+            If not specified, will default to:
+                - `plotly.io.defaults.default_format` if engine is "kaleido"
+                - `plotly.io.orca.config.default_format` if engine is "orca" (deprecated)
 
         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`
+            If not specified, will default to:
+                - `plotly.io.defaults.default_width` if engine is "kaleido"
+                - `plotly.io.orca.config.default_width` if engine is "orca" (deprecated)
 
         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`
+            If not specified, will default to:
+                - `plotly.io.defaults.default_height` if engine is "kaleido"
+                - `plotly.io.orca.config.default_height` if engine is "orca" (deprecated)
 
         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`
+            If not specified, will default to:
+                - `plotly.io.defaults.default_scale` if engine is "kaliedo"
+                - `plotly.io.orca.config.default_scale` if engine is "orca" (deprecated)
 
         validate: bool
             True if the figure should be validated before being converted to
             an image, False otherwise.
 
-        engine: str
-            Image export engine to use:
-             - "kaleido": Use Kaleido for image export
-             - "orca": Use Orca for image export
-             - "auto" (default): Use Kaleido if installed, otherwise use orca
+        engine (deprecated): str
+            Image export engine to use. This parameter is deprecated and Orca engine support will be
+            dropped in the next major Plotly version. Until then, the following values are supported:
+            - "kaleido": Use Kaleido for image export
+            - "orca": Use Orca for image export
+            - "auto" (default): Use Kaleido if installed, otherwise use Orca
 
         Returns
         -------
         bytes
             The image data
         """
         import plotly.io as pio
+        from plotly.io.kaleido import (
+            kaleido_available,
+            kaleido_major,
+            KALEIDO_DEPRECATION_MSG,
+            ORCA_DEPRECATION_MSG,
+            ENGINE_PARAM_DEPRECATION_MSG,
+        )
+
+        if (
+            kwargs.get("engine", None) in {None, "auto", "kaleido"}
+            and kaleido_available()
+            and kaleido_major() < 1
+        ):
+            warnings.warn(KALEIDO_DEPRECATION_MSG, DeprecationWarning, stacklevel=2)
+        if kwargs.get("engine", None) == "orca":
+            warnings.warn(ORCA_DEPRECATION_MSG, DeprecationWarning, stacklevel=2)
+        if kwargs.get("engine", None):
+            warnings.warn(
+                ENGINE_PARAM_DEPRECATION_MSG, DeprecationWarning, stacklevel=2
+            )
 
         return pio.to_image(self, *args, **kwargs)
 
@@ -3803,49 +3832,78 @@ def write_image(self, *args, **kwargs):
               - 'webp'
               - 'svg'
               - 'pdf'
-              - 'eps' (Requires the poppler library to be installed)
+              - 'eps' (deprecated) (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`
+            will default to:
+                - `plotly.io.defaults.default_format` if engine is "kaleido"
+                - `plotly.io.orca.config.default_format` if engine is "orca" (deprecated)
 
         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`
+            If not specified, will default to:
+                - `plotly.io.defaults.default_width` if engine is "kaleido"
+                - `plotly.io.orca.config.default_width` if engine is "orca" (deprecated)
 
         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`
+            If not specified, will default to:
+                - `plotly.io.defaults.default_height` if engine is "kaleido"
+                - `plotly.io.orca.config.default_height` if engine is "orca" (deprecated)
 
         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`
+            If not specified, will default to:
+                - `plotly.io.defaults.default_scale` if engine is "kaleido"
+                - `plotly.io.orca.config.default_scale` if engine is "orca" (deprecated)
 
         validate: bool
             True if the figure should be validated before being converted to
             an image, False otherwise.
 
-        engine: str
-            Image export engine to use:
-             - "kaleido": Use Kaleido for image export
-             - "orca": Use Orca for image export
-             - "auto" (default): Use Kaleido if installed, otherwise use orca
+        engine (deprecated): str
+            Image export engine to use. This parameter is deprecated and Orca engine support will be
+            dropped in the next major Plotly version. Until then, the following values are supported:
+            - "kaleido": Use Kaleido for image export
+            - "orca": Use Orca for image export
+            - "auto" (default): Use Kaleido if installed, otherwise use Orca
+
         Returns
         -------
         None
         """
         import plotly.io as pio
+        from plotly.io.kaleido import (
+            kaleido_available,
+            kaleido_major,
+            KALEIDO_DEPRECATION_MSG,
+            ORCA_DEPRECATION_MSG,
+            ENGINE_PARAM_DEPRECATION_MSG,
+        )
 
+        if (
+            kwargs.get("engine", None) in {None, "auto", "kaleido"}
+            and kaleido_available()
+            and kaleido_major() < 1
+        ):
+            warnings.warn(KALEIDO_DEPRECATION_MSG, DeprecationWarning, stacklevel=2)
+        if kwargs.get("engine", None) == "orca":
+            warnings.warn(ORCA_DEPRECATION_MSG, DeprecationWarning, stacklevel=2)
+        if kwargs.get("engine", None):
+            warnings.warn(
+                ENGINE_PARAM_DEPRECATION_MSG, DeprecationWarning, stacklevel=2
+            )
         return pio.write_image(self, *args, **kwargs)
 
     # Static helpers

plotly/io/__init__.py

@@ -3,18 +3,25 @@
 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,
+        write_images,
+        full_figure_for_development,
+    )
     from . import orca, kaleido
     from . import json
     from ._json import to_json, from_json, read_json, write_json
     from ._templates import templates, to_templated
     from ._html import to_html, write_html
     from ._renderers import renderers, show
     from . import base_renderers
+    from ._kaleido import defaults
 
     __all__ = [
         "to_image",
         "write_image",
+        "write_images",
         "orca",
         "json",
         "to_json",
@@ -29,6 +36,7 @@
         "show",
         "base_renderers",
         "full_figure_for_development",
+        "defaults",
     ]
 else:
     __all__, __getattr__, __dir__ = relative_import(
@@ -37,6 +45,7 @@
         [
             "._kaleido.to_image",
             "._kaleido.write_image",
+            "._kaleido.write_images",
             "._kaleido.full_figure_for_development",
             "._json.to_json",
             "._json.from_json",
@@ -48,6 +57,7 @@
             "._html.write_html",
             "._renderers.renderers",
             "._renderers.show",
+            "._kaleido.defaults",
         ],
     )
 

plotly/io/_defaults.py

@@ -0,0 +1,18 @@
+# Default settings for image generation
+
+
+class _Defaults(object):
+    """
+    Class to store default settings for image generation.
+    """
+
+    def __init__(self):
+        self.default_format = "png"
+        self.default_width = 700
+        self.default_height = 500
+        self.default_scale = 1
+        self.mathjax = None
+        self.topojson = None
+
+
+defaults = _Defaults()

plotly/io/_utils.py

@@ -1,3 +1,5 @@
+from typing import List
+
 import plotly
 import plotly.graph_objs as go
 from plotly.offline import get_plotlyjs_version
@@ -43,6 +45,49 @@ def validate_coerce_output_type(output_type):
     return cls
 
 
+def broadcast_args_to_dicts(**kwargs: dict) -> List[dict]:
+    """
+    Given one or more keyword arguments which may be either a single value or a list of values,
+    return a list of keyword dictionaries by broadcasting the single valuesacross all the dicts.
+    If more than one item in the input is a list, all lists must be the same length.
+
+    Parameters
+    ----------
+    **kwargs: dict
+        The keyword arguments
+
+    Returns
+    -------
+    list of dicts
+        A list of dictionaries
+
+    Raises
+    ------
+    ValueError
+        If any of the input lists are not the same length
+    """
+    # 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 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_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 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_kwargs
+
+
 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(

plotly/io/kaleido.py

@@ -1 +1,10 @@
-from ._kaleido import to_image, write_image, scope
+from ._kaleido import (
+    to_image,
+    write_image,
+    scope,
+    kaleido_available,
+    kaleido_major,
+    KALEIDO_DEPRECATION_MSG,
+    ORCA_DEPRECATION_MSG,
+    ENGINE_PARAM_DEPRECATION_MSG,
+)

pyproject.toml

@@ -38,17 +38,20 @@ classifiers = [
 ]
 requires-python = ">=3.8"
 license = {file="LICENSE.txt"}
-version = "6.0.1"
+version = "6.1.0b0"
 dependencies = [
     "narwhals>=1.15.1",
     "packaging"
 ]
 
 [project.optional-dependencies]
 express = ["numpy"]
-dev = [
-    "black==25.1.0"
-]
+kaleido = ["kaleido==1.0.0rc11"]
+dev = ["black==25.1.0"]
+
+[project.scripts]
+plotly_get_chrome = "plotly.io._kaleido:get_chrome"
+
 
 [tool.setuptools.packages.find]
 where = ["."]

test_requirements/requirements_optional.txt

@@ -17,9 +17,11 @@ pyshp
 matplotlib
 scikit-image
 psutil
-kaleido
+# kaleido>=1.0.0  # Uncomment and delete line below once Kaleido v1 is released
+git+https://github.com/plotly/Kaleido.git@v1.0.0rc12#subdirectory=src/py
 orjson
 polars[timezone]
 pyarrow
 plotly-geo
 vaex;python_version<="3.9"
+pdfrw

tests/test_optional/test_kaleido/test_kaleido.py

@@ -1,66 +1,35 @@
-import plotly.io as pio
-import plotly.io.kaleido
-from contextlib import contextmanager
-from io import BytesIO
+from io import BytesIO, StringIO
 from pathlib import Path
-from unittest.mock import Mock
-
-fig = {"layout": {"title": {"text": "figure title"}}}
-
-
-def make_writeable_mocks():
-    """Produce some mocks which we will use for testing the `write_image()` function.
-
-    These mocks should be passed as the `file=` argument to `write_image()`.
-
-    The tests should verify that the method specified in the `active_write_function`
-    attribute is called once, and that scope.transform is called with the `format=`
-    argument specified by the `.expected_format` attribute.
-
-    In total we provide two mocks: one for a writable file descriptor, and other for a
-    pathlib.Path object.
-    """
-
-    # Part 1: A mock for a file descriptor
-    # ------------------------------------
-    mock_file_descriptor = Mock()
-
-    # A file descriptor has no write_bytes method, unlike a pathlib Path.
-    del mock_file_descriptor.write_bytes
-
-    # The expected write method for a file descriptor is .write
-    mock_file_descriptor.active_write_function = mock_file_descriptor.write
+import tempfile
+from contextlib import redirect_stdout
+import base64
 
-    # Since there is no filename, there should be no format detected.
-    mock_file_descriptor.expected_format = None
-
-    # Part 2: A mock for a pathlib path
-    # ---------------------------------
-    mock_pathlib_path = Mock(spec=Path)
-
-    # A pathlib Path object has no write method, unlike a file descriptor.
-    del mock_pathlib_path.write
-
-    # The expected write method for a pathlib Path is .write_bytes
-    mock_pathlib_path.active_write_function = mock_pathlib_path.write_bytes
-
-    # Mock a path with PNG suffix
-    mock_pathlib_path.suffix = ".png"
-    mock_pathlib_path.expected_format = "png"
-
-    return mock_file_descriptor, mock_pathlib_path
-
-
-@contextmanager
-def mocked_scope():
-    # Code to acquire resource, e.g.:
-    scope_mock = Mock()
-    original_scope = pio._kaleido.scope
-    pio._kaleido.scope = scope_mock
-    try:
-        yield scope_mock
-    finally:
-        pio._kaleido.scope = original_scope
+from pdfrw import PdfReader
+from PIL import Image
+import plotly.io as pio
+from plotly.io.kaleido import kaleido_available, kaleido_major
+import pytest
+
+fig = {"data": [], "layout": {"title": {"text": "figure title"}}}
+
+
+def check_image(path_or_buffer, size=(700, 500), format="PNG"):
+    if format == "PDF":
+        img = PdfReader(path_or_buffer)
+        # TODO: There is a conversion factor needed here
+        # In Kaleido v0 the conversion factor is 0.75
+        factor = 0.75
+        expected_size = tuple(int(s * factor) for s in size)
+        actual_size = tuple(int(s) for s in img.pages[0].MediaBox[2:])
+        assert actual_size == expected_size
+    else:
+        if isinstance(path_or_buffer, (str, Path)):
+            with open(path_or_buffer, "rb") as f:
+                img = Image.open(f)
+        else:
+            img = Image.open(path_or_buffer)
+        assert img.size == size
+        assert img.format == format
 
 
 def test_kaleido_engine_to_image_returns_bytes():
@@ -75,80 +44,95 @@ def test_kaleido_fulljson():
 
 
 def test_kaleido_engine_to_image():
-    with mocked_scope() as scope:
-        pio.to_image(fig, engine="kaleido", validate=False)
+    bytes = pio.to_image(fig, engine="kaleido", validate=False)
 
-    scope.transform.assert_called_with(
-        fig, format=None, width=None, height=None, scale=None
-    )
+    # Check that image dimensions match default dimensions (700x500)
+    # and format is default format (png)
+    check_image(BytesIO(bytes))
 
 
-def test_kaleido_engine_write_image():
-    for writeable_mock in make_writeable_mocks():
-        with mocked_scope() as scope:
-            pio.write_image(fig, writeable_mock, engine="kaleido", validate=False)
+def test_kaleido_engine_write_image(tmp_path):
+    path_str = tempfile.mkstemp(suffix=".png", dir=tmp_path)[1]
+    path_path = Path(tempfile.mkstemp(suffix=".png", dir=tmp_path)[1])
 
-        scope.transform.assert_called_with(
-            fig,
-            format=writeable_mock.expected_format,
-            width=None,
-            height=None,
-            scale=None,
-        )
-
-        assert writeable_mock.active_write_function.call_count == 1
+    for out_path in [path_str, path_path]:
+        pio.write_image(fig, out_path, engine="kaleido", validate=False)
+        check_image(out_path)
 
 
 def test_kaleido_engine_to_image_kwargs():
-    with mocked_scope() as scope:
-        pio.to_image(
+    bytes = pio.to_image(
+        fig,
+        format="pdf",
+        width=700,
+        height=600,
+        scale=2,
+        engine="kaleido",
+        validate=False,
+    )
+    check_image(BytesIO(bytes), size=(700 * 2, 600 * 2), format="PDF")
+
+
+def test_kaleido_engine_write_image_kwargs(tmp_path):
+    path_str = tempfile.mkstemp(suffix=".png", dir=tmp_path)[1]
+    path_path = Path(tempfile.mkstemp(suffix=".png", dir=tmp_path)[1])
+
+    for out_path in [path_str, path_path]:
+        pio.write_image(
             fig,
-            format="pdf",
+            out_path,
+            format="jpg",
             width=700,
             height=600,
             scale=2,
             engine="kaleido",
             validate=False,
         )
-
-    scope.transform.assert_called_with(
-        fig, format="pdf", width=700, height=600, scale=2
+        check_image(out_path, size=(700 * 2, 600 * 2), format="JPEG")
+
+
+@pytest.mark.skipif(
+    not kaleido_available() or kaleido_major() < 1,
+    reason="requires Kaleido v1.0.0 or higher",
+)
+def test_kaleido_engine_write_images(tmp_path):
+    fig1 = {"data": [], "layout": {"title": {"text": "figure 1"}}}
+    fig2 = {"data": [], "layout": {"title": {"text": "figure 2"}}}
+
+    path_str = tempfile.mkstemp(suffix=".png", dir=tmp_path)[1]
+    path_path = Path(tempfile.mkstemp(suffix=".png", dir=tmp_path)[1])
+
+    pio.write_images(
+        [fig1, fig2],
+        [path_str, path_path],
+        format=["jpg", "png"],
+        width=[700, 900],
+        height=600,
+        scale=2,
+        validate=False,
     )
-
-
-def test_kaleido_engine_write_image_kwargs():
-    for writeable_mock in make_writeable_mocks():
-        with mocked_scope() as scope:
-            pio.write_image(
-                fig,
-                writeable_mock,
-                format="jpg",
-                width=700,
-                height=600,
-                scale=2,
-                engine="kaleido",
-                validate=False,
-            )
-
-        scope.transform.assert_called_with(
-            fig, format="jpg", width=700, height=600, scale=2
-        )
-
-        assert writeable_mock.active_write_function.call_count == 1
+    check_image(path_str, size=(700 * 2, 600 * 2), format="JPEG")
+    check_image(str(path_path), size=(900 * 2, 600 * 2), format="PNG")
 
 
 def test_image_renderer():
-    with mocked_scope() as scope:
-        pio.show(fig, renderer="svg", engine="kaleido", validate=False)
-
-    renderer = pio.renderers["svg"]
-    scope.transform.assert_called_with(
-        fig,
-        format="svg",
-        width=None,
-        height=None,
-        scale=renderer.scale,
+    """Verify that the image renderer returns the expected mimebundle."""
+    with redirect_stdout(StringIO()) as f:
+        pio.show(fig, renderer="png", engine="kaleido", validate=False)
+    mimebundle = f.getvalue().strip()
+    mimebundle_expected = str(
+        {
+            "image/png": base64.b64encode(
+                pio.to_image(
+                    fig,
+                    format="png",
+                    engine="kaleido",
+                    validate=False,
+                )
+            ).decode("utf8")
+        }
     )
+    assert mimebundle == mimebundle_expected
 
 
 def test_bytesio():
@@ -163,3 +147,16 @@ def test_bytesio():
     bio_bytes = bio.read()
     to_image_bytes = pio.to_image(fig, format="jpg", engine="kaleido", validate=False)
     assert bio_bytes == to_image_bytes
+
+
+def test_defaults():
+    """Test that image output defaults can be set using pio.defaults.*"""
+    try:
+        assert pio.defaults.default_format == "png"
+        pio.defaults.default_format = "svg"
+        assert pio.defaults.default_format == "svg"
+        result = pio.to_image(fig, format="svg", validate=False)
+        assert result.startswith(b"<svg")
+    finally:
+        pio.defaults.default_format = "png"
+        assert pio.defaults.default_format == "png"