arrayview 0.42.2__tar.gz → 0.43.1__tar.gz

{arrayview-0.42.2 → arrayview-0.43.1}/PKG-INFO

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

{arrayview-0.42.2 → arrayview-0.43.1}/pyproject.toml

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

{arrayview-0.42.2 → arrayview-0.43.1}/src/arrayview/_diagnostics.py

@@ -75,11 +75,29 @@ _DIAGNOSES: list[tuple[str, str, str, str]] = [
      "fine.",
      _RETRY),
 
+    # ── A window that is alive but not answering ──────────────────────────
+    # Its process exists, so nothing treats it as dead and no other window may
+    # take the request from it — targeted requests are invisible to everyone
+    # else. The user sees nothing happen at all, and reloading that one window
+    # is the only recovery, so say so rather than suggesting a plain retry:
+    # retrying sends the next launch to the same stuck window.
+    (r"integrated browser open timeout|command discovery timeout|"
+     r"browser command did not return", ACTION,
+     "The VS Code window handling this request has stopped responding. It is "
+     "still running, so nothing else will take the request from it.",
+     _RELOAD + "  Retrying without reloading sends the next launch to the "
+     "same window."),
+    (r"claimed but never|no progress after being claimed", ACTION,
+     "A VS Code window took this request and then went quiet, so the launch is "
+     "stuck with it.",
+     _RELOAD),
+
     # ── Timing — slow, not broken ─────────────────────────────────────────
     (r"did not start the viewer script", ACTION,
      "VS Code opened an integrated-browser tab, but the tab did not navigate "
      "to the ArrayView page.",
-     _RETRY + "  If it repeats, reload the VS Code window."),
+     _RELOAD + "  Retrying without reloading sends the next launch to the "
+     "same stuck browser."),
     (r"did not render a frame|did not become ready",
      ACTION,
      "The viewer opened but showed no frame before the deadline — usually a "
@@ -131,7 +149,7 @@ _DIAGNOSES: list[tuple[str, str, str, str]] = [
      "Check the path — and that the share it lives on is mounted."),
     (r"not a directory", FATAL,
      "That path is not a directory.",
-     "Point --stack at a directory of arrays."),
+     "Point --match at a directory of arrays."),
     (r"invalid vector ?field", FATAL,
      "The vector field file could not be used with this array.",
      "It needs the array's spatial shape plus a trailing components axis."),

arrayview-0.43.1/src/arrayview/_extra_ports.py

@@ -0,0 +1,181 @@
+"""Extra listening ports on the already-running server.
+
+Why this exists
+---------------
+
+In VS Code the viewer is fetched over a forwarded port.  Measured 2026-08-06 on
+the real host: a forward that VS Code has *just created* never loses a page
+request (4/4, and 3/3 on a genuine cold start), while one that already exists
+and has sat idle for tens of seconds drops the first two to four.  A dropped
+request never arrives — the opener can only discard the tab and open another,
+which the user sees as the viewer flickering before the array appears.
+
+While any viewer is open the server keeps the forward from going idle (see the
+nudge in ``_routes_websocket``).  The case that leaves is the cold one: no
+viewer is open, so nothing has kept the forward alive, and the first launch pays.
+
+A port that has never been forwarded does not have that problem.  So a cold
+launch is served from a fresh port, which VS Code forwards for the first time.
+This module adds that port to the process that is *already* running, rather than
+starting another server: same process, same loaded arrays, nothing extra to shut
+down, and repeat opens keep using the original port.
+
+Lifetime
+--------
+
+An extra port is closed as soon as no viewer is connected **on that port**.
+Viewers report the port they arrived on, so a port is released the moment its
+own viewer goes away, rather than waiting for every viewer everywhere to close —
+otherwise one cold start early in a session would leave a port listening for the
+rest of the day.
+
+It must not be closed while a viewer loaded from it is alive: the viewer keeps
+using HTTP on its own origin long after the page has rendered, so pulling the
+port out from under it would break the viewer rather than tidy up after it.
+
+A port that never receives a viewer at all — the launch failed, or the user
+closed the tab before it loaded — is closed after ``UNUSED_GRACE_S``.  Without
+that, a failed cold start would leak a port with nothing to trigger its release.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import socket
+import time
+
+import arrayview._session as _session_mod
+from arrayview._session import _vprint
+
+# Cold starts are rare — one per session in practice, because the first launch
+# leaves a viewer open and every launch after that is warm.  The cap is a guard
+# against a pathological caller, not an expected working set.
+MAX_EXTRA_PORTS = 3
+
+# How long a freshly opened port may sit with no viewer on it before it is
+# reclaimed.  This is the leak guard for a launch that never produced a viewer;
+# it has to outlast a slow array load, because the port is opened before the
+# page is even requested and a large file can take a while to reach its socket.
+UNUSED_GRACE_S = 180.0
+
+# port -> {"socket", "server", "task", "viewers", "opened_at"}
+_EXTRA_PORTS: dict[int, dict] = {}
+
+
+def extra_ports() -> list[int]:
+    """Ports currently being served in addition to the main one."""
+    return sorted(_EXTRA_PORTS)
+
+
+def _bind_free_port() -> socket.socket:
+    """Bind a port the OS says is free, so nothing has to be guessed."""
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    sock.bind(("localhost", 0))
+    sock.listen(128)
+    return sock
+
+
+async def open_extra_port() -> int | None:
+    """Serve the running app on one more, never-before-used port.
+
+    Returns the port, or ``None`` if one could not be added.  Never raises: a
+    launch that cannot get a fresh port is still a working launch on the main
+    port, only with the cold-start flicker it would have had anyway.
+    """
+    if len(_EXTRA_PORTS) >= MAX_EXTRA_PORTS:
+        _vprint(
+            f"[ArrayView] not adding another port; {len(_EXTRA_PORTS)} already open"
+        )
+        return None
+    try:
+        import uvicorn
+
+        from arrayview import _server as _server_mod
+
+        sock = _bind_free_port()
+        port = sock.getsockname()[1]
+        config = uvicorn.Config(
+            _server_mod.app,
+            log_level="error",
+            timeout_keep_alive=30,
+            ws_ping_interval=None,
+            ws="websockets",
+            ws_per_message_deflate=True,
+        )
+        server = uvicorn.Server(config)
+        task = asyncio.create_task(server.serve(sockets=[sock]))
+        _EXTRA_PORTS[port] = {
+            "socket": sock,
+            "server": server,
+            "task": task,
+            "viewers": 0,
+            "opened_at": time.monotonic(),
+        }
+        asyncio.create_task(_close_if_unused(port))
+        # The socket is already listening and accepting before serve() runs, so
+        # a client that connects immediately is queued rather than refused.
+        _vprint(f"[ArrayView] serving a cold-start port on {port}")
+        return port
+    except Exception as exc:  # pragma: no cover - defensive
+        _vprint(f"[ArrayView] could not add a cold-start port: {exc}")
+        return None
+
+
+def viewer_connected(port: int | None) -> None:
+    """Note that a viewer arrived on *port*, if it is one of ours."""
+    entry = _EXTRA_PORTS.get(port)
+    if entry is not None:
+        entry["viewers"] += 1
+
+
+async def viewer_disconnected(port: int | None) -> None:
+    """Note a viewer left *port*, and release the port if it was the last one."""
+    entry = _EXTRA_PORTS.get(port)
+    if entry is None:
+        return
+    entry["viewers"] = max(0, entry["viewers"] - 1)
+    if entry["viewers"] == 0:
+        await _close_port(port)
+
+
+async def _close_if_unused(port: int) -> None:
+    """Reclaim a port that never got a viewer.
+
+    Its own release is driven by the viewer that loaded from it, so a launch
+    that never produced one would otherwise leave the port listening forever.
+    """
+    await asyncio.sleep(UNUSED_GRACE_S)
+    entry = _EXTRA_PORTS.get(port)
+    if entry is not None and entry["viewers"] == 0:
+        _vprint(f"[ArrayView] cold-start port {port} was never used")
+        await _close_port(port)
+
+
+async def _close_port(port: int) -> None:
+    entry = _EXTRA_PORTS.pop(port, None)
+    if entry is None:
+        return
+    try:
+        entry["server"].should_exit = True
+        await asyncio.wait_for(entry["task"], timeout=5)
+    except Exception:
+        entry["task"].cancel()
+    finally:
+        try:
+            entry["socket"].close()
+        except Exception:
+            pass
+    _vprint(f"[ArrayView] released cold-start port {port}")
+
+
+async def close_extra_ports() -> None:
+    """Release every extra port.  Only safe with no viewer connected anywhere.
+
+    A backstop for the per-port release above: if a viewer is lost without its
+    disconnect being seen, this still reclaims the port once the server is idle.
+    """
+    if not _EXTRA_PORTS or _session_mod.VIEWER_SOCKETS > 0:
+        return
+    for port in list(_EXTRA_PORTS):
+        await _close_port(port)

{arrayview-0.42.2 → arrayview-0.43.1}/src/arrayview/_io.py

@@ -1139,7 +1139,7 @@ def load_dir_collection(
     overlay match.
     """
     if not base_patterns:
-        raise ValueError("--stack requires at least one positional image pattern.")
+        raise ValueError("--match requires at least one positional image pattern.")
     overlays = overlays or []
 
     inferred_case_depth = None
@@ -1338,7 +1338,7 @@ def _load_file_series(path, *, load="lazy", stack="auto"):
 
     One file per patient folder → 4D ``(*vol, P)``.  When a folder holds
     several arrays side by side there is no per-folder case to key on, so every
-    file becomes its own case — the same collection ``--stack`` builds for that
+    file becomes its own case — the same collection ``--match`` builds for that
     directory.
 
     If every file is NIfTI (.nii/.nii.gz), delegates to
@@ -1383,9 +1383,9 @@ def _load_file_series(path, *, load="lazy", stack="auto"):
 
     # A folder holding several arrays side by side is a flat collection: one
     # case per file. This used to raise and tell the user to retype the command
-    # with --stack, which made "open this folder" unreachable from any caller
+    # with --match, which made "open this folder" unreachable from any caller
     # that can only hand over a path (VS Code Explorer, drag-and-drop, the
-    # /load route). Route it through the same builder --stack uses so both
+    # /load route). Route it through the same builder --match uses so both
     # spellings produce the same session instead of one of them failing.
     if any(len(files) != 1 for files in patients.values()):
         flat = sorted(fpath for files in patients.values() for fpath in files)
@@ -1445,7 +1445,7 @@ def _load_nifti_series(path, *, load="lazy", stack="auto"):
             raise ValueError(
                 f"Patient folder {pdir!r} contains {len(nii_files)} NIfTI "
                 f"files: {[os.path.basename(f) for f in nii_files]}. "
-                "Use --stack with explicit file patterns for multi-file folders."
+                "Use --match with explicit file patterns for multi-file folders."
             )
 
     return _series_from_file_matrix(file_matrix, load=load, stack=stack)

{arrayview-0.42.2 → arrayview-0.43.1}/src/arrayview/_launcher.py

@@ -2314,6 +2314,16 @@ def _handle_cli_spawned_daemon(
                 expected_server_id=daemon_server_id,
             ):
                 raise RuntimeError("ArrayView could not confirm no-display session cleanup")
+            # Say what happened. This mode loads the array, proves it registers,
+            # and then deliberately releases it so nothing is left holding the
+            # source — which is the whole point of it, and is why no server
+            # survives and no window opens. Printing nothing at all made a
+            # successful check indistinguishable from silently doing nothing.
+            print(
+                f"[ArrayView] {name}: loaded and released. "
+                f"No display was opened and no server is left running.",
+                flush=True,
+            )
     except Exception:
         _terminate_owned_process(daemon_proc)
         _cleanup_source_staging_dirs(source_staging_dirs)
@@ -5079,7 +5089,7 @@ class _CliCollectionScanProgress:
 
 
 def _print_dir_collection_summary(summary):
-    print("[ArrayView] --stack matched collection:")
+    print("[ArrayView] --match matched collection:")
     print(f"  cases: {len(summary['cases'])}")
     print(f"  spatial shape: {summary['spatial_shape']}")
     print(f"  image shape: {summary['shape']}")
@@ -5396,7 +5406,7 @@ def arrayview():
         default=None,
         help=(
             "Segmentation mask overlay. In file mode, pass a concrete mask file. "
-            "In --stack mode, pass NAME=PATTERN to add a named overlay role. "
+            "In --match mode, pass NAME=PATTERN to add a named overlay role. "
             "Repeat --overlay to load multiple overlays."
         ),
     )
@@ -5406,7 +5416,7 @@ def arrayview():
         action="append",
         default=None,
         help=(
-            "In --stack mode, discover mask filenames below matching per-case "
+            "In --match mode, discover mask filenames below matching per-case "
             "directories as sparse overlay roles. Missing masks render as empty. "
             "Case directories are inferred automatically; --case-regex can "
             "override unusual layouts. Repeat to include multiple directories."
@@ -5493,7 +5503,7 @@ def arrayview():
         help="Display name for the array",
     )
     parser.add_argument(
-        "--stack",
+        "--match",
         action="store_true",
         dest="stack_mode",
         help=(
@@ -5502,6 +5512,16 @@ def arrayview():
             "--overlay values become overlay role patterns."
         ),
     )
+    # --stack was renamed to --match. Without this it would not error: argparse
+    # matches unambiguous prefixes, and --stack is a prefix of --stack-policy,
+    # which takes an optional value — so an old command would run and quietly
+    # ignore what the user asked for. Failing loudly is the point of it.
+    parser.add_argument(
+        "--stack",
+        action="store_true",
+        dest="stack_flag_removed",
+        help=argparse.SUPPRESS,
+    )
     parser.add_argument(
         "--series",
         default=None,
@@ -5515,7 +5535,7 @@ def arrayview():
         default=None,
         dest="case_regex",
         help=(
-            "Regex used in --stack mode to extract a case id. Must define "
+            "Regex used in --match mode to extract a case id. Must define "
             "a named (?P<case>...) group."
         ),
     )
@@ -5523,7 +5543,7 @@ def arrayview():
         "--dry-run",
         action="store_true",
         dest="dry_run",
-        help="In --stack mode, print matched cases and roles without opening a viewer.",
+        help="In --match mode, print matched cases and roles without opening a viewer.",
     )
     parser.add_argument(
         "--stack-policy",
@@ -5532,7 +5552,7 @@ def arrayview():
         choices=("auto", "dense", "ragged"),
         dest="stack_policy",
         help=(
-            "Collection stacking policy for --stack mode: auto picks dense when "
+            "Collection stacking policy for --match mode: auto picks dense when "
             "shapes agree and ragged otherwise; dense requires matching shapes; "
             "ragged always keeps per-item shapes."
         ),
@@ -5643,19 +5663,25 @@ def arrayview():
                 f"--dims {args.dims!r} is invalid. "
                 "Use e.g. 'x,y,:,:' or ':,:,x,y' or '0,1'."
             )
+    if getattr(args, "stack_flag_removed", False):
+        parser.error(
+            "--stack has been renamed to --match, because it never controlled "
+            "stacking: a directory of arrays is stacked either way. It selects "
+            "which files form the collection."
+        )
     if args.dry_run and not args.stack_mode:
-        parser.error("--dry-run requires --stack.")
+        parser.error("--dry-run requires --match.")
     excluded_cases = set()
     if args.stack_mode:
         if not args.files:
-            parser.error("--stack requires at least one image pattern.")
+            parser.error("--match requires at least one image pattern.")
         if args.compare or args.vectorfield or args.watch or args.rgb:
             parser.error(
-                "--stack is incompatible with --compare, --vectorfield, "
+                "--match is incompatible with --compare, --vectorfield, "
                 "--watch, and --rgb."
             )
         if args.relay:
-            parser.error("--stack is incompatible with --relay.")
+            parser.error("--match is incompatible with --relay.")
     if args.stack_policy and not args.stack_mode:
         if len(args.files) != 1:
             parser.error(
@@ -5866,7 +5892,7 @@ def arrayview():
             if mount is not None or nested_mount is not None:
                 _print_failure(
                     "network directory collections are not accessed directly. "
-                    "Copy the collection to local storage before using --stack."
+                    "Copy the collection to local storage before using --match."
                 )
                 sys.exit(1)
         if len(dir_patterns) == 1 and os.path.isdir(dir_patterns[0]):
@@ -5906,11 +5932,11 @@ def arrayview():
                 break
             except MissingOverlayCasesError as e:
                 if not _confirm_partial_overlay_match(e):
-                    _print_failure(f"--stack could not match collection: {e}")
+                    _print_failure(f"--match could not match collection: {e}")
                     sys.exit(1)
                 excluded_cases.update(e.missing_cases)
             except Exception as e:
-                _print_failure(f"--stack could not match collection: {e}")
+                _print_failure(f"--match could not match collection: {e}")
                 sys.exit(1)
         _print_dir_collection_summary(summary)
         if args.dry_run:
@@ -5919,7 +5945,7 @@ def arrayview():
         from arrayview._source_safety import lexical_abspath
 
         if args.overlay_dir:
-            parser.error("--overlay-dir requires --stack.")
+            parser.error("--overlay-dir requires --match.")
         try:
             file_overlay_specs = _normalize_file_overlay_specs(args.overlay)
         except ValueError as e:

{arrayview-0.42.2 → arrayview-0.43.1}/src/arrayview/_routes_loading.py

@@ -137,32 +137,33 @@ def register_loading_routes(app, *, notify_shells, setup_rgb) -> None:
         staging_dir = validated_staging_directory(abs_path, claimed_staging)
         if claimed_staging and staging_dir is None:
             raise HTTPException(status_code=400, detail="invalid source staging directory")
-        unsafe_mount = direct_network_mount(abs_path)
-        if unsafe_mount is not None:
-            return {
-                "error": (
-                    f"Direct server access to network mount {unsafe_mount.mountpoint!r} "
-                    "is refused. Launch the file through the arrayview CLI so it can "
-                    "be staged safely."
-                )
-            }
-        nested_source_mount = network_mount_below(abs_path)
-        if nested_source_mount is not None:
-            return {
-                "error": (
-                    f"Source discovery would enter network mount "
-                    f"{nested_source_mount.mountpoint!r}; copy the collection locally first."
-                )
-            }
-        if source_may_require_sibling_discovery(abs_path):
-            nested_sibling_mount = network_mount_below(os.path.dirname(abs_path))
-            if nested_sibling_mount is not None:
+        if os.environ.get("ARRAYVIEW_SKIP_SOURCE_STAGING", "1") == "0":
+            unsafe_mount = direct_network_mount(abs_path)
+            if unsafe_mount is not None:
                 return {
                     "error": (
-                        f"Related-file discovery would enter network mount "
-                        f"{nested_sibling_mount.mountpoint!r}; copy the series locally first."
+                        f"Direct server access to network mount {unsafe_mount.mountpoint!r} "
+                        "is refused. Launch the file through the arrayview CLI so it can "
+                        "be staged safely."
                     )
                 }
+            nested_source_mount = network_mount_below(abs_path)
+            if nested_source_mount is not None:
+                return {
+                    "error": (
+                        f"Source discovery would enter network mount "
+                        f"{nested_source_mount.mountpoint!r}; copy the collection locally first."
+                    )
+                }
+            if source_may_require_sibling_discovery(abs_path):
+                nested_sibling_mount = network_mount_below(os.path.dirname(abs_path))
+                if nested_sibling_mount is not None:
+                    return {
+                        "error": (
+                            f"Related-file discovery would enter network mount "
+                            f"{nested_sibling_mount.mountpoint!r}; copy the series locally first."
+                        )
+                    }
         for pattern in dir_patterns or []:
             pattern_path = lexical_abspath(str(pattern))
             scan_root = scan_root_before_magic(pattern_path)

{arrayview-0.42.2 → arrayview-0.43.1}/src/arrayview/_routes_rendering.py

@@ -23,7 +23,7 @@ from arrayview._render import (
     render_rgb_rgba,
     render_rgba,
 )
-from arrayview._session import HEAVY_OP_LIMIT_BYTES, SESSIONS
+from arrayview._session import HEAVY_OP_LIMIT_BYTES, SESSIONS, _schedule_prefetch
 from arrayview._synthetic_mri import (
     _qmri_adjust_vmin_vmax,
     qmri_display_slice,
@@ -276,6 +276,21 @@ def register_rendering_routes(app, *, get_session_or_404) -> None:
                     mosaic_cols,
                 )
         render_ms = (time.perf_counter() - render_t0) * 1000.0
+        # This endpoint is what compare mode polls per scroll step (the live
+        # WS path has its own prefetch call). Without this, a second array
+        # open puts every pane on the request-then-wait path with nothing
+        # warmed ahead, which is a much bigger hit than the extra data alone.
+        # No per-request direction field here (stateless HTTP), so infer it
+        # from the index this session last rendered, mirroring the WS guard.
+        if slice_dim >= 0 and dim_z < 0:
+            prev_idx = getattr(session, "_http_prefetch_prev_idx", None)
+            direction = 1
+            if prev_idx is not None and len(prev_idx) == len(idx_tuple):
+                delta = idx_tuple[slice_dim] - prev_idx[slice_dim]
+                if delta:
+                    direction = 1 if delta > 0 else -1
+            session._http_prefetch_prev_idx = idx_tuple
+            _schedule_prefetch(session, dim_x, dim_y, list(idx_tuple), slice_dim, direction)
         encode_t0 = time.perf_counter()
         img = _pil_image().fromarray(rgba[:, :, :3], mode="RGB")
         buf = io.BytesIO()

{arrayview-0.42.2 → arrayview-0.43.1}/src/arrayview/_routes_vectorfield.py

@@ -79,26 +79,27 @@ def register_vectorfield_routes(app) -> None:
         staging_dir = validated_staging_directory(filepath, claimed_staging)
         if claimed_staging and staging_dir is None:
             raise HTTPException(status_code=400, detail="invalid source staging directory")
-        unsafe_mount = direct_network_mount(filepath)
-        if unsafe_mount is not None:
-            return {
-                "error": (
-                    f"Direct server access to network mount {unsafe_mount.mountpoint!r} "
-                    "is refused; launch through the arrayview CLI."
-                )
-            }
-        nested_mount = network_mount_below(filepath)
-        if source_may_require_sibling_discovery(filepath):
-            nested_mount = nested_mount or network_mount_below(
-                os.path.dirname(filepath)
-            )
-        if nested_mount is not None:
-            return {
-                "error": (
-                    f"Vector-field discovery would enter network mount "
-                    f"{nested_mount.mountpoint!r}; copy it locally first."
+        if os.environ.get("ARRAYVIEW_SKIP_SOURCE_STAGING", "1") == "0":
+            unsafe_mount = direct_network_mount(filepath)
+            if unsafe_mount is not None:
+                return {
+                    "error": (
+                        f"Direct server access to network mount {unsafe_mount.mountpoint!r} "
+                        "is refused; launch through the arrayview CLI."
+                    )
+                }
+            nested_mount = network_mount_below(filepath)
+            if source_may_require_sibling_discovery(filepath):
+                nested_mount = nested_mount or network_mount_below(
+                    os.path.dirname(filepath)
                 )
-            }
+            if nested_mount is not None:
+                return {
+                    "error": (
+                        f"Vector-field discovery would enter network mount "
+                        f"{nested_mount.mountpoint!r}; copy it locally first."
+                    )
+                }
         components_dim = body.get("components_dim")
         session = SESSIONS.get(sid)
         if not session: