arrayview 0.26.1__tar.gz → 0.26.3__tar.gz

{arrayview-0.26.1 → arrayview-0.26.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arrayview
-Version: 0.26.1
+Version: 0.26.3
 Summary: Fast multi-dimensional array viewer
 Project-URL: Home, https://github.com/oscarvanderheide/arrayview
 Project-URL: Source, https://github.com/oscarvanderheide/arrayview

arrayview-0.26.3/docs/launch-routing-refactor.md

@@ -0,0 +1,167 @@
+# Launch Routing Refactor
+
+ArrayView currently opens displays through several partially overlapping paths:
+CLI, `view()`, Jupyter, Julia, VS Code local, VS Code tunnel, SSH, native
+pywebview, browser fallback, and stdio/direct webview mode.  The same policy is
+encoded in multiple places, so fixes in one path can leave another path broken.
+
+This refactor makes launch routing explicit, shared, and inspectable.
+
+## Problem
+
+The brittle behavior comes from policy being split across:
+
+- environment detection in `_platform.py`
+- CLI planning in `_launcher.py`
+- Python `view()` planning in `_launcher.py`
+- VS Code signal/direct-mode fallback in `_vscode_browser.py` and `_vscode_signal.py`
+- separate HTTP and stdio session registration paths
+
+Symptoms seen recently:
+
+- CLI diagnose says native pywebview should open, but runtime falls back to a browser.
+- Linux native detection allows GTK systems while native launch forced Qt.
+- `view()` and CLI had different native readiness checks.
+- Existing-server remote behavior can accidentally switch from registered URL mode to direct stdio mode.
+
+## Target Model
+
+Create a single launch plan used by both CLI and `view()`.
+
+The plan should be data-only:
+
+```python
+Invocation = "cli" | "python" | "jupyter" | "julia" | "stdio" | "codex"
+Environment = "terminal" | "vscode_local" | "vscode_remote" | "ssh" | "jupyter" | "julia"
+Transport = "http" | "stdio_file" | "stdio_shm" | "none"
+ServerOwner = "existing" | "spawned_daemon" | "in_process" | "persistent" | "external"
+Display = "native" | "browser" | "vscode" | "inline" | "none"
+Registration = "http_load" | "daemon_startup" | "in_process_session" | "stdio_register" | "relay"
+```
+
+Executors may perform work, but should not invent policy.  Browser fallback,
+VS Code direct mode, native readiness, and remote behavior must be selected by
+the plan.
+
+## Phase 1: Snapshot And Diagnose
+
+Add a launch environment snapshot:
+
+```python
+snapshot_launch_environment(port, invocation, requested_window)
+```
+
+It should capture:
+
+- platform
+- relevant environment variables
+- config default
+- native backend: `qt`, `gtk`, `""`, or `None`
+- port busy / ArrayView server alive / server PID / hostname
+- VS Code local vs remote/tunnel
+- SSH state
+- Jupyter and Julia state
+
+`arrayview --diagnose` must print the same snapshot and plan used by real launch.
+
+## Phase 2: Shared Planner
+
+Add:
+
+```python
+plan_launch(invocation, request, env) -> LaunchPlan
+```
+
+The planner decides:
+
+- transport: HTTP, stdio file, stdio SHM, or none
+- display: native, browser, vscode, inline, none
+- server owner: existing, spawned daemon, in-process, persistent, external
+- registration: HTTP load, daemon startup, in-process session, stdio register, relay
+- fallback policy: whether fallback is allowed and where it goes
+
+CLI and `view()` should both call this planner.
+
+## Phase 3: Native Readiness
+
+Use one native readiness primitive everywhere:
+
+```python
+open_native_shell(...)
+wait_native_ready(shell_socket=True, viewer_socket=True, process_alive=True)
+```
+
+Rules:
+
+- process crash is native launch failure
+- shell WebSocket means the native window is usable
+- viewer WebSocket means the content loaded
+- missing viewer WebSocket alone is not native failure
+- browser fallback happens only after native process/shell failure
+
+## Phase 4: Remote Existing-Server Fix
+
+Separate these cases explicitly:
+
+- `Display=vscode`, `Transport=http`: open the registered HTTP URL in VS Code
+- `Display=vscode`, `Transport=stdio_file`: open direct stdio file session
+
+Do not let `_open_browser(..., filepath=...)` implicitly switch an existing
+registered URL into direct stdio mode.
+
+## Phase 5: VS Code Direct Mode
+
+Consolidate SHM/direct mode:
+
+- one `_open_direct_via_shm()` implementation
+- one SHM wait loop
+- Julia remote, Python remote, and tunnel notebook paths call the same helper
+
+Remove or clearly deprecate duplicate direct-mode helpers.
+
+## Phase 6: Registration Semantics
+
+Align HTTP `/load` and stdio registration:
+
+- shared file/key selection behavior
+- shared RAM guard behavior where possible
+- shared RGB/vectorfield/overlay/compare semantics where possible
+- documented differences where transports genuinely diverge
+
+## Contract Tests
+
+Prefer contract tests over broad visual smoke for launch routing:
+
+- macOS terminal CLI native
+- Linux Qt native
+- Linux GTK native
+- Linux no display browser fallback
+- plain SSH guidance
+- VS Code local tab
+- VS Code remote direct stdio
+- VS Code remote existing HTTP URL
+- Jupyter inline
+- VS Code remote notebook direct
+- Julia subprocess/direct
+
+Execution contracts:
+
+- existing server native shell does not fall back only because viewer socket is late
+- spawned daemon native shell does not fall back only because viewer socket is late
+- `view()` native shell does not fall back only because viewer socket is late
+- remote existing server opens registered URL, not direct stdio
+- GTK-only Linux passes `gui="gtk"` to pywebview
+
+## Migration Order
+
+1. Add launch data model and environment snapshot without behavior changes.
+2. Make `--diagnose` use the snapshot and shared planner.
+3. Move CLI planning into `plan_launch()`.
+4. Move `view()` planning into `plan_launch()`.
+5. Unify native readiness for CLI and `view()`.
+6. Fix remote existing-server URL/direct ambiguity.
+7. Consolidate SHM direct mode.
+8. Align HTTP and stdio registration semantics.
+
+Each step should have focused invocation tests and should avoid unrelated UI or
+rendering changes.

{arrayview-0.26.1 → arrayview-0.26.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arrayview"
-version = "0.26.1"
+version = "0.26.3"
 description = "Fast multi-dimensional array viewer"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.12"

arrayview-0.26.3/src/arrayview/_launch_plan.py

@@ -0,0 +1,285 @@
+"""Data-only launch routing primitives and environment snapshots."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from enum import Enum
+import json
+import os
+import socket
+import sys
+import urllib.request
+
+_LOOPBACK_HOST = "localhost"
+_PING_TIMEOUT_SECONDS = 0.2
+
+_SNAPSHOT_ENV_KEYS = (
+    "ARRAYVIEW_WINDOW",
+    "ARRAYVIEW_WINDOW_ID",
+    "DISPLAY",
+    "TERM_PROGRAM",
+    "VSCODE_AGENT_FOLDER",
+    "VSCODE_INJECTION",
+    "VSCODE_IPC_HOOK_CLI",
+    "WAYLAND_DISPLAY",
+    "SSH_CLIENT",
+    "SSH_CONNECTION",
+)
+
+
+class _StrEnum(str, Enum):
+    def __str__(self) -> str:
+        return self.value
+
+
+class Invocation(_StrEnum):
+    CLI = "cli"
+    PYTHON = "python"
+    JUPYTER = "jupyter"
+    JULIA = "julia"
+    STDIO = "stdio"
+    CODEX = "codex"
+
+
+class Environment(_StrEnum):
+    TERMINAL = "terminal"
+    VSCODE_LOCAL = "vscode_local"
+    VSCODE_REMOTE = "vscode_remote"
+    SSH = "ssh"
+    JUPYTER = "jupyter"
+    JULIA = "julia"
+
+
+class Transport(_StrEnum):
+    HTTP = "http"
+    STDIO_FILE = "stdio_file"
+    STDIO_SHM = "stdio_shm"
+    NONE = "none"
+
+
+class ServerOwner(_StrEnum):
+    EXISTING = "existing"
+    SPAWNED_DAEMON = "spawned_daemon"
+    IN_PROCESS = "in_process"
+    PERSISTENT = "persistent"
+    EXTERNAL = "external"
+
+
+class Display(_StrEnum):
+    NATIVE = "native"
+    BROWSER = "browser"
+    VSCODE = "vscode"
+    INLINE = "inline"
+    NONE = "none"
+
+
+class Registration(_StrEnum):
+    HTTP_LOAD = "http_load"
+    DAEMON_STARTUP = "daemon_startup"
+    IN_PROCESS_SESSION = "in_process_session"
+    STDIO_REGISTER = "stdio_register"
+    RELAY = "relay"
+
+
+@dataclass(frozen=True)
+class ServerSnapshot:
+    port: int
+    port_busy: bool
+    arrayview_server_alive: bool
+    server_pid: int | None = None
+    server_hostname: str | None = None
+
+
+@dataclass(frozen=True)
+class LaunchEnvironmentSnapshot:
+    invocation: Invocation
+    requested_window: str | None
+    environment: Environment
+    platform: str
+    env_vars: dict[str, str]
+    config_default: str | None
+    native_backend: str | None
+    server: ServerSnapshot
+    in_jupyter: bool
+    in_julia: bool
+    in_vscode_terminal: bool
+    is_vscode_remote: bool
+    in_vscode_tunnel: bool
+    ssh_connection: bool
+    ssh_client: bool
+    hostname: str
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class LaunchRequest:
+    port: int
+    requested_window: str | None = None
+
+
+@dataclass(frozen=True)
+class LaunchPlan:
+    invocation: Invocation
+    environment: Environment
+    transport: Transport
+    server_owner: ServerOwner
+    display: Display
+    registration: Registration
+    fallback_display: Display | None = None
+    fallback_allowed: bool = False
+
+
+def snapshot_launch_environment(
+    port: int,
+    invocation: Invocation | str,
+    requested_window: str | None = None,
+) -> LaunchEnvironmentSnapshot:
+    """Capture launch-relevant facts without importing the server stack."""
+    inv = _coerce_invocation(invocation)
+    env_vars = _snapshot_env_vars()
+    in_jupyter = _platform_bool("_in_jupyter")
+    in_julia = _platform_bool("_is_julia_env")
+    in_vscode_terminal = _platform_bool("_in_vscode_terminal")
+    is_vscode_remote = _platform_bool("_is_vscode_remote")
+    in_vscode_tunnel = _platform_bool("_in_vscode_tunnel")
+    ssh_connection = bool(os.environ.get("SSH_CONNECTION"))
+    ssh_client = bool(os.environ.get("SSH_CLIENT"))
+    environment = _classify_environment(
+        in_jupyter=in_jupyter,
+        in_julia=in_julia,
+        in_vscode_terminal=in_vscode_terminal,
+        is_vscode_remote=is_vscode_remote,
+        ssh_connection=ssh_connection,
+        ssh_client=ssh_client,
+    )
+
+    return LaunchEnvironmentSnapshot(
+        invocation=inv,
+        requested_window=requested_window,
+        environment=environment,
+        platform=sys.platform,
+        env_vars=env_vars,
+        config_default=_config_window_default(environment.value),
+        native_backend=_native_window_gui(),
+        server=_server_snapshot(port),
+        in_jupyter=in_jupyter,
+        in_julia=in_julia,
+        in_vscode_terminal=in_vscode_terminal,
+        is_vscode_remote=is_vscode_remote,
+        in_vscode_tunnel=in_vscode_tunnel,
+        ssh_connection=ssh_connection,
+        ssh_client=ssh_client,
+        hostname=socket.gethostname(),
+    )
+
+
+def _coerce_invocation(value: Invocation | str) -> Invocation:
+    if isinstance(value, Invocation):
+        return value
+    return Invocation(value)
+
+
+def _snapshot_env_vars() -> dict[str, str]:
+    return {key: os.environ[key] for key in _SNAPSHOT_ENV_KEYS if key in os.environ}
+
+
+def _platform_bool(name: str) -> bool:
+    try:
+        from arrayview import _platform
+
+        return bool(getattr(_platform, name)())
+    except Exception:
+        return False
+
+
+def _native_window_gui() -> str | None:
+    try:
+        from arrayview._platform import _native_window_gui as native_window_gui
+
+        return native_window_gui()
+    except Exception:
+        return None
+
+
+def _config_window_default(environment: str) -> str | None:
+    try:
+        from arrayview._config import load_config
+
+        cfg = load_config()
+    except Exception:
+        return None
+    window_cfg = cfg.get("window", {})
+    if not isinstance(window_cfg, dict):
+        return None
+    env_key = "vscode" if environment in {"vscode_local", "vscode_remote"} else environment
+    value = window_cfg.get(env_key) or window_cfg.get("default")
+    if isinstance(value, str):
+        return value.strip().lower() or None
+    return None
+
+
+def _classify_environment(
+    *,
+    in_jupyter: bool,
+    in_julia: bool,
+    in_vscode_terminal: bool,
+    is_vscode_remote: bool,
+    ssh_connection: bool,
+    ssh_client: bool,
+) -> Environment:
+    if in_jupyter:
+        return Environment.JUPYTER
+    if in_julia:
+        return Environment.JULIA
+    if is_vscode_remote:
+        return Environment.VSCODE_REMOTE
+    if in_vscode_terminal:
+        return Environment.VSCODE_LOCAL
+    if ssh_connection or ssh_client:
+        return Environment.SSH
+    return Environment.TERMINAL
+
+
+def _server_snapshot(port: int) -> ServerSnapshot:
+    payload = _ping_arrayview_server(port)
+    return ServerSnapshot(
+        port=port,
+        port_busy=_port_busy(port),
+        arrayview_server_alive=payload is not None,
+        server_pid=_int_or_none(payload.get("pid")) if payload else None,
+        server_hostname=_str_or_none(payload.get("hostname")) if payload else None,
+    )
+
+
+def _port_busy(port: int) -> bool:
+    try:
+        with socket.create_connection(
+            (_LOOPBACK_HOST, port), timeout=_PING_TIMEOUT_SECONDS
+        ):
+            return True
+    except OSError:
+        return False
+
+
+def _ping_arrayview_server(port: int) -> dict | None:
+    url = f"http://{_LOOPBACK_HOST}:{port}/ping"
+    try:
+        with urllib.request.urlopen(url, timeout=_PING_TIMEOUT_SECONDS) as resp:
+            if resp.status != 200:
+                return None
+            payload = json.loads(resp.read().decode("utf-8"))
+    except Exception:
+        return None
+    if payload.get("ok") is True and payload.get("service") == "arrayview":
+        return payload
+    return None
+
+
+def _int_or_none(value: object) -> int | None:
+    return value if isinstance(value, int) else None
+
+
+def _str_or_none(value: object) -> str | None:
+    return value if isinstance(value, str) else None