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 library answers “one path, one predicate at a time” well, and a shell already answers it too — which is why os-helper ships no command line. A GUI has to go further to be worth anything, 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.

Where the words live

In the markup, in English. Each one is wrapped as {{_("…")}} in the HTML, or listed in _JS_NAME_TO_SOURCE for the script, and Catalog translates it through the compiled gettext catalogues under locales/ — the loader this very package provides (CODING.md 21.3), so the foundation reads its own strings through the same door it offers the rest of the suite.

English is the msgid, so it needs no catalogue and cannot fall out of sync with one; a string the French catalogue has not caught up with renders as readable English instead of as a key. The cost is the mirror image: rewording the English here orphans its French entry, and gettext would quietly serve the English. tests/test_gui_i18n.py exists to catch that — it hands every source string to Catalog.problems(), so an orphaned translation is a red build rather than a half-reverted page.

render_gui() resolves a language and returns the finished page.

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

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)

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)

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.default_language()

The language an unknown or absent ?lang= falls back to.

Return type:

str

os_helper.gui.render_gui(lang='', root='')

Render the Tree Radar page in the requested language.

Parameters:

• lang (str) – Two-letter language code. Anything outside the locale file’s a compiled catalogue — including the empty string — falls back to meta.default_locale, so an unknown ?lang= never 500s.

• root (str) – Folder to pre-fill in the input and auto-scan on load. Embedded as a JSON string literal, so a Windows path keeps its backslashes.

Returns:

The complete HTML document for that language.

Return type:

str

Examples

>>> "<!DOCTYPE html>" in render_gui("en")
True
>>> render_gui("tlh") == render_gui(default_language())
True

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

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).

os_helper.gui.supported_languages()

Language codes the GUI can render: English plus every compiled catalogue.

Return type:

tuple[str, …]