arrayview 0.42.0__tar.gz → 0.42.2__tar.gz

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

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

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

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

@@ -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.0 → arrayview-0.42.2}/src/arrayview/_launch_trace.py

@@ -1,8 +1,10 @@
 """Best-effort, opt-in launch event tracing.
 
 The trace is deliberately dependency-free and inert unless
-``ARRAYVIEW_LAUNCH_TRACE`` names an absolute JSONL file.  Launch behavior must
-never depend on a trace write succeeding.
+``ARRAYVIEW_LAUNCH_TRACE`` names an absolute JSONL file.  Integrated-browser
+route tracing can also be enabled explicitly with
+``~/.arrayview/enable-launch-trace``.  Launch behavior must never depend on a
+trace write succeeding.
 """
 
 from __future__ import annotations
@@ -20,6 +22,8 @@ TRACE_PATH_ENV = "ARRAYVIEW_LAUNCH_TRACE"
 TRACE_ID_ENV = "ARRAYVIEW_LAUNCH_ID"
 TRACE_ROLE_ENV = "ARRAYVIEW_LAUNCH_ROLE"
 TRACE_SCHEMA = 1
+TRACE_MARKER_NAME = "enable-launch-trace"
+TRACE_DEFAULT_NAME = "launch-trace.jsonl"
 _MAX_EVENT_BYTES = 4096
 
 _lock = threading.Lock()
@@ -70,6 +74,56 @@ def trace_tag(value: object) -> str:
     return hashlib.sha256(str(value).encode("utf-8", "replace")).hexdigest()[:12]
 
 
+def configure_route_launch_trace() -> bool:
+    """Enable route tracing from an explicit environment or marker opt-in.
+
+    Route handlers call this directly so an already-running server can notice
+    the marker even when its process environment never contained the trace
+    variable.  An explicit environment value always wins, including an invalid
+    relative value, which keeps the normal trace contract unambiguous.
+    """
+    try:
+        explicit = os.environ.get(TRACE_PATH_ENV)
+        if explicit is not None:
+            if not explicit or not Path(explicit).is_absolute():
+                return False
+            if _path != explicit:
+                configure_launch_trace()
+            return _path == explicit
+
+        trace_dir = Path.home() / ".arrayview"
+        if not (trace_dir / TRACE_MARKER_NAME).is_file():
+            return False
+        candidate = str(trace_dir / TRACE_DEFAULT_NAME)
+        if _path != candidate:
+            configure_launch_trace(path=candidate, role="server")
+        return _path == candidate
+    except Exception:
+        return False
+
+
+def emit_route_launch_event(
+    event: str,
+    *,
+    navigation_key: str,
+    tab_key: str | None = None,
+    **attrs: object,
+) -> None:
+    """Emit a route event without exposing private route credentials."""
+    try:
+        if not configure_route_launch_trace():
+            return
+        safe_attrs = {
+            "navigation_key_tag": trace_tag(navigation_key),
+            **attrs,
+        }
+        if tab_key is not None:
+            safe_attrs["tab_key_tag"] = trace_tag(tab_key)
+        emit_launch_event(event, **safe_attrs)
+    except Exception:
+        return
+
+
 def emit_launch_event(event: str, **attrs: object) -> None:
     """Append one compact event, swallowing every tracing-related failure."""
     try:
@@ -113,10 +167,13 @@ def _ensure_environment_configuration() -> None:
 
 __all__ = [
     "TRACE_ID_ENV",
+    "TRACE_MARKER_NAME",
     "TRACE_PATH_ENV",
     "TRACE_ROLE_ENV",
     "configure_launch_trace",
+    "configure_route_launch_trace",
     "emit_launch_event",
+    "emit_route_launch_event",
     "trace_child_environment",
     "trace_tag",
 ]

{arrayview-0.42.0 → arrayview-0.42.2}/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.0 → arrayview-0.42.2}/src/arrayview/_routes_query.py

@@ -140,6 +140,20 @@ def register_query_routes(app, *, get_session_or_404, pil_image, pil_imageops) -
                     previous_navigation_key,
                     None,
                 )
+                try:
+                    from arrayview._launch_trace import emit_route_launch_event
+
+                    emit_route_launch_event(
+                        "page.route_retired",
+                        navigation_key=previous_navigation_key,
+                        tab_key=previous_journal.get("tab_key"),
+                        request_id=request_id,
+                        navigation_attempt=previous_journal.get(
+                            "navigation_attempt"
+                        ),
+                    )
+                except Exception:
+                    pass
             journal = journals[request_id] = {
                 "token": token,
                 "window_id": window_id,
@@ -159,6 +173,18 @@ def register_query_routes(app, *, get_session_or_404, pil_image, pil_imageops) -
                     sid,
                     request_id,
                 )
+                try:
+                    from arrayview._launch_trace import emit_route_launch_event
+
+                    emit_route_launch_event(
+                        "page.route_prepared",
+                        navigation_key=navigation_key,
+                        tab_key=tab_key,
+                        request_id=request_id,
+                        navigation_attempt=navigation_attempt,
+                    )
+                except Exception:
+                    pass
             return {
                 "sid": sid,
                 "request_id": request_id,
@@ -191,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 {

{arrayview-0.42.0 → arrayview-0.42.2}/src/arrayview/_routes_websocket.py

@@ -111,6 +111,42 @@ def _render_progress_reporter(
     return report
 
 
+async def _await_session_reporting_read_progress(ws, sid):
+    """Wait for a background read, telling the viewer how far along it is.
+
+    Nothing else can report this: the reader is a plain thread and the array
+    is not a session until it finishes, so this socket is the only thing
+    holding a line to the viewer while the wait happens.
+
+    Silent for the first stretch, so an ordinary fast open never flashes a
+    bar on its way past — the same rule the render progress reporter uses.
+    """
+    quiet_for_s = 0.6
+    started = time.perf_counter()
+    waiter = asyncio.ensure_future(wait_for_session_ready(sid))
+    last = None
+    while True:
+        done, _pending = await asyncio.wait({waiter}, timeout=0.15)
+        if waiter in done:
+            break
+        if time.perf_counter() - started < quiet_for_s:
+            continue
+        state = _session_mod.LOAD_PROGRESS.get(sid)
+        if state and state != last:
+            last = state
+            read, total = state
+            await _send_json_quietly(ws, {
+                "type": "render_progress",
+                "done": int(read),
+                "total": int(total),
+                "label": "Reading array",
+            })
+    try:
+        return waiter.result()
+    except Exception:
+        return _session_mod.SESSIONS.get(sid)
+
+
 async def _send_json_quietly(ws, payload):
     try:
         await ws.send_json(payload)
@@ -190,8 +226,28 @@ def register_websocket_routes(app) -> None:
         native_request_id = ws.query_params.get("native_request_id")
         launch_request_id = ws.query_params.get("launch_request_id")
         launch_token = ws.query_params.get("launch_token")
-        session = await wait_for_session_ready(sid)
+        # Answer the handshake before the array is ready.  Holding it closed
+        # until the load finished made the viewer decide the backend was dead:
+        # it gives up after three attempts and shows "could not connect", which
+        # a large array reaches purely by being slow to load.  Accepting first
+        # stops that clock.  The viewer keeps its splash up until the metadata
+        # below arrives, so an early accept shows nothing half-rendered.
+        await ws.accept()
+
+        session = _session_mod.SESSIONS.get(sid)
+        if session is None:
+            session = await _await_session_reporting_read_progress(ws, sid)
         if not session:
+            # The socket has already opened, and the viewer treats a drop after
+            # a successful open as a recoverable reconnect — it would retry
+            # forever.  Say the load failed so it shows an error instead.
+            try:
+                await ws.send_json({
+                    "type": "render_error",
+                    "message": "the array could not be loaded",
+                })
+            except Exception:
+                pass
             await ws.close()
             return
 
@@ -208,8 +264,6 @@ def register_websocket_routes(app) -> None:
                 await ws.close(code=1008)
                 return
 
-        await ws.accept()
-
         # A new viewer proves that the prior disconnect was a reload, tunnel
         # interruption, or other recoverable transport break. Invalidate and
         # cancel its cleanup before recording this connection.

{arrayview-0.42.0 → arrayview-0.42.2}/src/arrayview/_server.py

@@ -422,6 +422,16 @@ def get_short_viewer_ui(
     navigation_key: str,
 ):
     """Resolve a private integrated-browser launch without exposing its query."""
+    try:
+        from arrayview._launch_trace import emit_route_launch_event
+
+        emit_route_launch_event(
+            "page.route_entered",
+            navigation_key=navigation_key,
+            tab_key=tab_key,
+        )
+    except Exception:
+        pass
     owner = _session_mod.VIEWER_LAUNCH_ROUTES.get(navigation_key)
     if owner is None:
         raise HTTPException(status_code=404, detail="Viewer launch route expired")
@@ -437,6 +447,18 @@ def get_short_viewer_ui(
         or journal.get("navigation_key") != navigation_key
     ):
         raise HTTPException(status_code=409, detail="Viewer launch route changed")
+    try:
+        from arrayview._launch_trace import emit_route_launch_event
+
+        emit_route_launch_event(
+            "page.route_resolved",
+            navigation_key=navigation_key,
+            tab_key=tab_key,
+            request_id=request_id,
+            navigation_attempt=journal["navigation_attempt"],
+        )
+    except Exception:
+        pass
     bootstrap_query = journal["viewer_query"] + "&" + urlencode(
         {
             "_av_integrated_browser": "1",

{arrayview-0.42.0 → arrayview-0.42.2}/src/arrayview/_session.py

@@ -51,6 +51,10 @@ CANCELLED_PENDING_SESSIONS: set[str] = set()
 # without this the opener cannot tell "still loading" from "will never load" and
 # waits out its whole deadline on a file that failed in the first second.
 FAILED_PENDING_SESSIONS: dict[str, str] = {}
+# sid -> (bytes read, bytes total) for a background read still in progress.
+# The reader is a plain thread with no socket of its own, so it leaves its
+# progress here and the viewer's websocket picks it up while it waits.
+LOAD_PROGRESS: dict[str, tuple[int, int]] = {}
 
 
 def file_signature(filepath: str):

{arrayview-0.42.0 → arrayview-0.42.2}/src/arrayview/_viewer.html

@@ -2,6 +2,24 @@
 <html>
 <head>
     <title>ArrayView</title>
+    <script>
+        // Name the tab at parse time. Without this the tab shows the host
+        // ("localhost:8000") until metadata arrives over the WebSocket, and
+        // that wait is the array load — seconds for a large file. The name
+        // rides in on ?av_name= because the hash already carries #av-<id>.
+        // Formatting must match _setWindowIdentity(), or the title changes a
+        // second time when metadata lands.
+        (function () {
+            try {
+                var name = new URLSearchParams(location.search).get('av_name');
+                if (!name) return;
+                var clean = String(name).trim();
+                document.title = clean && clean !== 'welcome'
+                    ? 'ArrayView: ' + clean
+                    : 'ArrayView';
+            } catch (_) {}
+        })();
+    </script>
     <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Crect width='16' height='16' rx='2.5' fill='%230c0c0c'/%3E%3Crect x='2' y='2' width='3' height='3' fill='%233a0ca3'/%3E%3Crect x='6.5' y='2' width='3' height='3' fill='%23560bad'/%3E%3Crect x='11' y='2' width='3' height='3' fill='%23c77dff'/%3E%3Crect x='2' y='6.5' width='3' height='3' fill='%234361ee'/%3E%3Crect x='6.5' y='6.5' width='3' height='3' fill='%234cc9f0'/%3E%3Crect x='11' y='6.5' width='3' height='3' fill='%23f5c842'/%3E%3Crect x='2' y='11' width='3' height='3' fill='%234895ef'/%3E%3Crect x='6.5' y='11' width='3' height='3' fill='%2380ed99'/%3E%3Crect x='11' y='11' width='3' height='3' fill='%23f8961e'/%3E%3C/svg%3E">
     <style>
         /* ── CSS: Theme Variables and Base Layout ────────────────────── */
@@ -5552,8 +5570,11 @@
         // never need to appear in the browser toolbar.
         const _arrayViewLaunchSearch = __ARRAYVIEW_QUERY__ || window.location.search;
         const urlParams = new URLSearchParams(_arrayViewLaunchSearch);
-        const _integratedBrowserDisplayHash = (
+        const _isIntegratedBrowserViewer = (
             urlParams.get('_av_integrated_browser') === '1'
+        );
+        const _integratedBrowserDisplayHash = (
+            _isIntegratedBrowserViewer
             && window.location.hash.startsWith('#av-')
         ) ? window.location.hash : '';
         // isInlineEmbed: true when explicitly launched as an inline Jupyter/notebook embed
@@ -15485,7 +15506,14 @@
 
             // Shell-lite: when viewer is top-level (not in shell iframe), listen for
             // new-tab signals so CLI tab injection still works.
-            if (window === window.top) {
+            //
+            // Skipped inside a VS Code browser tab. Every such tab holds its
+            // sockets open through one shared VS Code channel that stops
+            // carrying new page requests at ~32 of them, so a second socket per
+            // viewer halves how many arrays can be open before opening breaks.
+            // Nothing is lost: each launch opens its own VS Code tab, so the
+            // window.open path this socket exists to serve never runs there.
+            if (window === window.top && !_isIntegratedBrowserViewer) {
                 try {
                     const _shellProto = location.protocol === 'https:' ? 'wss:' : 'ws:';
                     const _shellWs = new WebSocket(`${_shellProto}//${location.host}${resolveServerPath('/ws/shell')}`);

{arrayview-0.42.0 → arrayview-0.42.2}/src/arrayview/_vscode_extension.py

@@ -57,7 +57,7 @@ _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_NO_LIVE_WINDOW = False  # no live host claims this terminal's window id
-_VSCODE_EXT_VERSION = "0.15.18"  # current bundled extension version
+_VSCODE_EXT_VERSION = "0.15.23"  # current bundled extension version
 _VSCODE_CONFIGURED_PORTS: set[int] = set()
 # Version-skew notices already printed, so a long-lived process (Jupyter, a
 # script opening several arrays) states the mismatch once instead of per call.

{arrayview-0.42.0 → arrayview-0.42.2}/src/arrayview/_vscode_signal.py

@@ -384,6 +384,46 @@ def _find_arrayview_window_id() -> str | None:
     return None
 
 
+def _session_name_for_url(url: str) -> str | None:
+    """Return the session name behind *url*'s ``?sid=``, or None."""
+    try:
+        import urllib.parse as _up
+
+        sid = _up.parse_qs(_up.urlparse(url).query).get("sid", [None])[0]
+        if not sid:
+            return None
+        import arrayview._session as _sm
+
+        session = _sm.SESSIONS.get(sid)
+        return getattr(session, "name", None) if session else None
+    except Exception:
+        return None
+
+
+def _with_viewer_name(url: str, name: str | None) -> str:
+    """Add ``av_name`` so the viewer can title its tab before metadata lands.
+
+    The page otherwise shows the bare host until the WebSocket delivers the
+    session name, and that WebSocket waits on the array load — seconds for a
+    large file.  This stays a query parameter rather than being baked into the
+    served HTML because the gzip cache in ``_server`` is keyed on the page
+    body; a per-session body would evict on every open and re-compress ~2 MB.
+    """
+    if not name:
+        return url
+    try:
+        import urllib.parse as _up
+
+        parts = _up.urlsplit(url)
+        query = _up.parse_qsl(parts.query, keep_blank_values=True)
+        if any(key == "av_name" for key, _ in query):
+            return url
+        query.append(("av_name", str(name)))
+        return _up.urlunsplit(parts._replace(query=_up.urlencode(query)))
+    except Exception:
+        return url
+
+
 def _open_via_signal_file(
     url: str,
     delay: float = 0.0,
@@ -402,19 +442,13 @@ def _open_via_signal_file(
     If omitted it is auto-derived from the session name embedded in the URL's
     ``?sid=`` query parameter.
     """
-    if title is None:
-        try:
-            import urllib.parse as _up
-
-            _sid = _up.parse_qs(_up.urlparse(url).query).get("sid", [None])[0]
-            if _sid:
-                import arrayview._session as _sm
-
-                _sess = _sm.SESSIONS.get(_sid)
-                if _sess:
-                    title = f"ArrayView: {_sess.name}"
-        except Exception:
-            pass
+    session_name = _session_name_for_url(url)
+    if title is None and session_name:
+        title = f"ArrayView: {session_name}"
+    # The viewer titles its own tab from this, so it must be the session name
+    # the metadata will later carry — not *title*, which some callers pass
+    # pre-formatted and others pass as a bare filename.
+    url = _with_viewer_name(url, session_name)
 
     request_id = uuid.uuid4().hex
     if window_id is None:
@@ -454,6 +488,11 @@ def _open_via_signal_file(
         payload["title"] = title
     if handoff_path := os.environ.get("ARRAYVIEW_HANDOFF_PATH"):
         payload["handoffPath"] = handoff_path
+    # Opt-in measurement launch: the opener observes the navigation for a long
+    # budget instead of closing and reopening a blank tab after 1.5 s.  Only
+    # this launch is affected, so ordinary use continues alongside a run.
+    if os.environ.get("ARRAYVIEW_MEASURE_NAVIGATION") == "1":
+        payload["measureNavigation"] = True
     if floating:
         payload["floating"] = True
     if remote_was_supplied:

{arrayview-0.42.0 → arrayview-0.42.2}/tests/test_api.py

@@ -346,7 +346,8 @@ class TestLoad:
         started = threading.Event()
         finish = threading.Event()
 
-        def slow_load(filepath, key=None, select=None, *, load="lazy", stack="auto"):
+        def slow_load(filepath, key=None, select=None, *, load="lazy",
+                      stack="auto", progress=None):
             started.set()
             assert finish.wait(2.0)
             return np.zeros((4, 4), dtype=np.float32), None
@@ -390,7 +391,8 @@ class TestLoad:
         started = threading.Event()
         finish = threading.Event()
 
-        def slow_load(filepath, key=None, select=None, *, load="lazy", stack="auto"):
+        def slow_load(filepath, key=None, select=None, *, load="lazy",
+                      stack="auto", progress=None):
             started.set()
             assert finish.wait(2.0)
             return np.zeros((4, 4), dtype=np.float32), None