$ show plotly/Kaleido
Kaleido is a Python library for static image export of Plotly figures (PNG, SVG, PDF, etc.) by rendering them in a headless Chrome browser via the DevTools protocol. The library provides both async and sync APIs, with an optional singleton server mode for reuse across calls. It manages a pool of browser tabs for parallel rendering, supports chunked JSON transfer for large figures (>10MB), and includes profiling capabilities. The architecture is centered around the `Kaleido` class, which orchestrates browser lifecycle, tab allocation, and rendering through `_KaleidoTab` instances. The library is consumed by Plotly.py and can be used standalone or via CLI tools (`kaleido_mocker`, `kaleido_get_chrome`). Dependencies include `choreographer` (Python-DevTools bridge), `orjson`, and `logistro`. The test suite includes extensive integration tests with hundreds of Plotly figure mocks covering a vast range of trace types and layout features.
The LLM identified 4 files worth highlighting for reuse:
The `Kaleido` class implements an async pool of browser tabs using `asyncio.Queue` of `_KaleidoTab` instances. Tabs are acquired, used for rendering, and recycled after page reload. The class also implements chunked JSON transfer (`_calc_fig_chunked`) to handle figure specs larger than 10MB by splitting them into parts and reassembling in JavaScript via `window.__kaleido_chunks`. This pattern is reusable for any async resource pool and large-message handling across a DevTools bridge.
`GlobalKaleidoServer` provides a singleton pattern for reusing a single Chrome instance across synchronous calls. It uses `oneshot_async_run` to execute async rendering in a daemon thread, enabling synchronous `write_fig_sync`/`calc_fig_sync` wrappers. This pattern is reusable for any library that needs to expose an async core with a synchronous API while preserving browser instance reuse.
`_KaleidoTab` encapsulates a single browser tab's DevTools session. It handles sending figure JSON to the page, waiting for rendering completion via a JavaScript callback, and parsing errors (including JS exception stack traces). The class demonstrates a clean abstraction for bidirectional communication with a browser page, reusable for any headless browser automation task.
`PageGenerator` builds the HTML page that hosts plotly.js and MathJax. It accepts configurable script sources (CDN or local), figure width/height, and MathJax typesetting options. The pattern of injecting external libraries and configuring an isolated rendering environment is reusable for any server-side chart or document generation.