jsonl-cli 0.1.2__tar.gz

jsonl_cli-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taehoon Hwang
+
+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.

jsonl_cli-0.1.2/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: jsonl-cli
+Version: 0.1.2
+Summary: CLI JSONL viewer
+Requires-Python: >=3.9
+License-File: LICENSE
+Dynamic: license-file

jsonl_cli-0.1.2/README.md

@@ -0,0 +1,97 @@
+# jsonl-viewer
+
+A CLI tool to manually view the rows of a JSON lines file.
+
+![HellaSwag JSONL Sample](./resources/hellaswag_sample.png)
+Sample JSONL entry fron the HellaSwag dataset.
+
+## Requirements
+
+`curses` and Python (>= 3.9) must be installed.
+
+## Installation
+
+Run the following to install:
+```
+$ brew tap looooonk/tap
+$ brew install jsonl-cli
+```
+
+Alternatively, after cloning the repository, run the following installation command:
+
+```
+$ git clone https://github.com/looooonk/jsonl-viewer.git
+$ cd jsonl-viewer
+$ python -m pip install -e .
+```
+
+## Usage
+
+To view the contents of a JSON lines file, use
+
+```
+jsonl PATH_TO_FILE
+```
+
+To view a summary of a JSON lines file, use
+
+```
+jsonl PATH_TO_FILE -b
+```
+
+To view more information, use
+
+```
+jsonl -h
+```
+
+## Themes
+
+You can specify a certain color theme using the `-t` argument.
+
+Currently, 4 themes are supported:
+- `catppuccin-frappe`
+- `catppuccin-latte`
+- `catppuccin-macchiato`
+- `catppuccin-mocha`
+
+If not specified, the theme will default to `catppuccin-mocha`.
+
+You may add additional themes at `./json_cli/themes/`.
+
+## Commands
+For easy navigation, you can press `:` in the curses window to enter a command, much like vim.
+
+Currently, the following commands are supported:
+
+- Jump to certain line number (1-indexed):
+    ```
+    :goto INT
+    ```
+- Search all fields in parsed JSON rows:
+    ```
+    /TEXT
+    :find TEXT
+    ```
+- Search only specific fields, including nested fields:
+    ```
+    :find FIELD[,FIELD...]: TEXT
+    :find user.name,items[].title: alice
+    ```
+- Repeat the last search:
+    ```
+    n
+    N
+    :next
+    :prev
+    ```
+- Search options:
+    ```
+    :find -c TEXT
+    :find -r FIELD: REGEX
+    ```
+
+Field paths use `.` for nested objects, numeric list indexes such as `items.0.name`,
+`[]` for any list item, and `*` for any object value or list item. Search is
+case-insensitive by default; `-c` makes it case-sensitive and `-r` treats the
+query as a regular expression.

jsonl_cli-0.1.2/jsonl_cli/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

jsonl_cli-0.1.2/jsonl_cli/cli.py

@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+import argparse
+import curses
+import os
+from typing import List, Optional
+
+from .colors import _hex_to_rgb, _key_to_pair_id, _rgb_to_xterm256, _load_theme
+from .render import _render_json_styled, _wrap_styled_lines
+from .helpers import _validate_path, _build_offsets, _human_bytes, \
+                     _read_line_at, _scan_brief, _parse_row, _die
+from .command import _apply_command, _prompt_command
+from .search import SearchSpec, _find_next, _parse_search_spec
+
+
+def _viewer(stdscr: "curses._CursesWindow", path: str, theme: str) -> None:
+    """
+    Main driver code for the curses window.
+    
+    Args:
+        stdscr: The curses window to display to.
+        path:   Path to the JSONL file.
+    """
+    curses.curs_set(0)
+    
+    status_msg: str | None = None
+    
+    curses.start_color()
+    try:
+        curses.use_default_colors()
+    except curses.error:
+        pass
+    
+    color_theme = _load_theme(theme)
+
+    num_pairs = len(color_theme)
+    for i, hx in enumerate(color_theme, start=1):
+        r, g, b = _hex_to_rgb(hx)
+        fg = _rgb_to_xterm256(r, g, b)
+        try:
+            curses.init_pair(i, fg, -1)
+        except curses.error:
+            pass
+
+    def key_attr_fn(key: str) -> int:
+        pid = _key_to_pair_id(key, num_pairs)
+        return curses.A_BOLD | curses.color_pair(pid)
+
+    normal_attr = curses.A_NORMAL
+    
+    stdscr.keypad(True)
+
+    offsets = _build_offsets(path)
+    total_lines = max(0, len(offsets) - 1)
+
+    idx = 0
+    scroll = 0
+    indent_delta = 4
+    last_search: SearchSpec | None = None
+
+    def apply_search(raw: str, include_current: bool = False, direction: int = 1) -> None:
+        nonlocal idx, scroll, status_msg, last_search
+        spec, err = _parse_search_spec(raw)
+        if err:
+            status_msg = err
+            return
+
+        hit = _find_next(path, offsets, total_lines, idx, spec, direction, include_current)
+        last_search = spec
+        if hit is None:
+            status_msg = f"no match: {spec.label()}"
+            return
+
+        idx = hit.idx
+        scroll = 0
+        prefix = "wrapped to " if hit.wrapped else ""
+        status_msg = f"{prefix}row {idx + 1}: {spec.label()}"
+
+    def repeat_search(direction: int) -> None:
+        nonlocal idx, scroll, status_msg
+        if last_search is None:
+            status_msg = "no previous search"
+            return
+
+        hit = _find_next(path, offsets, total_lines, idx, last_search, direction, False)
+        if hit is None:
+            status_msg = f"no match: {last_search.label()}"
+            return
+
+        idx = hit.idx
+        scroll = 0
+        prefix = "wrapped to " if hit.wrapped else ""
+        status_msg = f"{prefix}row {idx + 1}: {last_search.label()}"
+
+    while True:
+        height, width = stdscr.getmaxyx()
+        stdscr.erase()
+
+        if total_lines == 0:
+            stdscr.addnstr(0, 0, "Empty file. Press q to quit.", width - 1)
+            stdscr.refresh()
+            ch = stdscr.getch()
+            if ch in (ord("q"), ord("Q")):
+                return
+            continue
+
+        if idx < 0:
+            idx = 0
+        if idx >= total_lines:
+            idx = total_lines - 1
+
+        start = offsets[idx]
+        end = offsets[idx + 1]
+        raw = _read_line_at(path, start, end)
+        row = _parse_row(raw, idx)
+
+        header = f"{os.path.basename(path)}  |  {idx + 1}/{total_lines}  |  ↑/↓ scroll  ←/→ row  / find  n/N next/prev  q quit"
+        stdscr.addnstr(0, 0, header, max(0, width - 1), curses.A_REVERSE)
+
+        title = row.title
+        stdscr.addnstr(1, 0, title, max(0, width - 1), curses.A_BOLD)
+
+        content_height = max(0, height - 3)
+        content_width = max(1, width - 1)
+
+        if row.ok:
+            styled_lines = _render_json_styled(row.obj, 0, key_attr_fn, normal_attr, indent_delta)
+        else:
+            raw = row.raw_fallback or ""
+            styled_lines = [[(raw, curses.A_DIM)]]
+
+        styled_lines = _wrap_styled_lines(styled_lines, content_width)
+
+        max_scroll = max(0, len(styled_lines) - content_height)
+        if scroll > max_scroll:
+            scroll = max_scroll
+        if scroll < 0:
+            scroll = 0
+
+        view = styled_lines[scroll : scroll + content_height]
+
+        for i, line in enumerate(view):
+            y = 2 + i
+            x = 0
+            remaining = content_width
+            for text, attr in line:
+                if remaining <= 0:
+                    break
+                if not text:
+                    continue
+                chunk = text[:remaining]
+                try:
+                    stdscr.addstr(y, x, chunk, attr)
+                except curses.error:
+                    pass
+                x += len(chunk)
+                remaining -= len(chunk)
+
+        footer = status_msg
+        if footer is None and max_scroll > 0:
+            footer = f"Lines {scroll} - {min(scroll + content_height, len(styled_lines))}"
+        if footer and height > 0:
+            stdscr.addnstr(height - 1, 0, footer, max(0, width - 1), curses.A_DIM)
+
+        stdscr.refresh()
+        ch = stdscr.getch()
+
+        if ch in (ord("q"), ord("Q")):
+            return
+        elif ch == ord(":"):
+            cmd = _prompt_command(stdscr, prompt=":")
+            status_msg = None
+            if cmd is not None:
+                parts = cmd.split(maxsplit=1)
+                name = parts[0].lower() if parts else ""
+                if name in ("find", "f", "search", "s"):
+                    apply_search(parts[1] if len(parts) == 2 else "", include_current=True)
+                elif name in ("next", "n"):
+                    repeat_search(1)
+                elif name in ("prev", "previous", "p"):
+                    repeat_search(-1)
+                else:
+                    new_idx, msg = _apply_command(cmd, total_lines, idx)
+                    if new_idx == -1:
+                        return
+                    idx = new_idx
+                    scroll = 0
+                    status_msg = msg
+        elif ch == ord("/"):
+            cmd = _prompt_command(stdscr, prompt="/")
+            status_msg = None
+            if cmd is not None:
+                apply_search(cmd, include_current=True)
+        elif ch == ord("n"):
+            repeat_search(1)
+        elif ch == ord("N"):
+            repeat_search(-1)
+        elif ch == curses.KEY_DOWN:
+            scroll += 1
+        elif ch == curses.KEY_UP:
+            scroll -= 1
+        elif ch == curses.KEY_LEFT:
+            idx -= 1
+            scroll = 0
+        elif ch == curses.KEY_RIGHT:
+            idx += 1
+            scroll = 0
+        elif ch in (curses.KEY_NPAGE,):
+            indent_delta = max(indent_delta - 1, 1)
+        elif ch in (curses.KEY_PPAGE,):
+            indent_delta = min(indent_delta + 1, 8)
+        elif ch == curses.KEY_RESIZE:
+            pass
+        else:
+            pass
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    parser = argparse.ArgumentParser(prog="jsonl", add_help=True)
+    parser.add_argument("file", metavar="FILE", help="Path to a .jsonl file")
+    parser.add_argument("-b", "--brief", action="store_true", help="Show file characteristics and exit")
+    parser.add_argument("-t", "--theme", metavar="STR", type=str, default="catppuccin-mocha", help="Color theme")
+    args = parser.parse_args(argv)
+
+    path = _validate_path(args.file)
+
+    if args.brief:
+        line_count, size, cols, invalid = _scan_brief(path)
+        print(f"File: {path}")
+        print(f"Size: {_human_bytes(size)} ({size} bytes)")
+        print(f"Lines: {line_count}")
+        if invalid:
+            print(f"Invalid JSON lines: {invalid}")
+        print("Columns:")
+        if cols:
+            for c in cols:
+                print(f"  - {c}")
+        else:
+            print("  (no object keys found)")
+        return
+
+    try:
+        curses.wrapper(_viewer, path, args.theme)
+    except KeyboardInterrupt:
+        return
+    except curses.error as e:
+        _die(f"curses error: {e}", code=1)

jsonl_cli-0.1.2/jsonl_cli/colors.py

@@ -0,0 +1,84 @@
+import zlib
+import json
+from pathlib import Path
+from typing import List
+
+
+def _hex_to_rgb(h: str) -> tuple[int, int, int]:
+    """
+    Converts a hex color string into RGB values.
+    
+    Args:
+        h: The hex string.
+    
+    Returns:
+        A 3-tuple of the RGB values in base 16, each between 00 and FF inclusive.
+    """
+    h = h.lstrip("#")
+    return (int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16))
+
+
+def _rgb_to_xterm256(r: int, g: int, b: int) -> int:
+    """
+    Maps 24-bit RGB values to xterm-256 color indices.
+    Will always map the closest possible color.
+    
+    Args:
+        r: The base 16 value for red.
+        g: The base 16 value for green.
+        b: The base 16 value for blue.
+    
+    Returns:
+        The index of the corresponding xterm-256 color.
+    """
+    if r == g == b:
+        if r < 8:
+            return 16
+        if r > 248:
+            return 231
+        return 232 + (r - 8) // 10
+
+    def to_6(x: int) -> int:
+        return int(round(x / 255 * 5))
+
+    rr, gg, bb = to_6(r), to_6(g), to_6(b)
+    return 16 + 36 * rr + 6 * gg + bb
+
+
+def _key_to_pair_id(key: str, num_pairs: int) -> int:
+    """
+    Maps a string to a color via hashing.
+    Uses zlib.crc32() as the hash function.
+    
+    Args:
+        key:       The string to assign a color to.
+        num_pairs: The number of colors that can be assigned.
+        
+    Returns:
+        The index in curses corresponding to that color.
+        Note that index 0 in curses corresponds to the default text color, so the return value is 1-indexed.
+    """
+    h = zlib.crc32(key.encode("utf-8")) & 0xFFFFFFFF
+    return 1 + (h % num_pairs)
+
+
+def _load_theme(theme: str) -> List[str]:
+    """
+    Loads a theme's hex colors.
+    
+    Args:
+        theme: Name of the theme.
+    
+    Returns:
+        A list of strings that represent hex colors for that theme.
+    """
+    try:
+        path = Path(__file__).parent / "themes" / f"{theme}.json"
+        with path.open("r", encoding="utf-8") as f:
+            data = json.load(f)
+        return data["key-colors"]
+    except:
+        path = Path(__file__).parent / "themes" / "catppuccin-mocha.json" # Default
+        with path.open("r", encoding="utf-8") as f:
+            data = json.load(f)
+        return data["key-colors"]

jsonl_cli-0.1.2/jsonl_cli/command.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import curses
+
+
+def _prompt_command(stdscr: "curses._CursesWindow", prompt: str = ":") -> str | None:
+    """
+    Read a command from the bottom line.
+
+    Args:
+        stdscr: The curses window to display to.
+        prompt: The prompt / command to read.
+    
+    Returns:
+        The command string (without leading ':') or None if cancelled (ESC).
+    """
+    height, width = stdscr.getmaxyx()
+    y = height - 1
+
+    buf: list[str] = []
+    pos = 0
+
+    stdscr.move(y, 0)
+    stdscr.clrtoeol()
+    stdscr.addnstr(y, 0, prompt, width - 1, curses.A_REVERSE)
+    stdscr.refresh()
+
+    while True:
+        ch = stdscr.get_wch()
+
+        if ch == "\x1b":
+            return None
+
+        if ch in ("\n", "\r"):
+            return "".join(buf).strip()
+
+        if ch in (curses.KEY_BACKSPACE, "\b", "\x7f"):
+            if pos > 0:
+                buf.pop(pos - 1)
+                pos -= 1
+
+        elif ch == curses.KEY_LEFT:
+            pos = max(0, pos - 1)
+        elif ch == curses.KEY_RIGHT:
+            pos = min(len(buf), pos + 1)
+        elif ch == curses.KEY_HOME:
+            pos = 0
+        elif ch == curses.KEY_END:
+            pos = len(buf)
+        elif isinstance(ch, str) and ch.isprintable():
+            buf.insert(pos, ch)
+            pos += 1
+
+        cmd_text = prompt + "".join(buf)
+        if len(cmd_text) >= width:
+            cmd_text = cmd_text[-(width - 1):]
+        stdscr.move(y, 0)
+        stdscr.clrtoeol()
+        stdscr.addnstr(y, 0, cmd_text, width - 1, curses.A_REVERSE)
+
+        cursor_x = min(width - 1, len(prompt) + pos)
+        stdscr.move(y, cursor_x)
+        stdscr.refresh()
+
+
+def _apply_command(cmd: str, total_lines: int, idx: int) -> tuple[int, str | None]:
+    """
+    Applies a command string.
+    
+    Args:
+        cmd:         The command inputted.
+        total_lines: The number of rows in the JSONL file.
+        idx:         The current index being viewed.
+    
+    Returns:
+        A tuple (new_idx, status_message_or_None).
+    """
+    if not cmd:
+        return idx, None
+
+    parts = cmd.split()
+    name = parts[0].lower()
+
+    if name in ("goto", "g") and len(parts) == 2:
+        try:
+            n = int(parts[1])
+        except ValueError:
+            return idx, "goto expects an integer row number"
+
+        if total_lines <= 0:
+            return idx, "file has no rows"
+
+        n = max(1, min(total_lines, n))
+        return n - 1, None
+
+    if name in ("q", "quit", "exit"):
+        return -1, None
+
+    return idx, f"unknown command: {cmd}"

jsonl_cli-0.1.2/jsonl_cli/containers.py

@@ -0,0 +1,14 @@
+from dataclasses import dataclass
+from typing import Any, Optional
+
+# We use this datastructure since different portions of 1 line need to have different curses bitmasks (due to colors and bolding).
+Segment = tuple[str, int]  # (raw_text, curses_attribute_bitmask)
+StyledLine = list[Segment] # 1 Line in the output
+
+# A container for 1 JSONL row.
+@dataclass
+class RowData:
+    ok: bool                            # Whether the line has been successfully parsed to JSON.
+    title: str                          # The status for the row displayed at the top of the window.
+    obj: Any = None                     # The parsed Python object for this JSONL row.
+    raw_fallback: Optional[str] = None  # Fallback raw JSONL text for failed formatting.