nodeview-slurm 0.1.0__py3-none-any.whl

nodeview/app.py

@@ -0,0 +1,423 @@
+"""The interactive TUI.
+
+Three screens: "me" (the main one), "cluster" and "queue". The content comes
+from render.py; here there's only the scaffolding: navigation, periodic refresh
+and data fetching in a separate thread, so the interface never freezes while
+it talks to Slurm.
+"""
+from __future__ import annotations
+
+import time
+from datetime import datetime
+
+from functools import partial
+
+from textual import work
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.command import DiscoveryHit, Hit, Hits, Provider
+from textual.containers import Container, VerticalScroll
+from textual.reactive import reactive
+from textual.screen import Screen
+from textual.widgets import Footer, Header, Input, Static
+
+from . import analysis as an
+from . import config
+from . import i18n
+from .i18n import t
+from . import palette
+from . import render
+from .profile import Profile, read_profile
+from .source import Snapshot, fetch
+
+
+def _retranslate(cls, bindings) -> None:
+    """Replace a class's key bindings with those in the active language.
+
+    Textual computes the key map only once, when the class is created
+    (`_merged_bindings` in `__init_subclass__`): reassigning BINDINGS isn't
+    enough, new instances would still read the old one.
+    """
+    cls.BINDINGS = bindings
+    cls._merged_bindings = cls._merge_bindings()
+
+
+def app_bindings():
+    return [
+        Binding("q", "quit", t('bind.quit')),
+        Binding("r", "reload", t('bind.reload')),
+        Binding("i", "switch_mode('main')", t('bind.me')),
+        Binding("n", "switch_mode('cluster')", t('bind.cluster')),
+        Binding("c", "switch_mode('queue')", t('bind.queue')),
+        Binding("m", "switch_mode('manual')", t('bind.manual')),
+        Binding("t", "cycle_theme", t('bind.theme')),
+    ]
+
+
+def cluster_bindings():
+    return [Binding("f", "toggle_free", t('bind.only_free'))]
+
+
+def queue_bindings():
+    # "only mine" is on s rather than m: screen bindings take precedence
+    # over global ones, and m here would shadow the manual
+    return [
+        Binding("s", "toggle_mine", t('bind.only_mine')),
+        Binding("slash", "search", t('bind.search')),
+        Binding("escape", "leave_search", t('bind.leave_search'), show=False),
+    ]
+
+
+class LanguageCommands(Provider):
+    """"Language" entry in the command palette (ctrl+p)."""
+
+    def _choices(self):
+        for code, label in i18n.LANGUAGES.items():
+            yield (code, label,
+                   t('app.cmd_language', lang=label),
+                   t('app.cmd_language_help', lang=label))
+
+    async def discover(self) -> Hits:
+        for code, _label, text, help_text in self._choices():
+            yield DiscoveryHit(text, partial(self.app.set_language, code), help=help_text)
+
+    async def search(self, query: str) -> Hits:
+        matcher = self.matcher(query)
+        for code, _label, text, help_text in self._choices():
+            score = matcher.match(text)
+            if score > 0:
+                yield Hit(score, matcher.highlight(text),
+                          partial(self.app.set_language, code), help=help_text)
+
+
+class Card(Container):
+    """Panel with its title drawn on the border."""
+
+    def __init__(self, title: str, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._title = title
+
+    def on_mount(self) -> None:
+        self.border_title = self._title
+
+
+class DataScreen(Screen):
+    """Base: refreshes when the app has new data or when it comes back to front."""
+
+    # Focus goes to the scrollable area, not the first focusable widget:
+    # on the queue that would be the search field, which would swallow the
+    # single-key shortcuts (m, i, n, c). This way the arrows scroll the list
+    # and you enter the field on purpose, with /.
+    AUTO_FOCUS = "VerticalScroll"
+
+    def apply(self, snap: Snapshot) -> None:  # pragma: no cover - overridden
+        raise NotImplementedError
+
+    def _pull(self) -> None:
+        snap = getattr(self.app, "snapshot", None)
+        if snap is not None:
+            self.apply(snap)
+
+    def on_mount(self) -> None:
+        self._pull()
+
+    def on_screen_resume(self) -> None:
+        self._pull()
+
+
+class MainScreen(DataScreen):
+    """'Me first': my jobs, where I fit right now, then the cluster."""
+
+    def compose(self) -> ComposeResult:
+        yield Header(show_clock=True)
+        with VerticalScroll(id="body"):
+            with Card(t('card.my_jobs'), classes="card"):
+                yield Static(id="mine")
+            with Card(t('card.fit'), classes="card"):
+                yield Static(id="fit")
+            with Card(t('card.cluster'), classes="card"):
+                yield Static(id="cluster")
+            # at the bottom on purpose: this is info you rarely look at
+            with Card(t('card.account'), classes="card"):
+                yield Static(id="account")
+        yield Footer()
+
+    def apply(self, snap: Snapshot) -> None:
+        self.query_one("#mine", Static).update(render.my_jobs(snap))
+        self.query_one("#fit", Static).update(render.where_do_i_fit(snap))
+        self.query_one("#cluster", Static).update(render.cluster(snap))
+        self.apply_profile(getattr(self.app, "profile", None))
+
+    def apply_profile(self, prof) -> None:
+        try:
+            widget = self.query_one("#account", Static)
+        except Exception:
+            return
+        widget.update(render.my_account(prof))
+
+
+class ClusterScreen(DataScreen):
+    """Everything the cluster exposes, on a single page."""
+
+    BINDINGS = cluster_bindings()
+
+    only_free = reactive(False)
+
+    def compose(self) -> ComposeResult:
+        yield Header(show_clock=True)
+        with VerticalScroll(id="body"):
+            with Card(t('card.totals'), classes="card"):
+                yield Static(id="totals")
+            with Card(t('card.nodes'), classes="card", id="nodes-card"):
+                yield Static(id="nodes")
+            with Card(t('card.usage'), classes="card"):
+                yield Static(id="breakdown")
+                yield Static(id="legend")
+            with Card(t('card.specs'), classes="card"):
+                yield Static(id="specs")
+        yield Footer()
+
+    def apply(self, snap: Snapshot) -> None:
+        occupants = palette.Occupants(an.occupant_counts(snap), me=snap.me)
+        self.query_one("#totals", Static).update(render.totals_strip(snap))
+        self.query_one("#nodes", Static).update(
+            render.node_table(snap, occupants, only_free=self.only_free))
+        self.query_one("#breakdown", Static).update(render.breakdown(snap, occupants))
+        self.query_one("#legend", Static).update(render.legend(occupants))
+        self.query_one("#specs", Static).update(render.specs_table(snap))
+        self.query_one("#nodes-card", Card).border_title = (
+            t('card.nodes_free') if self.only_free else t('card.nodes'))
+
+    def action_toggle_free(self) -> None:
+        self.only_free = not self.only_free
+        self._pull()
+
+
+class QueueScreen(DataScreen):
+    BINDINGS = queue_bindings()
+
+    mine_only = reactive(False)
+
+    def compose(self) -> ComposeResult:
+        yield Header(show_clock=True)
+        yield Input(placeholder=t('app.search_placeholder'), id="search")
+        with Card(t('card.queue'), classes="card grow"):
+            with VerticalScroll():
+                yield Static(id="queue")
+        yield Footer()
+
+    def apply(self, snap: Snapshot) -> None:
+        needle = self.query_one("#search", Input).value
+        self.query_one("#queue", Static).update(
+            render.queue_table(snap, mine_only=self.mine_only, needle=needle))
+        card = self.query_one(Card)
+        card.border_title = t('card.queue_mine') if self.mine_only else t('card.queue')
+
+    def action_search(self) -> None:
+        self.query_one("#search", Input).focus()
+
+    def action_leave_search(self) -> None:
+        self.query_one(VerticalScroll).focus()
+
+    def action_toggle_mine(self) -> None:
+        self.mine_only = not self.mine_only
+        self._pull()
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        self.query_one(VerticalScroll).focus()
+
+    def on_input_changed(self, event: Input.Changed) -> None:
+        self._pull()
+
+
+class ManualScreen(DataScreen):
+    """Cheat sheet of cluster commands. It doesn't depend on the data, but it
+    redraws on theme change to follow the palette."""
+
+    def compose(self) -> ComposeResult:
+        yield Header(show_clock=True)
+        with VerticalScroll(id="body"):
+            with Card(t('card.manual'), classes="card"):
+                yield Static(id="manual")
+        yield Footer()
+
+    def apply(self, snap: Snapshot | None = None) -> None:
+        self.query_one("#manual", Static).update(render.manual())
+
+    def on_mount(self) -> None:
+        self.apply()
+
+
+class NodeView(App):
+    """Cluster GPU status, from the point of view of the people using it."""
+
+    CSS_PATH = "app.tcss"
+    TITLE = "nodeview"
+
+    MODES = {"main": MainScreen, "cluster": ClusterScreen,
+             "queue": QueueScreen, "manual": ManualScreen}
+
+    BINDINGS = app_bindings()
+    COMMANDS = App.COMMANDS | {LanguageCommands}
+
+    snapshot: reactive = reactive(None, always_update=True)
+
+    def __init__(self, interval: float = 10.0) -> None:
+        super().__init__()
+        self.interval = interval
+        self._error: str | None = None
+        self._restored = False
+        self.profile: Profile | None = None
+
+    def on_mount(self) -> None:
+        self._restore_prefs()
+        self._sync_palette()
+        self.switch_mode("main")
+        self.action_reload()
+        self.set_interval(self.interval, self.action_reload)
+        # budget, quotas and expiration cost ~1.7s and don't change minute to
+        # minute: they're read only once at startup, outside the loop
+        self._load_profile()
+
+    # --- data -------------------------------------------------------------
+
+    def action_reload(self) -> None:
+        self.sub_title = t('app.loading')
+        self._load()
+
+    @work(exclusive=True, thread=True)
+    def _load(self) -> None:
+        """Runs in a thread: fetch() calls sinfo/squeue and blocks for ~0.2s."""
+        try:
+            snap = fetch()
+        except Exception as exc:  # the UI must stay alive and say what's wrong
+            self.call_from_thread(self._on_error, exc)
+        else:
+            self.call_from_thread(self._on_data, snap)
+
+    @work(thread=True, group="profile")
+    def _load_profile(self) -> None:
+        try:
+            prof = read_profile()
+        except Exception:
+            return
+        self.call_from_thread(self._on_profile, prof)
+
+    def _on_profile(self, prof: Profile) -> None:
+        self.profile = prof
+        screen = self.screen
+        if isinstance(screen, MainScreen):
+            screen.apply_profile(prof)
+
+    def _on_data(self, snap: Snapshot) -> None:
+        self._error = None
+        self.snapshot = snap
+        when = datetime.fromtimestamp(snap.taken_at).strftime('%H:%M:%S')
+        self.sub_title = t('app.subtitle', me=snap.me, nodes=len(snap.nodes),
+                           when=when, secs=f"{snap.duration:.2f}")
+        screen = self.screen
+        if isinstance(screen, DataScreen):
+            screen.apply(snap)
+
+    def _on_error(self, exc: Exception) -> None:
+        self._error = str(exc)
+        self.sub_title = t('app.read_error')
+        self.notify(str(exc), title=t('app.slurm_down'), severity="error", timeout=8)
+
+    # --- misc -------------------------------------------------------------
+
+    def _sync_palette(self) -> None:
+        """Colors follow the theme, measuring its actual background.
+
+        Knowing whether a theme is dark isn't enough: nord's panel is #434C5E
+        and textual-dark's is #242F38, and on the former the dark ramp and the
+        status colors vanished."""
+        theme = self.current_theme
+        if theme is None:
+            palette.use(palette.default())
+        else:
+            palette.use(palette.from_theme(theme))
+
+    def _apply_language(self, lang: str) -> None:
+        """Apply the language to texts and key bindings.
+
+        Binding descriptions are class attributes evaluated at import time:
+        they must be rebuilt, together with the app's key map, otherwise the
+        footer stays in the old language.
+        """
+        i18n.use(lang)
+        _retranslate(NodeView, app_bindings())
+        _retranslate(ClusterScreen, cluster_bindings())
+        _retranslate(QueueScreen, queue_bindings())
+        # Only our own bindings, updated in place. Replacing the whole map
+        # would throw away the ones Textual injects at runtime, starting with
+        # the palette's ctrl+p.
+        for binding in app_bindings():
+            self._bindings.key_to_bindings[binding.key] = [binding]
+
+    def _restore_prefs(self) -> None:
+        """Restore the language and theme chosen last time, if they still exist.
+
+        A saved theme may disappear between Textual versions, and a language
+        may have been removed: in that case the value is ignored and the
+        default is kept. The language is applied before the screens are
+        created, so they come out already translated."""
+        saved = config.load()
+        lang = saved.get('lang')
+        self._apply_language(lang if isinstance(lang, str) and lang in i18n.LANGUAGES
+                             else i18n.DEFAULT)
+        theme = saved.get('theme')
+        if isinstance(theme, str) and theme in self.available_themes:
+            self.theme = theme
+        self._restored = True
+
+    def set_language(self, lang: str) -> None:
+        """Switch language, remember it and rebuild the interface."""
+        if lang not in i18n.LANGUAGES or lang == i18n.active():
+            return
+        self._apply_language(lang)
+        config.save(lang=lang)
+        self.run_worker(self._rebuild_screens(), exclusive=True, group="relang")
+
+    async def _rebuild_screens(self) -> None:
+        """Recreate the screens in the new language.
+
+        Panel titles, placeholders and bindings are fixed when the screen is
+        composed: redrawing isn't enough to translate them, it has to be
+        recreated. Textual doesn't allow removing the active mode, so we first
+        switch to one that has already been rebuilt.
+        """
+        target = self.current_mode
+        others = [m for m in self.MODES if m != target]
+        for mode in others:
+            await self.remove_mode(mode)
+            self.add_mode(mode, self.MODES[mode])
+        if others:
+            await self.switch_mode(others[0])
+            await self.remove_mode(target)
+            self.add_mode(target, self.MODES[target])
+            await self.switch_mode(target)
+        self.refresh_bindings()
+        if self.snapshot is not None and isinstance(self.screen, DataScreen):
+            self.screen.apply(self.snapshot)
+        self.notify(t('app.lang_set', lang=i18n.language_name(i18n.active())), timeout=2)
+
+    def watch_theme(self, theme: str) -> None:
+        self._sync_palette()
+        if self.snapshot is not None and isinstance(self.screen, DataScreen):
+            self.screen.apply(self.snapshot)
+        # don't save during startup, or the factory theme would overwrite the
+        # preference before it has even been read
+        if getattr(self, '_restored', False):
+            config.save(theme=theme)
+
+    def action_cycle_theme(self) -> None:
+        available = list(self.available_themes)
+        if not available:
+            return
+        try:
+            idx = available.index(self.theme)
+        except ValueError:
+            idx = -1
+        self.theme = available[(idx + 1) % len(available)]
+        self.notify(t('app.theme_set', theme=self.theme), timeout=2)

nodeview/app.tcss

@@ -0,0 +1,35 @@
+/* Little decoration, lots of hierarchy: the cards separate the three questions
+   the screen answers, and Textual's theme does the rest. */
+
+Screen {
+    background: $surface;
+}
+
+#body {
+    padding: 1 2;
+}
+
+.card {
+    height: auto;
+    margin: 0 0 1 0;
+    padding: 0 1;
+    border: round $primary;
+    background: $panel;
+    border-title-color: $accent;
+    border-title-style: bold;
+}
+
+/* the nodes and queue cards take all the remaining space */
+.card.grow {
+    height: 1fr;
+    margin: 1 2;
+}
+
+.card > Static {
+    height: auto;
+}
+
+#search {
+    margin: 1 2 0 2;
+    border: tall $primary;
+}

nodeview/config.py

@@ -0,0 +1,61 @@
+"""Preferences that survive closing the app.
+
+A single, tiny file in $XDG_CONFIG_HOME/nodeview/config.json (or
+~/.config/nodeview/config.json). It is never essential: if it cannot be read or
+written, the application carries on with the defaults, without complaining. A
+read-only home or a full disk must not stop anyone from looking at the cluster
+state.
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+
+def config_dir() -> Path:
+    base = os.environ.get('XDG_CONFIG_HOME') or (Path.home() / '.config')
+    return Path(base) / 'nodeview'
+
+
+def config_file() -> Path:
+    return config_dir() / 'config.json'
+
+
+def load() -> dict:
+    try:
+        with open(config_file(), encoding='utf-8') as fh:
+            data = json.load(fh)
+        return data if isinstance(data, dict) else {}
+    except (OSError, ValueError):
+        # file missing, unreadable or malformed: fall back to the factory defaults
+        return {}
+
+
+def save(**changes) -> bool:
+    """Update the given keys, leaving the others untouched.
+
+    Atomic write: write alongside and rename, so an interruption never leaves a
+    half-written file that would have to be thrown away on the next start.
+    """
+    data = load()
+    data.update(changes)
+    try:
+        directory = config_dir()
+        directory.mkdir(parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=directory, prefix='.config-', suffix='.json')
+        try:
+            with os.fdopen(fd, 'w', encoding='utf-8') as fh:
+                json.dump(data, fh, indent=2, sort_keys=True)
+                fh.write('\n')
+            os.replace(tmp, config_file())
+        except BaseException:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
+        return True
+    except OSError:
+        return False