arrayview 0.36.0__tar.gz → 0.37.1__tar.gz

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

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

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

{arrayview-0.36.0 → arrayview-0.37.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.37.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.37.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.37.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.37.1}/src/arrayview/_vscode_extension.py

@@ -54,7 +54,7 @@ _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_VERSION = "0.14.88"  # current bundled extension version
 _VSCODE_CONFIGURED_PORTS: set[int] = set()
 
 def _bundled_vscode_vsix_version(vsix_path: str) -> str | None:

{arrayview-0.36.0 → arrayview-0.37.1}/tests/test_api.py

@@ -4093,7 +4093,7 @@ class TestCliOpenHelpers:
 
         message = str(excinfo.value)
         assert "older ArrayView process" in message
-        assert "arrayview --kill --port 8000" in message
+        assert "arrayview stop" in message
 
     def test_handle_cli_existing_server_opens_registered_session(self, monkeypatch):
         import arrayview._launcher as launcher
@@ -4190,7 +4190,7 @@ class TestCliOpenHelpers:
         out = capsys.readouterr().out
         assert "existing ArrayView server on port 8000" in out
         assert "directory stacking" in out
-        assert "arrayview --kill --port 8000" in out
+        assert "arrayview stop" in out
 
     def test_handle_cli_existing_server_reports_load_error_without_port_conflict(
         self, monkeypatch, tmp_path, capsys

{arrayview-0.36.0 → arrayview-0.37.1}/tests/test_cli.py

@@ -304,7 +304,7 @@ def test_cli_vscode_terminal_requires_extension_readiness_ack(tmp_path):
         assert not _wait_for_ping(port, timeout=1.0)
     finally:
         subprocess.run(
-            [sys.executable, "-m", "arrayview", "--kill", "--port", str(port)],
+            [sys.executable, "-m", "arrayview", "stop"],
             env=env,
             capture_output=True,
             text=True,

{arrayview-0.36.0 → arrayview-0.37.1}/tests/test_doctor_commands.py

@@ -59,8 +59,9 @@ def test_instances_json_lists_public_identity(monkeypatch, capsys):
     assert "control_token" not in result["instances"][0]
 
 
-def test_stop_resolves_instance_to_recorded_port(monkeypatch, capsys):
-    _Registry.records = [_record("known", 9001)]
+@pytest.mark.parametrize("command", ["stop", "kill"])
+def test_stop_kills_every_recorded_instance(monkeypatch, capsys, command):
+    _Registry.records = [_record("first", 9001), _record("second", 9002)]
     monkeypatch.setattr("arrayview._instance_registry.InstanceRegistry", _Registry)
     calls = []
     monkeypatch.setattr(
@@ -68,20 +69,36 @@ def test_stop_resolves_instance_to_recorded_port(monkeypatch, capsys):
         "_stop_verified_server",
         lambda port: (calls.append(port) or "stopped", 123),
     )
-    output = _run(monkeypatch, capsys, "stop", "known")
-    assert calls == [9001]
-    assert "known: stopped" in output
+    output = _run(monkeypatch, capsys, command)
+    assert calls == [9001, 9002]
+    assert "first: stopped" in output
+    assert "second: stopped" in output
 
 
-def test_stop_unknown_identity_never_invokes_port_stop(monkeypatch, capsys):
-    _Registry.records = [_record("known", 9001)]
+def test_stop_without_instances_is_not_an_error(monkeypatch, capsys):
+    _Registry.records = []
     monkeypatch.setattr("arrayview._instance_registry.InstanceRegistry", _Registry)
-    monkeypatch.setattr(_launcher, "_stop_verified_server", lambda _port: pytest.fail("must not stop"))
-    monkeypatch.setattr(sys, "argv", ["arrayview", "stop", "unknown"])
-    with pytest.raises(SystemExit):
-        _launcher.arrayview()
+    monkeypatch.setattr(
+        _launcher, "_stop_verified_server", lambda _port: pytest.fail("must not stop")
+    )
+    assert "No running ArrayView instances" in _run(monkeypatch, capsys, "stop")
 
 
-def test_legacy_diagnose_and_kill_still_bypass_subcommands(monkeypatch):
-    assert not _launcher._handle_management_command(["--diagnose"])
+def test_legacy_kill_flag_stops_every_instance(monkeypatch, capsys):
+    _Registry.records = [_record("first", 9001)]
+    monkeypatch.setattr("arrayview._instance_registry.InstanceRegistry", _Registry)
+    calls = []
+    monkeypatch.setattr(
+        _launcher,
+        "_stop_verified_server",
+        lambda port: (calls.append(port) or "stopped", 123),
+    )
+    # --kill is a flag on the file CLI, not a subcommand, so it bypasses
+    # _handle_management_command and lands in the launch parser.
     assert not _launcher._handle_management_command(["--kill"])
+    _run(monkeypatch, capsys, "--kill")
+    assert calls == [9001]
+
+
+def test_legacy_diagnose_still_bypasses_subcommands(monkeypatch):
+    assert not _launcher._handle_management_command(["--diagnose"])