Support Kaleido v1 in Plotly.py #5062

emilykl · 2025-03-04T17:08:04Z

Support both the Kaleido v0 and v1 APIs in Plotly.py.

Update fig.write_image(), fig.to_image(), pio.write_image(), and pio.to_image() to work with both Kaleido versions
Add deprecation warnings for:
- the engine argument to to_image() and write_image()
- Use of Orca
- Use of Kaleido v0
Add pio.write_images() and pio.to_images() functions for generating multiple images at a time
- These are needed due to the new Kaleido architecture. Eventually they will be much faster than calling write_image() and to_image() in a loop -- but as of this PR they are the same speed.
- Add pio.get_chrome() function which wraps kaleido.get_chrome_sync(), and add a CLI entry point plotly_get_chrome for installing Chrome from the command line
Update tests/test_optional/test_kaleido/test_kaleido.py tests to work with either Kaleido v0 or v1. They now also actually check that an image of the right format and dimensions has been generated, as opposed to using mocking to check that the right arguments are being passed to Kaleido.
Add tests for pio.to_images() and pio.write_images()
Update CI to run all tests with Kaleido v1, and add an additional job which runs the Kaleido tests with Kaleido v0, to protect against regressions

TODO

Update CI to run all tests with Kaleido v1
Add CI job to run Kaleido tests with Kaleido v0
Finalize UX for what happens if Chrome is not found
Finalize UX / API for EPS
Figure out what to do about 'renderers' Kaleido test
Add deprecation warning for engine argument to write_image / to_image
Re-add removed Orca support but with DeprecationWarning
Fix DeprecationWarnings not showing up
Expose API for setting default mathjax and topojson

gvwilson

Left a few comments and a question, happy to read through again as soon as you want.

gvwilson · 2025-03-04T17:23:46Z

plotly/io/_kaleido.py

+            - 'webp'
+            - 'svg'
+            - 'pdf'
+            - 'eps' (Requires the poppler library to be installed and on the PATH)


do we still handle EPS?

@gvwilson Following up on this — Kaleido v1 does not support EPS yet. So either we drop support for EPS entirely, or document that EPS is only available with Kaleido v0 and add an informative error message.

please do the latter - thanks

gvwilson · 2025-03-04T17:24:30Z

plotly/io/_kaleido.py

-         - "kaleido": Use Kaleido for image export
-         - "orca": Use Orca for image export
-         - "auto" (default): Use Kaleido if installed, otherwise use orca
+    engine (deprecated): str


do we print a deprecation warning if this argument is used?

Not yet, assuming we are in agreement about removing this argument, I'll add one

I'm in agreement that we should remove this argument

plotly/io/_kaleido.py

gvwilson · 2025-03-04T17:27:04Z

tests/test_optional/test_kaleido/test_kaleido.py

+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


Part of the TODO is for me to educate myself on how Plotly currently determines PDF size when writing to PDF. :)

But the size argument is measured in pixels (at least for raster file types) and PDFs have no concept of pixels so I wouldn't expect the PDF to report the same "size" as passed in the argument necessarily.

I will also take a looksy on that issue, lets say for this and the above tomorrow. I am flying today.

emilykl · 2025-03-04T17:44:57Z

cc @ayjayt

…lopment()

marthacryan · 2025-03-06T18:54:24Z

Do we need to maintain backwards compatibility with older Kaleido versions here?

marthacryan · 2025-03-06T20:07:59Z

tests/test_optional/test_kaleido/test_kaleido.py

Are there percy tests that use kaleido to make sure that the actual images generated are correct?

LiamConnors · 2025-03-06T20:29:38Z

plotly/io/_kaleido.py

-        If not specified, will default to:
-             - `plotly.io.kaleido.scope.default_format` if engine is "kaleido"
-             - `plotly.io.orca.config.default_format` if engine is "orca"
+        If not specified, will default to `plotly.io.kaleido.scope.default_format`


Do these references to plotly.io.kaleido.scope.. need to be something else if that's no longer imported here
https://github.com/plotly/plotly.py/pull/5062/files#diff-40813ac13aafeaa7135da57a86bec52cae638135b0acf9324677c9c4eee2ba2bR1

Yes, those docstrings should be changed -- I need to research where those defaults are defined in Kaleido v1. (@ayjayt do you know off the top of your head?)

https://github.com/plotly/Kaleido/blob/d493b9dc0c04940721dc2d67e8b342d31fc6bb18/src/py/kaleido/_fig_tools.py#L9-L13

The order is png default overridden by user-specified output path w/ extension overriden by user-specified format in opts

ayjayt · 2025-03-11T21:00:36Z

.circleci/config.yml

+            uv pip install -r ./test_requirements/requirements_optional.txt
+            # Install Kaleido v1 instead of the default version
+            uv pip uninstall -y kaleido
+            uv pip install 'git+https://github.com/plotly/[email protected]#subdirectory=src/py'


uv pip install kaleido>=1.0.0 || uv pip install 'git+https://github.com/plotly/Kaleido.git@latest-tag#subdirectory=src/py' is my recommendation

👍 I'll just update the CI manually once Kaleido 1.0.0 full version is on PyPI.

…text TBD)

plotly/io/_kaleido.py

…o so they are not faster

…_chrome to plotly_get_chrome

plotly/io/_kaleido.py

… compatible kaleido version

…into upgrade-kaleido

LiamConnors · 2025-03-31T17:41:43Z

plotly/io/_defaults.py

+    def __init__(self):
+        self.default_format = "png"
+        self.default_width = 700
+        self.default_height = 500
+        self.default_scale = 1
+


Will there be a way to set mathjax, topojson, and mapbox_access_token, the other export settings available in v0?

mapbox_access_token isn't relevant anymore since Mapbox traces are no longer supported; the other two I guess we should expose. I'll add a TODO.

Release 6.1.0b0

emilykl · 2025-03-31T19:08:41Z

Quick comment to note that commit 54985b8 on this branch has been released as beta version v6.1.0b0.

emilykl added 3 commits March 4, 2025 12:02

small io refactor to support kaleido v1

f0a78a6

update kaleido tests to support kaleido v1

a681c84

Merge branch 'main' into upgrade-kaleido

a7a6f24

emilykl requested review from gvwilson, LiamConnors and marthacryan March 4, 2025 17:13

update test requirements

2e9c8af

gvwilson reviewed Mar 4, 2025

View reviewed changes

emilykl added 2 commits March 4, 2025 13:29

simplify to_image

60bb748

use k.calc_fig() instead of k.write_fig() in pio.full_figure_for_deve…

b87f752

…lopment()

marthacryan reviewed Mar 6, 2025

View reviewed changes

LiamConnors reviewed Mar 6, 2025

View reviewed changes

merge main

e203623

gvwilson assigned emilykl Mar 7, 2025

gvwilson added feature something new P1 needed for current cycle labels Mar 7, 2025

This was referenced Mar 11, 2025

Upgrade to kaleido 1.0 / plotly 6 scikit-image/scikit-image#7623

Draft

Image export fails with Chromium 132 plotly/Kaleido#253

Closed

emilykl added 3 commits March 11, 2025 13:33

merge main

8054331

add ci job to test with kaleido v1

1a195a7

remove -y option

577d3ca

ayjayt reviewed Mar 11, 2025

View reviewed changes

emilykl added 6 commits March 11, 2025 17:18

run test_kaleido instead of test_io

89209ad

re-add orca, add deprecation warnings for orca and kaleido-v0 (exact …

96bf9a0

…text TBD)

error message for 'eps' with kaleido v1

350dd48

pin kaleido v1 (prerelease) in test requirements

08c1d4e

format

8b47a0a

deprecation warning wording

249cc9f

LiamConnors reviewed Mar 24, 2025

View reviewed changes

plotly/io/_kaleido.py Show resolved Hide resolved

emilykl added 10 commits March 24, 2025 16:12

fix if/else for when engine not specified

ad9dbd9

add flow and endpoint for installing chrome via plotly

e75a5df

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

a2b4f3c

…o so they are not faster

format

2549299

fix test_image_renderer() test to work with both kaleido v0 and v1

ab3b700

support pos args in to_images and write_images; rename plotly_install…

de473e1

…_chrome to plotly_get_chrome

mising pos args in write_images()

71696fe

add tests for write_images() and to_images()

100b955

add new API for setting image generation defaults

5541a79

format

95a05db

emilykl marked this pull request as ready for review March 27, 2025 15:48

emilykl added 2 commits March 27, 2025 11:53

Merge branch 'main' into upgrade-kaleido

0a73d0e

install kaleido 1.0.0rc11 from PyPI

4d3dd56

LiamConnors reviewed Mar 28, 2025

View reviewed changes

plotly/io/_kaleido.py Outdated Show resolved Hide resolved

emilykl added 6 commits March 28, 2025 12:35

remove extra import

d871e74

add [kaleido] install extra to pyproject.toml to help with installing…

b3e8d36

… compatible kaleido version

fix deprecation warnings

ef5f520

Merge branch 'main' into upgrade-kaleido

611e2e4

small updates to deprecation warning text

c92a1ee

Merge branch 'upgrade-kaleido' of https://github.com/plotly/plotly.py …

b56d5ec

…into upgrade-kaleido

LiamConnors reviewed Mar 31, 2025

View reviewed changes

emilykl added 4 commits March 31, 2025 14:28

add missing changelog entries

c01cb8a

update changelog for 6.1.0b0

bcd40f3

update pyproject.toml for 6.1.0b0

54985b8

Merge pull request #5121 from plotly/release-6.1.0b0

b4af0d5

Release 6.1.0b0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Support Kaleido v1 in Plotly.py #5062

Support Kaleido v1 in Plotly.py #5062

emilykl commented Mar 4, 2025 •

edited

Loading

gvwilson left a comment

gvwilson Mar 4, 2025

emilykl Mar 4, 2025

gvwilson Mar 5, 2025

gvwilson Mar 4, 2025

emilykl Mar 4, 2025

marthacryan Mar 6, 2025

gvwilson Mar 4, 2025

emilykl Mar 4, 2025

ayjayt Mar 6, 2025

emilykl commented Mar 4, 2025

marthacryan commented Mar 6, 2025

marthacryan Mar 6, 2025

LiamConnors Mar 6, 2025

emilykl Mar 7, 2025

ayjayt Mar 11, 2025

ayjayt Mar 11, 2025

emilykl Mar 12, 2025

LiamConnors Mar 31, 2025

emilykl Mar 31, 2025

emilykl commented Mar 31, 2025

Support Kaleido v1 in Plotly.py #5062

Are you sure you want to change the base?

Support Kaleido v1 in Plotly.py #5062

Conversation

emilykl commented Mar 4, 2025 • edited Loading

gvwilson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

emilykl commented Mar 4, 2025

marthacryan commented Mar 6, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

emilykl commented Mar 31, 2025

emilykl commented Mar 4, 2025 •

edited

Loading