nbsee 0.1.0__tar.gz

nbsee-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 nbsee contributors
+
+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.
+

nbsee-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+recursive-include src *.py
+recursive-include docs *.md
+recursive-include tests *.py
+global-exclude __pycache__ *.py[cod]
+exclude *.ipynb

nbsee-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: nbsee
+Version: 0.1.0
+Summary: Rich/Textual terminal viewer for Jupyter notebooks focused on copying code and text outputs
+Author: Yoga Yudistira
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AnakTeka/nbsee
+Project-URL: Repository, https://github.com/AnakTeka/nbsee
+Project-URL: Issues, https://github.com/AnakTeka/nbsee/issues
+Keywords: jupyter,notebook,cli,tui,rich,textual
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Environment :: Console
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.7
+Requires-Dist: textual>=0.58
+Dynamic: license-file
+
+nbsee
+=====
+
+Simple CLI viewer for Jupyter notebooks focused on fast reading and easy copying of code and text outputs from the terminal.
+
+Status: planning/design. See docs/TODO.md for the working task list.
+
+Goals (MVP)
+- Interactive terminal viewer for `.ipynb`.
+- Navigate cells with keys; focus input vs output.
+- Code cells: show source and text/plain outputs only.
+- Easy copying from the viewer using the keyboard (xclip).
+- Ignore images/HTML-rich outputs for now.
+
+Quick Concept (not implemented yet)
+- `nbsee notebook.ipynb` — open an interactive viewer.
+
+Key bindings (proposed)
+- `j`/`k`: move to next/previous cell
+- Arrow Up/Down: scroll the view line-by-line
+- PageUp/PageDown: page scroll
+- Ctrl+u / Ctrl+d: half-page scroll up/down
+- `Tab`: toggle focus between input (code/markdown) and output (text/plain)
+- If a cell has no text output, `Tab` does nothing and shows a brief message.
+- `y`: copy the currently focused region to clipboard using `xclip -selection clipboard`
+- `z`: hide/show all outputs (fold outputs)
+- `Shift+V`: start/stop visual selection for inputs; use `j`/`k` to expand/shrink; `y` copies all selected code cells
+- `/`: search (inputs+outputs). Enter to submit, `Esc` cancels
+- `n` / `N`: next/prev match
+- `gg` / `G`: jump to first / last cell
+- `G`/`gg`: jump to last/first cell (optional)
+- `q`: quit
+
+Notes
+- Copying uses Linux X11 clipboard via `xclip`. Wayland/macOS not targeted in MVP.
+- When an output is not available (e.g., no text/plain), copy will show an inline message.
+- Python syntax highlighting is built-in via Rich.
+
+Install (PyPI)
+- `python -m pip install nbsee`
+- Run: `nbsee path/to/notebook.ipynb`
+
+Development (uv)
+- Quick run without installing: `uv run -m nbsee path/to/notebook.ipynb`
+- Run tests: `uv run pytest`
+- Lint/format check: `uv run ruff check .` and `uv run ruff format --check .`
+- Build distributions: `uv build`
+- Release: push a tag like `v0.1.0` to trigger `.github/workflows/publish.yml` (requires PyPI trusted publishing setup).
+- Install editable and use `nbsee` command:
+  - Create venv: `uv venv`
+  - Activate: `source .venv/bin/activate`
+  - Install: `uv pip install -e .`
+  - Run: `nbsee path/to/notebook.ipynb`
+- Clipboard requirement: `xclip` on Linux/X11 must be installed and available in `PATH`.
+
+
+Docs
+- Design: `docs/DESIGN.md`
+- TODOs & roadmap: `docs/TODO.md`

nbsee-0.1.0/README.md

@@ -0,0 +1,59 @@
+nbsee
+=====
+
+Simple CLI viewer for Jupyter notebooks focused on fast reading and easy copying of code and text outputs from the terminal.
+
+Status: planning/design. See docs/TODO.md for the working task list.
+
+Goals (MVP)
+- Interactive terminal viewer for `.ipynb`.
+- Navigate cells with keys; focus input vs output.
+- Code cells: show source and text/plain outputs only.
+- Easy copying from the viewer using the keyboard (xclip).
+- Ignore images/HTML-rich outputs for now.
+
+Quick Concept (not implemented yet)
+- `nbsee notebook.ipynb` — open an interactive viewer.
+
+Key bindings (proposed)
+- `j`/`k`: move to next/previous cell
+- Arrow Up/Down: scroll the view line-by-line
+- PageUp/PageDown: page scroll
+- Ctrl+u / Ctrl+d: half-page scroll up/down
+- `Tab`: toggle focus between input (code/markdown) and output (text/plain)
+- If a cell has no text output, `Tab` does nothing and shows a brief message.
+- `y`: copy the currently focused region to clipboard using `xclip -selection clipboard`
+- `z`: hide/show all outputs (fold outputs)
+- `Shift+V`: start/stop visual selection for inputs; use `j`/`k` to expand/shrink; `y` copies all selected code cells
+- `/`: search (inputs+outputs). Enter to submit, `Esc` cancels
+- `n` / `N`: next/prev match
+- `gg` / `G`: jump to first / last cell
+- `G`/`gg`: jump to last/first cell (optional)
+- `q`: quit
+
+Notes
+- Copying uses Linux X11 clipboard via `xclip`. Wayland/macOS not targeted in MVP.
+- When an output is not available (e.g., no text/plain), copy will show an inline message.
+- Python syntax highlighting is built-in via Rich.
+
+Install (PyPI)
+- `python -m pip install nbsee`
+- Run: `nbsee path/to/notebook.ipynb`
+
+Development (uv)
+- Quick run without installing: `uv run -m nbsee path/to/notebook.ipynb`
+- Run tests: `uv run pytest`
+- Lint/format check: `uv run ruff check .` and `uv run ruff format --check .`
+- Build distributions: `uv build`
+- Release: push a tag like `v0.1.0` to trigger `.github/workflows/publish.yml` (requires PyPI trusted publishing setup).
+- Install editable and use `nbsee` command:
+  - Create venv: `uv venv`
+  - Activate: `source .venv/bin/activate`
+  - Install: `uv pip install -e .`
+  - Run: `nbsee path/to/notebook.ipynb`
+- Clipboard requirement: `xclip` on Linux/X11 must be installed and available in `PATH`.
+
+
+Docs
+- Design: `docs/DESIGN.md`
+- TODOs & roadmap: `docs/TODO.md`

nbsee-0.1.0/docs/DESIGN.md

@@ -0,0 +1,73 @@
+Design Notes
+============
+
+Problem
+- Quickly view Jupyter notebook cells in a terminal and easily copy either the code or the text/plain output.
+- Avoid heavy rendering; keep it fast and focused on text.
+
+Constraints / Non-goals (MVP)
+- Do not render images, rich HTML, plots, or dataframes (treat them as placeholders or omit).
+- Do not execute notebooks; viewing only.
+- No in-place editing of notebooks.
+
+CLI UX (proposed)
+- `nbsee <notebook.ipynb>`: open an interactive viewer.
+  - Multi-cell list layout with vertical scrolling provides context similar to a notebook editor.
+  - Each cell renders: header `[idx/type]`, Input, separator, Output, and spacing.
+  - Selection (J/K) highlights a cell header; focus marker (Tab) toggles Input/Output of the selected cell for copying.
+- Exit codes: 0 on success; non-zero on IO/parse errors.
+
+Keymap (MVP)
+- `J` / `K`: next / previous cell (change selection)
+- Arrow Up/Down: scroll the view line-by-line
+- PageUp/PageDown: page scroll
+- `Tab`: toggle focus between Input and Output for selected cell (no-op if no text output)
+- `Ctrl+u` / `Ctrl+d`: scroll up/down by half a page
+- `z`: toggle hide/show of all outputs (global fold)
+- `Shift+V`: enter/exit visual selection for inputs; `j`/`k` adjust the range; `y` yanks (copies) all selected code cells to clipboard
+- `/`: open a search prompt (inputs + outputs, case-insensitive)
+- `n` / `N`: jump to next/previous match, wrapping around
+- `gg` / `G`: jump to first/last cell
+- `y`: copy focused region to clipboard using `xclip -selection clipboard`
+- `G` / `gg`: jump to last / first cell (optional)
+- `q`: quit
+
+Copying Workflow
+- Interactive: pressing `C` copies the currently focused region (Input or Output) to the clipboard via `xclip -selection clipboard` on Linux/X11.
+- If Output is focused but the cell has no text/plain output, show a temporary inline message and do nothing.
+- Piping-based copying is not required in MVP; we optimize for the interactive flow.
+
+Rendering
+- Multi-cell stacked view; soft-wrap long lines to terminal width.
+- Rich/Textual UI only: panels with clear separation and high-quality `Syntax` highlighting.
+- No horizontal scrolling in MVP; lines are wrapped.
+
+Parsing
+- Use Python stdlib `json` for MVP (avoid deps); consider `nbformat` later for robustness.
+- Fields: `cells[]`, `cell_type`, `source`, `outputs[]`, `output_type`, `text`, `data["text/plain"]`.
+- Be robust to missing fields.
+
+Performance
+- Stream parsing is not necessary for typical sizes.
+- Avoid expensive re-renders; redraw only on navigation or copy feedback.
+
+Structure (proposed)
+- `nbsee/` package with `__main__.py` entry point.
+- Single UI: Rich/Textual-based TUI with `textual_app.py`.
+- `pyproject.toml` exposes console script `nbsee` and depends on `rich` and `textual`.
+
+Error Handling
+- Clear messages for: file not found, invalid JSON, not a notebook, cell out of range, missing output.
+- In-view ephemeral notices for copy failures (e.g., xclip missing or no output to copy).
+
+Future Ideas (post-MVP)
+- Multi-cell list pane with scrolling and preview.
+- Rich/HTML output fallback with `rich`/`textual`.
+- Image placeholders with metadata (e.g., [image output: 800x600]).
+- Search/filter cells by content or tags.
+- Copy multiple cells or ranges.
+
+Developer Workflow (uv)
+- Quick run without install: `uv run -m nbsee path/to/notebook.ipynb`
+- Create venv: `uv venv && source .venv/bin/activate`
+- Install editable: `uv pip install -e .`

nbsee-0.1.0/docs/TODO.md

@@ -0,0 +1,47 @@
+nbsee TODOs
+============
+
+MVP Scope (Interactive viewer)
+- [x] CLI skeleton: `nbsee <path.ipynb>` opens TUI
+- [x] Validate path and read file
+- [x] Parse notebook JSON (cells, types, sources)
+- [x] Multi-cell stacked layout with scrolling
+- [x] Render Input region (code/markdown/raw)
+- [x] Render Output region for code cells (text/plain only)
+- [x] Focus toggling: `Tab` cycles Input/Output
+- [x] Navigation: `J`/`K` select cells; `↑/↓` scroll; `PgUp/PgDn` page
+- [x] Copy: `y` copies focused region via `xclip -selection clipboard`
+- [x] Feedback: status line for copy success/failure
+- [ ] Handle errors (file not found, bad JSON, not a notebook, bad cell index) — basic done, refine messages
+- [ ] Tests for parsing and selection logic
+- [ ] Basic docs and examples
+
+Rich/Textual UI
+- [x] Use Rich/Textual as the default (and only) UI
+- [ ] Style tuning for panels, themes, and readability
+- [ ] Add cell collapse/expand interactions
+- [ ] Add search ("/") and go-to (":N")
+- [x] Global fold toggle for outputs (`z`)
+- [x] Visual selection of inputs with `Shift+V`, adjust with `j/k`, yank with `y`
+
+Copying Experience
+- [ ] Linux/X11 clipboard via `xclip -selection clipboard`
+- [ ] Detect missing `xclip` and show helpful message
+- [ ] Optional later: Wayland (`wl-copy`) and macOS (`pbcopy`) support
+
+Rendering
+- [x] Simple, readable headers and focus markers (Rich panels)
+- [x] Python syntax highlighting via Rich `Syntax`
+
+Packaging
+- [ ] `pyproject.toml` with console script entry `nbsee`
+- [x] Depend on `rich` and `textual` directly (no extras)
+- [ ] Document `uv` workflow (run, venv, install editable)
+
+Post-MVP / Later
+- [ ] Cell range display `--range A:B`
+- [ ] Colorized code (Pygments)
+- [ ] Rich outputs (HTML/images) placeholders
+- [ ] Interactive TUI mode (Textual)
+- [ ] Search/filter cells
+- [ ] Copy multiple cells/ranges

nbsee-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nbsee"
+version = "0.1.0"
+description = "Rich/Textual terminal viewer for Jupyter notebooks focused on copying code and text outputs"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Yoga Yudistira" }]
+keywords = ["jupyter", "notebook", "cli", "tui", "rich", "textual"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Environment :: Console",
+  "Topic :: Utilities",
+]
+dependencies = ["rich>=13.7", "textual>=0.58"]
+
+[project.scripts]
+nbsee = "nbsee.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/AnakTeka/nbsee"
+Repository = "https://github.com/AnakTeka/nbsee"
+Issues = "https://github.com/AnakTeka/nbsee/issues"
+
+
+[dependency-groups]
+test = ["pytest>=9.0.0"]
+lint = ["ruff>=0.8.0"]
+dev = [{ include-group = "test" }, { include-group = "lint" }]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+exclude = ["*.ipynb"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

nbsee-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nbsee-0.1.0/src/nbsee/__init__.py

@@ -0,0 +1 @@
+__all__ = []

nbsee-0.1.0/src/nbsee/__main__.py

@@ -0,0 +1,116 @@
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+from typing import Any
+
+
+def _read_file(path: str) -> dict[str, Any]:
+    with open(path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _as_text(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, list):
+        return "".join(str(x) for x in value)
+    return str(value)
+
+
+def _cell_input_text(cell: dict[str, Any]) -> str:
+    return _as_text(cell.get("source", ""))
+
+
+def _cell_output_text(cell: dict[str, Any]) -> str:
+    if cell.get("cell_type") != "code":
+        return ""
+    outs: list[str] = []
+    for out in cell.get("outputs", []) or []:
+        data = out.get("data") if isinstance(out, dict) else None
+        if isinstance(data, dict) and "text/plain" in data:
+            outs.append(_as_text(data.get("text/plain")))
+            continue
+        if out.get("output_type") == "stream" and "text" in out:
+            outs.append(_as_text(out.get("text")))
+            continue
+        if out.get("output_type") == "error" and "traceback" in out:
+            tb = out.get("traceback")
+            if isinstance(tb, list):
+                parts = [str(x) for x in tb]
+                # Jupyter tracebacks are often lists of lines. Sometimes newlines are
+                # embedded, sometimes they're separate elements; preserve embedded ones.
+                if any("\n" in p for p in parts):
+                    outs.append("".join(parts))
+                else:
+                    outs.append("\n".join(parts))
+            else:
+                outs.append(_as_text(tb))
+            continue
+    return "\n".join(x for x in outs if x)
+
+
+def _load_notebook(path: str) -> list[dict[str, Any]]:
+    nb = _read_file(path)
+    if (
+        not isinstance(nb, dict)
+        or "cells" not in nb
+        or not isinstance(nb["cells"], list)
+    ):
+        raise ValueError("Not a valid .ipynb: missing cells[]")
+    return nb["cells"]
+
+
+def _copy_to_clipboard(text: str) -> tuple[bool, str]:
+    if not text:
+        return False, "Nothing to copy"
+    if shutil.which("xclip") is None:
+        return False, "xclip not found"
+    try:
+        p = subprocess.Popen(
+            ["xclip", "-selection", "clipboard"], stdin=subprocess.PIPE
+        )
+        assert p.stdin is not None
+        p.stdin.write(text.encode("utf-8"))
+        p.stdin.close()
+        rc = p.wait(timeout=5)
+        if rc != 0:
+            return False, f"xclip failed (code {rc})"
+        return True, f"Copied {len(text)} chars to clipboard"
+    except FileNotFoundError:
+        return False, "xclip not found"
+    except Exception as e:
+        return False, f"Copy failed: {e}"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Rich/Textual viewer for Jupyter notebooks"
+    )
+    parser.add_argument("path", help="Path to .ipynb file")
+    args = parser.parse_args(argv)
+
+    if not os.path.exists(args.path):
+        sys.stderr.write(f"File not found: {args.path}\n")
+        return 2
+    try:
+        cells = _load_notebook(args.path)
+    except Exception as e:
+        sys.stderr.write(f"Failed to read notebook: {e}\n")
+        return 2
+    if not cells:
+        sys.stderr.write("Notebook has no cells\n")
+        return 1
+
+    try:
+        from .textual_app import run_textual_app
+    except Exception as e:  # pragma: no cover
+        sys.stderr.write(f"Rich/Textual UI not available: {e}\n")
+        return 2
+    return run_textual_app(cells)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

nbsee-0.1.0/src/nbsee/textual_app.py

@@ -0,0 +1,610 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+try:
+    from rich import box as rich_box
+    from rich.panel import Panel
+    from rich.syntax import Syntax
+    from rich.text import Text
+    from textual.app import App, ComposeResult
+    from textual.binding import Binding
+    from textual.containers import VerticalScroll
+    from textual.reactive import reactive
+    from textual.widgets import Footer, Input, Static
+
+    _HAS_TEXTUAL = True
+except Exception as e:  # pragma: no cover
+    _HAS_TEXTUAL = False
+    _IMPORT_ERROR = e
+
+from .__main__ import _cell_input_text, _cell_output_text, _copy_to_clipboard
+
+_ANSI_CSI_RE = re.compile(r"\x1b\[[0-?]*[ -/]*[@-~]")
+_ANSI_OSC_RE = re.compile(r"\x1b\].*?(?:\x07|\x1b\\)")
+_ANSI_SGR_RE = re.compile(r"\x1b\[([0-9;]*)m")
+_CONTROL_RE = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]")
+
+
+def _strip_sgr_background(text: str) -> str:
+    def repl(match: re.Match[str]) -> str:
+        raw = match.group(1)
+        if raw == "":
+            return match.group(0)
+
+        try:
+            params = [int(p) for p in raw.split(";") if p != ""]
+        except ValueError:
+            return match.group(0)
+
+        keep: list[int] = []
+        i = 0
+        while i < len(params):
+            p = params[i]
+            # Drop background colors:
+            # - 40-47, 100-107, 49
+            # - 48;5;n and 48;2;r;g;b
+            if p == 48:
+                if i + 1 < len(params) and params[i + 1] == 5:
+                    i += 3
+                    continue
+                if i + 1 < len(params) and params[i + 1] == 2:
+                    i += 5
+                    continue
+                i += 1
+                continue
+            if p == 49 or 40 <= p <= 47 or 100 <= p <= 107:
+                i += 1
+                continue
+            keep.append(p)
+            i += 1
+
+        if not keep:
+            return ""
+        return f"\x1b[{';'.join(str(p) for p in keep)}m"
+
+    return _ANSI_SGR_RE.sub(repl, text)
+
+
+def _sanitize_ansi_text(text: str) -> str:
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+    text = _ANSI_OSC_RE.sub("", text)
+
+    def csi_repl(match: re.Match[str]) -> str:
+        seq = match.group(0)
+        return seq if seq.endswith("m") else ""
+
+    text = _ANSI_CSI_RE.sub(csi_repl, text)
+    text = re.sub(r"\x1b(?!\[[0-9;]*m)", "", text)
+    text = _CONTROL_RE.sub("", text)
+    # IPython tracebacks sometimes render "Traceback ...Cell ..." without a newline.
+    text = re.sub(r"(Traceback \(most recent call last\))\s*Cell", r"\1\nCell", text)
+    return text
+
+
+def ensure_textual_available():
+    if not _HAS_TEXTUAL:
+        raise RuntimeError(
+            f"Rich/Textual UI requested but not available: {_IMPORT_ERROR}"
+        )
+
+
+if _HAS_TEXTUAL:
+
+    class CellView(Static):
+        selected: bool = reactive(False)
+        focus_region: str = reactive("input")  # input|output
+        outputs_hidden: bool = reactive(False)
+        in_visual: bool = reactive(False)  # in multi-cell visual selection range
+
+        def __init__(self, index: int, total: int, cell: dict[str, Any]):
+            super().__init__(id=f"cell-{index}")
+            self.index = index
+            self.total = total
+            self.cell = cell
+
+        def _render_input(self) -> Syntax | Text:
+            ctype = self.cell.get("cell_type")
+            source = _cell_input_text(self.cell)
+            if ctype == "code":
+                # Use Rich Syntax highlighter for Python
+                return Syntax(source or "", "python", theme="monokai", word_wrap=True)
+            # Markdown/raw rendered as plain text for now
+            return Text(source or "", style="default")
+
+        def _render_output(self) -> Text:
+            txt = _cell_output_text(self.cell)
+            if not (txt or "").strip():
+                t = Text("[no text output]", style="grey50 italic")
+                t.no_wrap = False
+                t.overflow = "fold"
+                return t
+
+            txt = txt or ""
+            if self._has_error_output():
+                cleaned = _strip_sgr_background(_sanitize_ansi_text(txt))
+                t = Text.from_ansi(f"{cleaned}\x1b[0m")
+            elif "\x1b" in txt:
+                cleaned = _sanitize_ansi_text(txt)
+                t = Text.from_ansi(f"{cleaned}\x1b[0m")
+            else:
+                t = Text(_sanitize_ansi_text(txt), style="grey70")
+            t.no_wrap = False
+            t.overflow = "fold"
+            return t
+
+        def _has_error_output(self) -> bool:
+            try:
+                for out in self.cell.get("outputs", []) or []:
+                    if out.get("output_type") == "error":
+                        return True
+            except Exception:
+                pass
+            txt = _cell_output_text(self.cell) or ""
+            return "Traceback (most recent call last)" in txt
+
+        def render(self):
+            # Header: color indicates selection
+            # Header styling
+            if self.selected:
+                header_style = "magenta bold"
+                prefix = "▶ "
+            elif self.in_visual:
+                header_style = "yellow"
+                prefix = "◆ "
+            else:
+                header_style = "grey50"
+                prefix = "  "
+            cell_type = self.cell.get("cell_type", "?")
+            header_text = f"[ {self.index + 1}/{self.total} | {cell_type} ]"
+            header = Text(prefix + header_text, style=header_style)
+
+            # Input and Output as rounded panels with clear distinction
+            input_border = (
+                "cyan" if (self.selected and self.focus_region == "input") else "grey50"
+            )
+            if self.selected and self.focus_region == "output":
+                output_border = "cyan"
+            elif self._has_error_output():
+                output_border = "red"
+            else:
+                output_border = "grey37"
+
+            input_panel = Panel(
+                self._render_input(),
+                box=rich_box.ROUNDED,
+                border_style=input_border,
+                padding=(0, 1),
+            )
+
+            parts = [header, input_panel]
+            out_text = _cell_output_text(self.cell)
+            if out_text.strip():
+                if self.outputs_hidden:
+                    out_render = Text("[output hidden]", style="grey37 italic")
+                else:
+                    out_render = self._render_output()
+                title = "Error" if self._has_error_output() else "Output"
+                output_panel = Panel(
+                    out_render,
+                    title=title,
+                    box=rich_box.ROUNDED,
+                    border_style=output_border,
+                    padding=(0, 1),
+                )
+                parts.append(output_panel)
+
+            from rich.console import Group
+
+            return Group(*parts)
+
+    class NotebookApp(App):
+        CSS = """
+        Screen { layers: base; }
+        VerticalScroll { padding: 0 1; }
+        #searchbar { dock: top; padding: 0 1; }
+        #footer { dock: bottom; }
+        """
+
+        BINDINGS = [
+            Binding("q", "quit", "Quit"),
+            Binding("j", "next_cell", "Next cell"),
+            Binding("k", "prev_cell", "Prev cell"),
+            # Override Textual's default focus-next so Tab toggles input/output
+            Binding("tab", "toggle_focus", "Toggle focus", priority=True),
+            Binding(
+                "shift+tab",
+                "toggle_focus",
+                "Toggle focus",
+                priority=True,
+                show=False,
+            ),
+            Binding("y", "copy", "Copy"),
+            Binding("ctrl+d", "half_down", "Half down"),
+            Binding("ctrl+u", "half_up", "Half up"),
+            Binding("z", "toggle_outputs", "Hide/show outputs"),
+            Binding("shift+v", "toggle_visual", "Visual (inputs)"),
+            Binding("/", "search_prompt", "Search"),
+            Binding("escape", "cancel_search", "Cancel search", show=False),
+            Binding("n", "search_next", "Next match"),
+            Binding("shift+n", "search_prev", "Prev match", show=False),
+            Binding("G", "go_last", "Last cell"),
+            Binding("g", "go_prefix", "g (prefix)", show=False),
+        ]
+
+        def __init__(self, cells: list[dict[str, Any]]):
+            super().__init__()
+            self.cells = cells
+            self.selected = 0
+            self._cell_views: list[CellView] = []
+            self.hide_outputs = False
+            self.visual_mode = False
+            self.visual_anchor = 0
+            self.search_query: str = ""
+            # For handling "gg" sequence
+            self._g_pending = False
+            self._g_timer = None
+
+        def compose(self) -> ComposeResult:
+            total = len(self.cells)
+            views: list[CellView] = []
+            for i, cell in enumerate(self.cells):
+                cv = CellView(i, total, cell)
+                views.append(cv)
+            self._cell_views = views
+            yield VerticalScroll(*views, id="cells")
+            yield Footer(id="footer")
+
+        def on_mount(self) -> None:
+            self._update_selection(0)
+
+        def action_next_cell(self) -> None:
+            if self.selected < len(self._cell_views) - 1:
+                self._update_selection(self.selected + 1)
+                if self.visual_mode:
+                    self._update_visual_flags()
+
+        def action_prev_cell(self) -> None:
+            if self.selected > 0:
+                self._update_selection(self.selected - 1)
+                if self.visual_mode:
+                    self._update_visual_flags()
+
+        def _scroll(self, delta: int) -> int:
+            try:
+                sc: VerticalScroll = self.query_one("#cells", VerticalScroll)
+            except Exception:
+                return 0
+            # Determine current y offset and target
+            current_y = 0
+            try:
+                off = getattr(sc, "scroll_offset", None)
+                if off is not None and hasattr(off, "y"):
+                    current_y = int(off.y)
+                else:
+                    current_y = int(getattr(sc, "scroll_y", 0))
+            except Exception:
+                pass
+            target = max(0, current_y + int(delta))
+            # Perform scroll using best available API
+            try:
+                sc.scroll_to(y=target, animate=False)
+                return target
+            except TypeError:
+                try:
+                    sc.scroll_to(0, target, animate=False)
+                    return target
+                except Exception:
+                    pass
+            except Exception:
+                pass
+            # Try duration=0 as a fallback to disable animation
+            try:
+                sc.scroll_to(y=target, duration=0)
+                return target
+            except Exception:
+                pass
+            try:
+                sc.scroll_y = target  # type: ignore[attr-defined]
+            except Exception:
+                pass
+            return target
+
+        def _visible_cells(self) -> list[int]:
+            # Return indices of cells currently intersecting the viewport
+            try:
+                sc: VerticalScroll = self.query_one("#cells", VerticalScroll)
+            except Exception:
+                return []
+            try:
+                sy = int(getattr(sc.scroll_offset, "y", getattr(sc, "scroll_y", 0)))
+            except Exception:
+                sy = int(getattr(sc, "scroll_y", 0))
+            try:
+                vh = (
+                    int(getattr(sc.size, "height", 0))
+                    or int(getattr(self.size, "height", 0))
+                    or 20
+                )
+            except Exception:
+                vh = 20
+            vis: list[int] = []
+            for i, cv in enumerate(self._cell_views):
+                try:
+                    y = int(getattr(cv.region, "y", 0))
+                    h = max(1, int(getattr(cv.region, "height", 1)))
+                except Exception:
+                    continue
+                if (y < sy + vh) and (y + h > sy):
+                    vis.append(i)
+            return vis
+
+        def action_half_down(self) -> None:
+            try:
+                sc: VerticalScroll = self.query_one("#cells", VerticalScroll)
+                height = (
+                    int(getattr(sc.size, "height", 0))
+                    or int(getattr(self.size, "height", 0))
+                    or 20
+                )
+            except Exception:
+                height = 20
+            delta = max(5, height // 2)
+            if self.visual_mode:
+                self._set_visual(False)
+            self._scroll(delta)
+            vis = self._visible_cells()
+            step = max(1, len(vis) // 2 or 1)
+            new_idx = min(len(self._cell_views) - 1, self.selected + step)
+            self._update_selection(new_idx, ensure_visible=False)
+
+        def action_half_up(self) -> None:
+            try:
+                sc: VerticalScroll = self.query_one("#cells", VerticalScroll)
+                height = (
+                    int(getattr(sc.size, "height", 0))
+                    or int(getattr(self.size, "height", 0))
+                    or 20
+                )
+            except Exception:
+                height = 20
+            delta = -max(5, height // 2)
+            if self.visual_mode:
+                self._set_visual(False)
+            self._scroll(delta)
+            vis = self._visible_cells()
+            step = max(1, len(vis) // 2 or 1)
+            new_idx = max(0, self.selected - step)
+            self._update_selection(new_idx, ensure_visible=False)
+
+        # --- Search ---
+        def _cell_text(self, idx: int) -> str:
+            cell = self.cells[idx]
+            return f"{_cell_input_text(cell)}\n{_cell_output_text(cell)}"
+
+        def _search_from(self, start: int, step: int) -> int:
+            if not self.search_query:
+                return -1
+            q = self.search_query.lower()
+            n = len(self.cells)
+            i = start
+            for _ in range(n):
+                text = self._cell_text(i).lower()
+                if q in text:
+                    return i
+                i = (i + step) % n
+            return -1
+
+        def action_search_prompt(self) -> None:
+            # Open a simple input bar at the top
+            if self.query("#searchbar"):
+                sb = self.query_one("#searchbar", Input)
+                self.call_after_refresh(sb.focus)
+                return
+            sb = Input(placeholder="/ search", id="searchbar")
+            sb.value = self.search_query
+            self.mount(sb)
+            self.call_after_refresh(sb.focus)
+
+        def action_cancel_search(self) -> None:
+            if self.query("#searchbar"):
+                try:
+                    self.query_one("#searchbar", Input).remove()
+                except Exception:
+                    pass
+
+        def on_input_submitted(self, event: Input.Submitted) -> None:
+            if event.input.id == "searchbar":
+                self.search_query = event.value or ""
+                event.input.remove()
+                if self.search_query:
+                    self.action_search_next()
+                else:
+                    self.notify("Search cleared")
+
+        def on_input_blurred(self, event: Input.Blurred) -> None:
+            if event.input.id == "searchbar":
+                # Remove the bar when focus leaves
+                try:
+                    event.input.remove()
+                except Exception:
+                    pass
+
+        def action_search_next(self) -> None:
+            if not self.search_query:
+                self.action_search_prompt()
+                return
+            start = (self.selected + 1) % len(self.cells)
+            idx = self._search_from(start, +1)
+            if idx >= 0:
+                self._update_selection(idx)
+                if self.visual_mode:
+                    self._update_visual_flags()
+                self.notify(f"Found at cell {idx + 1}")
+            else:
+                self.notify("No match")
+
+        def action_search_prev(self) -> None:
+            if not self.search_query:
+                self.action_search_prompt()
+                return
+            start = (self.selected - 1) % len(self.cells)
+            idx = self._search_from(start, -1)
+            if idx >= 0:
+                self._update_selection(idx)
+                if self.visual_mode:
+                    self._update_visual_flags()
+                self.notify(f"Found at cell {idx + 1}")
+            else:
+                self.notify("No match")
+
+        # --- Go to first/last (gg / G) ---
+        def action_go_last(self) -> None:
+            last = len(self._cell_views) - 1
+            self._update_selection(last)
+            if self.visual_mode:
+                self._update_visual_flags()
+
+        def _g_timeout(self) -> None:
+            self._g_pending = False
+            self._g_timer = None
+
+        def action_go_prefix(self) -> None:
+            # Handle the "gg" sequence with a short timeout
+            if self._g_pending:
+                if self._g_timer is not None:
+                    try:
+                        self._g_timer.pause()
+                    except Exception:
+                        pass
+                    self._g_timer = None
+                self._g_pending = False
+                self._update_selection(0)
+                if self.visual_mode:
+                    self._update_visual_flags()
+                return
+            # Arm pending state and timer
+            self._g_pending = True
+            try:
+                self._g_timer = self.set_timer(0.7, self._g_timeout)
+            except Exception:
+                self._g_timer = None
+
+        def action_toggle_focus(self) -> None:
+            if self.visual_mode:
+                # In visual mode we always operate on input text; ignore toggling
+                self.notify(
+                    "Visual mode: focus locked to Input", severity="information"
+                )
+                return
+            cv = self._cell_views[self.selected]
+            # Only allow switching to output if there is text output
+            if cv.focus_region == "input":
+                txt = _cell_output_text(cv.cell)
+                if not txt.strip():
+                    # No output available; stay on input (optional hint)
+                    self.notify("No text output for this cell", severity="warning")
+                    return
+                cv.focus_region = "output"
+            else:
+                cv.focus_region = "input"
+            cv.refresh()
+
+        def action_copy(self) -> None:
+            # If in visual mode, copy all selected inputs
+            if self.visual_mode:
+                a, b = sorted((self.visual_anchor, self.selected))
+                pieces: list[str] = []
+                count = 0
+                for i in range(a, b + 1):
+                    cell = self.cells[i]
+                    if cell.get("cell_type") != "code":
+                        continue
+                    src = _cell_input_text(cell)
+                    if src.strip():
+                        pieces.append(src.rstrip("\n"))
+                        count += 1
+                text = "\n\n".join(pieces)
+                if not text:
+                    self.notify("No code in selection", severity="warning")
+                    return
+                ok, msg = _copy_to_clipboard(text)
+                self.notify(f"Copied {count} cell(s): {msg}")
+                # Exit visual mode after yank
+                self._set_visual(False)
+                return
+
+            # Normal single-cell copy of focused region
+            cv = self._cell_views[self.selected]
+            cell = cv.cell
+            if cv.focus_region == "input":
+                text = _cell_input_text(cell)
+            else:
+                text = _cell_output_text(cell)
+                if not text.strip():
+                    self.notify("No text output to copy", severity="warning")
+                    return
+            ok, msg = _copy_to_clipboard(text)
+            self.notify(msg)
+
+        def action_toggle_outputs(self) -> None:
+            # Toggle global hide/show for outputs
+            self.hide_outputs = not self.hide_outputs
+            for cv in self._cell_views:
+                cv.outputs_hidden = self.hide_outputs
+                cv.refresh()
+
+        def _update_selection(
+            self, new_index: int, ensure_visible: bool = True
+        ) -> None:
+            self._cell_views[self.selected].selected = False
+            self._cell_views[self.selected].refresh()
+            self.selected = new_index
+            sel = self._cell_views[self.selected]
+            sel.selected = True
+            sel.refresh()
+            # scroll into view
+            if ensure_visible:
+                self.call_after_refresh(lambda: sel.scroll_visible())
+
+        def _update_visual_flags(self) -> None:
+            # Mark cells in visual range
+            for i, cv in enumerate(self._cell_views):
+                in_range = self.visual_mode and (
+                    min(self.visual_anchor, self.selected)
+                    <= i
+                    <= max(self.visual_anchor, self.selected)
+                )
+                cv.in_visual = in_range
+                cv.refresh()
+
+        def _set_visual(self, on: bool) -> None:
+            self.visual_mode = on
+            if on:
+                self.visual_anchor = self.selected
+            # Update flags
+            self._update_visual_flags()
+            # Ensure focus is Input in visual mode
+            if on:
+                self._cell_views[self.selected].focus_region = "input"
+            else:
+                # Clear markers
+                for cv in self._cell_views:
+                    cv.in_visual = False
+                    cv.refresh()
+
+        def action_toggle_visual(self) -> None:
+            self._set_visual(not self.visual_mode)
+            self.notify("Visual mode" if self.visual_mode else "Visual off")
+
+    def run_textual_app(cells: list[dict[str, Any]]) -> int:
+        ensure_textual_available()
+        app = NotebookApp(cells)
+        app.run()
+        return 0
+else:
+
+    def run_textual_app(cells: list[dict[str, Any]]) -> int:  # pragma: no cover
+        ensure_textual_available()
+        return 1

nbsee-0.1.0/src/nbsee.egg-info/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: nbsee
+Version: 0.1.0
+Summary: Rich/Textual terminal viewer for Jupyter notebooks focused on copying code and text outputs
+Author: Yoga Yudistira
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AnakTeka/nbsee
+Project-URL: Repository, https://github.com/AnakTeka/nbsee
+Project-URL: Issues, https://github.com/AnakTeka/nbsee/issues
+Keywords: jupyter,notebook,cli,tui,rich,textual
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Environment :: Console
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.7
+Requires-Dist: textual>=0.58
+Dynamic: license-file
+
+nbsee
+=====
+
+Simple CLI viewer for Jupyter notebooks focused on fast reading and easy copying of code and text outputs from the terminal.
+
+Status: planning/design. See docs/TODO.md for the working task list.
+
+Goals (MVP)
+- Interactive terminal viewer for `.ipynb`.
+- Navigate cells with keys; focus input vs output.
+- Code cells: show source and text/plain outputs only.
+- Easy copying from the viewer using the keyboard (xclip).
+- Ignore images/HTML-rich outputs for now.
+
+Quick Concept (not implemented yet)
+- `nbsee notebook.ipynb` — open an interactive viewer.
+
+Key bindings (proposed)
+- `j`/`k`: move to next/previous cell
+- Arrow Up/Down: scroll the view line-by-line
+- PageUp/PageDown: page scroll
+- Ctrl+u / Ctrl+d: half-page scroll up/down
+- `Tab`: toggle focus between input (code/markdown) and output (text/plain)
+- If a cell has no text output, `Tab` does nothing and shows a brief message.
+- `y`: copy the currently focused region to clipboard using `xclip -selection clipboard`
+- `z`: hide/show all outputs (fold outputs)
+- `Shift+V`: start/stop visual selection for inputs; use `j`/`k` to expand/shrink; `y` copies all selected code cells
+- `/`: search (inputs+outputs). Enter to submit, `Esc` cancels
+- `n` / `N`: next/prev match
+- `gg` / `G`: jump to first / last cell
+- `G`/`gg`: jump to last/first cell (optional)
+- `q`: quit
+
+Notes
+- Copying uses Linux X11 clipboard via `xclip`. Wayland/macOS not targeted in MVP.
+- When an output is not available (e.g., no text/plain), copy will show an inline message.
+- Python syntax highlighting is built-in via Rich.
+
+Install (PyPI)
+- `python -m pip install nbsee`
+- Run: `nbsee path/to/notebook.ipynb`
+
+Development (uv)
+- Quick run without installing: `uv run -m nbsee path/to/notebook.ipynb`
+- Run tests: `uv run pytest`
+- Lint/format check: `uv run ruff check .` and `uv run ruff format --check .`
+- Build distributions: `uv build`
+- Release: push a tag like `v0.1.0` to trigger `.github/workflows/publish.yml` (requires PyPI trusted publishing setup).
+- Install editable and use `nbsee` command:
+  - Create venv: `uv venv`
+  - Activate: `source .venv/bin/activate`
+  - Install: `uv pip install -e .`
+  - Run: `nbsee path/to/notebook.ipynb`
+- Clipboard requirement: `xclip` on Linux/X11 must be installed and available in `PATH`.
+
+
+Docs
+- Design: `docs/DESIGN.md`
+- TODOs & roadmap: `docs/TODO.md`

nbsee-0.1.0/src/nbsee.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+docs/DESIGN.md
+docs/TODO.md
+src/nbsee/__init__.py
+src/nbsee/__main__.py
+src/nbsee/textual_app.py
+src/nbsee.egg-info/PKG-INFO
+src/nbsee.egg-info/SOURCES.txt
+src/nbsee.egg-info/dependency_links.txt
+src/nbsee.egg-info/entry_points.txt
+src/nbsee.egg-info/requires.txt
+src/nbsee.egg-info/top_level.txt
+tests/test_notebook_parsing.py

nbsee-0.1.0/src/nbsee.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nbsee-0.1.0/src/nbsee.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nbsee = nbsee.__main__:main

nbsee-0.1.0/src/nbsee.egg-info/requires.txt

@@ -0,0 +1,2 @@
+rich>=13.7
+textual>=0.58

nbsee-0.1.0/src/nbsee.egg-info/top_level.txt

@@ -0,0 +1 @@
+nbsee

nbsee-0.1.0/tests/test_notebook_parsing.py

@@ -0,0 +1,45 @@
+import json
+
+import pytest
+
+from nbsee.__main__ import _as_text, _cell_input_text, _cell_output_text, _load_notebook
+
+
+def test_as_text_handles_none_and_lists():
+    assert _as_text(None) == ""
+    assert _as_text(["a", "b", 3]) == "ab3"
+    assert _as_text("x") == "x"
+
+
+def test_cell_input_text_reads_source():
+    assert _cell_input_text({"source": "print(1)\n"}) == "print(1)\n"
+    assert _cell_input_text({"source": ["a\n", "b\n"]}) == "a\nb\n"
+
+
+def test_cell_output_text_supports_text_plain_stream_and_error():
+    cell = {
+        "cell_type": "code",
+        "outputs": [
+            {"output_type": "execute_result", "data": {"text/plain": ["1", "\n"]}},
+            {"output_type": "stream", "name": "stdout", "text": ["hello", "\n"]},
+            {"output_type": "error", "traceback": ["Traceback...", "\n", "Boom"]},
+        ],
+    }
+    assert _cell_output_text(cell) == "1\n\nhello\n\nTraceback...\nBoom"
+
+
+def test_cell_output_text_ignores_non_code_cells():
+    assert (
+        _cell_output_text({"cell_type": "markdown", "outputs": [{"text": "x"}]}) == ""
+    )
+
+
+def test_load_notebook_requires_cells_list(tmp_path):
+    good = tmp_path / "good.ipynb"
+    good.write_text(json.dumps({"cells": [{"cell_type": "markdown", "source": "hi"}]}))
+    assert _load_notebook(str(good)) == [{"cell_type": "markdown", "source": "hi"}]
+
+    bad = tmp_path / "bad.ipynb"
+    bad.write_text(json.dumps({"metadata": {}}))
+    with pytest.raises(ValueError, match="missing cells"):
+        _load_notebook(str(bad))