arrayview 0.42.1__tar.gz → 0.43.0__tar.gz

{arrayview-0.42.1 → arrayview-0.43.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arrayview
-Version: 0.42.1
+Version: 0.43.0
 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.1 → arrayview-0.43.0}/pyproject.toml

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

{arrayview-0.42.1 → arrayview-0.43.0}/src/arrayview/_diagnostics.py

@@ -75,6 +75,23 @@ _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 "
@@ -131,7 +148,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.0/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.1 → arrayview-0.43.0}/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)
@@ -1521,7 +1521,41 @@ def mmap_first_frame_is_cheap(arr, total_bytes) -> bool:
     return runs <= max_runs and faulted <= fraction * total_bytes
 
 
-def load_data_with_meta(filepath, key=None, *, load="lazy", stack="auto", select=None):
+def _read_npy_reporting_progress(mapped, progress):
+    """Copy a memmapped .npy into RAM in chunks, saying how far along it is.
+
+    For a large array this read is the whole wait between a click and the
+    first frame — 9 s for a 1.6 GB file on a cold cache — and ``np.load``
+    reports nothing while it runs.  Copying in pieces costs the same reads
+    and makes the wait explainable.
+
+    The flat view follows the array's own memory order, so the copy stays
+    sequential whether the file is C- or Fortran-ordered.  A .npy memmap is
+    always contiguous in one of the two, so both reshapes are views.
+    """
+    order = "F" if mapped.flags.f_contiguous and not mapped.flags.c_contiguous else "C"
+    out = np.empty(mapped.shape, dtype=mapped.dtype, order=order)
+    src = mapped.reshape(-1, order="A")
+    dst = out.reshape(-1, order="A")
+    total = int(src.shape[0])
+    itemsize = int(mapped.dtype.itemsize)
+    # ~200 updates: smooth enough to read as motion, coarse enough that the
+    # per-chunk overhead stays lost in the read itself.
+    step = max(1, total // 200)
+    done = 0
+    while done < total:
+        end = min(done + step, total)
+        dst[done:end] = src[done:end]
+        done = end
+        try:
+            progress(done * itemsize, total * itemsize)
+        except Exception:
+            pass
+    return out
+
+
+def load_data_with_meta(filepath, key=None, *, load="lazy", stack="auto", select=None,
+                        progress=None):
     """Like load_data but also returns spatial metadata for NIfTI files.
 
     Returns (array, meta_or_None). meta is None for non-NIfTI formats.
@@ -1547,10 +1581,10 @@ def load_data_with_meta(filepath, key=None, *, load="lazy", stack="auto", select
         return _load_file_series(filepath, load=load, stack=stack)
     if filepath.endswith(".nii") or filepath.endswith(".nii.gz"):
         return _load_nifti_with_meta(filepath)
-    return load_data(filepath, key=key), None
+    return load_data(filepath, key=key, progress=progress), None
 
 
-def load_data(filepath, key=None):
+def load_data(filepath, key=None, *, progress=None):
     if filepath.lower().endswith(".dcm"):
         from ._dicom import load_dicom_series
 
@@ -1577,6 +1611,8 @@ def load_data(filepath, key=None):
         if mmap_first_frame_is_cheap(mapped, size):
             # Session creation upgrades this to an in-RAM array in the background.
             return mapped
+        if progress is not None:
+            return _read_npy_reporting_progress(mapped, progress)
         del mapped
         return np.load(filepath)
     elif filepath.endswith(".npz"):

{arrayview-0.42.1 → arrayview-0.43.0}/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.1 → arrayview-0.43.0}/src/arrayview/_routes_loading.py

@@ -320,6 +320,14 @@ def register_loading_routes(app, *, notify_shells, setup_rgb) -> None:
             PENDING_SESSION_EVENTS[sid] = pending_event
             signature_before_load = file_signature(abs_path)
 
+            def _report_read_progress(done: int, total: int) -> None:
+                # Read from the viewer's websocket while it waits; see
+                # LOAD_PROGRESS. Kept to a plain assignment so the read loop
+                # pays nothing for it.
+                import arrayview._session as _sm
+
+                _sm.LOAD_PROGRESS[sid] = (done, total)
+
             def _load_in_background() -> None:
                 try:
                     from ._io import load_data_with_meta
@@ -327,6 +335,7 @@ def register_loading_routes(app, *, notify_shells, setup_rgb) -> None:
                     data, spatial_meta = load_data_with_meta(
                         filepath,
                         select=body.get("select"),
+                        progress=_report_read_progress,
                     )
                     session = Session(data, filepath=filepath, name=name)
                     session.sid = sid
@@ -369,6 +378,9 @@ def register_loading_routes(app, *, notify_shells, setup_rgb) -> None:
                     if staging_dir:
                         cleanup_staging_directory(staging_dir)
                 finally:
+                    import arrayview._session as _sm
+
+                    _sm.LOAD_PROGRESS.pop(sid, None)
                     PENDING_SESSIONS.discard(sid)
                     CANCELLED_PENDING_SESSIONS.discard(sid)
                     pending_event.set()

{arrayview-0.42.1 → arrayview-0.43.0}/src/arrayview/_routes_query.py

@@ -217,6 +217,24 @@ def register_query_routes(app, *, get_session_or_404, pil_image, pil_imageops) -
         phases = journal["phases"]
         if phase not in phases:
             phases.append(phase)
+            # Timestamps the page's own milestones against the navigation that
+            # delivered it, so time-to-first-script can be measured per
+            # navigation rather than inferred from opener poll intervals.
+            navigation_key = journal.get("navigation_key")
+            if navigation_key:
+                try:
+                    from arrayview._launch_trace import emit_route_launch_event
+
+                    emit_route_launch_event(
+                        "page.phase_recorded",
+                        navigation_key=navigation_key,
+                        tab_key=journal.get("tab_key"),
+                        request_id=request_id,
+                        navigation_attempt=journal.get("navigation_attempt"),
+                        phase=phase,
+                    )
+                except Exception:
+                    pass
         if bool(body.get("release_on_disconnect")):
             journal["disconnect_release_grace_seconds"] = 30.0
         return {