streamlit-file-explorer 0.1.0__py3-none-any.whl

streamlit_file_explorer/__init__.py

@@ -0,0 +1,12 @@
+"""Finder-style file browsing for local and cluster Streamlit applications."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .component import file_explorer
+from .models import ExplorerResult, SelectionMode
+
+__all__ = ["ExplorerResult", "SelectionMode", "file_explorer"]
+try:
+    __version__ = version("streamlit-file-explorer")
+except PackageNotFoundError:
+    __version__ = "0+uninstalled"

streamlit_file_explorer/component.py

@@ -0,0 +1,145 @@
+"""Thin Streamlit adapter around the independently testable filesystem controller."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+import streamlit as st
+
+from .controller import ExplorerController
+from .filesystem import LocalFilesystem
+from .models import ExplorerResult, SelectionMode
+
+
+@lru_cache(maxsize=1)
+def _get_component() -> Callable[..., Any]:
+    # Register once, on first render, so importing the public API also works in
+    # scripts and tests that do not have a Streamlit runtime.
+    return st.components.v2.component(
+        "streamlit-file-explorer.streamlit_file_explorer",
+        js="index-*.js",
+        css="*.css",
+        html='<div class="react-root"></div>',
+        isolate_styles=True,
+    )
+
+
+def file_explorer(
+    roots: Mapping[str, str | Path],
+    *,
+    key: str,
+    label: str = "Files",
+    environment_label: str = "",
+    selection_mode: SelectionMode = "file",
+    multiple: bool = False,
+    extensions: Sequence[str] | None = None,
+    show_hidden: bool = False,
+    preview: bool = True,
+    height: int = 420,
+    page_size: int = 100,
+    max_entries: int = 10_000,
+    max_preview_bytes: int = 262_144,
+    cache_ttl: float = 2.0,
+) -> ExplorerResult:
+    """Browse explicitly configured server-side filesystem roots.
+
+    roots maps visible location names to directories. The app's OS identity
+    determines access locally and on a cluster. This component performs no writes,
+    never follows child symlinks, and requires no second HTTP server.
+
+    key must be unique and stable. Every instance and browser session has its
+    own navigation and cache. Changing filesystem/selection settings resets that
+    instance. height is the scrollable file-list height (240–500 pixels).
+
+    selection_mode accepts 'file', 'directory', or 'any'. multiple permits
+    selection within the current folder. extensions accepts suffixes such as
+    ['.csv', '.tar.gz']; folders remain visible for navigation. Hidden-file
+    visibility and extension filters are UI controls, not authorization policies.
+
+    max_entries bounds scanned entries per folder. If hit, the UI explicitly
+    reports that sorting/search apply to a partial listing. max_preview_bytes
+    bounds reads; text/table rendering has additional row/character limits.
+
+    Returns an immutable ExplorerResult. confirmed is true for one run only
+    when the user presses Use. Highlighted items are available in selection.
+    Place this call and its result handling inside st.fragment to isolate reruns.
+    """
+    if not isinstance(key, str) or not key:
+        raise ValueError("key must be a nonempty string")
+    if selection_mode not in ("file", "directory", "any"):
+        raise ValueError("selection_mode must be 'file', 'directory', or 'any'")
+    for name, flag in [("multiple", multiple), ("show_hidden", show_hidden), ("preview", preview)]:
+        if type(flag) is not bool:
+            raise ValueError(f"{name} must be a boolean")
+    if not isinstance(label, str) or not isinstance(environment_label, str):
+        raise ValueError("label and environment_label must be strings")
+    for name, value, low, high in [
+        ("height", height, 240, 500),
+        ("page_size", page_size, 1, 500),
+        ("max_preview_bytes", max_preview_bytes, 1024, 2_097_152),
+    ]:
+        if type(value) is not int or not low <= value <= high:
+            raise ValueError(f"{name} must be an integer between {low} and {high}")
+    if type(cache_ttl) not in (int, float) or not 0 <= cache_ttl <= 60:
+        raise ValueError("cache_ttl must be between 0 and 60 seconds")
+    if extensions is not None and (
+        not isinstance(extensions, Sequence)
+        or isinstance(extensions, str)
+        or any(not isinstance(s, str) for s in extensions)
+    ):
+        raise ValueError("extensions must be a sequence of string suffixes")
+    suffixes = tuple(
+        sorted({s.lower() if s.startswith(".") else "." + s.lower() for s in extensions or ()})
+    )
+    if any(s == "." or "/" in s or "\\" in s for s in suffixes):
+        raise ValueError("extensions must contain valid filename suffixes")
+    fs = LocalFilesystem(roots, max_entries=max_entries)
+    config = (
+        tuple(fs.roots.items()),
+        selection_mode,
+        multiple,
+        suffixes,
+        show_hidden,
+        preview,
+        page_size,
+        max_entries,
+        max_preview_bytes,
+        cache_ttl,
+    )
+    state_key = f"_file_explorer:{key}"
+    pending_key = f"{state_key}:pending"
+    previous = st.session_state.get(state_key)
+    controller: ExplorerController
+    if previous is None or previous[0] != config:
+        controller = ExplorerController(
+            fs,
+            selection_mode=selection_mode,
+            multiple=multiple,
+            extensions=suffixes,
+            show_hidden=show_hidden,
+            preview=preview,
+            page_size=page_size,
+            max_preview_bytes=max_preview_bytes,
+            cache_ttl=cache_ttl,
+        )
+        st.session_state[state_key] = (config, controller)
+        st.session_state.pop(pending_key, None)
+    else:
+        controller = previous[1]
+    controller.apply(st.session_state.pop(pending_key, None))
+
+    def receive_action() -> None:
+        widget: Any = st.session_state.get(key, {})
+        st.session_state[pending_key] = widget.get("action")
+
+    _get_component()(
+        key=key,
+        data=controller.payload(label=label, environment=environment_label, height=height),
+        on_action_change=receive_action,
+        width="stretch",
+        height="content",
+    )
+    return controller.result()

streamlit_file_explorer/controller.py

@@ -0,0 +1,232 @@
+"""Per-instance navigation state and validated frontend actions."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import asdict
+from pathlib import PurePosixPath
+from typing import Any
+
+from .filesystem import LocalFilesystem, relative_path
+from .models import Entry, ExplorerError, ExplorerResult, Listing, SelectionMode, SortBy
+
+
+class ExplorerController:
+    """One controller per Streamlit session and component key. No global cache."""
+
+    def __init__(
+        self,
+        fs: LocalFilesystem,
+        *,
+        selection_mode: SelectionMode,
+        multiple: bool,
+        extensions: tuple[str, ...],
+        show_hidden: bool,
+        preview: bool,
+        page_size: int,
+        max_preview_bytes: int,
+        cache_ttl: float,
+    ) -> None:
+        self.fs = fs
+        self.instance_id = str(uuid.uuid4())
+        self.selection_mode = selection_mode
+        self.multiple = multiple
+        self.extensions = extensions
+        self.root = next(iter(fs.roots))
+        self.path = ""
+        self.selected: list[str] = []
+        self.query = ""
+        self.sort: SortBy = "name"
+        self.descending = False
+        self.page = 0
+        self.show_hidden = show_hidden
+        self.show_preview = preview
+        self.page_size = page_size
+        self.max_preview_bytes = max_preview_bytes
+        self.cache_ttl = cache_ttl
+        self.error: str | None = None
+        self.confirmed = False
+        self.ack = ""
+        self.revision = 0
+        self._listing: tuple[tuple[str, str, bool], float, Listing] | None = None
+
+    def apply(self, event: Any) -> None:
+        self.confirmed = False
+        if not isinstance(event, dict):
+            return
+        action_id = event.get("id")
+        if not isinstance(action_id, str) or not action_id or len(action_id) > 128:
+            self.error = "Invalid explorer action. Refresh the folder."
+            return
+        if action_id == self.ack:
+            return
+        self.ack = action_id
+        self.revision += 1
+        self.error = None
+        try:
+            # Reject delayed actions from a folder that has already been left.
+            if event.get("context") != {"root": self.root, "path": self.path}:
+                return
+            action = event.get("type")
+            if action == "navigate":
+                target_root = event.get("root")
+                if not isinstance(target_root, str):
+                    raise ExplorerError("Invalid location.")
+                target_path = relative_path(event.get("path"))
+                if self.fs.inspect(target_root, target_path).kind != "directory":
+                    raise ExplorerError("This item is not a folder.")
+                self.root, self.path = target_root, target_path
+                self.selected, self.query, self.page = [], "", 0
+                self._listing = None
+            elif action == "select":
+                self.selected = self._validate_selection(event.get("paths"), confirming=False)
+            elif action == "confirm":
+                selection = self._validate_selection(event.get("paths"), confirming=True)
+                if not selection:
+                    raise ExplorerError("Select an item first.")
+                self.selected, self.confirmed = selection, True
+            elif action == "search":
+                query = event.get("query")
+                if not isinstance(query, str) or len(query) > 1000:
+                    raise ExplorerError("Search must be at most 1,000 characters.")
+                self.query, self.page = query, 0
+            elif action == "sort":
+                sort = event.get("sort")
+                descending = event.get("descending")
+                if sort not in ("name", "size", "modified", "type") or type(descending) is not bool:
+                    raise ExplorerError("Invalid sort option.")
+                self.sort, self.descending, self.page = sort, descending, 0
+            elif action == "page":
+                page = event.get("page")
+                if type(page) is not int or not 0 <= page <= self.fs.max_entries:
+                    raise ExplorerError("Invalid page.")
+                self.page = page
+            elif action == "hidden":
+                self.show_hidden = not self.show_hidden
+                self.page = 0
+                self._listing = None
+            elif action == "preview":
+                self.show_preview = not self.show_preview
+            elif action == "refresh":
+                self._listing = None
+            else:
+                raise ExplorerError("Unknown explorer action.")
+        except ExplorerError as exc:
+            self.error = str(exc)
+
+    def _validate_selection(self, paths: Any, *, confirming: bool) -> list[str]:
+        if not isinstance(paths, list) or len(paths) > (1000 if self.multiple else 1):
+            raise ExplorerError("Invalid selection.")
+        validated: list[str] = []
+        for value in paths:
+            path = relative_path(value)
+            parent = str(PurePosixPath(path).parent)
+            parent = "" if parent == "." else parent
+            if path != self.path and parent != self.path:
+                raise ExplorerError("Select items from the current folder.")
+            entry = self.fs.inspect(self.root, path)
+            if (
+                entry.kind == "file"
+                and self.extensions
+                and not path.lower().endswith(self.extensions)
+            ):
+                raise ExplorerError("This file type is not allowed by the app.")
+            if confirming and not self.can_select(entry):
+                raise ExplorerError(f"Choose a {self.selection_mode} for this picker.")
+            if path not in validated:
+                validated.append(path)
+        return validated
+
+    def can_select(self, entry: Entry) -> bool:
+        return self.selection_mode == "any" or entry.kind == self.selection_mode
+
+    def _read_listing(self) -> Listing:
+        key = (self.root, self.path, self.show_hidden)
+        now = time.monotonic()
+        if self._listing and self._listing[0] == key and now - self._listing[1] < self.cache_ttl:
+            return self._listing[2]
+        listing = self.fs.list_directory(self.root, self.path, show_hidden=self.show_hidden)
+        self._listing = (key, now, listing)
+        return listing
+
+    def payload(self, *, label: str, environment: str, height: int) -> dict[str, Any]:
+        listing = Listing(())
+        selected_entries = []
+        preview: dict[str, Any] | None = None
+        try:
+            listing = self._read_listing()
+            # Revalidate references even when the listing came from cache.
+            for path in self.selected:
+                selected_entries.append(self.fs.inspect(self.root, path))
+        except ExplorerError as exc:
+            self.error = str(exc)
+            self.selected, selected_entries, self.confirmed = [], [], False
+        if self.show_preview and selected_entries:
+            try:
+                preview = self.fs.preview(
+                    self.root, selected_entries[-1].path, max_bytes=self.max_preview_bytes
+                )
+            except ExplorerError as exc:
+                preview = {"kind": "error", "message": str(exc)}
+        entries = [
+            e
+            for e in listing.entries
+            if (not self.extensions or e.kind != "file" or e.name.lower().endswith(self.extensions))
+            and self.query.casefold() in e.name.casefold()
+        ]
+
+        def sort_key(entry: Entry) -> tuple[Any, str]:
+            if self.sort == "size":
+                return (entry.size or 0), entry.name.casefold()
+            if self.sort == "modified":
+                return (entry.modified or 0), entry.name.casefold()
+            if self.sort == "type":
+                return PurePosixPath(entry.name).suffix.casefold(), entry.name.casefold()
+            return entry.name.casefold(), entry.name
+
+        entries.sort(key=sort_key, reverse=self.descending)
+        entries.sort(key=lambda entry: entry.kind != "directory")
+        pages = max(1, (len(entries) + self.page_size - 1) // self.page_size)
+        self.page = min(self.page, pages - 1)
+        start = self.page * self.page_size
+        return {
+            "instance_id": self.instance_id,
+            "label": label,
+            "environment": environment,
+            "height": height,
+            "locations": [{"id": name, "label": name} for name in self.fs.roots],
+            "root": self.root,
+            "path": self.path,
+            "display_path": str(self.fs.path(self.root, self.path)),
+            "entries": [asdict(entry) for entry in entries[start : start + self.page_size]],
+            "total": len(entries),
+            "page": self.page,
+            "pages": pages,
+            "page_size": self.page_size,
+            "truncated": listing.truncated,
+            "max_entries": self.fs.max_entries,
+            "selected": self.selected,
+            "selected_entries": [asdict(entry) for entry in selected_entries],
+            "query": self.query,
+            "sort": self.sort,
+            "descending": self.descending,
+            "show_hidden": self.show_hidden,
+            "show_preview": self.show_preview,
+            "preview": preview,
+            "multiple": self.multiple,
+            "selection_mode": self.selection_mode,
+            "can_confirm": bool(selected_entries)
+            and all(self.can_select(e) for e in selected_entries),
+            "error": self.error,
+            "ack": self.ack,
+            "revision": self.revision,
+        }
+
+    def result(self) -> ExplorerResult:
+        return ExplorerResult(
+            directory=self.fs.path(self.root, self.path),
+            selection=tuple(self.fs.path(self.root, path) for path in self.selected),
+            confirmed=self.confirmed,
+            error=self.error,
+        )

streamlit_file_explorer/filesystem.py

@@ -0,0 +1,235 @@
+"""Bounded, read-only filesystem access without recursive traversal or shared caches."""
+
+from __future__ import annotations
+
+import base64
+import codecs
+import csv
+import errno
+import io
+import os
+import stat
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from pathlib import Path, PurePosixPath, PureWindowsPath
+from typing import Any
+
+from .models import Entry, ExplorerError, Listing
+
+
+def relative_path(value: object) -> str:
+    """Validate the platform-independent path format used by the frontend."""
+    if not isinstance(value, str) or len(value) > 4096 or "\x00" in value:
+        raise ExplorerError("Invalid path.")
+    path = PurePosixPath(value)
+    if path.is_absolute() or ".." in path.parts or "\\" in value or PureWindowsPath(value).drive:
+        raise ExplorerError("Choose a path inside a configured location.")
+    return "" if str(path) == "." else path.as_posix()
+
+
+def friendly_error(exc: OSError) -> str:
+    if exc.errno in {errno.EACCES, errno.EPERM}:
+        return "Permission denied. The app's account cannot access this item."
+    if exc.errno == errno.ENOENT:
+        return "This item is no longer available. Refresh the folder."
+    if exc.errno in {errno.ELOOP, errno.ENOTDIR}:
+        return "This path is a symbolic link or is no longer a folder."
+    return "The filesystem could not read this item. Try refreshing the folder."
+
+
+class LocalFilesystem:
+    """Access explicit filesystem roots using the Streamlit process's OS identity.
+
+    Symbolic links below a root are never followed. On POSIX, reads walk directory
+    descriptors with O_NOFOLLOW, so replacing a child with a symlink cannot redirect
+    the read. Roots and their ancestors must be controlled by the deploying app.
+    """
+
+    def __init__(self, roots: Mapping[str, str | Path], *, max_entries: int = 10_000):
+        if (
+            not isinstance(roots, Mapping)
+            or not roots
+            or any(not isinstance(label, str) or not label.strip() for label in roots)
+        ):
+            raise ValueError("roots must contain at least one nonempty location label")
+        if type(max_entries) is not int or not 1 <= max_entries <= 100_000:
+            raise ValueError("max_entries must be between 1 and 100,000")
+        if any(not isinstance(path, (str, Path)) for path in roots.values()):
+            raise ValueError("root paths must be strings or pathlib.Path objects")
+        self.roots = {label: Path(path).expanduser().resolve() for label, path in roots.items()}
+        self.max_entries = max_entries
+
+    def path(self, root: str, relative: object) -> Path:
+        if root not in self.roots:
+            raise ExplorerError("Unknown filesystem location.")
+        return self.roots[root] / relative_path(relative)
+
+    @contextmanager
+    def _open(self, root: str, relative: object, *, directory: bool = False) -> Iterator[int]:
+        rel = relative_path(relative)
+        path = self.path(root, rel)
+        descriptors: list[int] = []
+        try:
+            if os.open in os.supports_dir_fd and hasattr(os, "O_NOFOLLOW"):
+                flags = os.O_RDONLY | os.O_NOFOLLOW | getattr(os, "O_NONBLOCK", 0)
+                fd = os.open(self.roots[root], flags | os.O_DIRECTORY)
+                descriptors.append(fd)
+                parts = PurePosixPath(rel).parts
+                for index, part in enumerate(parts):
+                    child_flags = flags
+                    if index < len(parts) - 1 or directory:
+                        child_flags |= os.O_DIRECTORY
+                    fd = os.open(part, child_flags, dir_fd=fd)
+                    descriptors.append(fd)
+            else:
+                # Portable fallback. OS permissions remain the security boundary;
+                # concurrent path replacement is not defended on this platform.
+                current = self.roots[root]
+                for part in PurePosixPath(rel).parts:
+                    current /= part
+                    if current.is_symlink():
+                        raise ExplorerError("Symbolic links are not followed.")
+                fd = os.open(path, os.O_RDONLY | getattr(os, "O_BINARY", 0))
+                descriptors.append(fd)
+            mode = os.fstat(fd).st_mode
+            if directory and not stat.S_ISDIR(mode):
+                raise ExplorerError("This item is not a folder.")
+            if not directory and not (stat.S_ISREG(mode) or stat.S_ISDIR(mode)):
+                raise ExplorerError("Only regular files and folders can be selected.")
+            yield fd
+        except OSError as exc:
+            raise ExplorerError(friendly_error(exc)) from exc
+        finally:
+            for descriptor in reversed(descriptors):
+                os.close(descriptor)
+
+    def inspect(self, root: str, relative: object) -> Entry:
+        rel = relative_path(relative)
+        with self._open(root, rel) as fd:
+            info = os.fstat(fd)
+        return Entry(
+            name=PurePosixPath(rel).name or root,
+            path=rel,
+            kind="directory" if stat.S_ISDIR(info.st_mode) else "file",
+            size=info.st_size if stat.S_ISREG(info.st_mode) else None,
+            modified=info.st_mtime,
+        )
+
+    def list_directory(self, root: str, relative: object, *, show_hidden: bool) -> Listing:
+        rel = relative_path(relative)
+        entries: list[Entry] = []
+        truncated = False
+        with self._open(root, rel, directory=True) as fd:
+            source: int | Path = fd if os.scandir in os.supports_fd else self.path(root, rel)
+            with os.scandir(source) as items:
+                for index, item in enumerate(items):
+                    if index >= self.max_entries:
+                        truncated = True
+                        break
+                    if not show_hidden and item.name.startswith("."):
+                        continue
+                    child = f"{rel}/{item.name}" if rel else item.name
+                    try:
+                        relative_path(child)
+                        # Undecodable Unix filenames cannot be transported by JSON.
+                        item.name.encode("utf-8")
+                        info = item.stat(follow_symlinks=False)
+                        mode = info.st_mode
+                        kind: Any = (
+                            "symlink"
+                            if stat.S_ISLNK(mode)
+                            else "directory"
+                            if stat.S_ISDIR(mode)
+                            else "file"
+                            if stat.S_ISREG(mode)
+                            else "other"
+                        )
+                        error = None
+                        if kind == "symlink":
+                            error = "Symbolic links are not followed."
+                        elif kind == "other":
+                            error = "Special filesystem entries cannot be opened."
+                        entries.append(
+                            Entry(
+                                item.name,
+                                child,
+                                kind,
+                                info.st_size if kind == "file" else None,
+                                info.st_mtime,
+                                error,
+                            )
+                        )
+                    except (OSError, ExplorerError, UnicodeError):
+                        # Include an unavailable row without leaking invalid Unicode.
+                        safe_name = item.name.encode("utf-8", errors="replace").decode()
+                        entries.append(
+                            Entry(
+                                safe_name,
+                                "",
+                                "unavailable",
+                                None,
+                                None,
+                                "This entry is unavailable or has an unsupported name.",
+                            )
+                        )
+        return Listing(tuple(entries), truncated)
+
+    def preview(self, root: str, relative: str, *, max_bytes: int) -> dict[str, Any]:
+        """Never deserialize documents, execute markup, or read an unbounded file."""
+        with self._open(root, relative) as fd:
+            info = os.fstat(fd)
+            if stat.S_ISDIR(info.st_mode):
+                return {"kind": "directory", "message": "Open this folder to browse its contents."}
+            # read() is bounded even if a file grows after fstat().
+            with os.fdopen(os.dup(fd), "rb") as stream:
+                raw = stream.read(max_bytes + 1)
+        truncated = len(raw) > max_bytes
+        raw = raw[:max_bytes]
+        image_type = _image_type(raw)
+        if image_type:
+            if truncated:
+                return {"kind": "metadata", "message": "Image exceeds the preview size limit."}
+            return {
+                "kind": "image",
+                "src": f"data:{image_type};base64," + base64.b64encode(raw).decode("ascii"),
+            }
+        if b"\x00" in raw:
+            return {"kind": "metadata", "message": "Preview is unavailable for this binary file."}
+        try:
+            text = codecs.getincrementaldecoder("utf-8-sig")().decode(raw, final=not truncated)
+        except UnicodeError:
+            return {"kind": "metadata", "message": "Preview supports UTF-8 text and small images."}
+        suffix = PurePosixPath(relative).suffix.lower()
+        if suffix in {".csv", ".tsv"}:
+            try:
+                rows = []
+                for index, row in enumerate(
+                    csv.reader(io.StringIO(text), delimiter="\t" if suffix == ".tsv" else ",")
+                ):
+                    if index == 51:
+                        truncated = True
+                        break
+                    truncated |= len(row) > 20 or any(len(cell) > 300 for cell in row)
+                    rows.append([cell[:300] for cell in row[:20]])
+                return {"kind": "table", "rows": rows, "truncated": truncated}
+            except csv.Error:
+                pass
+        lines = text.splitlines()
+        clipped = "\n".join(lines[:200])[:20_000]
+        return {
+            "kind": "text",
+            "text": clipped,
+            "truncated": truncated or len(lines) > 200 or len(text) > 20_000,
+        }
+
+
+def _image_type(raw: bytes) -> str | None:
+    if raw.startswith(b"\x89PNG\r\n\x1a\n"):
+        return "image/png"
+    if raw.startswith(b"\xff\xd8\xff"):
+        return "image/jpeg"
+    if raw[:6] in {b"GIF87a", b"GIF89a"}:
+        return "image/gif"
+    if raw.startswith(b"RIFF") and raw[8:12] == b"WEBP":
+        return "image/webp"
+    return None