nicegui-treebrowser 0.1.0__tar.gz

nicegui_treebrowser-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          enable-cache: true
+      - name: Check tag matches project version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version="$(uv version --short)"
+          if [ "$tag" != "$version" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match project version $version" >&2
+            exit 1
+          fi
+      - run: uv build
+      - uses: actions/upload-artifact@v5
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v6
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

nicegui_treebrowser-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,37 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked
+      - run: uv run pytest
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy src tests

nicegui_treebrowser-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store

nicegui_treebrowser-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

nicegui_treebrowser-0.1.0/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.

nicegui_treebrowser-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,120 @@
+# 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/examples/.gitignore

@@ -0,0 +1 @@
+sample/

nicegui_treebrowser-0.1.0/examples/demo.py

@@ -0,0 +1,82 @@
+"""Run the browser against a generated sample directory.
+
+    uv run python examples/demo.py          # strict allowlist (the default)
+    uv run python examples/demo.py --sniff  # also preview unrecognised text files
+
+Then open http://localhost:8080.
+"""
+
+from __future__ import annotations
+
+import base64
+import sys
+from pathlib import Path
+
+from nicegui import ui
+
+from nicegui_treebrowser import TreeBrowser
+
+SAMPLE = Path(__file__).parent / "sample"
+
+PNG = base64.b64decode(
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAE"
+    "hQGAhKmMIQAAAABJRU5ErkJggg=="
+)
+
+PDF = b"""%PDF-1.4
+1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj
+2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj
+3 0 obj<</Type/Page/Parent 2 0 R/MediaBox[0 0 200 200]>>endobj
+trailer<</Root 1 0 R>>
+%%EOF
+"""
+
+
+def build_sample() -> None:
+    """Create a directory with one file of most previewable kinds."""
+    (SAMPLE / "reports").mkdir(parents=True, exist_ok=True)
+    (SAMPLE / "empty").mkdir(exist_ok=True)
+
+    (SAMPLE / "README.md").write_text(
+        "# Sample tree\n\nPick something on the left.\n\n- images\n- PDFs\n- tables\n"
+    )
+    (SAMPLE / "settings.yaml").write_text("debug: true\nthreads: 4\n")
+    (SAMPLE / "analysis.py").write_text(
+        "from pathlib import Path\n\n\ndef main() -> None:\n"
+        '    print(sorted(Path(".").glob("*")))\n'
+    )
+    (SAMPLE / "results.csv").write_text(
+        "sample,score,note\n"
+        + "".join(f"S{i:03d},{i * 7 % 100},row {i}\n" for i in range(200))
+    )
+    (SAMPLE / "matrix.tsv").write_text("gene\tcount\nTP53\t120\nBRCA1\t44\n")
+    (SAMPLE / "logo.svg").write_text(
+        '<svg xmlns="http://www.w3.org/2000/svg" width="80" height="80">'
+        '<circle cx="40" cy="40" r="36" fill="teal"/></svg>\n'
+    )
+    (SAMPLE / "Dockerfile").write_text(
+        "FROM python:3.14-slim\nRUN pip install nicegui\n"
+    )
+    (SAMPLE / "changelog").write_text("0.1.0 - first cut, no suffix on this file\n")
+    (SAMPLE / "pixel.png").write_bytes(PNG)
+    (SAMPLE / "reports" / "summary.pdf").write_bytes(PDF)
+    (SAMPLE / "reports" / "run.log").write_text("started\nworking\nfinished\n")
+    (SAMPLE / "opaque.bin").write_bytes(bytes(range(256)) * 8)
+
+
+def main() -> None:
+    build_sample()
+    sniff = "--sniff" in sys.argv
+
+    @ui.page("/")
+    def index() -> None:
+        ui.label("nicegui-treebrowser demo").classes("text-2xl font-medium px-6 pt-6")
+        ui.label(f"sniff_text={sniff} — restart with --sniff to flip it").classes(
+            "text-sm text-gray-500 px-6"
+        )
+        TreeBrowser(SAMPLE, title="Sample tree", focus="README.md", sniff_text=sniff)
+
+    ui.run(title="TreeBrowser demo", reload=False)
+
+
+main()

nicegui_treebrowser-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nicegui-treebrowser"
+version = "0.1.0"
+description = "A NiceGUI element that browses, previews and downloads a server-side directory tree"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.13"
+authors = [{ name = "Owen Solberg", email = "owen.solberg@gmail.com" }]
+keywords = ["nicegui", "file-browser", "directory-tree", "widget", "gui"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: User Interfaces",
+    "Typing :: Typed",
+]
+# NiceGUI before 3.0.4 pulls in a vbuild that calls pkgutil.find_loader,
+# removed in Python 3.14, so those releases cannot even be imported there.
+dependencies = [
+    "nicegui>=2.14; python_version < '3.14'",
+    "nicegui>=3.0.4; python_version >= '3.14'",
+]
+
+[project.urls]
+Homepage = "https://github.com/odoublewen/nicegui-treebrowser"
+Issues = "https://github.com/odoublewen/nicegui-treebrowser/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "types-pygments>=2.21.0.20260819",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nicegui_treebrowser"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+# Empty on purpose: NiceGUI 3.x's `user` fixture otherwise runpy's a main.py.
+# With no main file, pages declared with @ui.page inside a test module are used.
+main_file = ""
+
+[tool.ruff]
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "C4", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+warn_unused_ignores = false

nicegui_treebrowser-0.1.0/src/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"