nicegui-treebrowser 0.1.0__py3-none-any.whl

nicegui_treebrowser/__init__.py

@@ -0,0 +1,7 @@
+"""A NiceGUI element for browsing, previewing and downloading a
+server-side directory."""
+
+from .browser import TreeBrowser
+
+__all__ = ["TreeBrowser", "__version__"]
+__version__ = "0.1.0"

nicegui_treebrowser/browser.py

@@ -0,0 +1,474 @@
+"""The :class:`TreeBrowser` NiceGUI element."""
+
+from __future__ import annotations
+
+import csv
+import logging
+from collections.abc import Callable, Iterable
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from nicegui import app, events, ui
+
+from . import filetypes
+from .fsutil import get_dir_size, looks_like_text, make_tarball, natural_size, read_text
+
+LOG = logging.getLogger(__name__)
+
+__all__ = ["TreeBrowser"]
+
+
+# inspired by (but not copied from)
+# https://github.com/zauberzeug/nicegui/tree/main/examples/local_file_picker
+class TreeBrowser(ui.column):
+    """Browse, preview and download the contents of a server-side directory.
+
+    A NiceGUI element: it renders where it is created, and takes `.classes()`,
+    `.style()`, `.props()` and `.move()` like any other `ui.*` element.
+
+    :param root: directory to expose; nothing outside it is ever served
+    :param focus: file or folder to reveal and open upon init
+    :param title: heading shown above the tree
+    :param show_hidden: include dot-files and dot-directories
+    :param exclude: predicate function returning True for paths to exclude
+    :param max_preview_bytes: largest text preview to load into the browser
+    :param max_table_rows: row cap for .csv/.tsv previews
+    :param allow_archive: show the "Download all" and per-folder archive buttons
+    :param show_full_path: show the full path of the directory
+    :param sniff_text: preview unrecognised files that look like UTF-8 text,
+        instead of offering only a download
+    """
+
+    _tree_container: ui.column
+    _tree: ui.tree
+    _viewer: ui.column
+
+    def __init__(
+        self,
+        root: str | Path,
+        *,
+        focus: str | Path | None = None,
+        title: str = "Files",
+        show_hidden: bool = False,
+        exclude: Callable[[Path], bool] | None = None,
+        max_preview_bytes: int = 1000000,
+        max_table_rows: int = 5000,
+        allow_archive: bool = True,
+        show_full_path: bool = True,
+        sniff_text: bool = False,
+    ) -> None:
+        resolved_root = Path(root).expanduser().resolve()
+        if not resolved_root.is_dir():
+            raise NotADirectoryError(f"{resolved_root} is not a directory")
+
+        super().__init__()
+        self.root = resolved_root
+        self.title = title
+        self.show_hidden = show_hidden
+        self.exclude = exclude
+        self.max_preview_bytes = max_preview_bytes
+        self.max_table_rows = max_table_rows
+        self.allow_archive = allow_archive
+        self.show_full_path = show_full_path
+        self.sniff_text = sniff_text
+
+        self._paths: dict[str, Path] = {}
+        self._selected: str | None = None
+        # URLs this browser has published for the current preview; see _pane()
+        self._routes: list[str] = []
+
+        self.classes("w-full min-h-[50vh] gap-0 p-0 flex-nowrap")
+        with self:
+            self._build_header()
+            with ui.splitter(value=32).classes("w-full min-h-0 flex-grow") as splitter:
+                with splitter.before:
+                    self._build_sidebar()
+                with splitter.after:
+                    self._viewer = ui.column().classes(
+                        "w-full h-full gap-4 p-6 overflow-auto flex-nowrap"
+                    )
+            if focus is None or not self.focus(focus):
+                self._show_placeholder()
+
+    def focus(self, path: str | Path, *, collapse_others: bool = True) -> bool:
+        """Select path and open just the folders needed to reveal it.
+
+        Only the target's ancestors are expanded — an expanded sibling branch is
+        never needed to show it. The target itself stays as it is, so focusing a
+        folder reveals it without dumping its contents into the tree.
+
+        Accepts an absolute path or one relative to the root. Returns False if
+        the path lies outside the root or is not in the tree (missing, hidden,
+        or excluded), in which case the current selection is left alone. To
+        open the browser on a given path, pass `focus=` to the constructor.
+
+        :param path: the file or folder to reveal
+        :param collapse_others: close every other branch, so only this one is open
+        """
+
+        target = Path(path).expanduser()
+        if not target.is_absolute():
+            target = self.root / target
+        target = target.resolve()
+        try:
+            key = self._key(target)
+        except ValueError:
+            ui.notify(f"{target} is outside {self.root}", type="warning")
+            return False
+
+        if key not in self._paths:
+            self.refresh()  # the tree may predate the file
+        if key not in self._paths:
+            ui.notify(f"{target.name} is not in this tree", type="warning")
+            return False
+
+        if collapse_others:
+            self._tree.collapse()
+        ancestors = self._ancestor_keys(target)
+        if ancestors:
+            self._tree.expand(ancestors)
+        self._tree.select(key)
+        self._selected = key
+
+        self._display(target)
+        self._scroll_to_selection()
+        return True
+
+    def refresh(self) -> None:
+        """Re-read the directory tree from disk and redraw it."""
+        self._tree_container.clear()
+        with self._tree_container:
+            self._build_tree()
+        if self._selected is not None and self._selected not in self._paths:
+            self._selected = None
+            self._show_placeholder()
+
+    def _build_header(self) -> None:
+        with ui.row().classes(
+            "w-full items-center justify-between gap-4 px-6 py-3 "
+            "border-b border-gray-200 dark:border-gray-700"
+        ):
+            with ui.column().classes("gap-0 min-w-0"):
+                ui.label(self.title).classes("text-lg font-medium leading-tight")
+                if self.show_full_path:
+                    ui.label(str(self.root)).classes(
+                        "text-xs text-gray-500 font-mono truncate"
+                    )
+            with ui.row().classes("items-center gap-2 flex-nowrap"):
+                ui.button(icon="refresh", on_click=self.refresh).props(
+                    "flat round dense"
+                ).tooltip("Reload the tree from disk")
+                if self.allow_archive:
+                    ui.button(
+                        "Download all",
+                        icon="archive",
+                        on_click=lambda: self._download_archive(self.root),
+                    ).props("outline no-caps")
+
+    def _build_sidebar(self) -> None:
+        with ui.column().classes("w-full h-full gap-0 flex-nowrap"):
+            search = (
+                ui.input(placeholder="Filter by name")
+                .props("dense outlined clearable")
+                .classes("w-full px-3 py-2")
+            )
+            search.on_value_change(lambda e: self._filter(e.value))
+            self._tree_container = ui.column().classes(
+                "w-full min-h-0 flex-grow overflow-auto px-2 pb-4 flex-nowrap"
+            )
+            with self._tree_container:
+                self._build_tree()
+
+    def _build_tree(self) -> None:
+        self._paths.clear()
+        self._tree = ui.tree(
+            [self._node(self.root)],
+            label_key="label",
+            on_select=self._on_select,
+        ).classes("w-full")
+        self._tree.expand()
+
+    def _node(self, path: Path) -> dict[str, Any]:
+        key = self._key(path)
+        self._paths[key] = path
+        node: dict[str, Any] = {
+            "id": key,
+            "label": path.name or str(path),
+            "icon": "folder" if path.is_dir() else filetypes.icon_for(path),
+        }
+        if path.is_dir():
+            node["children"] = [self._node(child) for child in self._entries(path)]
+        return node
+
+    def _entries(self, directory: Path) -> Iterable[Path]:
+        try:
+            entries = list(directory.iterdir())
+        except PermissionError:
+            return []
+        entries = [entry for entry in entries if not self._skip(entry)]
+        # directories first, then files, each alphabetically and case-insensitively
+        entries.sort(key=lambda entry: (not entry.is_dir(), entry.name.lower()))
+        return entries
+
+    def _skip(self, path: Path) -> bool:
+        if not self.show_hidden and path.name.startswith("."):
+            return True
+        if path.is_symlink():  # keeps the walk free of loops and escapes
+            return True
+        if not path.is_dir() and not path.is_file():
+            return True
+        return bool(self.exclude and self.exclude(path))
+
+    def _key(self, path: Path) -> str:
+        relative = path.relative_to(self.root).as_posix()
+        return relative or "."
+
+    def _ancestor_keys(self, path: Path) -> list[str]:
+        """Keys of every folder between the root and *path*, outermost first."""
+        keys: list[str] = []
+        current = path
+        while current != self.root:
+            current = current.parent
+            keys.append(self._key(current))
+        keys.reverse()
+        return keys
+
+    def _resolve(self, key: str) -> Path | None:
+        """Map a tree key back to a path, refusing anything outside the root."""
+        path = self._paths.get(key)
+        if path is None:
+            return None
+        resolved = path.resolve()
+        if resolved != self.root and self.root not in resolved.parents:
+            return None
+        return resolved if resolved.exists() else None
+
+    def _filter(self, text: str | None) -> None:
+        # QTree's own filter prop: matching nodes stay, the rest are hidden.
+        self._tree.filter = text or ""
+
+    # -- selection ---------------------------------------------------------
+
+    # ValueChangeEventArguments only became generic in NiceGUI 3.0; the
+    # subscript is safe on 2.x because `from __future__ import annotations`
+    # keeps it an unevaluated string.
+    def _on_select(self, event: events.ValueChangeEventArguments[str | None]) -> None:
+        key = event.value
+        self._selected = key
+        if key is None:
+            self._show_placeholder()
+            return
+        path = self._resolve(key)
+        if path is None:
+            self._show_message(
+                "That item is gone", "Reload the tree to see what changed."
+            )
+            return
+        self._display(path)
+
+    def _display(self, path: Path) -> None:
+        if path.is_dir():
+            self._show_directory(path)
+        else:
+            self._show_file(path)
+
+    def _scroll_to_selection(self) -> None:
+        with self._tree_container:
+            ui.timer(0.1, self._scroll_now, once=True)
+
+    def _scroll_now(self) -> None:
+        try:
+            ui.run_javascript(f"""
+                getElement({self._tree.id})?.$el
+                    ?.querySelector(
+                        '.q-tree__node--selected, .q-tree__node-header--selected')
+                    ?.scrollIntoView({{block: 'nearest'}});
+            """)
+        except Exception as e:
+            # the client went away; the scroll is cosmetic either way
+            LOG.warning(e)
+
+    def _pane(self) -> ui.element:
+        # Elements that publish their own file (ui.image, ui.audio, ui.video)
+        # drop their route when they are deleted. The PDF iframe has no such
+        # element behind it, so retire those routes here: a file stays reachable
+        # only for as long as the preview that published it is on screen.
+        for url in self._routes:
+            app.remove_route(url)
+        self._routes.clear()
+        self._viewer.clear()
+        return self._viewer
+
+    def _show_placeholder(self) -> None:
+        with (
+            self._pane(),
+            ui.column().classes("w-full h-full items-center justify-center gap-2"),
+        ):
+            ui.icon("folder_open", size="3rem").classes("text-gray-400")
+            ui.label("Pick a file to read it here.").classes("text-gray-500")
+
+    def _show_message(self, heading: str, detail: str) -> None:
+        with self._pane():
+            ui.label(heading).classes("text-lg font-medium")
+            ui.label(detail).classes("text-gray-500")
+
+    def _show_directory(self, path: Path) -> None:
+        with self._pane():
+            # _resolve() has already confirmed the path, but it may still go
+            # away between that check and this read.
+            try:
+                files, directories, total = get_dir_size(path)
+                self._file_header(path)
+            except OSError as error:
+                ui.label(f"Could not read this folder: {error}").classes("text-red-600")
+                return
+            ui.label(
+                f"{files} file{'' if files == 1 else 's'} in "
+                f"{directories} subfolder{'' if directories == 1 else 's'} · "
+                f"{natural_size(total)}"
+            ).classes("text-sm text-gray-500")
+
+    def _show_file(self, path: Path) -> None:
+        kind = filetypes.classify(path)
+        with self._pane():
+            # The header stats the file, so it belongs inside the guard too: the
+            # file may vanish between _resolve() confirming it and this read.
+            try:
+                self._file_header(path)
+                self._preview(path, kind)
+            except Exception as error:  # unreadable file, bad CSV, broken encoding…
+                ui.label(f"Could not read this file: {error}").classes("text-red-600")
+
+    def _preview(self, path: Path, kind: filetypes.PreviewKind) -> None:
+        if kind == "image":
+            self._preview_image(path)
+        elif kind == "pdf":
+            self._preview_pdf(path)
+        elif kind == "audio":
+            self._preview_audio(path)
+        elif kind == "video":
+            self._preview_video(path)
+        elif kind == "table":
+            self._preview_table(path, filetypes.table_delimiter(path))
+        elif kind == "markdown":
+            self._preview_markdown(path)
+        elif kind == "code":
+            self._preview_code(path, filetypes.code_language(path))
+        elif self.sniff_text and looks_like_text(path):
+            self._preview_code(path, "text")
+        else:
+            ui.label(
+                "No preview for this file type — download it to open it locally."
+            ).classes("text-gray-500")
+
+    def _file_header(self, path: Path) -> None:
+        info = path.stat()
+        with ui.row().classes("w-full items-start justify-between gap-4 flex-nowrap"):
+            with ui.column().classes("gap-1 min-w-0"):
+                ui.label(path.name or str(path)).classes("text-lg font-medium truncate")
+                details = [
+                    datetime.fromtimestamp(info.st_mtime).strftime("%Y-%m-%d %H:%M")
+                ]
+                if path.is_file():
+                    details.insert(0, natural_size(info.st_size))
+                ui.label(" · ".join(details)).classes("text-xs text-gray-500")
+            with ui.row().classes("items-center gap-2 flex-nowrap"):
+                if path.is_file():
+                    ui.button(
+                        "Download",
+                        icon="download",
+                        on_click=lambda p=path: ui.download.file(p, p.name),
+                    ).props("outline no-caps")
+                elif self.allow_archive:
+                    ui.button(
+                        "Download folder",
+                        icon="archive",
+                        on_click=lambda p=path: self._download_archive(p),
+                    ).props("outline no-caps")
+
+    def _preview_code(self, path: Path, language: str) -> None:
+        text, truncated = read_text(path, self.max_preview_bytes)
+        if truncated:
+            self._truncation_note(
+                f"Showing the first {natural_size(self.max_preview_bytes)}."
+            )
+        ui.code(text, language=language).classes("w-full")
+
+    def _preview_markdown(self, path: Path) -> None:
+        text, truncated = read_text(path, self.max_preview_bytes)
+        if truncated:
+            self._truncation_note(
+                f"Showing the first {natural_size(self.max_preview_bytes)}."
+            )
+        ui.markdown(text).classes("w-full max-w-none prose dark:prose-invert")
+
+    def _preview_image(self, path: Path) -> None:
+        # ui.image publishes the file itself and retires the route when the
+        # element is deleted, so there is nothing for us to clean up.
+        ui.image(path).classes("max-w-full").style("max-height: 80vh")
+
+    def _preview_audio(self, path: Path) -> None:
+        ui.audio(path).classes("w-full")
+
+    def _preview_video(self, path: Path) -> None:
+        # ui.video serves through add_media_file, which honours Range requests,
+        # so the viewer can seek without downloading the whole file first.
+        ui.video(path).classes("w-full").style("max-height: 80vh")
+
+    def _preview_pdf(self, path: Path) -> None:
+        url = app.add_static_file(local_file=path)
+        self._routes.append(url)
+        ui.element("iframe").props(f'src="{url}"').classes(
+            "w-full min-h-[70vh] flex-grow border-0"
+        )
+
+    def _preview_table(self, path: Path, delimiter: str) -> None:
+        with open(path, newline="", encoding="utf-8", errors="replace") as handle:
+            reader = csv.reader(handle, delimiter=delimiter)
+            header = next(reader, None)
+            if header is None:
+                ui.label("This file is empty.").classes("text-gray-500")
+                return
+            # Synthetic field names: a CSV header may repeat itself, be blank,
+            # or collide with the row key, none of which QTable tolerates.
+            fields = [f"c{index}" for index in range(len(header))]
+            rows: list[dict[str, Any]] = []
+            truncated = False
+            for index, record in enumerate(reader):
+                if index >= self.max_table_rows:
+                    truncated = True
+                    break
+                row: dict[str, Any] = dict(zip(fields, record, strict=False))
+                row["_row"] = index
+                rows.append(row)
+        if truncated:
+            self._truncation_note(f"Showing the first {self.max_table_rows:,} rows.")
+        columns = [
+            {
+                "name": field,
+                "label": label,
+                "field": field,
+                "align": "left",
+                "sortable": True,
+            }
+            for field, label in zip(fields, header, strict=True)
+        ]
+        ui.table(rows=rows, columns=columns, row_key="_row", pagination=25).classes(
+            "w-full"
+        )
+
+    @staticmethod
+    def _truncation_note(text: str) -> None:
+        with ui.row().classes("items-center gap-2 text-xs text-gray-500"):
+            ui.icon("content_cut", size="1rem")
+            ui.label(f"{text} Download the file for everything.")
+
+    def _download_archive(self, path: Path) -> None:
+        name = path.name or self.root.name or "archive"
+        try:
+            data = make_tarball(str(path), name)
+        except Exception as error:
+            ui.notify(f"Could not pack {name}.tar.gz: {error}", type="negative")
+            return
+        ui.download.content(data, f"{name}.tar.gz", media_type="application/gzip")

nicegui_treebrowser/filetypes.py

@@ -0,0 +1,169 @@
+"""Maps a filename to the way its contents should be previewed.
+
+Every table below is a plain module-level dict or set, so an application can
+extend them at import time, e.g. ``filetypes.CODE_LANGUAGES[".ino"] = "cpp"``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+__all__ = [
+    "AUDIO_SUFFIXES",
+    "CODE_LANGUAGES",
+    "IMAGE_SUFFIXES",
+    "MARKDOWN_SUFFIXES",
+    "PDF_SUFFIXES",
+    "STEM_LANGUAGES",
+    "TABLE_DELIMITERS",
+    "VIDEO_SUFFIXES",
+    "PreviewKind",
+    "classify",
+    "code_language",
+    "icon_for",
+    "table_delimiter",
+]
+
+PreviewKind = Literal[
+    "image", "pdf", "audio", "video", "table", "markdown", "code", "none"
+]
+
+#: Suffixes every mainstream browser can decode in an ``<img>`` tag.
+#: Formats they cannot (``.tif``, ``.psd``, ``.heic``) are left download-only.
+IMAGE_SUFFIXES = {
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".webp",
+    ".bmp",
+    ".avif",
+    ".ico",
+}
+
+PDF_SUFFIXES = {".pdf"}
+
+AUDIO_SUFFIXES = {".mp3", ".wav", ".ogg", ".oga", ".m4a", ".flac", ".aac"}
+
+VIDEO_SUFFIXES = {".mp4", ".webm", ".ogv", ".mov"}
+
+TABLE_DELIMITERS = {
+    ".csv": ",",
+    ".tsv": "\t",
+}
+
+MARKDOWN_SUFFIXES = {".md", ".markdown"}
+
+#: Suffix to Pygments lexer name. ``.svg`` and ``.html`` are here on purpose:
+#: both are served from the app's own origin, so rendering them would run any
+#: script they carry. Showing the source is safe and still useful.
+CODE_LANGUAGES = {
+    ".bash": "bash",
+    ".c": "c",
+    ".cfg": "ini",
+    ".config": "text",
+    ".cpp": "cpp",
+    ".css": "css",
+    ".diff": "diff",
+    ".go": "go",
+    ".h": "c",
+    ".hpp": "cpp",
+    ".html": "html",
+    ".ini": "ini",
+    ".java": "java",
+    ".jl": "julia",
+    ".js": "javascript",
+    ".json": "json",
+    ".jsx": "jsx",
+    ".kt": "kotlin",
+    ".log": "text",
+    ".lua": "lua",
+    ".patch": "diff",
+    ".php": "php",
+    ".pl": "perl",
+    ".py": "python",
+    ".r": "r",
+    ".rb": "ruby",
+    ".rs": "rust",
+    ".scala": "scala",
+    ".scss": "scss",
+    ".sh": "bash",
+    ".sql": "sql",
+    ".svg": "xml",
+    ".swift": "swift",
+    ".tex": "tex",
+    ".toml": "toml",
+    ".ts": "typescript",
+    ".tsx": "tsx",
+    ".txt": "text",
+    ".vue": "html",
+    ".xml": "xml",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+    ".zsh": "bash",
+}
+
+#: Well-known files that carry no suffix at all, keyed by lowercased name.
+STEM_LANGUAGES = {
+    "authors": "text",
+    "changelog": "text",
+    "dockerfile": "docker",
+    "gemfile": "ruby",
+    "justfile": "make",
+    "license": "text",
+    "makefile": "make",
+    "notice": "text",
+    "rakefile": "ruby",
+    "readme": "text",
+}
+
+
+def classify(path: Path) -> PreviewKind:
+    """Return how *path* should be previewed, or ``"none"`` if we do not know."""
+    suffix = path.suffix.lower()
+    if suffix in IMAGE_SUFFIXES:
+        return "image"
+    if suffix in PDF_SUFFIXES:
+        return "pdf"
+    if suffix in AUDIO_SUFFIXES:
+        return "audio"
+    if suffix in VIDEO_SUFFIXES:
+        return "video"
+    if suffix in TABLE_DELIMITERS:
+        return "table"
+    if suffix in MARKDOWN_SUFFIXES:
+        return "markdown"
+    if suffix in CODE_LANGUAGES or path.name.lower() in STEM_LANGUAGES:
+        return "code"
+    return "none"
+
+
+def code_language(path: Path) -> str:
+    """Return the Pygments lexer name for *path*, defaulting to plain text."""
+    suffix = path.suffix.lower()
+    if suffix in CODE_LANGUAGES:
+        return CODE_LANGUAGES[suffix]
+    return STEM_LANGUAGES.get(path.name.lower(), "text")
+
+
+def table_delimiter(path: Path) -> str:
+    """Return the column delimiter for a tabular file, defaulting to a comma."""
+    return TABLE_DELIMITERS.get(path.suffix.lower(), ",")
+
+
+_ICONS: dict[PreviewKind, str] = {
+    "image": "image",
+    "pdf": "picture_as_pdf",
+    "audio": "audio_file",
+    "video": "video_file",
+    "table": "table_chart",
+    "markdown": "article",
+    "code": "description",
+    "none": "insert_drive_file",
+}
+
+
+def icon_for(path: Path) -> str:
+    """Return the Material icon name that suits *path*."""
+    return _ICONS[classify(path)]

nicegui_treebrowser/fsutil.py

@@ -0,0 +1,88 @@
+"""Filesystem helpers: sizing, safe text reads and folder archives.
+
+Deliberately stdlib-only, so the package depends on nothing but NiceGUI itself.
+"""
+
+from __future__ import annotations
+
+import io
+import tarfile
+from pathlib import Path
+
+__all__ = [
+    "get_dir_size",
+    "looks_like_text",
+    "make_tarball",
+    "natural_size",
+    "read_text",
+]
+
+_UNITS = ("kB", "MB", "GB", "TB", "PB", "EB")
+
+
+def natural_size(size: int) -> str:
+    """Format a byte count using decimal units, e.g. ``1.5 kB`` or ``2.3 MB``."""
+    if size < 1000:
+        return f"{size} byte" if size == 1 else f"{size} bytes"
+    value = float(size)
+    for unit in _UNITS:
+        value /= 1000.0
+        if value < 1000.0 or unit == _UNITS[-1]:
+            return f"{value:.1f} {unit}"
+    raise AssertionError("unreachable")  # pragma: no cover
+
+
+def make_tarball(directory: str, arcname: str) -> bytes:
+    """Return *directory* as an in-memory gzipped tarball."""
+    buffer = io.BytesIO()
+    with tarfile.open(fileobj=buffer, mode="w:gz") as archive:
+        archive.add(directory, arcname=arcname)
+    return buffer.getvalue()
+
+
+def read_text(path: Path, limit: int) -> tuple[str, bool]:
+    """Read at most *limit* bytes of *path* as text.
+
+    Returns the decoded text and whether the file continued past the limit.
+    Undecodable bytes become replacement characters rather than raising.
+    """
+    with open(path, "rb") as handle:
+        raw = handle.read(limit + 1)
+    content = raw[:limit].decode("utf-8", errors="replace")
+    is_truncated = len(raw) > limit
+    return content, is_truncated
+
+
+def looks_like_text(path: Path, probe: int = 8192) -> bool:
+    """Guess whether *path* holds UTF-8 text, by sniffing its first *probe* bytes.
+
+    A NUL byte means binary. A decode error at the very end of the probe is
+    ignored, since a multi-byte character may simply straddle the cut.
+    """
+    try:
+        with open(path, "rb") as handle:
+            head = handle.read(probe)
+    except OSError:
+        return False
+    if b"\x00" in head:
+        return False
+    try:
+        head.decode("utf-8")
+    except UnicodeDecodeError as error:
+        # tolerate a character chopped in half by the probe boundary
+        return len(head) == probe and error.start >= probe - 4
+    return True
+
+
+def get_dir_size(directory: Path) -> tuple[int, int, int]:
+    """Return directory's file count, directory count, and total bytes."""
+    files = directories = total = 0
+    for entry in directory.rglob("*"):
+        if entry.is_symlink():
+            continue
+        if entry.is_dir():
+            directories += 1
+        elif entry.is_file():
+            files += 1
+            total += entry.stat().st_size
+    return files, directories, total

nicegui_treebrowser-0.1.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.5
+Name: nicegui-treebrowser
+Version: 0.1.0
+Summary: A NiceGUI element that browses, previews and downloads a server-side directory tree
+Project-URL: Homepage, https://github.com/odoublewen/nicegui-treebrowser
+Project-URL: Issues, https://github.com/odoublewen/nicegui-treebrowser/issues
+Author-email: Owen Solberg <owen.solberg@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: directory-tree,file-browser,gui,nicegui,widget
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: nicegui>=2.14; python_version < '3.14'
+Requires-Dist: nicegui>=3.0.4; python_version >= '3.14'
+Description-Content-Type: text/markdown
+
+# nicegui-treebrowser
+
+[![tests](https://github.com/odoublewen/nicegui-treebrowser/actions/workflows/tests.yml/badge.svg?branch=develop)](https://github.com/odoublewen/nicegui-treebrowser/actions/workflows/tests.yml)
+
+A [NiceGUI](https://nicegui.io) element that renders a server-side directory as a
+browsable tree, previews the files it finds, and lets people download them
+individually or as a `.tar.gz`.
+
+It is an ordinary NiceGUI element: it renders where you create it and accepts
+`.classes()`, `.style()`, `.props()` and `.move()` like anything else in `ui.*`.
+
+## Install
+
+```bash
+pip install nicegui-treebrowser     # or: uv add nicegui-treebrowser
+```
+
+### Supported versions
+
+| Python | NiceGUI |
+|---|---|
+| 3.13 | 2.14+ or 3.x |
+| 3.14 | 3.0.4+ |
+
+NiceGUI releases before 3.0.4 pull in a `vbuild` that calls `pkgutil.find_loader`,
+removed in Python 3.14, so they cannot be imported there at all. The dependency
+markers pick a workable floor for you.
+
+Python 3.15 is not supported yet: `aiohttp`, which NiceGUI requires, has no 3.15
+wheels. Nothing in this package stands in the way — it should work as soon as the
+wheels land.
+
+The test suite runs against NiceGUI 2.14.1, 3.0.4 and 3.17.1.
+
+## Quickstart
+
+```python
+from nicegui import ui
+from nicegui_treebrowser import TreeBrowser
+
+
+@ui.page("/")
+def index() -> None:
+    TreeBrowser("/srv/results", title="Results")
+
+
+ui.run()
+```
+
+## Options
+
+| Parameter | Default | Meaning |
+|---|---|---|
+| `root` | — | Directory to expose. Nothing outside it is ever served. |
+| `focus` | `None` | File or folder to reveal and open on load. |
+| `title` | `"Files"` | Heading shown above the tree. |
+| `show_hidden` | `False` | Include dot-files and dot-directories. |
+| `exclude` | `None` | Predicate returning `True` for paths to leave out. |
+| `max_preview_bytes` | `1_000_000` | Largest text preview loaded into the browser. |
+| `max_table_rows` | `5000` | Row cap for `.csv`/`.tsv` previews. |
+| `allow_archive` | `True` | Show the "Download all" and per-folder archive buttons. |
+| `show_full_path` | `True` | Print the root's absolute path under the title. |
+| `sniff_text` | `False` | Preview unrecognised files that look like UTF-8 text. |
+
+Two methods are worth knowing:
+
+- `browser.focus(path)` — select `path` and expand only the folders needed to reveal
+  it. Returns `False` if the path is outside the root or not in the tree.
+- `browser.refresh()` — re-read the tree from disk.
+
+## What gets previewed
+
+| Kind | Extensions |
+|---|---|
+| Image | `.png` `.jpg` `.jpeg` `.gif` `.webp` `.bmp` `.avif` `.ico` |
+| PDF | `.pdf` |
+| Audio | `.mp3` `.wav` `.ogg` `.oga` `.m4a` `.flac` `.aac` |
+| Video | `.mp4` `.webm` `.ogv` `.mov` |
+| Table | `.csv` `.tsv` |
+| Markdown | `.md` `.markdown` |
+| Source | ~40 suffixes (`.py` `.js` `.ts` `.json` `.yaml` `.toml` `.sql` `.go` `.rs` …) plus suffixless `Dockerfile`, `Makefile`, `Gemfile`, `Rakefile`, `justfile`, `LICENSE`, `NOTICE`, `AUTHORS`, `README` and `changelog` |
+
+Anything else offers a download. Set `sniff_text=True` to additionally preview
+unrecognised files whose first 8 KiB decode as UTF-8 and contain no NUL bytes.
+
+`.svg` and `.html` are shown **as source**, not rendered — see below.
+
+The tables are plain module-level dicts, so you can extend them:
+
+```python
+from nicegui_treebrowser import filetypes
+
+filetypes.CODE_LANGUAGES[".ino"] = "cpp"
+filetypes.IMAGE_SUFFIXES.add(".jxl")
+```
+
+## Security
+
+Read this before pointing the widget at anything sensitive.
+
+- **`root` is the boundary.** Tree keys are resolved back through a dictionary built
+  by walking `root`, and the result is re-checked against `root` before anything is
+  served. A key naming a path outside the root, or one that was never in the tree,
+  resolves to nothing.
+- **Symlinks are skipped entirely**, so a link inside the root cannot be used to read
+  or traverse outside it.
+- **`exclude` and `show_hidden` are real filters**, not just display ones. A file they
+  keep out of the tree cannot be previewed or downloaded.
+- **Previewing a file publishes it at an app URL** for as long as the preview is on
+  screen, and downloading publishes it briefly. Those URLs are unguessable in
+  practice but carry no authentication of their own — whatever middleware protects
+  your NiceGUI app protects them too, and nothing else does. If your app is public,
+  so is anything in `root`.
+- **`.svg` and `.html` are deliberately shown as source.** Both are served from your
+  app's own origin, so rendering them would run any script they carry with your
+  app's cookies in scope.
+
+## License
+
+MIT

nicegui_treebrowser-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+nicegui_treebrowser/__init__.py,sha256=wuZiiwPdE6kVavS0f44kCctznp0jPUDVPYihiG-aVjU,188
+nicegui_treebrowser/browser.py,sha256=a8pQobbuJQfksTjd7pveNn6exo-8Fl3PA-9M2cqDkhQ,19199
+nicegui_treebrowser/filetypes.py,sha256=TpHqS5eamJp1ecj944UxeWje3DlrSablbCTQwnFSgis,4120
+nicegui_treebrowser/fsutil.py,sha256=3cb_R4ReCl9sWwojrSu0nfHaWkT4YYV5thh7S0yf5fs,2742
+nicegui_treebrowser/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nicegui_treebrowser-0.1.0.dist-info/METADATA,sha256=yDoiXpQSldRR9kiU3lcvODZahPGV_VFWz9XU7pjQWxY,5601
+nicegui_treebrowser-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+nicegui_treebrowser-0.1.0.dist-info/licenses/LICENSE,sha256=FPJHfx2Udw2EdaFL9mbB4qtLwjfwYoqeb4Ox7BlBX3k,1069
+nicegui_treebrowser-0.1.0.dist-info/RECORD,,

nicegui_treebrowser-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

nicegui_treebrowser-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Owen Solberg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.