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
- Setting defaults via kaleido.scope.*
Add a new way of setting image export defaults: plotly.io.defaults.*. This can be used in place of kaleido.scope.* and supports all the same settings: default_format, default_height, default_width, default_scale, mathjax, and topojson
Add pio.write_images() function for generating multiple images at a time
- Required due to the new Kaleido architecture; much faster than calling write_image() in a loop
- 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 test for 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?

plotly/io/_kaleido.py

.circleci/config.yml

…text TBD)

…_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.

topojson has been added but I have not tested it yet; mathjax is added in defaults but not functional quite yet

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

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

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

.circleci/config.yml Outdated Show resolved Hide resolved

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

emilykl added 5 commits March 26, 2025 23:01

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

emilykl added 9 commits April 13, 2025 18:33

remove to_images tests

0f61cc3

remove to_images function

fe12aec

refactor write_images to use kaleido write_fig function (WIP)

692842f

refactor write_images() to use kaleido.write_fig_from_object_sync()

aac9c20

update kaleido tests

ad57031

Merge branch 'main' into upgrade-kaleido

b9e5f7a

add and fix type hints

720ada5

add mathjax and topojson config options

53d486a

format

c990736

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 31, 2025

emilykl Mar 31, 2025

emilykl Apr 15, 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

emilykl commented Mar 31, 2025

emilykl commented Mar 4, 2025 •

edited

Loading