From 1b0c4c71f1bd5bd50d71b13defbb79ea70f4afc8 Mon Sep 17 00:00:00 2001
From: Mikko Ohtamaa <mikko@redinnovation.com>
Date: Wed, 25 Jun 2025 12:07:45 +0200
Subject: [PATCH 1/2] Add synchronous Kaleido usage example

---
 src/py/README.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)

diff --git a/src/py/README.md b/src/py/README.md
index 7b238078..ec1dfcc2 100644
--- a/src/py/README.md
+++ b/src/py/README.md
@@ -92,6 +92,84 @@ asyncio.run(
 )
 ```
 
+You can also use threaded and synchronous Python. Here is an example how to create one Kaleido instance per-application, and launch the background Chrome browser for rendering only once.
+
+```python
+import threading
+from io import BytesIO
+import asyncio
+
+from plotly.graph_objects import Figure
+from kaleido import Kaleido
+
+_kaleido = None
+_lock = threading.Lock()
+
+
+def get_kaleido() -> Kaleido:
+  """Create Kaleido rendering backend.
+
+  - Creates a Chrome browser on background
+
+  - `See usage examples <https://github.com/plotly/Kaleido>`__
+  """
+  global _kaleido
+  with _lock:
+    if _kaleido is None:
+      _kaleido = Kaleido()
+
+  return _kaleido
+
+
+def render_plotly_figure_as_image_file(
+  figure: Figure,
+  format: str = "png",
+  width: int = 512,
+  height: int = 512,
+) -> bytes:
+  """"Render Plotly figure as a static PNG image.
+
+  - Uses Kaleido to render the Plotly figure as a PNG or SVG image.
+  - Creates Kaleido backend (Chrome browser) on the first call.
+
+  :param format:
+    "png" or "svg"
+
+  :param width:
+    Width in pixels
+
+  :param height:
+    Height in pixels
+
+  :return:
+    Image data encoded as byttes blob.
+  """
+
+  assert format in ["png", "svg"], "Format must be png or svg"
+
+  stream = BytesIO()
+
+  kaleido_instance = get_kaleido()
+
+  opts = dict(
+    format=format,
+    width=width,
+    height=height,
+  )
+
+  asyncio.run(
+    kaleido_instance.write_fig(
+      figure,
+      stream,
+      opts=opts,
+    )
+  )
+  data = stream.getvalue()
+  assert len(data) > 0, "Rendered image data is empty"
+  stream.close()
+  return data
+```
+
 ### PageGenerators
 
 The `page` argument takes a `kaleido.PageGenerator()` to customize versions.

From 6bb4c00dfb991b3827c1b6da72fb7ea81979cf45 Mon Sep 17 00:00:00 2001
From: Mikko Ohtamaa <mikko@redinnovation.com>
Date: Wed, 25 Jun 2025 12:09:59 +0200
Subject: [PATCH 2/2] Hint where to find supported formats by Kaleido

---
 src/py/README.md | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/src/py/README.md b/src/py/README.md
index ec1dfcc2..ca9d63a1 100644
--- a/src/py/README.md
+++ b/src/py/README.md
@@ -129,11 +129,11 @@ def render_plotly_figure_as_image_file(
 ) -> bytes:
   """"Render Plotly figure as a static PNG image.
 
-  - Uses Kaleido to render the Plotly figure as a PNG or SVG image.
+  - Uses Kaleido to render the Plotly figure as a PNG, SVG image, PDF or similar.
   - Creates Kaleido backend (Chrome browser) on the first call.
 
   :param format:
-    "png" or "svg"
+    See ``kaleido._fig_tools`` module for supported forms.
 
   :param width:
     Width in pixels
@@ -142,11 +142,9 @@ def render_plotly_figure_as_image_file(
     Height in pixels
 
   :return:
-    Image data encoded as byttes blob.
+    Image data encoded as bytes blob.
   """
 
-  assert format in ["png", "svg"], "Format must be png or svg"
-
   stream = BytesIO()
 
   kaleido_instance = get_kaleido()