leika 0.1.0__py3-none-any.whl

leika/__init__.py

@@ -0,0 +1,49 @@
+from ._gui_api import GuiApi as GuiApi
+from ._gui_handles import CommandEvent as CommandEvent
+from ._gui_handles import CommandHandle as CommandHandle
+from ._gui_handles import GuiButtonGroupHandle as GuiButtonGroupHandle
+from ._gui_handles import GuiButtonHandle as GuiButtonHandle
+from ._gui_handles import GuiCheckboxHandle as GuiCheckboxHandle
+from ._gui_handles import GuiContainer as GuiContainer
+from ._gui_handles import GuiDividerHandle as GuiDividerHandle
+from ._gui_handles import GuiDropdownHandle as GuiDropdownHandle
+from ._gui_handles import GuiEvent as GuiEvent
+from ._gui_handles import GuiFolderHandle as GuiFolderHandle
+from ._gui_handles import GuiFormHandle as GuiFormHandle
+from ._gui_handles import GuiHtmlHandle as GuiHtmlHandle
+from ._gui_handles import GuiImageHandle as GuiImageHandle
+from ._gui_handles import GuiInputHandle as GuiInputHandle
+from ._gui_handles import GuiMarkdownHandle as GuiMarkdownHandle
+from ._gui_handles import GuiModalHandle as GuiModalHandle
+from ._gui_handles import GuiMultiSliderHandle as GuiMultiSliderHandle
+from ._gui_handles import GuiNumberHandle as GuiNumberHandle
+from ._gui_handles import GuiPlotlyHandle as GuiPlotlyHandle
+from ._gui_handles import GuiProgressBarHandle as GuiProgressBarHandle
+from ._gui_handles import GuiRgbaHandle as GuiRgbaHandle
+from ._gui_handles import GuiRgbHandle as GuiRgbHandle
+from ._gui_handles import GuiSliderHandle as GuiSliderHandle
+from ._gui_handles import GuiTabGroupHandle as GuiTabGroupHandle
+from ._gui_handles import GuiTabHandle as GuiTabHandle
+from ._gui_handles import GuiTextHandle as GuiTextHandle
+from ._gui_handles import GuiUploadButtonHandle as GuiUploadButtonHandle
+from ._gui_handles import GuiUplotHandle as GuiUplotHandle
+from ._gui_handles import GuiVector2Handle as GuiVector2Handle
+from ._gui_handles import GuiVector3Handle as GuiVector3Handle
+from ._gui_handles import UploadedFile as UploadedFile
+from ._icons_enum import Icon as Icon
+from ._icons_enum import IconName as IconName
+from ._panes import ImageFit as ImageFit
+from ._panes import ImagePaneHandle as ImagePaneHandle
+from ._panes import PaneGrid as PaneGrid
+from ._panes import PaneGroup as PaneGroup
+from ._panes import PaneHandle as PaneHandle
+from ._panes import PaneId as PaneId
+from ._panes import Panes as Panes
+from ._panes import Placement as Placement
+from ._panes import PlotlyPaneHandle as PlotlyPaneHandle
+from ._server import ClientHandle as ClientHandle
+from ._server import Server as Server
+
+GuiTabGroup = GuiTabGroupHandle
+
+__version__ = "0.1.0"

leika/_assignable_props_api.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import abc
+from functools import cached_property
+from typing import Any, Dict, Generic, Protocol, TypeVar, get_type_hints
+
+import numpy as np
+import numpy.typing as npt
+
+# Type variable for props.
+
+
+class HasProps(Protocol):
+    props: Any  # One of the `*Props` objects in _messages.py.
+    removed: bool  # Lifecycle flag; see AssignablePropsBase guard below.
+
+
+TImpl = TypeVar("TImpl", bound=HasProps)
+
+
+def colors_to_uint8(colors: np.ndarray) -> npt.NDArray[np.uint8]:
+    """Convert intensity values to uint8. We assume the range [0,1] for floats, and
+    [0,255] for integers. Accepts any shape."""
+    if colors.dtype != np.uint8:
+        if np.issubdtype(colors.dtype, np.floating):
+            colors = np.clip(colors * 255.0, 0, 255).astype(np.uint8)
+        if np.issubdtype(colors.dtype, np.integer):
+            colors = np.clip(colors, 0, 255).astype(np.uint8)
+    return colors
+
+
+class AssignablePropsBase(Generic[TImpl]):
+    """Base class for all API objects with assignable properties."""
+
+    _impl: TImpl
+
+    def __init__(self, impl: TImpl):
+        # Make sure arrays are copied to avoid shared references.
+        # This will also make sure that our `np.array_equal` checks below work
+        # correctly.
+        for k, v in vars(impl.props).items():
+            if isinstance(v, np.ndarray):
+                setattr(impl.props, k, v.copy())
+
+        # Store the implementation object.
+        self._impl = impl
+
+    def _cast_value_recursive(self, hint: Any, value: Any, prop_name: str) -> Any:
+        """Recursively cast values to match type hints, handling arrays and tuples."""
+        # Handle numpy arrays.
+        if hint == npt.NDArray[np.float16]:
+            return np.asarray(value).astype(np.float16)
+        elif hint == npt.NDArray[np.float32]:
+            return np.asarray(value).astype(np.float32)
+        elif hint == npt.NDArray[np.float64]:
+            return np.asarray(value).astype(np.float64)
+        elif hint == npt.NDArray[np.uint8] and "color" in prop_name:
+            return colors_to_uint8(value)
+        if isinstance(value, np.ndarray):
+            return value
+
+        # Handle tuple[T, ...] pattern.
+        if (
+            isinstance(value, tuple)
+            and hasattr(hint, "__origin__")
+            and hint.__origin__ is tuple
+            and hasattr(hint, "__args__")
+            and len(hint.__args__) == 2
+            and hint.__args__[1] is ...
+        ):
+            element_type = hint.__args__[0]
+            return tuple(
+                self._cast_value_recursive(element_type, item, prop_name) for item in value
+            )
+
+        return value
+
+    @cached_property
+    def _prop_hints(self) -> Dict[str, Any]:
+        return get_type_hints(type(self._impl.props))
+
+    @abc.abstractmethod
+    def _queue_update(self, name: str, value: Any) -> None:
+        """Queue an update message with the property change."""
+
+    def _on_prop_assigned(self, name: str) -> None:
+        """Hook called after a props field is assigned and its update is queued.
+        Subclasses can override to enforce cross-field invariants (e.g. keeping
+        an array's dtype in sync with another field). No-op by default."""
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name == "_impl":
+            return object.__setattr__(self, name, value)
+
+        prop = getattr(self.__class__, name, None)
+        prop_setter = prop.fset if isinstance(prop, property) and prop.fset is not None else None
+        is_prop_hint = name in self._prop_hints
+
+        # Reject property writes after the handle has been removed. This prevents
+        # stale update messages from being queued against a no-longer-registered
+        # entity, which would otherwise re-introduce it on the client (ghost
+        # entity) because the client blindly processes incoming updates. Guard
+        # both the @property.setter path (e.g. `value` on GUI input handles) and
+        # the _prop_hints path (generic props forwarded to _queue_update).
+        if (prop_setter is not None or is_prop_hint) and self._impl.removed:
+            raise RuntimeError(f"Cannot assign to {name!r} on a removed {type(self).__name__}.")
+
+        if prop_setter is not None:
+            prop_setter(self, value)
+            return
+
+        # Try to handle as a props field.
+        if is_prop_hint:
+            # Handle type casting (arrays, tuples of arrays, etc.).
+            value = self._cast_value_recursive(self._prop_hints[name], value, name)
+            current_value = getattr(self._impl.props, name)
+
+            # Skip update if value hasn't changed.
+            try:
+                hash(current_value)
+                if current_value == value:
+                    return
+            except (TypeError, ValueError):
+                pass
+
+            # Update the value based on type.
+            if isinstance(value, np.ndarray):
+                if hasattr(current_value, "dtype"):
+                    # Ensure consistent dtype.
+                    if value.dtype != current_value.dtype:
+                        value = value.astype(current_value.dtype)
+                    if np.array_equal(current_value, value):
+                        return
+
+                # In-place update for same shape arrays.
+                if hasattr(current_value, "shape") and value.shape == current_value.shape:
+                    current_value[:] = value
+                else:
+                    setattr(self._impl.props, name, value.copy())
+                # Queue a private snapshot for the wire. It must alias NEITHER the
+                # caller's ``value`` (which the caller may mutate after assignment,
+                # e.g. an animation loop reusing one buffer) NOR the server's stored
+                # array (which a later same-shape update mutates in place, possibly
+                # while the event-loop thread is still serializing this message).
+                queued: Any = value.copy()
+            else:
+                # Non-array properties (immutable / already a fresh cast).
+                setattr(self._impl.props, name, value)
+                queued = value
+        else:
+            return object.__setattr__(self, name, value)
+
+        self._queue_update(name, queued)
+        self._on_prop_assigned(name)
+
+    def __getattr__(self, name: str) -> Any:
+        if name in self._prop_hints:
+            return getattr(self._impl.props, name)
+        else:
+            raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{name}'")

leika/_client_autobuild.py

@@ -0,0 +1,208 @@
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+client_dir = Path(__file__).resolve().parent / "client"
+build_dir = client_dir / "build"
+
+
+def _is_editable_install() -> bool:
+    """Check if Leika is installed in editable mode.
+
+    In editable installs, __file__ is in src/leika/ within the source tree.
+    In regular installs, __file__ is in site-packages/leika/.
+    """
+    leika_dir = Path(__file__).parent
+    return leika_dir.name == "leika" and leika_dir.parent.name == "src"
+
+
+def _check_leika_dev_running() -> bool:
+    """Returns True if the viewer client has been launched via `npm run dev`."""
+    try:
+        import psutil
+    except ImportError:
+        # If psutil is not installed, we can't check for dev server.
+        # This is fine for normal usage - only needed for development.
+        return False
+
+    for process in psutil.process_iter():
+        try:
+            # Check if the process is running from the correct Leika client directory
+            # and is actually a vite dev server (not just any vite command).
+            cwd = Path(process.cwd()).resolve()
+            expected_cwd = client_dir.resolve()
+
+            if cwd == expected_cwd:
+                cmdline = process.cmdline()
+                # Check for vite with --host flag (which is our dev command)
+                # Make sure it's not a build command.
+                has_vite = any("vite" in part for part in cmdline)
+                has_host = any("--host" in part for part in cmdline)
+                not_build = not any("build" in part for part in cmdline)
+
+                if has_vite and has_host and not_build:
+                    return True
+        except (psutil.AccessDenied, psutil.ZombieProcess, psutil.NoSuchProcess):
+            pass
+    return False
+
+
+def ensure_client_is_built() -> None:
+    """Ensure that the client is built or already running."""
+
+    # For non-editable installs, just verify the build exists.
+    # Skip timestamp checks and dev server detection.
+    if not _is_editable_install() and (build_dir / "index.html").exists():
+        return
+
+    if not (client_dir / "src").exists():
+        # Can't build client.
+        assert (build_dir / "index.html").exists(), (
+            "Something went wrong! At least one of the client source or build"
+            " directories should be present."
+        )
+        return
+
+    # Do we need to re-trigger a build?
+    build = False
+    if _check_leika_dev_running():
+        # Don't run build if dev server is already running.
+        import rich
+
+        rich.print(
+            "[bold](leika)[/bold] The Leika viewer looks like it has been launched via"
+            " `npm run dev`. Skipping build check..."
+        )
+        build = False
+    elif not (build_dir / "index.html").exists():
+        import rich
+
+        rich.print("[bold](leika)[/bold] No client build found. Building now...")
+        build = True
+    elif (
+        # We should be at least 10 seconds newer than the last build.
+        # This buffer is important when we install from pip, and the src/ +
+        # build/ directories have very similar timestamps.
+        _modified_time_recursive(client_dir / "src") > _modified_time_recursive(build_dir) + 10.0
+    ):
+        import rich
+
+        rich.print("[bold](leika)[/bold] Client build looks out of date. Building now...")
+        build = True
+
+    # Install nodejs and build if necessary. We assume bash is installed.
+    if build:
+        _build_leika_client(out_dir=build_dir, cached=False)
+
+
+def _build_leika_client(out_dir: Path, cached: bool = True) -> None:
+    """Create a build of the Leika client.
+
+    Args:
+        out_dir: The directory to write the built client to.
+        cached: If True, skip the build if the client is already built.
+            Instead, we'll simply copy the previous build to the new location.
+    """
+
+    if cached and build_dir.exists() and (build_dir / "index.html").exists():
+        import rich
+
+        rich.print(f"[bold](leika)[/bold] Copying client build from {build_dir} to {out_dir}.")
+        shutil.copytree(build_dir, out_dir)
+        return
+
+    node_bin_dir = _install_sandboxed_node()
+    npx_path = node_bin_dir / "npx"
+
+    subprocess_env = os.environ.copy()
+    subprocess_env["NODE_VIRTUAL_ENV"] = str(node_bin_dir.parent)
+    subprocess_env["PATH"] = (
+        str(node_bin_dir) + (";" if sys.platform == "win32" else ":") + subprocess_env["PATH"]
+    )
+    npm_path = node_bin_dir / "npm"
+
+    if sys.platform == "win32":
+        npx_path = npx_path.with_suffix(".cmd")
+        npm_path = npm_path.with_suffix(".cmd")
+
+    subprocess.run(
+        args=[str(npm_path), "install"],
+        env=subprocess_env,
+        cwd=client_dir,
+        check=False,
+    )
+    subprocess.run(
+        args=[
+            str(npx_path),
+            "vite",
+            "build",
+            "--base",
+            "./",
+            "--outDir",
+            # Relative path needs to be made absolute, since we change the CWD.
+            str(out_dir.absolute()),
+        ],
+        env=subprocess_env,
+        cwd=client_dir,
+        check=False,
+    )
+
+
+def build_client_entrypoint() -> None:
+    """Build the Leika client entrypoint, which is used to launch the viewer."""
+    parser = argparse.ArgumentParser(description="Build the Leika client.")
+    parser.add_argument("--out-dir", required=True)
+    parser.add_argument(
+        "--no-cached",
+        action="store_false",
+        help="If set, skip the build if the client is already built.",
+    )
+    args = parser.parse_args()
+    out_dir = Path(args.out_dir) if args.out_dir else build_dir
+    _build_leika_client(out_dir=out_dir, cached=args.no_cached)
+
+
+def _install_sandboxed_node() -> Path:
+    """Install a sandboxed copy of nodejs using nodeenv, and return a path to the
+    environment's bin directory (`.nodeenv/bin` or `.nodeenv/Scripts`).
+
+    On Windows, the `.nodeenv/bin` does not exist. Instead, executables are
+    installed to `.nodeenv/Scripts`."""
+
+    def get_node_bin_dir() -> Path:
+        env_dir = client_dir / ".nodeenv"
+        node_bin_dir = env_dir / "bin"
+        if not node_bin_dir.exists():
+            node_bin_dir = env_dir / "Scripts"
+        return node_bin_dir
+
+    node_bin_dir = get_node_bin_dir()
+    if (node_bin_dir / "npx").exists():
+        import rich
+
+        rich.print("[bold](leika)[/bold] nodejs is set up!")
+        return node_bin_dir
+
+    env_dir = client_dir / ".nodeenv"
+    result = subprocess.run(
+        [sys.executable, "-m", "nodeenv", "--node=24.12.0", env_dir], check=False
+    )
+
+    if result.returncode != 0:
+        raise RuntimeError(
+            "Failed to install Node.js using nodeenv. "
+            "To rebuild the Leika client, install nodeenv with: "
+            "pip install 'nodeenv>=1.9.1'"
+        )
+
+    node_bin_dir = get_node_bin_dir()
+    assert (node_bin_dir / "npx").exists()
+    return node_bin_dir
+
+
+def _modified_time_recursive(dir: Path) -> float:
+    """Recursively get the last time a file was modified in a directory."""
+    return max([f.stat().st_mtime for f in dir.glob("**/*")])