os_helper.gui module

OS Helper — optional “Tree Radar” treemap GUI.

Module summary

This module is an optional surface on top of the pure os_helper library. It serves a small, self-contained web dashboard — the “Tree Radar” from GUI.md — that turns “what is on disk” into a single, legible treemap:

  • Each rectangle is a file or folder; its area is the file/subtree size, and its color encodes one of three modes: - age (recent vs. stale, from each file’s mtime), - hash-dedupe (files that share a content hash form a cluster,

    colored so duplicates stand out), or

    • type family (code / data / media / archive / other).

  • Hovering a rectangle reveals its absolute path, human-readable size (via os_helper.format_size()), last-modified timestamp and — on demand — its RIPEMD-160 / BLAKE2b content hash (via os_helper.hashfile()).

Why it exists

The CLI handles “one path, one predicate at a time” well. A GUI must go further, so this one shows the whole tree at a glance. It is a thin client: all the read/compute work is delegated to the existing os_helper helpers (os.walk size collection, format_size, hashfile), never reinvented here.

What it consumes / produces

  • Consumes: a local directory root (a path on this machine).

  • Produces: a locally-served HTML page (GET /gui) and a JSON tree (GET /api/tree). Nothing is uploaded; no telemetry; no account.

Lean-import contract

import os_helper as osh must stay free of FastAPI/uvicorn. FastAPI is therefore imported inside create_app() / run(), never at module top level, and the whole GUI lives behind the optional os-helper[gui] extra. Importing this module is cheap; it only pulls FastAPI when you actually build or run the app.

Usage example

>>> # Requires the optional extra:  pip install "os-helper[gui]"
>>> from os_helper.gui import run
>>> run(root="~/Downloads", port=8017)

Author

Warith Harchaoui, Ph.D. — https://linkedin.com/in/warith-harchaoui/

class os_helper.gui.TreeNode[source]

Bases: TypedDict

One node of the directory tree sent to the browser as JSON.

A node is either a file (no children) or a directory (with a children list). Sizes are in bytes; size_h is the pre-formatted human-readable string so the front-end never re-implements os_helper.format_size().

children: list[TreeNode]
family: str
is_dir: bool
mtime: float
name: str
path: str
size: int
size_h: str
os_helper.gui.build_tree_payload(root, max_depth=12, max_entries=20000, dedupe=False)[source]

Build the full JSON payload served by GET /api/tree.

This is the backend entry point behind the data endpoint. It scans the tree (sizes + mtimes + families) and, when dedupe is set, also computes content-hash duplicate groups.

Parameters:

  • root (str) – Directory to scan. ~ is expanded and the path is made absolute.

  • max_depth (int, optional) – Maximum recursion depth (default 12).

  • max_entries (int, optional) – Global cap on entries visited (default 20000).

  • dedupe (bool, optional) – If True, also hash every file and include a dedupe mapping of duplicate clusters. Defaults to False (cheap, no content reads).

Returns:

{"root": <abs path>, "tree": <TreeNode>, "dedupe": {hash: [paths]}}.

Return type:

dict

Raises:

NotADirectoryError – If root does not resolve to an existing directory.

os_helper.gui.create_app(default_root=None)[source]

Build the FastAPI application serving the Tree Radar GUI.

FastAPI is imported here, not at module top level, so that merely importing os_helper (or even this module) never pulls the web stack. The web dependencies live behind the os-helper[gui] extra.

Parameters:

default_root (str, optional) – Folder to pre-fill in the page and auto-scan on load. Defaults to the current working directory when not given.

Returns:

The configured application, exposing GET /gui (the page) and GET /api/tree (the JSON data endpoint).

Return type:

fastapi.FastAPI

Raises:

ImportError – If FastAPI is not installed (i.e. the gui extra is missing), with a message pointing at pip install "os-helper[gui]".

os_helper.gui.run(root=None, host='127.0.0.1', port=8017)[source]

Launch the Tree Radar GUI with uvicorn (blocking).

Binds to loopback by default so the dashboard is reachable only from this machine — consistent with the local-first promise.

Parameters:

  • root (str, optional) – Folder to pre-fill and auto-scan. Defaults to the current directory.

  • host (str, optional) – Interface to bind. Defaults to "127.0.0.1" (localhost only).

  • port (int, optional) – TCP port to serve on. Defaults to 8017.

Raises:

ImportError – If the gui extra (FastAPI/uvicorn) is not installed.

Return type:

None

Notes

This call blocks until the server is stopped (Ctrl-C).