Skip to content

Process viewer

Sortable, filterable table of running processes.

Same example in PowerShell: Process viewer

Process viewer

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

What it teaches: rendering data as a table; input event value; sortable headers with aria-sort.

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_viewer.py

Related guide: updating the page

Source: process_viewer.py

View on GitHub

"""Process viewer: a sortable, filterable table of running processes.

What it teaches
  * rendering plain Python data as an HTML table with escaped cells (``html.escape``)
  * the ``input`` event's ``value`` member (no extra round trip while typing)
  * sorting by clicking column headers, with ``aria-sort`` kept up to date
  * a status line with counts

The process list uses only the standard library: ``/proc`` on Linux and the Win32 API (through
``ctypes``) on Windows. In your own code, ``psutil`` is a good alternative.

Run:  uv run process_viewer.py
"""
from __future__ import annotations

import html
import os
import sys
import time
from dataclasses import dataclass

from nativehtmlkit import Application, Document


@dataclass(frozen=True)
class Process:
    name: str
    pid: int
    memory_mb: float
    cpu_seconds: float


def list_processes() -> list[Process]:
    """A snapshot of running processes: name, id, resident memory (MB) and CPU time (s)."""
    return _windows_processes() if sys.platform == "win32" else _linux_processes()


def _linux_processes() -> list[Process]:
    tick, page = os.sysconf("SC_CLK_TCK"), os.sysconf("SC_PAGE_SIZE")
    result = []
    for entry in os.listdir("/proc"):
        if not entry.isdigit():
            continue
        try:
            with open(f"/proc/{entry}/stat", encoding="utf-8", errors="replace") as handle:
                stat = handle.read()
        except OSError:          # the process ended, or access is denied
            continue
        # The name is in parentheses and may itself contain spaces or ')'.
        name = _full_name(entry, stat[stat.index("(") + 1:stat.rindex(")")])
        fields = stat[stat.rindex(")") + 2:].split()
        cpu = (int(fields[11]) + int(fields[12])) / tick       # utime + stime
        memory = int(fields[21]) * page / 2**20                 # rss pages
        result.append(Process(name, int(entry), round(memory, 1), round(cpu, 1)))
    return result


def _full_name(pid: str, comm: str) -> str:
    """The kernel truncates comm to 15 characters; take the full name from argv[0] or the executable."""
    if len(comm) < 15:
        return comm
    candidates = []
    try:
        with open(f"/proc/{pid}/cmdline", "rb") as handle:
            candidates.append(handle.read().split(b"\0", 1)[0].decode("utf-8", errors="replace"))
    except OSError:
        pass
    try:
        candidates.append(os.readlink(f"/proc/{pid}/exe"))
    except OSError:                      # other users' processes: no access
        pass
    for candidate in candidates:
        base = os.path.basename(candidate)
        if base.startswith(comm):
            return base
    return comm


def _windows_processes() -> list[Process]:
    import ctypes
    from ctypes import wintypes

    class ProcessEntry(ctypes.Structure):
        _fields_ = [("dwSize", wintypes.DWORD), ("cntUsage", wintypes.DWORD), ("th32ProcessID", wintypes.DWORD),
                    ("th32DefaultHeapID", ctypes.c_size_t), ("th32ModuleID", wintypes.DWORD),
                    ("cntThreads", wintypes.DWORD), ("th32ParentProcessID", wintypes.DWORD),
                    ("pcPriClassBase", wintypes.LONG), ("dwFlags", wintypes.DWORD),
                    ("szExeFile", wintypes.WCHAR * 260)]

    class MemoryCounters(ctypes.Structure):
        _fields_ = [("cb", wintypes.DWORD), ("PageFaultCount", wintypes.DWORD)] + [
            (name, ctypes.c_size_t) for name in ("PeakWorkingSetSize", "WorkingSetSize", "QuotaPeakPagedPoolUsage",
                                                 "QuotaPagedPoolUsage", "QuotaPeakNonPagedPoolUsage",
                                                 "QuotaNonPagedPoolUsage", "PagefileUsage", "PeakPagefileUsage")]

    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
    kernel32.CreateToolhelp32Snapshot.restype = wintypes.HANDLE
    kernel32.OpenProcess.restype = wintypes.HANDLE
    snapshot = kernel32.CreateToolhelp32Snapshot(0x2, 0)        # TH32CS_SNAPPROCESS
    if snapshot in (None, wintypes.HANDLE(-1).value):
        return []
    result = []
    try:
        entry = ProcessEntry(dwSize=ctypes.sizeof(ProcessEntry))
        more = kernel32.Process32FirstW(wintypes.HANDLE(snapshot), ctypes.byref(entry))
        while more:
            memory = cpu = 0.0
            handle = kernel32.OpenProcess(0x1000, False, entry.th32ProcessID)   # QUERY_LIMITED_INFORMATION
            if handle:                                                      # None: access denied
                counters = MemoryCounters(cb=ctypes.sizeof(MemoryCounters))
                if kernel32.K32GetProcessMemoryInfo(wintypes.HANDLE(handle), ctypes.byref(counters), counters.cb):
                    memory = counters.WorkingSetSize / 2**20
                times = [wintypes.FILETIME() for _ in range(4)]            # creation, exit, kernel, user
                if kernel32.GetProcessTimes(wintypes.HANDLE(handle), *map(ctypes.byref, times)):
                    cpu = sum((t.dwHighDateTime << 32 | t.dwLowDateTime) for t in times[2:]) / 1e7
                kernel32.CloseHandle(wintypes.HANDLE(handle))
            name = entry.szExeFile.removesuffix(".exe")
            result.append(Process(name, entry.th32ProcessID, round(memory, 1), round(cpu, 1)))
            more = kernel32.Process32NextW(wintypes.HANDLE(snapshot), ctypes.byref(entry))
    finally:
        kernel32.CloseHandle(wintypes.HANDLE(snapshot))
    return result


PAGE = """<!doctype html>
<html><head><meta charset="utf-8"><style>
  body { font-family: system-ui, sans-serif; margin: 16px; }
  .bar { display: flex; gap: 8px; align-items: center; margin-bottom: 10px; }
  #filter { flex: 1; padding: 6px 8px; font-size: 14px; }
  table { border-collapse: collapse; width: 100%; font-size: 13px; }
  th, td { text-align: left; padding: 4px 8px; border-bottom: 1px solid #ddd; }
  th { background: #eef1f6; }
  th button { all: unset; cursor: default; font-weight: 700; }
  td.num, th.num { text-align: right; }
  #status { color: #555; font-size: 13px; margin-top: 8px; }
</style></head>
<body>
  <div class="bar">
    <input id="filter" placeholder="Filter by name or id" aria-label="Filter">
    <button id="refresh">Refresh</button>
  </div>
  <table>
    <thead><tr id="headers">
      <th aria-sort="none" id="col-Name"><button id="sort-Name">Name</button></th>
      <th class="num" aria-sort="none" id="col-Id"><button id="sort-Id">PID</button></th>
      <th class="num" aria-sort="descending" id="col-MemoryMB"><button id="sort-MemoryMB">Memory (MB)</button></th>
      <th class="num" aria-sort="none" id="col-CpuSeconds"><button id="sort-CpuSeconds">CPU (s)</button></th>
    </tr></thead>
    <tbody id="rows"></tbody>
  </table>
  <p id="status"></p>
</body></html>"""

# Column id in the page -> Process attribute.
COLUMNS = {"Name": "name", "Id": "pid", "MemoryMB": "memory_mb", "CpuSeconds": "cpu_seconds"}
MAX_ROWS = 200


class ProcessViewer:
    def __init__(self, document: Document):
        self.document = document
        self.snapshot: list[Process] = []
        self.filter_text = ""
        self.sort_by, self.descending = "MemoryMB", True
        # The input event carries the control's current value: no get_value needed.
        document.on("input", self.on_filter, element="filter")
        document.on("click", self.on_header, element="headers")
        document.on("click", lambda _event: self.refresh(), element="refresh")
        self.refresh()

    def refresh(self) -> None:
        # Plain data only: the view never keeps OS handles.
        self.snapshot = list_processes()
        self.render()

    def visible(self) -> list[Process]:
        rows = self.snapshot
        needle = self.filter_text.lower()
        if needle:
            rows = [p for p in rows if needle in p.name.lower() or str(p.pid) == needle]
        attribute = COLUMNS[self.sort_by]
        key = (lambda p: p.name.lower()) if attribute == "name" else (lambda p: getattr(p, attribute))
        return sorted(rows, key=key, reverse=self.descending)[:MAX_ROWS]

    def render(self) -> None:
        rows = self.visible()
        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 rows)
        operations = [{"op": "replace_children_html", "element": "rows", "html": cells}]
        for column in COLUMNS:
            sort = "none" if column != self.sort_by else ("descending" if self.descending else "ascending")
            operations.append({"op": "set_attribute", "element": f"col-{column}", "name": "aria-sort", "value": sort})
        operations.append({"op": "set_text", "element": "status",
                           "text": f"Showing {len(rows)} of {len(self.snapshot)} processes. "
                                   f"Updated {time.strftime('%H:%M:%S')}."})
        self.document.batch(operations)

    def on_filter(self, event: dict) -> None:
        self.filter_text = str(event.get("value", "")).strip()
        self.render()

    def on_header(self, event: dict) -> None:
        column = event["element"].removeprefix("sort-")
        if column not in COLUMNS:
            return
        self.sort_by, self.descending = self.sort_column(column)
        self.render()

    def sort_column(self, column: str) -> tuple[str, bool]:
        """Clicking the sorted column flips the order; a new column starts descending (Name ascending)."""
        if column == self.sort_by:
            return column, not self.descending
        return column, column != "Name"


def build(app: Application) -> ProcessViewer:
    window = app.open_html(PAGE, title="Processes", width=760, height=620)
    return ProcessViewer(window.document)


def main() -> None:
    with Application.start(name="Process viewer") as app:
        build(app)
        app.run()


if __name__ == "__main__":
    main()