scanpath-studio 0.35.0__tar.gz → 0.37.0__tar.gz

{scanpath_studio-0.35.0/scanpath_studio.egg-info → scanpath_studio-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scanpath-studio
-Version: 0.35.0
+Version: 0.37.0
 Summary: Interactive workbench for eye-tracking-while-reading data: draw, replay and compare scanpaths over the text, and export figures and tables.
 Author: Keren Gruteke Klein, Maya Grossman, Ella Lion, Deborah N. Jakobi, David R. Reich, Lena Jäger, Yevgeni Berzak
 Author-email: Omer Shubi <lacclab.technion@gmail.com>
@@ -24,6 +24,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
 Requires-Dist: streamlit>=1.65.0
+Requires-Dist: packaging>=26.3
 Requires-Dist: pandas>=3.0
 Requires-Dist: plotly>=7.1
 Requires-Dist: numpy>=2.4
@@ -35,6 +36,7 @@ Requires-Dist: streamlit-sortables>=0.3.1
 Requires-Dist: pillow>=12.3
 Requires-Dist: imageio[ffmpeg]>=2.37
 Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: truststore>=0.10
 Requires-Dist: xlrd>=2.0.2
 Provides-Extra: test
 Requires-Dist: pytest>=8.0.0; extra == "test"
@@ -74,7 +76,7 @@ for a paper.
 ## Get started
 
 - **As a desktop app**, the easiest way to work with your own data:
-  [Windows](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-windows-x86_64.zip) ·
+  [Windows](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-windows-x86_64-setup.exe) ·
   [macOS (Apple silicon)](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-macos-arm64.dmg) ·
   [Linux](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-linux-x86_64.tar.gz).
 - **With pip** (Python 3.11–3.14):

{scanpath_studio-0.35.0 → scanpath_studio-0.37.0}/README.md

@@ -20,7 +20,7 @@ for a paper.
 ## Get started
 
 - **As a desktop app**, the easiest way to work with your own data:
-  [Windows](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-windows-x86_64.zip) ·
+  [Windows](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-windows-x86_64-setup.exe) ·
   [macOS (Apple silicon)](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-macos-arm64.dmg) ·
   [Linux](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-linux-x86_64.tar.gz).
 - **With pip** (Python 3.11–3.14):

{scanpath_studio-0.35.0 → scanpath_studio-0.37.0}/pyproject.toml

@@ -35,6 +35,8 @@ classifiers = [
 ]
 dependencies = [
     "streamlit>=1.65.0",
+    # Build versions sort and compare as PEP 440 (`build_info.py`, `updates.py`, #139).
+    "packaging>=26.3",
     "pandas>=3.0",
     "plotly>=7.1",
     "numpy>=2.4",
@@ -59,6 +61,10 @@ dependencies = [
     # workbook is a shipped enrichment, so without it an upload raises and the
     # questions column silently never appears (#BUG-41).
     "openpyxl>=3.1.5",
+    # Dataset downloads verify HTTPS against the OS certificate store, so a
+    # python.org Python without its CA bundle, or a TLS-inspecting network,
+    # can still fetch OneStop / PoTeC / MultiplEYE (`datasets._open_url`).
+    "truststore>=0.10",
     # The legacy Excel 97–2003 (.xls) engine, for the same readers (#DATA-53).
     "xlrd>=2.0.2",
 ]
@@ -103,8 +109,9 @@ Issues = "https://github.com/lacclab/scanpath-studio/issues"
 scanpath-studio = "scanpath_studio.cli:main"
 
 [tool.setuptools.dynamic]
-# Single source of truth for the version: scanpath_studio/__version__
-version = { attr = "scanpath_studio.__version__" }
+# Single source of truth for the release number: scanpath_studio.__release__
+# (`__version__` is the exact build, worked out from it at runtime — #139).
+version = { attr = "scanpath_studio.__release__" }
 
 [tool.setuptools]
 include-package-data = true

{scanpath_studio-0.35.0 → scanpath_studio-0.37.0}/scanpath_studio/__init__.py

@@ -9,6 +9,7 @@ __all__ = [
     "build_authored_scanpath",
     "cache_status",
     "check_data_health",
+    "check_for_updates",
     "clear_cache",
     "compare_scanpaths",
     "figure_code",
@@ -32,8 +33,14 @@ __all__ = [
     "render_parent_trial",
     "save_figure",
     "save_figure_layers",
+    "version_info",
 ]
-__version__ = "0.35.0"
+# The release this tree descends from: the number `/release` bumps (with
+# CITATION.cff), `pyproject.toml` builds with, and publish.yml checks a tag
+# against. `__version__` is the exact build, worked out from it lazily
+# (build_info.py, #139) — "0.35.0" at the release itself,
+# "0.35.0.post3+g8f18219" three commits after it.
+__release__ = "0.37.0"
 
 # Public headless API (see api.py / datasets.py / eyegenbench.py). Resolved lazily so
 # `import scanpath_studio` stays cheap and doesn't pull in pandas/plotly/
@@ -65,6 +72,12 @@ _API_EXPORTS = (
 
 
 def __getattr__(name: str):
+    if name == "__version__":
+        from .build_info import build_info
+
+        # Worked out once (it may run `git describe`), then a plain attribute.
+        globals()["__version__"] = build_info().version
+        return globals()["__version__"]
     if name in _API_EXPORTS:
         from . import api
 

{scanpath_studio-0.35.0 → scanpath_studio-0.37.0}/scanpath_studio/api.py

@@ -53,6 +53,7 @@ for _name in (
 from . import column_names as _cn  # noqa: E402
 from . import data as _data  # noqa: E402
 from . import export as _export  # noqa: E402
+from .build_info import BuildInfo  # noqa: E402
 from .column_names import ColumnNames  # noqa: E402
 from .constants import (  # noqa: E402
     DEFAULT_BACKGROUND_COLOR,
@@ -95,6 +96,7 @@ from .plots import (  # noqa: E402
     replay_page,
     split_scanpath_layers,
 )
+from .updates import UpdateCheck  # noqa: E402
 
 
 def build_authored_scanpath(
@@ -3802,3 +3804,41 @@ def clear_cache() -> dict:
 
     clear_local_state()
     return cache_status()
+
+
+def version_info() -> BuildInfo:
+    """Which build of Scanpath Studio this is — no network access.
+
+    ``version`` is what ``scanpath_studio.__version__`` holds: the release itself
+    (``"0.35.0"``), or between releases a PEP 440 version that sorts after it —
+    ``"0.35.0.post3+g8f18219"`` is three commits after v0.35.0, at commit
+    ``8f18219``, and it ends ``.dirty`` with uncommitted changes. ``release`` is
+    the release it descends from (``scanpath_studio.__release__``), ``distance``
+    the commits since (``None`` when unknown), ``commit``, ``dirty``, and
+    ``source`` — how it was worked out: ``"checkout"`` (``git describe``),
+    ``"stamp"`` (a desktop bundle's build stamp), ``"vcs"`` (a
+    ``pip install git+…``) or ``"release"``. ``describe()`` says it in a
+    sentence. The same is in Help → About and ``scanpath-studio version``."""
+    from .build_info import build_info
+
+    return build_info()
+
+
+def check_for_updates(timeout: float = 5.0) -> UpdateCheck:
+    """Ask GitHub whether a newer release than this build is out.
+
+    The one call here that uses the network, and only when made: it reads the
+    latest release from ``api.github.com`` (drafts and pre-releases excluded)
+    and compares it with [`version_info`][scanpath_studio.api.version_info]. It
+    never raises. ``status`` is ``"up_to_date"``, ``"update_available"``,
+    ``"ahead"`` (a development build past the latest release) or ``"error"``
+    (offline, no answer within ``timeout`` seconds, rate-limited, …), and
+    ``message`` says it in a sentence. With an update available, ``command`` is
+    the shell command that updates this install (``pip install -U
+    scanpath-studio``, ``uv tool upgrade scanpath-studio``, ``git pull``, …),
+    ``latest.url`` the release notes, and in the desktop app ``download`` the
+    archive for this computer. The same check is Help → About → *Check for
+    updates* and ``scanpath-studio version --check``."""
+    from .updates import check_for_updates as _check
+
+    return _check(timeout)

{scanpath_studio-0.35.0 → scanpath_studio-0.37.0}/scanpath_studio/app.py

@@ -63,8 +63,15 @@ if __package__ is None or __package__ == "":
     if str(root) not in sys.path:
         sys.path.insert(0, str(root))
 
-from scanpath_studio import dataset_table, loading, progress, wizard_shell
+from scanpath_studio import (
+    dataset_table,
+    desktop_update,
+    loading,
+    progress,
+    wizard_shell,
+)
 from scanpath_studio import metadata as metadata_mod
+from scanpath_studio import updates as update_check
 from scanpath_studio.annotations import (
     filter_keys,
 )
@@ -278,7 +285,7 @@ from scanpath_studio.session_keys import (
     PARAM_CORPUS,
     PARAM_DATASET,
 )
-from scanpath_studio.styles import get_app_css
+from scanpath_studio.styles import get_app_css, widen_menu
 from scanpath_studio.tabs import (
     _EDITOR_KEY_NOISE,
     _REMAP_DIRTY_KEY,
@@ -1337,6 +1344,12 @@ def _arm_about() -> None:
     st.session_state["_about_dialog_requested"] = True
 
 
+#: #139 — the last *Check for updates* answer, shown under the button until the
+#: dialog is opened again. A plain session key, not in the recovery cache's
+#: allowlist, so it is never written to disk.
+_UPDATE_CHECK_KEY = "_about_update_check"
+
+
 def maybe_show_about() -> None:
     """Open the About dialog if the ❓ Help menu button armed it.
 
@@ -1346,6 +1359,7 @@ def maybe_show_about() -> None:
     rerun (including the ~10 s plot embeds).
     """
     if st.session_state.pop("_about_dialog_requested", False):
+        st.session_state.pop(_UPDATE_CHECK_KEY, None)
         _about_dialog()
 
 
@@ -1353,7 +1367,7 @@ def maybe_show_about() -> None:
 @guarded()
 def _about_dialog() -> None:
     """The About modal: version, authors, links, citation, AI-assistance note."""
-    from scanpath_studio import __version__
+    from scanpath_studio import __release__, __version__
 
     # The button that opened this sits inside the ❓ Help popover, whose open
     # state is client-side — without this it floats on top of the modal.
@@ -1370,15 +1384,17 @@ def _about_dialog() -> None:
         "month = jun,\n"
         "title = {{Scanpath Studio}},\n"
         f"url = {{{CITATION['url']}}},\n"
-        f"version = {{{__version__}}},\n"
+        f"version = {{{__release__}}},\n"
         "year = {2026}\n"
         "}"
     )
+    st.markdown(
+        f"**Scanpath Studio** v{__version__} — interactive visualization of eye "
+        "movements in reading."
+    )
+    _render_build_and_updates()
     st.markdown(
         f"""
-**Scanpath Studio** v{__version__} — interactive visualization of eye
-movements in reading.
-
 Developed by [Omer Shubi](https://omershubi.github.io/),
 [Keren Gruteke Klein](https://kerengruteke.github.io/),
 [Maya Grossman](https://www.linkedin.com/in/maya-harram-32b547292/),
@@ -1444,6 +1460,171 @@ and feature requests to [an issue]({CITATION["url"]}/issues) ↗.
         st.rerun()
 
 
+def _update_check_offered() -> bool:
+    """#139: *Check for updates* only where updating means something — a local
+    run or the desktop app, i.e. a server on loopback alone. The hosted demo
+    runs the `stable` branch, and its visitors have nothing to update."""
+    return server_bound_to_loopback()
+
+
+@st.cache_data(ttl=600, show_spinner=False)
+def _latest_release_cached() -> update_check.Release:
+    """GitHub's latest release, kept ten minutes: a second click, or a second
+    session on this machine, doesn't spend another of the 60 anonymous requests
+    an hour. A failure raises, and `st.cache_data` keeps no failed result."""
+    return update_check.latest_release()
+
+
+def _build_info():
+    """This process's build (a seam the About tests pin)."""
+    from scanpath_studio.build_info import build_info
+
+    return build_info()
+
+
+def _render_last_update(last: desktop_update.UpdateResult, current: str) -> None:
+    """#385: the outcome the update helper left behind, across the restart.
+
+    Said only of the build that is running: a record that names neither
+    ``current`` version — a later install by hand — says nothing.
+    """
+    because = f": {last.reason}" if last.reason else ""
+    if last.status == "updated":
+        if last.version == current:
+            st.caption(f"Updated from v{last.previous}.")
+    elif last.previous == current:
+        # This build is the one that stayed.
+        st.warning(
+            f"The update to v{last.version} didn't go through{because}. "
+            f"This is still v{last.previous}.",
+            icon=ICONS["warning"],
+        )
+    elif last.version == current:
+        # A double failure kept the new version's files in place.
+        st.warning(
+            f"The update to v{last.version} didn't finish cleanly{because}. If "
+            f"something misbehaves, download v{last.version} again from the "
+            "release page.",
+            icon=ICONS["warning"],
+        )
+
+
+def _render_build_and_updates() -> None:
+    """#139: which build this is, and — on a local run — *Check for updates*."""
+    info = _build_info()
+    if info.version != info.release:
+        st.caption(info.describe())
+    # #385: how the desktop app's last update ended — None anywhere else.
+    last = desktop_update.last_result()
+    if last is not None:
+        _render_last_update(last, info.version)
+    if not _update_check_offered():
+        return
+    if st.button(
+        "Check for updates",
+        icon=ICONS["update"],
+        key="about_check_updates",
+        help="Asks GitHub for the latest release — the only time the app goes "
+        "online for this.",
+    ):
+        # One opaque request of at most 5 s inside a dialog: a spinner, not a
+        # UX-165 loading card.
+        with st.spinner("Asking GitHub…"):
+            st.session_state[_UPDATE_CHECK_KEY] = update_check.check_for_updates(
+                latest=_latest_release_cached
+            )
+    result = st.session_state.get(_UPDATE_CHECK_KEY)
+    if result is not None:
+        _render_update_result(result)
+
+
+def _render_update_result(result: update_check.UpdateCheck) -> None:
+    """One *Check for updates* answer: the sentence, then what to do about it."""
+    if result.status == "up_to_date":
+        st.success(result.message, icon=ICONS["success"])
+        return
+    if result.status == "ahead":
+        st.info(result.message, icon=ICONS["info"])
+        return
+    if result.status == "error":
+        st.warning(result.message, icon=ICONS["warning"])
+        return
+    st.info(result.message, icon=ICONS["update"])
+    if result.install_kind == "desktop":
+        _render_desktop_update(result)
+    elif result.command:
+        st.code(result.command, language="bash")
+        st.caption("Then restart the app.")
+    if result.latest is not None:
+        st.markdown(f"[What's new in v{result.latest.version}]({result.latest.url}) ↗")
+
+
+def _render_desktop_update(result: update_check.UpdateCheck) -> None:
+    """#385: **Update & restart** when this app can update itself, and the
+    download either way — beside the button, or instead of it with the reason."""
+    install = desktop_update.current_install()
+    reason = desktop_update.refusal(result, install)
+    clicked = False
+    if reason is None:
+        clicked = st.button(
+            "Update & restart",
+            type="primary",
+            icon=ICONS["update"],
+            key="about_update_restart",
+            help="Downloads the new version, checks and tests it, then restarts "
+            "into it. Your datasets and settings come back with it.",
+        )
+    else:
+        st.caption(reason)
+    if result.download is not None:
+        label = (
+            "Download instead"
+            if reason is None
+            else f"Download {result.download.name} ({human_size(result.download.size)})"
+        )
+        st.link_button(label, result.download.url, icon=ICONS["download"])
+    if clicked:
+        _run_desktop_update(result, install)
+
+
+def _stop_desktop_update(task_key: tuple) -> None:
+    """#385: Cancel on the update card — the download stops at its next chunk."""
+    progress.cancel(task_key)
+
+
+def _run_desktop_update(
+    result: update_check.UpdateCheck, install: desktop_update.Install
+) -> None:
+    """Download, check and test under a card, then hand over to the helper and quit."""
+    task_key = ("desktop_update", loading.session_id())
+    try:
+        with loading.card(
+            st.empty(),
+            key="desktop_update",
+            title=f"Updating to v{result.latest.version}",
+            steps=desktop_update.STEPS,
+            step_list=True,
+            task_key=task_key,
+            cancel=loading.Cancel(
+                "Cancel update", _stop_desktop_update, args=(task_key,)
+            ),
+        ):
+            plan = desktop_update.prepare(result, install)
+        desktop_update.start_swap(plan)
+    except desktop_update.UpdateFailed as error:
+        message = str(error)
+        if "nothing was changed" not in message.lower():
+            message += " Nothing was changed."
+        st.error(message, icon=ICONS["error"])
+        return
+    st.success(
+        f"Restarting into v{plan.version}. A new window opens when it's ready "
+        "(on Windows that can take a minute or two); you can close this one.",
+        icon=ICONS["update"],
+    )
+    desktop_update.exit_soon()
+
+
 # --- Public-dataset access UI (directory + expected files + download) --------
 # Shared by the per-corpus loaders below. Each corpus shows the on-disk layout
 # it expects (so a user who already downloaded the data knows what to drop
@@ -5240,6 +5421,8 @@ def render_data_source_picker(host=None) -> None:
         key="data_source_picker",
         on_change=_on_data_source_pick,
     )
+    # The menu opens as wide as the longest dataset name.
+    widen_menu("data_source_picker", [_entry_label(entry) for entry in entries])
     # The help icon sits in the label row, right-aligned over +, not beside the
     # label: the bottom-aligned row keeps + level with the picker, so the icon
     # lands on the label's line.
@@ -6214,11 +6397,14 @@ def apply_editor_restore() -> None:
         return
     if snapshot.get("owner") != st.session_state.get(metadata_mod.OWNER_KEY):
         return
-    for grain in _metadata_grains_changed(snapshot):
+    changed = _metadata_grains_changed(snapshot)
+    if changed:
+        # The uploader still holds the cancelled edit's file in the browser.
+        metadata_mod.reset_uploads(st.session_state)
+    for grain in changed:
         before = snapshot["grains"][grain]
         key, raw, file = metadata_mod.grain_keys(grain)
         for name in (
-            f"{grain}_metadata_upload",
             f"{grain}_metadata_id_column",
             f"{grain}_metadata_keep_fields",
         ):