ncview 0.1.0__tar.gz

ncview-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.claude/

ncview-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: ncview
+Version: 0.1.0
+Summary: Terminal file browser with vim keybindings
+Requires-Python: >=3.12
+Requires-Dist: polars>=1.0.0
+Requires-Dist: pyarrow>=14.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: textual>=0.85.0
+Provides-Extra: dev
+Requires-Dist: textual-dev>=1.0.0; extra == 'dev'

ncview-0.1.0/README.md

@@ -0,0 +1,84 @@
+# ncview
+
+Terminal file browser with vim keybindings, inspired by [ncdu](https://dev.yorhel.nl/ncdu). Built with [Textual](https://textual.textualize.io/), [Polars](https://pola.rs/), and [PyArrow](https://arrow.apache.org/docs/python/).
+
+![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)
+
+## Features
+
+- **Vim-style navigation** — `j`/`k`/`h`/`l`, arrow keys, and more
+- **Parquet viewer** — schema, scrollable data table (first 1K rows), and statistics via Polars. Handles 50GB+ files efficiently using PyArrow metadata reads (O(1), no full scan)
+- **JSON viewer** — collapsible/expandable tree with color-coded values
+- **Text viewer** — syntax highlighting for 50+ languages via Rich
+- **Fallback viewer** — file metadata for unknown/binary types
+
+## Install
+
+```bash
+# Clone and install
+git clone git@github.com:dannyfriar/ncview.git
+cd ncview
+uv venv --python 3.12
+uv pip install -e .
+```
+
+## Usage
+
+```bash
+ncview              # browse current directory
+ncview /some/path   # browse a specific directory
+ncview --help       # show usage
+```
+
+## Keybindings
+
+### File browser
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` / `↑` / `↓` | Move cursor up/down |
+| `l` / `Enter` / `→` | Enter directory or open file preview |
+| `h` / `Backspace` / `←` | Go to parent directory |
+| `g` / `G` | Jump to top/bottom |
+| `.` | Toggle hidden files |
+| `s` | Cycle sort (name → size → modified) |
+| `/` | Search in current directory |
+| `e` | Open file in `$EDITOR` (default: `vim`) |
+| `q` / `Ctrl+C` | Quit |
+
+### Preview (all file types)
+
+| Key | Action |
+|-----|--------|
+| `h` / `Backspace` / `←` / `Escape` | Close preview, return to browser |
+| `j` / `k` | Scroll up/down |
+| `Ctrl+D` / `Ctrl+U` | Page down/up |
+| `q` / `Ctrl+C` | Quit |
+
+### Parquet viewer
+
+| Key | Action |
+|-----|--------|
+| `1` | Data tab (default) |
+| `2` | Schema tab |
+| `3` | Stats tab (computed on first visit) |
+| `↑` / `↓` | Scroll through rows in data table |
+
+### JSON viewer
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` | Move cursor through visible nodes |
+| `l` | Expand node (or move to first child if already expanded) |
+| `h` | Collapse node (or move to parent if leaf/already collapsed) |
+| `Space` / `Enter` | Toggle expand/collapse |
+| `g` / `G` | Jump to top/bottom |
+
+## Test data
+
+The `test_data/` directory contains sample files for testing:
+
+- `users.parquet` — 500 rows, 7 columns
+- `sales.parquet` — 2,000 rows, 7 columns (with nulls)
+- `numeric_series.parquet` — 5,000 rows, 6 columns
+- `sample.json` — nested JSON with arrays and objects

ncview-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ncview"
+version = "0.1.0"
+description = "Terminal file browser with vim keybindings"
+requires-python = ">=3.12"
+dependencies = [
+    "textual>=0.85.0",
+    "polars>=1.0.0",
+    "pyarrow>=14.0.0",
+    "rich>=13.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "textual-dev>=1.0.0",
+]
+
+[project.scripts]
+ncview = "ncview.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ncview"]

ncview-0.1.0/src/ncview/__init__.py

@@ -0,0 +1 @@
+"""ncview — Terminal file browser with vim keybindings."""

ncview-0.1.0/src/ncview/__main__.py

@@ -0,0 +1,11 @@
+"""Entry point for `python -m ncview`."""
+
+from ncview.app import run
+
+
+def main() -> None:
+    run()
+
+
+if __name__ == "__main__":
+    main()

ncview-0.1.0/src/ncview/app.py

@@ -0,0 +1,177 @@
+"""Main Textual application for ncview."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from textual import on
+from textual.app import App, ComposeResult
+from textual.containers import VerticalScroll
+from textual.widgets import Footer, Header
+
+from ncview.utils.file_types import registry
+from ncview.viewers.fallback_viewer import FallbackViewer
+from ncview.viewers.json_viewer import JsonViewer
+from ncview.viewers.parquet_viewer import ParquetViewer
+from ncview.viewers.text_viewer import TextViewer
+from ncview.widgets.file_browser import DirectoryChanged, FileBrowser, FileSelected
+from ncview.widgets.path_bar import PathBar
+from ncview.widgets.preview_panel import PreviewPanel
+
+# Register viewers
+registry.register(TextViewer)
+registry.register(ParquetViewer)
+registry.register(JsonViewer)
+registry.register(FallbackViewer)
+
+
+class NcviewApp(App):
+    """Terminal file browser with vim keybindings."""
+
+    TITLE = "ncview"
+    CSS_PATH = "ncview.tcss"
+
+    BINDINGS = [
+        ("q", "quit", "Quit"),
+        ("ctrl+c", "quit", "Quit"),
+        ("escape", "close_preview", "Back"),
+        ("h", "close_preview_or_parent", "Back"),
+        ("backspace", "close_preview_or_parent", "Back"),
+        ("left", "close_preview_or_parent", "Back"),
+        ("j", "preview_scroll_down", "Down"),
+        ("k", "preview_scroll_up", "Up"),
+        ("ctrl+d", "preview_page_down", "Page down"),
+        ("ctrl+u", "preview_page_up", "Page up"),
+        ("1", "viewer_tab('1')", "Tab 1"),
+        ("2", "viewer_tab('2')", "Tab 2"),
+        ("3", "viewer_tab('3')", "Tab 3"),
+    ]
+
+    def __init__(self, start_path: Path | None = None, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._start_path = start_path or Path.cwd()
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield PathBar(self._start_path, id="path-bar")
+        yield FileBrowser(self._start_path, id="browser")
+        yield PreviewPanel(id="preview")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        browser = self.query_one("#browser", FileBrowser)
+        browser.border_title = "Files"
+        browser.focus()
+        preview = self.query_one("#preview", PreviewPanel)
+        preview.border_title = "Preview"
+
+    def _preview_is_open(self) -> bool:
+        return self.query_one("#preview", PreviewPanel).has_class("visible")
+
+    @on(FileSelected)
+    async def _on_file_selected(self, event: FileSelected) -> None:
+        """User pressed Enter/l on a file — show preview."""
+        if not event.path.is_file():
+            return
+        preview = self.query_one("#preview", PreviewPanel)
+        browser = self.query_one("#browser", FileBrowser)
+
+        await preview.show_file(event.path)
+
+        # Hide browser, show preview full-width
+        browser.styles.display = "none"
+        preview.add_class("visible")
+
+        # Auto-focus the interactive widget inside the viewer
+        from textual.widgets import DataTable
+        from ncview.viewers.json_viewer import JsonTree
+        try:
+            dt = preview.query_one(DataTable)
+            dt.focus()
+        except Exception:
+            try:
+                jt = preview.query_one(JsonTree)
+                jt.focus()
+            except Exception:
+                pass
+
+    async def _close_preview(self) -> None:
+        """Return from preview to browser."""
+        preview = self.query_one("#preview", PreviewPanel)
+        browser = self.query_one("#browser", FileBrowser)
+
+        await preview.clear()
+
+        preview.remove_class("visible")
+        browser.styles.display = "block"
+        browser.query_one("#file-list").focus()
+
+    async def action_close_preview(self) -> None:
+        if self._preview_is_open():
+            await self._close_preview()
+
+    async def action_close_preview_or_parent(self) -> None:
+        """h/backspace: close preview if open, otherwise go to parent dir."""
+        if self._preview_is_open():
+            await self._close_preview()
+        # If preview is not open, let the FileBrowser handle h/backspace itself
+
+    def action_preview_scroll_down(self) -> None:
+        if self._preview_is_open():
+            self.query_one("#preview-scroll", VerticalScroll).scroll_down()
+
+    def action_preview_scroll_up(self) -> None:
+        if self._preview_is_open():
+            self.query_one("#preview-scroll", VerticalScroll).scroll_up()
+
+    def action_preview_page_down(self) -> None:
+        if self._preview_is_open():
+            self.query_one("#preview-scroll", VerticalScroll).scroll_page_down()
+
+    def action_preview_page_up(self) -> None:
+        if self._preview_is_open():
+            self.query_one("#preview-scroll", VerticalScroll).scroll_page_up()
+
+    def action_viewer_tab(self, tab_num: str) -> None:
+        """Switch parquet viewer tabs with 1/2/3 keys."""
+        if not self._preview_is_open():
+            return
+        from ncview.viewers.parquet_viewer import ParquetViewer
+        from textual.widgets import TabbedContent, DataTable
+        try:
+            pv = self.query_one(ParquetViewer)
+        except Exception:
+            return
+        tc = pv.query_one(TabbedContent)
+        tab_map = {"1": "data-tab", "2": "schema-tab", "3": "stats-tab"}
+        tab_id = tab_map.get(tab_num)
+        if tab_id:
+            tc.active = tab_id
+            # Refocus DataTable when switching to data tab
+            if tab_id == "data-tab":
+                try:
+                    pv.query_one(DataTable).focus()
+                except Exception:
+                    pass
+
+    @on(DirectoryChanged)
+    def _on_directory_changed(self, event: DirectoryChanged) -> None:
+        path_bar = self.query_one("#path-bar", PathBar)
+        path_bar.update_path(event.path)
+
+
+def run() -> None:
+    """Run the ncview app."""
+    import argparse
+
+    parser = argparse.ArgumentParser(prog="ncview", description="Terminal file browser with vim keybindings")
+    parser.add_argument("path", nargs="?", default=".", help="Directory to browse (default: current directory)")
+    args = parser.parse_args()
+
+    path = Path(args.path).resolve()
+    if not path.exists():
+        parser.error(f"{path} does not exist")
+    if path.is_file():
+        path = path.parent
+    app = NcviewApp(start_path=path)
+    app.run()

ncview-0.1.0/src/ncview/ncview.tcss

@@ -0,0 +1,30 @@
+Header {
+    dock: top;
+}
+
+Footer {
+    dock: bottom;
+}
+
+PathBar {
+    dock: top;
+}
+
+FileBrowser {
+    height: 1fr;
+    width: 1fr;
+    border: solid $primary;
+    border-title-color: $text;
+}
+
+PreviewPanel {
+    height: 1fr;
+    width: 1fr;
+    border: solid $secondary;
+    border-title-color: $text;
+    display: none;
+}
+
+PreviewPanel.visible {
+    display: block;
+}

ncview-0.1.0/src/ncview/utils/file_info.py

@@ -0,0 +1,87 @@
+"""File metadata extraction and size formatting."""
+
+from __future__ import annotations
+
+import os
+import stat
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def human_size(size: int | float) -> str:
+    """Convert bytes to human-readable string."""
+    for unit in ("B", "K", "M", "G", "T"):
+        if abs(size) < 1024:
+            if unit == "B":
+                return f"{int(size)}{unit}"
+            return f"{size:.1f}{unit}"
+        size = size / 1024
+    return f"{size:.1f}P"
+
+
+def file_icon(path: Path) -> str:
+    """Return a simple icon character for a path."""
+    if path.is_dir():
+        return "\U0001f4c1"  # folder
+    ext = path.suffix.lower()
+    if ext in {".py", ".js", ".ts", ".rs", ".go", ".c", ".cpp", ".java"}:
+        return "\U0001f4c4"  # code
+    if ext in {".parquet", ".csv", ".tsv", ".xlsx"}:
+        return "\U0001f4ca"  # data
+    if ext in {".json", ".yaml", ".yml", ".toml", ".xml"}:
+        return "\u2699"  # config
+    if ext in {".md", ".txt", ".rst", ".log"}:
+        return "\U0001f4dd"  # text
+    if ext in {".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp"}:
+        return "\U0001f5bc"  # image
+    return "\U0001f4c3"  # generic file
+
+
+def file_metadata(path: Path) -> dict[str, str]:
+    """Extract metadata dict for display in fallback viewer."""
+    info: dict[str, str] = {
+        "Name": path.name,
+        "Path": str(path.resolve()) if not path.is_symlink() else str(path),
+    }
+
+    # Check for broken symlinks first (lstat doesn't follow the link)
+    if path.is_symlink():
+        try:
+            target = os.readlink(path)
+            info["Link target"] = target
+            if not path.exists():
+                info["Link status"] = "broken"
+                return info
+        except OSError:
+            info["Link target"] = "(unreadable)"
+            return info
+
+    try:
+        st = path.stat()
+    except OSError:
+        info["error"] = "Cannot read file metadata"
+        return info
+
+    info.update({
+        "Size": human_size(st.st_size),
+        "Size (bytes)": f"{st.st_size:,}",
+        "Modified": datetime.fromtimestamp(st.st_mtime, tz=timezone.utc)
+            .astimezone().strftime("%Y-%m-%d %H:%M:%S"),
+        "Created": datetime.fromtimestamp(st.st_ctime, tz=timezone.utc)
+            .astimezone().strftime("%Y-%m-%d %H:%M:%S"),
+        "Permissions": stat.filemode(st.st_mode),
+    })
+
+    try:
+        import pwd
+        info["Owner"] = pwd.getpwuid(st.st_uid).pw_name
+    except (ImportError, KeyError, AttributeError):
+        info["Owner"] = str(st.st_uid)
+
+    try:
+        import grp
+        info["Group"] = grp.getgrgid(st.st_gid).gr_name
+    except (ImportError, KeyError, AttributeError):
+        info["Group"] = str(st.st_gid)
+
+    return info

ncview-0.1.0/src/ncview/utils/file_types.py

@@ -0,0 +1,68 @@
+"""Viewer registry — maps file extensions to viewer classes."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ncview.viewers.base import BaseViewer
+
+
+class ViewerRegistry:
+    """Maps file extensions to viewer widget classes."""
+
+    def __init__(self) -> None:
+        self._viewers: list[type[BaseViewer]] = []
+
+    def register(self, viewer_cls: type[BaseViewer]) -> type[BaseViewer]:
+        """Register a viewer class."""
+        self._viewers.append(viewer_cls)
+        return viewer_cls
+
+    def get_viewer(self, path: Path) -> type[BaseViewer]:
+        """Return the best viewer class for a given file path."""
+        ext = path.suffix.lower()
+        best: type[BaseViewer] | None = None
+        best_priority = float("-inf")
+
+        for viewer_cls in self._viewers:
+            if ext in viewer_cls.supported_extensions():
+                p = viewer_cls.priority()
+                if p > best_priority:
+                    best = viewer_cls
+                    best_priority = p
+
+        if best is None:
+            # Try text viewer for extensionless files that look like text
+            if not ext and _is_likely_text(path):
+                from ncview.viewers.text_viewer import TextViewer
+                return TextViewer
+            from ncview.viewers.fallback_viewer import FallbackViewer
+            return FallbackViewer
+
+        return best
+
+
+# Common extensionless text files
+_TEXT_FILENAMES = {
+    "makefile", "dockerfile", "vagrantfile", "gemfile", "rakefile",
+    "license", "licence", "readme", "changelog", "authors", "contributors",
+    "todo", "news", "install", "copying", "notice",
+}
+
+
+def _is_likely_text(path: Path) -> bool:
+    """Heuristic check for extensionless text files."""
+    if path.name.lower() in _TEXT_FILENAMES:
+        return True
+    # Peek at first 512 bytes for null bytes (binary indicator)
+    try:
+        chunk = path.read_bytes()[:512]
+        return b"\x00" not in chunk
+    except OSError:
+        return False
+
+
+# Singleton registry
+registry = ViewerRegistry()

ncview-0.1.0/src/ncview/viewers/base.py

@@ -0,0 +1,43 @@
+"""Abstract base viewer."""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from pathlib import Path
+
+from textual.widget import Widget
+
+
+class BaseViewer(Widget):
+    """Base class for all file viewers."""
+
+    DEFAULT_CSS = """
+    BaseViewer {
+        height: 1fr;
+        width: 1fr;
+    }
+    """
+
+    def __init__(self, path: Path, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self.path = path
+
+    @staticmethod
+    @abstractmethod
+    def supported_extensions() -> set[str]:
+        """Return set of supported file extensions (e.g. {'.txt', '.py'})."""
+        ...
+
+    @staticmethod
+    def priority() -> int:
+        """Higher priority wins when multiple viewers match an extension."""
+        return 0
+
+    @abstractmethod
+    async def load_content(self) -> None:
+        """Load file content. Called after mount."""
+        ...
+
+    async def on_mount(self) -> None:
+        """Trigger content loading after mount."""
+        await self.load_content()

ncview-0.1.0/src/ncview/viewers/fallback_viewer.py

@@ -0,0 +1,42 @@
+"""Fallback viewer — shows file metadata for unknown/binary files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from rich.table import Table
+from textual.widgets import Static
+
+from ncview.utils.file_info import file_metadata
+from ncview.viewers.base import BaseViewer
+
+
+class FallbackViewer(BaseViewer):
+    """Shows file metadata when no specialized viewer matches."""
+
+    DEFAULT_CSS = """
+    FallbackViewer {
+        height: 1fr;
+        padding: 1 2;
+    }
+    """
+
+    @staticmethod
+    def supported_extensions() -> set[str]:
+        return set()
+
+    @staticmethod
+    def priority() -> int:
+        return -100
+
+    def compose(self):
+        yield Static(id="fallback-content")
+
+    async def load_content(self) -> None:
+        meta = file_metadata(self.path)
+        table = Table(title="File Info", show_header=False, expand=True)
+        table.add_column("Key", style="bold cyan", ratio=1)
+        table.add_column("Value", ratio=3)
+        for key, value in meta.items():
+            table.add_row(key, value)
+        self.query_one("#fallback-content", Static).update(table)