textual-universal-directorytree

DirectoryTree widget for textual, compatible with all filesystems

Installation

pip install textual-universal-directorytree

Extra Dependencies

Some filesystems require additional dependencies to be installed. The remote extra includes all the known optional dependencies. See the Filesystems Supported section for more information.

pip install "textual-universal-directorytree[remote]"

Usage

The below example shows how to use textual-universal-directorytree in a Textual app. It uses the GitHub filesystem to display the contents of the textual GitHub repository. It requires the requests library to be installed (or the remote extra).

from __future__ import annotations

from typing import Any, ClassVar

from rich.syntax import Syntax
from textual import on
from textual.app import App, ComposeResult
from textual.binding import BindingType
from textual.containers import Horizontal, VerticalScroll
from textual.widgets import DirectoryTree, Footer, Header, Static

from textual_universal_directorytree import UniversalDirectoryTree, UPath


class UniversalDirectoryTreeApp(App):
    """
    The power of upath and fsspec in a Textual app
    """

    TITLE = "UniversalDirectoryTree"

    CSS = """
    UniversalDirectoryTree {
        max-width: 50%;
        width: auto;
        height: 100%;
        dock: left;
    }
    """

    BINDINGS: ClassVar[list[BindingType]] = [
        ("q", "quit", "Quit"),
    ]

    def __init__(self, path: str | UPath, *args: Any, **kwargs: Any):
        super().__init__(*args, **kwargs)
        self.universal_path = UPath(path).resolve()
        self.directory_tree = UniversalDirectoryTree(path=self.universal_path)
        self.file_content = Static(expand=True)

    def compose(self) -> ComposeResult:
        yield Header()
        yield Horizontal(self.directory_tree, VerticalScroll(self.file_content))
        yield Footer()

    @on(DirectoryTree.FileSelected)
    def handle_file_selected(self, message: DirectoryTree.FileSelected) -> None:
        """
        Do something with the selected file.

        Objects returned by the FileSelected event are upath.UPath objects and
        they are compatible with the familiar pathlib.Path API built into Python.
        """
        self.sub_title = str(message.path)
        try:
            file_content = message.path.read_text()
        except UnicodeDecodeError:
            self.file_content.update("")
            return None
        lexer = Syntax.guess_lexer(path=message.path.name, code=file_content)
        code = Syntax(code=file_content, lexer=lexer)
        self.file_content.update(code)

Run the above app in your terminal:

python -m textual_universal_directorytree github://juftin:textual-universal-directorytree@main/

Filesystems Supported

textual-universal-directorytree leverages fsspec and universal_pathlib to enable compatibility with local and remote filesystems.

In some cases you need to install a filesystem-specific library to enable compatibility with that filesystem. For example, to enable compatibility with AWS S3 you must install s3fs which is an fsspec implementation for S3.

The following filesystems are known to be supported by textual-universal-directorytree, but it's possible that others filesystems are supported as well and just haven't been tested. If you find a filesystem that works, please open an issue.

File System	Format	Optional Dependencies
Local	path/to/file	None
Local	file://path/to/file	None
AWS S3	s3://bucket/path	s3fs
AWS S3	s3a://bucket/path	s3fs
Google GCS	gs://bucket/path	gcsfs
Azure Data Lake	adl://bucket/path	adlfs
Azure Blob	abfs://bucket/path	adlfs
Azure Blob	az://bucket/path	adlfs
GitHub	github://owner:repo@branch	requests
GitHub	github://owner:repo@branch/path	requests
SSH	ssh://user@host:port/path	paramiko
SFTP	sftp://user@host:port/path	paramiko

License

textual-universal-directorytree is distributed under the terms of the MIT license.