arrayview 0.36.0__tar.gz → 0.38.1__tar.gz

{arrayview-0.36.0 → arrayview-0.38.1}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arrayview"
-version = "0.36.0"
+version = "0.38.1"
 description = "Fast multi-dimensional array viewer"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.12"
@@ -43,7 +43,6 @@ dependencies = [
 
 [project.scripts]
 arrayview = "arrayview._launcher:arrayview"
-arrayview-codex = "arrayview._codex_open:main"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/arrayview"]

{arrayview-0.36.0 → arrayview-0.38.1}/src/arrayview/_io.py

@@ -1397,6 +1397,76 @@ def _load_nifti_series(path, *, load="lazy", stack="auto"):
     return _series_from_file_matrix(file_matrix, load=load, stack=stack)
 
 
+_MMAP_PAGE_BYTES = 4096
+
+
+def npy_eager_limit() -> int:
+    """Largest .npy that may be read fully into RAM."""
+    return int(os.environ.get("AV_NPY_EAGER_BYTES", 2 * 1024**3))
+
+
+def first_frame_fault_cost(shape, itemsize, strides, dims, total_bytes):
+    """Estimate what a memmap must fetch to render one 2D slice.
+
+    Returns ``(runs, bytes)``.  Both matter, and on network storage the run
+    count matters more: a frame of 210 single-page runs measured 1.34 s off an
+    SMB share while transferring under a megabyte, because the cost was 210
+    round-trips rather than the bytes.
+
+    Only the layout is consulted, so this touches no data.  The displayed axes
+    are ordered by stride; the inner one decides whether the frame arrives as a
+    few long runs or as one page per element.
+    """
+    dx, dy = dims
+    inner, outer = sorted(
+        ((abs(int(strides[d])), int(shape[d])) for d in (dx, dy)),
+        key=lambda pair: pair[0],
+    )
+    inner_stride, inner_len = inner
+    outer_stride, outer_len = outer
+
+    row_span = inner_len * inner_stride
+    if inner_stride == itemsize and outer_stride == row_span:
+        # The displayed pair is itself one contiguous block (e.g. axes (0, 1) of
+        # a Fortran-order array, or the trailing pair of a C-order one).
+        return 1, min(row_span * outer_len, int(total_bytes))
+    if inner_stride >= _MMAP_PAGE_BYTES:
+        # Nothing shares a page: one fetch per element, the pathological case.
+        runs = inner_len * outer_len
+        return runs, min(runs * _MMAP_PAGE_BYTES, int(total_bytes))
+    # Each row is one near-contiguous span; rows are scattered across the file.
+    row_bytes = max(row_span, _MMAP_PAGE_BYTES)
+    return outer_len, min(outer_len * row_bytes, int(total_bytes))
+
+
+def mmap_first_frame_is_cheap(arr, total_bytes) -> bool:
+    """Whether serving the viewer's first frame off *arr* beats reading it whole.
+
+    A memmap wins when the axes the viewer starts on are the fastest-varying
+    ones in the file layout, and loses badly when they are the slowest: the same
+    4D array costs a single contiguous block in Fortran order and roughly one
+    page per element in C order.  Both regimes are common, so decide per array
+    rather than assuming either.
+    """
+    if os.environ.get("AV_MMAP_FIRST_FRAME", "1") == "0":
+        return False
+    from ._session import _viewer_start_dims_for_shape
+
+    shape = tuple(int(s) for s in getattr(arr, "shape", ()))
+    strides = tuple(int(s) for s in getattr(arr, "strides", ()))
+    if len(shape) < 2 or len(strides) != len(shape) or not total_bytes:
+        return False
+    dims = _viewer_start_dims_for_shape(shape)
+    if dims is None:
+        return False
+    runs, faulted = first_frame_fault_cost(
+        shape, arr.dtype.itemsize, strides, dims, total_bytes
+    )
+    max_runs = int(os.environ.get("AV_MMAP_FIRST_FRAME_MAX_RUNS", "1024"))
+    fraction = float(os.environ.get("AV_MMAP_FIRST_FRAME_FRACTION", "0.25"))
+    return runs <= max_runs and faulted <= fraction * total_bytes
+
+
 def load_data_with_meta(filepath, key=None, *, load="lazy", stack="auto", select=None):
     """Like load_data but also returns spatial metadata for NIfTI files.
 
@@ -1430,15 +1500,20 @@ def load_data(filepath, key=None):
         series, _meta = _load_file_series(filepath)
         return series
     if filepath.endswith(".npy"):
-        # Eager-load small-to-medium files into RAM.  mmap_mode="r" on a C-order
-        # 4D+ array forces scattered page faults for every orthogonal slice
-        # (elements are thousands of bytes apart), making first renders very slow.
-        # Sequential read is much faster and the PENDING_SESSIONS background thread
-        # hides the upfront cost.  Keep mmap only for files that don't fit in RAM.
-        _NPY_EAGER_LIMIT = int(os.environ.get("AV_NPY_EAGER_BYTES", 2 * 1024**3))
-        if os.path.getsize(filepath) < _NPY_EAGER_LIMIT:
-            return np.load(filepath)
-        return np.load(filepath, mmap_mode="r")
+        # Files that do not fit in RAM must be mapped whatever the access cost.
+        # Below that limit the array ends up in RAM either way; the only question
+        # is whether the first frame is served from the map while the sequential
+        # read runs behind it (see mmap_first_frame_is_cheap) or the viewer shows
+        # a spinner until the read completes.
+        size = os.path.getsize(filepath)
+        if size >= npy_eager_limit():
+            return np.load(filepath, mmap_mode="r")
+        mapped = np.load(filepath, mmap_mode="r")
+        if mmap_first_frame_is_cheap(mapped, size):
+            # Session creation upgrades this to an in-RAM array in the background.
+            return mapped
+        del mapped
+        return np.load(filepath)
     elif filepath.endswith(".npz"):
         npz = np.load(filepath)
         try:

{arrayview-0.36.0 → arrayview-0.38.1}/src/arrayview/_launch_plan.py

@@ -41,7 +41,6 @@ class Invocation(_StrEnum):
     JULIA = "julia"
     MATLAB = "matlab"
     VSCODE_EXPLORER = "vscode_explorer"
-    CODEX = "codex"
 
 
 class Environment(_StrEnum):

{arrayview-0.36.0 → arrayview-0.38.1}/src/arrayview/_launcher.py

@@ -1672,7 +1672,7 @@ def _register_cli_session_with_existing_server_impl(
             error += (
                 "\nThe server on this port is an older ArrayView process that "
                 "does not support automatic --overlay-dir case inference yet. "
-                f"Restart it with: arrayview --kill --port {port}"
+                "Restart it with: arrayview stop"
             )
         raise RuntimeError(f"Error from server: {error}")
     _loaded_sids.append(str(result["sid"]))
@@ -1860,7 +1860,7 @@ def _handle_cli_existing_server(
             print(
                 f"Error: existing ArrayView server on port {port} does not support "
                 "directory stacking. Restart it with "
-                f"`arrayview --kill --port {port}` or choose a free port with "
+                "`arrayview stop` or choose a free port with "
                 f"`--port`. ({e})"
             )
             sys.exit(1)
@@ -4307,6 +4307,7 @@ def _serve_daemon(
                         f"[ArrayView] Warning: failed to load vector field {vfield_filepath}: {e}",
                         flush=True,
                     )
+            _session_mod.upgrade_memmap_in_background(session)
             _session_mod.SESSIONS[session.sid] = session
             if dir_overlay_items is not None:
                 for item, ov_sid in zip(dir_overlay_items, overlay_sids or []):
@@ -4815,9 +4816,29 @@ def _instance_public_dict(record) -> dict[str, object]:
     return value
 
 
+def _run_stop_command() -> None:
+    """Stop every running ArrayView instance and clean up stale state."""
+    from arrayview._instance_registry import InstanceRegistry  # noqa: PLC0415
+
+    records = InstanceRegistry().discover(clean_stale=True)
+    if not records:
+        print("[ArrayView] No running ArrayView instances.")
+    for record in records:
+        message, _pid = _stop_verified_server(record.port)
+        print(f"[ArrayView] {record.instance_id}: {message}")
+
+    from arrayview._vscode_signal import (  # noqa: PLC0415
+        _cleanup_zombie_registrations,
+    )
+
+    cleaned = _cleanup_zombie_registrations(verbose=True)
+    if cleaned:
+        print(f"[ArrayView] Cleaned {cleaned} zombie window registration(s)")
+
+
 def _handle_management_command(argv: list[str]) -> bool:
     """Handle dependency-light management subcommands before the file CLI."""
-    if not argv or argv[0] not in {"doctor", "instances", "stop"}:
+    if not argv or argv[0] not in {"doctor", "instances", "stop", "kill"}:
         return False
     command = argv[0]
     parser = argparse.ArgumentParser(prog=f"arrayview {command}")
@@ -4843,22 +4864,10 @@ def _handle_management_command(argv: list[str]) -> bool:
                 )
         return True
 
-    if command == "stop":
-        group = parser.add_mutually_exclusive_group(required=True)
-        group.add_argument("instance_id", nargs="?")
-        group.add_argument("--all", action="store_true")
-        args = parser.parse_args(argv[1:])
-        records = InstanceRegistry().discover(clean_stale=True)
-        selected = (
-            records
-            if args.all
-            else [record for record in records if record.instance_id == args.instance_id]
-        )
-        if not selected:
-            parser.error("no matching running ArrayView instance")
-        for record in selected:
-            message, _pid = _stop_verified_server(record.port)
-            print(f"[ArrayView] {record.instance_id}: {message}")
+    if command in {"stop", "kill"}:
+        parser.description = "Stop every running ArrayView server."
+        parser.parse_args(argv[1:])
+        _run_stop_command()
         return True
 
     parser.add_argument("--json", action="store_true")
@@ -5002,7 +5011,7 @@ def arrayview():
     parser.add_argument(
         "--kill",
         action="store_true",
-        help="Kill the ArrayView server running on --port (default 8000) and exit",
+        help="Deprecated: use `arrayview stop`",
     )
     parser.add_argument(
         "--overlay",
@@ -5350,15 +5359,9 @@ def arrayview():
             sys.exit(1)
         return
 
-    # -- --kill: stop the server on the given port --
+    # -- --kill: deprecated alias for `arrayview stop` --
     if args.kill:
-        message, _pid = _stop_verified_server(args.port)
-        print(f"[ArrayView] {message}")
-
-        from arrayview._vscode_signal import _cleanup_zombie_registrations
-        cleaned = _cleanup_zombie_registrations(verbose=True)
-        if cleaned:
-            print(f"[ArrayView] Cleaned {cleaned} zombie window registration(s)")
+        _run_stop_command()
         return
 
     # -- --serve: start a persistent empty server and exit --
@@ -5403,7 +5406,7 @@ def arrayview():
                 if serve_context.evidence.is_vscode_remote:
                     print(
                         f"[ArrayView] Port {args.port} was claimed while starting.\n"
-                        f"  Run 'arrayview --kill --port {args.port}' to free it, "
+                        "  Run 'arrayview stop' to free it, "
                         "or use --port to specify a different port.",
                         flush=True,
                     )
@@ -5675,7 +5678,7 @@ def arrayview():
     if launch_plan.failure is LaunchFailure.REMOTE_PORT_CONFLICT:
         print(
             f"[ArrayView] Port {args.port} is in use by another process.\n"
-            f"  Run 'arrayview --kill --port {args.port}' to free it, "
+            "  Run 'arrayview stop' to free it, "
             f"or use --port to specify a different port.",
             flush=True,
         )

{arrayview-0.36.0 → arrayview-0.38.1}/src/arrayview/_platform.py

@@ -6,6 +6,7 @@ import importlib.util
 import hashlib
 import json
 import os
+from collections.abc import Callable
 import subprocess
 import sys
 
@@ -450,6 +451,42 @@ def _process_is_alive(pid: object) -> bool:
         return False
 
 
+def _superseding_window_registration(
+    claimed_ids: list[str],
+    signal_dir: str,
+    read: Callable[[str], tuple[str, dict] | None],
+) -> tuple[str, dict] | None:
+    """Return the live window that replaced one of ``claimed_ids``, if unique.
+
+    Each registration lists the window ids it took over from, so a terminal left
+    holding a pre-reload id resolves to its own window rather than to a sibling
+    that merely shares a server root.  Two live windows claiming one id would be a
+    contradiction, so an ambiguous answer is refused instead of guessed.
+    """
+    if not claimed_ids:
+        return None
+    wanted = set(claimed_ids)
+    try:
+        filenames = os.listdir(signal_dir)
+    except OSError:
+        return None
+
+    matches: list[tuple[str, dict]] = []
+    for filename in filenames:
+        if not filename.startswith("window-") or not filename.endswith(".json"):
+            continue
+        candidate = read(filename[len("window-") : -len(".json")])
+        if candidate is None:
+            continue
+        superseded = candidate[1].get("supersedes")
+        if not isinstance(superseded, list):
+            continue
+        if wanted.intersection(item for item in superseded if isinstance(item, str)):
+            matches.append(candidate)
+
+    return matches[0] if len(matches) == 1 else None
+
+
 def _exact_vscode_window_registration(
     ipc: str | None = None,
 ) -> tuple[str, dict] | None:
@@ -461,6 +498,11 @@ def _exact_vscode_window_registration(
     remote registration is unsafe.  When direct window evidence is unavailable,
     match the live extension-host executable to the exact server root named by
     the terminal's NLS configuration, and only accept a unique match.
+
+    Reloading a window rotates its IPC socket and re-injects ``ARRAYVIEW_WINDOW_ID``
+    into new terminals only, so a terminal that predates the reload keeps naming a
+    window id that no longer registers.  The extension records the ids it replaced,
+    which turns that stale name back into an exact match on the window that owns it.
     """
     signal_dir = os.path.expanduser("~/.arrayview")
 
@@ -479,16 +521,23 @@ def _exact_vscode_window_registration(
             return None
         return window_id, registration
 
+    claimed_ids: list[str] = []
     registration = None
     if ipc:
         window_id = hashlib.sha256(ipc.encode()).hexdigest()[:16]
         if reg := _read(window_id):
             return reg
+        claimed_ids.append(window_id)
         registration = reg
     if registration is None:
         window_id = os.environ.get("ARRAYVIEW_WINDOW_ID")
-        if window_id and (reg := _read(window_id)):
-            return reg
+        if window_id:
+            if reg := _read(window_id):
+                return reg
+            claimed_ids.append(window_id)
+
+    if reg := _superseding_window_registration(claimed_ids, signal_dir, _read):
+        return reg
 
     exact_cli = _current_vscode_remote_cli()
     if exact_cli is None:

{arrayview-0.36.0 → arrayview-0.38.1}/src/arrayview/_routes_loading.py

@@ -24,6 +24,7 @@ from arrayview._session import (
     SESSIONS,
     Session,
     file_signature,
+    upgrade_memmap_in_background,
     wait_for_session_ready,
 )
 
@@ -293,6 +294,7 @@ def register_loading_routes(app, *, notify_shells, setup_rgb) -> None:
                     session.related_release_sids = [
                         str(value) for value in body.get("related_sids", [])
                     ]
+                    upgrade_memmap_in_background(session)
                     commit_pending_session(sid, session)
                 except Exception as exc:
                     # Keep the server alive, and record why this sid will never

{arrayview-0.36.0 → arrayview-0.38.1}/src/arrayview/_session.py

@@ -458,6 +458,49 @@ def _startup_dims_for_data(data, shape=None) -> tuple[int, int] | None:
     return _viewer_start_dims_for_shape(target_shape)
 
 
+def upgrade_memmap_in_background(session) -> bool:
+    """Read a memmap-backed session into RAM behind the viewer.
+
+    ``load_data`` hands back a memmap only when the first frame is cheap to
+    fault in, which buys an immediate picture but leaves later orientations
+    paying scattered reads.  The sequential read still has to happen, so run it
+    off the hot path and swap the array in when it lands.
+
+    Rebinding ``session.data`` is atomic under the GIL and the values are
+    identical, so a render already holding the memmap stays correct and the
+    slice caches stay valid.
+    """
+    data = getattr(session, "data", None)
+    filepath = getattr(session, "filepath", None)
+    if not isinstance(data, np.memmap) or not filepath:
+        return False
+    if not str(filepath).endswith(".npy"):
+        return False
+    try:
+        from ._io import npy_eager_limit
+
+        if os.path.getsize(filepath) >= npy_eager_limit():
+            return False  # does not fit in RAM — the map is the only option
+    except OSError:
+        return False
+
+    expected = data
+    version = getattr(session, "data_version", 0)
+
+    def _upgrade():
+        try:
+            loaded = np.load(filepath)
+        except Exception:
+            return  # keep serving from the map
+        # A /reload or a released session must not be clobbered by a read that
+        # started against the previous array.
+        if session.data is expected and getattr(session, "data_version", 0) == version:
+            session.data = loaded
+
+    threading.Thread(target=_upgrade, daemon=True).start()
+    return True
+
+
 SESSIONS = {}
 
 COLORMAPS = [

{arrayview-0.36.0 → arrayview-0.38.1}/src/arrayview/_vscode_browser.py

@@ -275,6 +275,12 @@ def _open_browser(
                         "ArrayView could not safely install its VS Code opener in "
                         "this exact remote window; no viewer request was sent."
                     )
+                elif _extension_state._VSCODE_EXT_NO_LIVE_WINDOW:
+                    detail = (
+                        "This terminal was opened before its VS Code window reloaded, "
+                        "so it still points at a window that no longer exists. Open a "
+                        "new terminal in the target window and retry."
+                    )
                 elif _extension_state._VSCODE_EXT_RELOAD_REQUIRED:
                     detail = (
                         "ArrayView's VS Code opener was installed; reload this exact "

{arrayview-0.36.0 → arrayview-0.38.1}/src/arrayview/_vscode_extension.py

@@ -54,7 +54,8 @@ _VSCODE_EXT_INSTALLED = False  # cached so we only check once per process
 _VSCODE_EXT_FRESH_INSTALL = False  # True if we just installed it this session
 _VSCODE_EXT_RELOAD_REQUIRED = False  # installed files are newer than the live host
 _VSCODE_EXT_INSTALL_FAILED = False  # automatic install could not complete safely
-_VSCODE_EXT_VERSION = "0.14.87"  # current bundled extension version
+_VSCODE_EXT_NO_LIVE_WINDOW = False  # no live host claims this terminal's window id
+_VSCODE_EXT_VERSION = "0.14.89"  # current bundled extension version
 _VSCODE_CONFIGURED_PORTS: set[int] = set()
 
 def _bundled_vscode_vsix_version(vsix_path: str) -> str | None:
@@ -471,9 +472,11 @@ def _ensure_vscode_extension(*, is_remote: bool | None = None) -> bool:
     """
     global _VSCODE_EXT_INSTALLED, _VSCODE_EXT_FRESH_INSTALL
     global _VSCODE_EXT_RELOAD_REQUIRED, _VSCODE_EXT_INSTALL_FAILED
+    global _VSCODE_EXT_NO_LIVE_WINDOW
     _VSCODE_EXT_FRESH_INSTALL = False
     _VSCODE_EXT_RELOAD_REQUIRED = False
     _VSCODE_EXT_INSTALL_FAILED = False
+    _VSCODE_EXT_NO_LIVE_WINDOW = False
 
     vsix_path = str(_pkg_files("arrayview").joinpath("arrayview-opener.vsix"))
     if not os.path.isfile(vsix_path):
@@ -496,6 +499,31 @@ def _ensure_vscode_extension(*, is_remote: bool | None = None) -> bool:
         and active_registration.get("extensionVersion") == active_version
         else None
     )
+    def _reject_unmatched_host(installed_version: str) -> bool:
+        """Record why the live host was rejected, so callers can advise correctly.
+
+        A version disagreement is fixed by reloading; an unidentifiable window is
+        not.  Conflating them tells the user to reload when the reload is what
+        stranded their terminal in the first place.
+        """
+        global _VSCODE_EXT_RELOAD_REQUIRED, _VSCODE_EXT_NO_LIVE_WINDOW
+        if active_version is None:
+            _VSCODE_EXT_NO_LIVE_WINDOW = True
+            _vprint(
+                f"[ArrayView] opener v{installed_version} is installed, but no live "
+                "VS Code window claims this terminal; open a new terminal in the "
+                "target window",
+                flush=True,
+            )
+            return False
+        _VSCODE_EXT_RELOAD_REQUIRED = True
+        _vprint(
+            f"[ArrayView] opener v{installed_version} is installed, but this VS Code "
+            "window is still running an older extension host; reload this window",
+            flush=True,
+        )
+        return False
+
     if _extension_on_disk(ext_version, vsix_path, remote=is_remote):
         active_matches = (
             active_version == ext_version
@@ -503,13 +531,7 @@ def _ensure_vscode_extension(*, is_remote: bool | None = None) -> bool:
             else active_version in (None, ext_version)
         )
         if not active_matches:
-            _VSCODE_EXT_RELOAD_REQUIRED = True
-            _vprint(
-                f"[ArrayView] opener v{ext_version} is installed, but this VS Code "
-                "window is still running an older extension host; reload this window",
-                flush=True,
-            )
-            return False
+            return _reject_unmatched_host(ext_version)
         if not is_remote:
             _remove_old_extension_versions(ext_version, remote=False)
         _VSCODE_EXT_INSTALLED = True
@@ -527,13 +549,7 @@ def _ensure_vscode_extension(*, is_remote: bool | None = None) -> bool:
             else active_version in (None, newer_version)
         )
         if not active_matches:
-            _VSCODE_EXT_RELOAD_REQUIRED = True
-            _vprint(
-                f"[ArrayView] newer opener v{newer_version} is installed, but this "
-                "VS Code window is still running an older extension host; reload this window",
-                flush=True,
-            )
-            return False
+            return _reject_unmatched_host(newer_version)
         _VSCODE_EXT_INSTALLED = True
         _vprint(
             f"[ArrayView] newer extension v{newer_version} is installed — keeping it",