Merge branch 'master' into patch-4

Author: tschm

.gitignore

@@ -26,3 +26,5 @@ node_modules/
 
 # IDE
 .idea
+
+src/py/site/*

src/py/.pre-commit-config.yaml

@@ -30,7 +30,7 @@ repos:
       - id: add-trailing-comma
   - repo: https://github.com/astral-sh/ruff-pre-commit
     #  Ruff version.
-    rev: v0.8.2
+    rev: v0.12.10
     hooks:
       #  Run the linter.
       - id: ruff

src/py/CHANGELOG.txt

@@ -1,3 +1,14 @@
+v1.1.0
+- Add testing
+- Fix a variety of type bugs
+- Change order of browser closer to fix hang
+- Explicitly handle certain argument options better
+- Move temp file creation to .open() out of __init__()
+- Reduce mathjax version to plotly.py
+- Fix hang and add automatic close with stop_sync_server
+- Add option to silence warnings in start/stop_sync_server
+- Fix bug where attribute was inconsistently named
+
 v1.1.0rc0
 - Improve verbosity of errors when starting kaleido improperly
 - Add new api functions start/stop_sync_server

src/py/kaleido/__init__.py

@@ -6,30 +6,23 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from choreographer.cli import get_chrome, get_chrome_sync
 
 from . import _sync_server
 from ._page_generator import PageGenerator
 from .kaleido import Kaleido
 
-_global_server = _sync_server.GlobalKaleidoServer()
-
-
-def start_sync_server(*args, **kwargs):
-    """
-    Start a kaleido server which will process all sync generation requests.
-
-    Only one server can be started at a time.
-
-    This wrapper function takes the exact same arguments as kaleido.Kaleido().
-    """
-    _global_server.open(*args, **kwargs)
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterable, Iterable
+    from pathlib import Path
+    from typing import Any, TypeVar, Union
 
+    from ._fig_tools import Figurish, LayoutOpts
 
-def stop_sync_server():
-    """Stop the kaleido server. It can be restarted."""
-    _global_server.close()
-
+    T = TypeVar("T")
+    AnyIterable = Union[AsyncIterable[T], Iterable[T]]
 
 __all__ = [
     "Kaleido",
@@ -46,14 +39,48 @@ def stop_sync_server():
     "write_fig_sync",
 ]
 
+_global_server = _sync_server.GlobalKaleidoServer()
+
+
+def start_sync_server(*args: Any, silence_warnings: bool = False, **kwargs: Any):
+    """
+    Start a kaleido server which will process all sync generation requests.
+
+    The kaleido server is a singleton, so it can't be opened twice. This
+    function will warn you if the server is already running.
+
+    This wrapper function takes the exact same arguments as kaleido.Kaleido(),
+    except one extra, `silence_warnings`.
+
+    Args:
+        *args: all arguments `Kaleido()` would take.
+        silence_warnings: (bool, default False): If True, don't emit warning if
+        starting an already started server.
+        **kwargs: all keyword arguments `Kaleido()` would take.
+
+    """
+    _global_server.open(*args, silence_warnings=silence_warnings, **kwargs)
+
+
+def stop_sync_server(*, silence_warnings: bool = False):
+    """
+    Stop the kaleido server. It can be restarted. Warns if not started.
+
+    Args:
+        silence_warnings: (bool, default False): If True, don't emit warning if
+        stopping a server that's not running.
+
+    """
+    _global_server.close(silence_warnings=silence_warnings)
+
 
 async def calc_fig(
-    fig,
-    path=None,
-    opts=None,
+    fig: Figurish,
+    path: str | None | Path = None,
+    opts: LayoutOpts | None = None,
     *,
-    topojson=None,
-    kopts=None,
+    topojson: str | None = None,
+    kopts: dict[str, Any] | None = None,
 ):
     """
     Return binary for plotly figure.
@@ -70,7 +97,7 @@ async def calc_fig(
 
     """
     kopts = kopts or {}
-    kopts["n"] = 1
+    kopts["n"] = 1  # should we force this?
     async with Kaleido(**kopts) as k:
         return await k.calc_fig(
             fig,
@@ -80,15 +107,14 @@ async def calc_fig(
         )
 
 
-async def write_fig(  # noqa: PLR0913 (too many args, complexity)
-    fig,
-    path=None,
-    opts=None,
+async def write_fig(
+    fig: Figurish,
+    path: str | None | Path = None,
+    opts: LayoutOpts | None = None,
     *,
-    topojson=None,
-    error_log=None,
-    profiler=None,
-    kopts=None,
+    topojson: str | None = None,
+    kopts: dict[str, Any] | None = None,
+    **kwargs,
 ):
     """
     Write a plotly figure(s) to a file.
@@ -108,17 +134,15 @@ async def write_fig(  # noqa: PLR0913 (too many args, complexity)
             path=path,
             opts=opts,
             topojson=topojson,
-            error_log=error_log,
-            profiler=profiler,
+            **kwargs,
         )
 
 
 async def write_fig_from_object(
-    generator,
+    generator: AnyIterable,  # this could be more specific with []
     *,
-    error_log=None,
-    profiler=None,
-    kopts=None,
+    kopts: dict[str, Any] | None = None,
+    **kwargs,
 ):
     """
     Write a plotly figure(s) to a file.
@@ -135,28 +159,27 @@ async def write_fig_from_object(
     async with Kaleido(**(kopts or {})) as k:
         await k.write_fig_from_object(
             generator,
-            error_log=error_log,
-            profiler=profiler,
+            **kwargs,
         )
 
 
-def calc_fig_sync(*args, **kwargs):
+def calc_fig_sync(*args: Any, **kwargs: Any):
     """Call `calc_fig` but blocking."""
     if _global_server.is_running():
         return _global_server.call_function("calc_fig", *args, **kwargs)
     else:
         return _sync_server.oneshot_async_run(calc_fig, args=args, kwargs=kwargs)
 
 
-def write_fig_sync(*args, **kwargs):
+def write_fig_sync(*args: Any, **kwargs: Any):
     """Call `write_fig` but blocking."""
     if _global_server.is_running():
         _global_server.call_function("write_fig", *args, **kwargs)
     else:
         _sync_server.oneshot_async_run(write_fig, args=args, kwargs=kwargs)
 
 
-def write_fig_from_object_sync(*args, **kwargs):
+def write_fig_from_object_sync(*args: Any, **kwargs: Any):
     """Call `write_fig_from_object` but blocking."""
     if _global_server.is_running():
         _global_server.call_function("write_fig_from_object", *args, **kwargs)