Skip to content

Process dashboard

Live process monitor that refreshes in the background, with filter, sort, pause and copy.

Same example in PowerShell: Process dashboard

Process dashboard

Real capture on KDE Plasma 6.6 Wayland with the released packages.

What it teaches: background thread; thread-safe updates; pause/resume; clipboard.

Run it

uv init --app myapp && cd myapp    # once: a uv project for your app
uv add nativehtmlkit
# save the example file(s) in the project folder, then:
uv run process_dashboard/dashboard.py

Related guide: background work

Source: process_dashboard/dashboard.py

View on GitHub

"""Process dashboard: a live process monitor (final code of the process dashboard tutorial).

What it teaches
  * collecting data in a background thread and updating the page from it (SDK calls are
    thread-safe), so slow work never blocks the window's event callbacks
  * a refresh loop that waits on a ``threading.Event`` (wakes early to resume or to quit)
  * pausing with a checkbox (the ``change`` event carries ``checked``)
  * filtering and sorting a cached snapshot under a lock
  * copying the table to the clipboard with ``set_clipboard_text`` (and a fallback without one)
  * stopping the thread from ``app.on_shutdown``

Run:    uv run process_dashboard/dashboard.py [--refresh-seconds 3]
Guide:  docs/tutorials/process-dashboard.md (step 3 of 3)
"""
from __future__ import annotations

import argparse
import html
import threading
import time

from nativehtmlkit import Application, Document, NativeHTMLKitError, RpcError
from processes import list_processes

PAGE = """<!doctype html>
<html><head><meta charset="utf-8"><style>
  body { font: 14px sans-serif; margin: 0; background: #11161f; color: #e6ebf3; }
  main { padding: 18px 22px; }
  header { display: flex; align-items: baseline; gap: 12px; }
  h1 { font-size: 20px; margin: 0 0 12px; }
  #status { color: #9fb0c8; }
  form { display: flex; gap: 8px; align-items: center; margin-bottom: 10px; }
  input, select { background: #1b2331; color: #e6ebf3; border: 1px solid #3a475c; border-radius: 5px; padding: 6px; }
  #filter { flex: 1; }
  button { background: #3574c6; color: white; border: 0; border-radius: 5px; padding: 6px 12px; }
  table { border-collapse: collapse; width: 100%; }
  th, td { text-align: left; padding: 6px 8px; border-bottom: 1px solid #2a3445; }
  th { color: #9fb0c8; font-weight: 600; }
  td.num, th.num { text-align: right; }
  #summary { color: #9fb0c8; }
</style></head>
<body><main>
  <header><h1>Processes</h1><span id="status" role="status">Collecting...</span></header>
  <form id="view-form">
    <input id="filter" type="search" placeholder="Filter by name" aria-label="Filter by name">
    <select id="sort" aria-label="Sort by">
      <option value="memory">Memory</option><option value="cpu">CPU time</option><option value="name">Name</option>
    </select>
    <label><input type="checkbox" id="paused"> Pause</label>
    <button id="copy" type="button">Copy table</button>
  </form>
  <p id="summary"></p>
  <table>
    <thead><tr><th>Name</th><th class="num">Id</th><th class="num">Memory (MB)</th><th class="num">CPU (s)</th></tr></thead>
    <tbody id="rows"></tbody>
  </table>
</main></body></html>"""

SORT_KEYS = {
    "memory": (lambda p: p.memory_mb, True),
    "cpu": (lambda p: p.cpu_seconds, True),
    "name": (lambda p: p.name.lower(), False),
}
SHOWN = 25


class Dashboard:
    def __init__(self, app: Application, document: Document, refresh_seconds: float):
        self.app, self.document, self.refresh_seconds = app, document, refresh_seconds
        self.lock = threading.Lock()          # rows/shown are read by callbacks and the worker
        self.rows: list = []
        self.shown: list = []
        self.refreshes = 0
        self.paused = False
        self.wake = threading.Event()         # set to refresh now (resume) or to stop
        self.stopped = threading.Event()
        doc = document
        doc.on("input", lambda _event: self.update_view(), element="filter")
        doc.on("change", lambda _event: self.update_view(), element="sort")
        doc.on("submit", lambda _event: self.update_view(), element="view-form")
        doc.on("change", self.on_pause, element="paused")
        doc.on("click", lambda _event: self.copy(), element="copy")
        app.on_shutdown(self.stop)

    # ----- the background refresh loop -----
    def start(self) -> threading.Thread:
        thread = threading.Thread(target=self._loop, name="process-refresh", daemon=True)
        thread.start()
        return thread

    def _loop(self) -> None:
        while not self.stopped.is_set():
            if not self.paused:
                try:
                    self.refresh()
                except NativeHTMLKitError:    # the window closed or the app is shutting down
                    return
            self.wake.wait(self.refresh_seconds)
            self.wake.clear()

    def refresh(self) -> None:
        rows = list_processes()               # the slow part: runs on this worker thread
        with self.lock:
            self.rows = rows
            self.refreshes += 1
            count = self.refreshes
        self.update_view()
        if not self.paused:                   # paused while collecting: keep showing "Paused"
            self.document.set_text("status", f"Updated {time.strftime('%H:%M:%S')} (refresh #{count})")

    def stop(self) -> None:
        self.stopped.set()
        self.wake.set()

    # ----- the view -----
    def update_view(self) -> None:
        needle = self.document.get_value("filter").strip().lower()
        key, descending = SORT_KEYS.get(self.document.get_value("sort"), SORT_KEYS["memory"])
        with self.lock:
            matching = [p for p in self.rows if needle in p.name.lower()]
            self.shown = sorted(matching, key=key, reverse=descending)[:SHOWN]
            shown, total = list(self.shown), len(self.rows)
            memory = sum(p.memory_mb for p in self.rows)
        cells = "".join(f'<tr><td>{html.escape(p.name)}</td><td class="num">{p.pid}</td>'
                        f'<td class="num">{p.memory_mb:,.1f}</td><td class="num">{p.cpu_seconds:,.1f}</td></tr>'
                        for p in shown)
        self.document.batch([
            {"op": "replace_children_html", "element": "rows", "html": cells},
            {"op": "set_text", "element": "summary",
             "text": f"Showing {len(shown)} of {total} processes, {memory:,.0f} MB in total"},
        ])

    def on_pause(self, event: dict) -> None:
        self.paused = bool(event.get("checked"))
        if self.paused:
            self.document.set_text("status", "Paused")
        else:
            self.wake.set()                   # refresh at once instead of after the interval

    def copy(self) -> None:
        with self.lock:
            lines = ["Name\tId\tMemoryMB\tCpu"] + [f"{p.name}\t{p.pid}\t{p.memory_mb}\t{p.cpu_seconds}"
                                                  for p in self.shown]
        try:
            self.app.set_clipboard_text("\n".join(lines))
            self.document.set_text("status", f"Copied {len(lines) - 1} rows")
        except RpcError:                      # -32001: no clipboard (for example headless runs)
            self.document.set_text("status", "The clipboard is not available in this session")


def build(app: Application, refresh_seconds: float = 3) -> Dashboard:
    window = app.open_html(PAGE, title="Process Dashboard", width=760, height=640)
    return Dashboard(app, window.document, refresh_seconds)


def main() -> None:
    # Parse inside main(): the host re-runs this script with the same arguments.
    parser = argparse.ArgumentParser(description="Live process dashboard")
    parser.add_argument("--refresh-seconds", type=float, default=3, help="refresh interval (1-3600)")
    args = parser.parse_args()
    if not 1 <= args.refresh_seconds <= 3600:
        parser.error("--refresh-seconds must be between 1 and 3600")
    with Application.start(name="Process Dashboard") as app:
        build(app, args.refresh_seconds).start()
        app.run()


if __name__ == "__main__":
    main()