File viewer¶
Text file viewer and editor with native Open, Save As and Choose Folder dialogs.
Same example in PowerShell: File viewer

Real capture on KDE Plasma 6.6 Wayland with the released packages.
What it teaches: open_files/save_file/choose_folder; wait=False futures; file filters; -32001 fallback.
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 file_viewer.py [FILE]
Related guide: file dialogs
Source: file_viewer.py¶
"""Text file viewer and editor with native Open, Save As and Choose Folder dialogs.
What it teaches
* ``Window.open_files`` / ``save_file`` / ``choose_folder`` with filters and a start directory
* ``wait=False``: the dialog returns a Future, so the event callback returns at once and other
events keep flowing while the dialog is open; the result arrives in a done-callback
* the dialog result shape ``{"cancelled": bool, "paths": [...]}``
* graceful degradation: without a desktop session (headless/CI) dialogs fail with RpcError -32001
* showing file content safely with ``set_value`` (plain text) and escaping file names
Run: uv run file_viewer.py [FILE]
"""
from __future__ import annotations
import html
import sys
from concurrent.futures import Future
from pathlib import Path
from nativehtmlkit import Application, RpcError, Window
MAX_BYTES = 512 * 1024
TEXT_SUFFIXES = ["txt", "md", "py", "json", "csv", "log", "toml"]
TEXT_FILTERS = [{"name": "Text files", "extensions": TEXT_SUFFIXES}] # extensions without the dot
PAGE = """<!doctype html>
<html><head><meta charset="utf-8"><style>
body { margin:0; font:14px sans-serif; background:#f3f4f7; color:#20242c; display:flex; flex-direction:column; height:100vh; }
header { display:flex; gap:8px; align-items:center; padding:10px 12px; background:#fff; border-bottom:1px solid #d9dce3; }
button { padding:6px 12px; border:1px solid #b8bfcc; border-radius:5px; background:#fff; cursor:pointer; }
#path { margin-left:12px; color:#5b6474; font-family:monospace; }
.body { flex:1; display:flex; min-height:0; }
aside { width:220px; overflow:auto; background:#fbfbfd; border-right:1px solid #d9dce3; }
aside ul { list-style:none; margin:0; padding:6px 0; }
aside li { padding:4px 12px; cursor:pointer; font-family:monospace; }
aside li:hover { background:#e8eefc; }
textarea { flex:1; border:0; padding:12px; font:13px monospace; resize:none; }
footer { padding:6px 12px; background:#fff; border-top:1px solid #d9dce3; color:#5b6474; }
</style></head>
<body>
<header>
<button id="open">Open…</button><button id="save-as">Save As…</button><button id="folder">Folder…</button>
<span id="path">No file</span>
</header>
<div class="body">
<aside><ul id="files"></ul></aside>
<textarea id="editor" spellcheck="false" placeholder="Open a text file"></textarea>
</div>
<footer id="status">Ready.</footer>
</body></html>"""
class FileViewer:
def __init__(self, window: Window):
self.window, self.document = window, window.document
self.current: Path | None = None
self.folder_files: list[Path] = []
doc = self.document
doc.on("click", lambda _e: self.ask_open(), element="open")
doc.on("click", lambda _e: self.ask_save_as(), element="save-as")
doc.on("click", lambda _e: self.ask_folder(), element="folder")
doc.on("click", self._on_file_click, element="files")
# ----- native dialogs (non-blocking) -----
def ask_open(self) -> Future:
start = self.current.parent if self.current else Path.home()
future = self.window.open_files(title="Open a text file", directory=start, filters=TEXT_FILTERS,
multiple=False, wait=False)
future.add_done_callback(lambda f: self._dialog_done(f, self.load))
return future
def ask_save_as(self) -> Future:
name = self.current.name if self.current else "untitled.txt"
future = self.window.save_file(title="Save as", file_name=name, filters=TEXT_FILTERS, wait=False)
future.add_done_callback(lambda f: self._dialog_done(f, self.save))
return future
def ask_folder(self) -> Future:
future = self.window.choose_folder(title="Show the text files of a folder", wait=False)
future.add_done_callback(lambda f: self._dialog_done(f, self.show_folder))
return future
def _dialog_done(self, future: Future, action) -> None:
# Runs on an SDK completion thread; calling the synchronous SDK from here is fine.
try:
result = future.result()
except RpcError as error:
if error.code == -32001: # unsupported here, e.g. no desktop session (headless)
self.status("Native file dialogs are not available in this session.")
else:
self.status(f"Dialog failed (code {error.code}).")
return
except Exception as error: # window closed, application shutting down, ...
print("dialog ended:", type(error).__name__)
return
if result["cancelled"] or not result["paths"]:
self.status("Cancelled.")
return
action(Path(result["paths"][0]))
# ----- file operations (also used directly by the tests) -----
def load(self, path: Path) -> None:
try:
if path.stat().st_size > MAX_BYTES:
self.status(f"{path.name} is larger than {MAX_BYTES // 1024} KiB.")
return
text = path.read_text(encoding="utf-8")
except UnicodeDecodeError:
self.status(f"{path.name} is not UTF-8 text.")
return
except OSError as error:
self.status(f"Cannot read {path.name}: {error.strerror}")
return
self.current = path
self.document.set_value("editor", text) # plain text: never parsed as HTML
self.document.set_text("path", str(path))
self.window.set(title=f"{path.name} — File viewer")
self.status(f"Opened {path.name} ({len(text)} characters).")
def save(self, path: Path) -> None:
try:
path.write_text(self.document.get_value("editor"), encoding="utf-8")
except OSError as error:
self.status(f"Cannot save {path.name}: {error.strerror}")
return
self.current = path
self.document.set_text("path", str(path))
self.status(f"Saved {path.name}.")
def show_folder(self, folder: Path) -> None:
suffixes = {"." + e for e in TEXT_SUFFIXES}
self.folder_files = sorted(p for p in folder.iterdir() if p.is_file() and p.suffix.lower() in suffixes)[:200]
items = "".join(f'<li id="file-{i}">{html.escape(p.name)}</li>' for i, p in enumerate(self.folder_files))
self.document.replace_html("files", items or "<li>(no text files)</li>")
self.status(f"{len(self.folder_files)} text file(s) in {folder.name or folder}.")
def _on_file_click(self, event: dict) -> None:
element = event["element"]
if element.startswith("file-") and element[5:].isdigit():
self.load(self.folder_files[int(element[5:])])
def status(self, text: str) -> None:
self.document.set_text("status", text)
def build(app: Application) -> FileViewer:
return FileViewer(app.open_html(PAGE, title="File viewer", width=900, height=600))
def main() -> None:
with Application.start(name="File viewer") as app:
viewer = build(app)
if len(sys.argv) > 1: # optional: open a file at start, without a dialog
viewer.load(Path(sys.argv[1]))
app.run()
if __name__ == "__main__":
main()