Andrew/refactor tab api

.github/workflows/publish_testpypi.yml

@@ -9,18 +9,22 @@ on:
 jobs:
   super-test:
     strategy:
-      max-parallel: 2
+      fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python_v: ['3.8', '3.9', '3.10', '']
+        python_v: ['3.8', '3.9', '3.10', '3.12', '3.13', '3.14', '3.14t']
         # chrome_v: ['-1']
     defaults:
       run:
         working-directory: ./src/py/
     name: Build and Test
     runs-on: ${{ matrix.os }}
+    env:
+      UV_PYTHON: ${{ matrix.python_v }}
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
       - uses: astral-sh/setup-uv@v5
       - name: Install Dependencies
         if: ${{ matrix.os == 'ubuntu-latest' }}
@@ -29,10 +33,10 @@ jobs:
       # must actually checkout for version determination
       - run: git checkout ${{ github.ref_name }}
       - run: uv python install ${{ matrix.python_v }}
-      - run: uv python pin ${{ matrix.python_v }}
-        if: ${{ matrix.python_v != '' }}
       # don't modify sync file! messes up version!
-      - run: uv sync --all-extras --frozen # does order matter?
+      - run: uv sync --all-extras --locked --no-sources
+      - run: git status
+      - run: git diff --quiet HEAD || { echo "Working tree dirty"; exit 1; }
       - run: uv build
       - name: Reinstall from wheel
         run: >
@@ -80,11 +84,10 @@ jobs:
         working-directory: ./src/py/
     name: Upload release to TestPyPI
     needs: super-test
-    if: |
-      always() &&
-      !cancelled() &&
-      !failure() &&
-      startsWith(github.ref, 'refs/tags/')
+    if: ${{ !cancelled() &&
+            !failure() &&
+            github.event_name == 'push' &&
+            github.run_attempt == 1 }}
     runs-on: ubuntu-latest
     environment:
       name: testpypi

.github/workflows/test.yml

@@ -25,6 +25,7 @@ jobs:
         run: >
           uv sync
           --no-sources
+          --locked
           --all-extras
 
       - name: Install google-chrome-for-testing

.gitignore

@@ -25,3 +25,4 @@ src/py/integration_tests/report*
 node_modules/
 
 src/py/site/*
+.hypothesis/

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

@@ -14,7 +14,7 @@ default_install_hook_types: [pre-commit, commit-msg]
 default_stages: [pre-commit]
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v3.2.0
+    rev: v6.0.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
@@ -25,12 +25,12 @@ repos:
       - id: check-toml
       - id: debug-statements
   - repo: https://github.com/asottile/add-trailing-comma
-    rev: v3.1.0
+    rev: v3.2.0
     hooks:
       - id: add-trailing-comma
   - repo: https://github.com/astral-sh/ruff-pre-commit
     #  Ruff version.
-    rev: v0.12.10
+    rev: v0.13.3
     hooks:
       #  Run the linter.
       - id: ruff
@@ -40,7 +40,7 @@ repos:
         types_or: [python, pyi]
         #  options: ignore one line things [E701]
   - repo: https://github.com/adrienverge/yamllint
-    rev: v1.35.1
+    rev: v1.37.1
     hooks:
       - id: yamllint
         name: yamllint
@@ -55,7 +55,7 @@ repos:
           }\
         }"]
   - repo: https://github.com/rhysd/actionlint
-    rev: v1.7.4
+    rev: v1.7.7
     hooks:
       - id: actionlint
         name: Lint GitHub Actions workflow files
@@ -76,18 +76,9 @@ repos:
         args: [--staged, -c, "general.ignore=B6,T3", --msg-filename]
         stages: [commit-msg]
   - repo: https://github.com/crate-ci/typos
-    rev: v1.28.2
+    rev: v1
     hooks:
       - id: typos
-  - repo: https://github.com/markdownlint/markdownlint
-    rev: v0.13.0
-    hooks:
-      - id: markdownlint
-        name: Markdownlint
-        description: Run markdownlint on your Markdown files
-        entry: mdl --rules ~MD026 --style .markdown.rb
-        language: ruby
-        files: \.(md|mdown|markdown)$
   - repo: https://github.com/Yelp/detect-secrets
     rev: v1.5.0
     hooks:
@@ -96,3 +87,16 @@ repos:
         language: python
         entry: detect-secrets-hook
         args: ['']
+  - repo: https://github.com/rvben/rumdl-pre-commit
+    rev: v0.0.153  # Use the latest release tag
+    hooks:
+      - id: rumdl
+        # To only check (default):
+        # args: []
+        # To automatically fix issues:
+        # args: [--fix]
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.406   # pin a tag; latest as of 2025-10-01
+    hooks:
+      - id: pyright
+        args: ["--project=src/py"]

src/py/CHANGELOG.txt

@@ -1,3 +1,11 @@
+v1.3.0rc0
+- Significant refactor, better organization
+- `write_fig` and `_from_object` now take an additional argument:
+  `cancel_on_error: bool, default False`. See docs.
+- Unused `path` argument for `calc_fig` was deprecated.
+- Fixed race condition where two render tasks would choose the same filename
+
+
 v1.2.0
 - Try to use plotly JSON encoder instead of default
 

src/py/kaleido/__init__.py

@@ -19,11 +19,13 @@
     from pathlib import Path
     from typing import Any, TypeVar, Union
 
-    from ._fig_tools import Figurish, LayoutOpts
+    from ._utils.fig_tools import Figurish, LayoutOpts
 
     T = TypeVar("T")
     AnyIterable = Union[AsyncIterable[T], Iterable[T]]
 
+    from .kaleido import FigureDict
+
 __all__ = [
     "Kaleido",
     "PageGenerator",
@@ -50,7 +52,7 @@ def start_sync_server(*args: Any, silence_warnings: bool = False, **kwargs: Any)
     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`.
+    except one extra: `silence_warnings`.
 
     Args:
         *args: all arguments `Kaleido()` would take.
@@ -64,19 +66,20 @@ def start_sync_server(*args: Any, silence_warnings: bool = False, **kwargs: Any)
 
 def stop_sync_server(*, silence_warnings: bool = False):
     """
-    Stop the kaleido server. It can be restarted. Warns if not started.
+    Stop the kaleido server. It can be restarted.
+
+    This function will warn you if the server is already stopped.
 
     Args:
         silence_warnings: (bool, default False): If True, don't emit warning if
-        stopping a server that's not running.
+        stopping an already stopped server.
 
     """
     _global_server.close(silence_warnings=silence_warnings)
 
 
 async def calc_fig(
     fig: Figurish,
-    path: str | None | Path = None,
     opts: LayoutOpts | None = None,
     *,
     topojson: str | None = None,
@@ -86,22 +89,20 @@ async def calc_fig(
     Return binary for plotly figure.
 
     A convenience wrapper for `Kaleido.calc_fig()` which starts a `Kaleido` and
-    executes the `calc_fig()`.
+    executes `calc_fig()`.
     It takes an additional argument, `kopts`, a dictionary of arguments to pass
     to the kaleido process. See the `kaleido.Kaleido` docs. However,
     `calc_fig()` will never use more than one processor, so any `n` value will
     be overridden.
 
-
-    See documentation for `Kaleido.calc_fig()`.
+    See also the documentation for `Kaleido.calc_fig()`.
 
     """
     kopts = kopts or {}
     kopts["n"] = 1  # should we force this?
     async with Kaleido(**kopts) as k:
         return await k.calc_fig(
             fig,
-            path=path,
             opts=opts,
             topojson=topojson,
         )
@@ -122,14 +123,13 @@ async def write_fig(
     A convenience wrapper for `Kaleido.write_fig()` which starts a `Kaleido` and
     executes the `write_fig()`.
     It takes an additional argument, `kopts`, a dictionary of arguments to pass
-    to the kaleido process. See the `kaleido.Kaleido` docs.
-
+    to the `Kaleido` constructor. See the `kaleido.Kaleido` docs.
 
-    See documentation for `Kaleido.write_fig()` for the other arguments.
+    See also the documentation for `Kaleido.write_fig()`.
 
     """
     async with Kaleido(**(kopts or {})) as k:
-        await k.write_fig(
+        return await k.write_fig(
             fig,
             path=path,
             opts=opts,
@@ -139,26 +139,25 @@ async def write_fig(
 
 
 async def write_fig_from_object(
-    generator: AnyIterable,  # this could be more specific with []
+    fig_dicts: FigureDict | AnyIterable[FigureDict],
     *,
     kopts: dict[str, Any] | None = None,
     **kwargs,
 ):
     """
-    Write a plotly figure(s) to a file.
+    Write a plotly figure(s) to a file specified by a dictionary or iterable of.
 
     A convenience wrapper for `Kaleido.write_fig_from_object()` which starts a
     `Kaleido` and executes the `write_fig_from_object()`
     It takes an additional argument, `kopts`, a dictionary of arguments to pass
-    to the kaleido process. See the `kaleido.Kaleido` docs.
+    to the `Kaleido` constructor. See the `kaleido.Kaleido` docs.
 
-    See documentation for `Kaleido.write_fig_from_object()` for the other
-    arguments.
+    See also the documentation for `Kaleido.write_fig_from_object()`.
 
     """
     async with Kaleido(**(kopts or {})) as k:
-        await k.write_fig_from_object(
-            generator,
+        return await k.write_fig_from_object(
+            fig_dicts,
             **kwargs,
         )
 
@@ -174,14 +173,18 @@ def calc_fig_sync(*args: Any, **kwargs: Any):
 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)
+        return _global_server.call_function("write_fig", *args, **kwargs)
     else:
-        _sync_server.oneshot_async_run(write_fig, args=args, kwargs=kwargs)
+        return _sync_server.oneshot_async_run(write_fig, args=args, kwargs=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)
+        return _global_server.call_function("write_fig_from_object", *args, **kwargs)
     else:
-        _sync_server.oneshot_async_run(write_fig_from_object, args=args, kwargs=kwargs)
+        return _sync_server.oneshot_async_run(
+            write_fig_from_object,
+            args=args,
+            kwargs=kwargs,
+        )