curses-components 26.7.2__tar.gz → 26.9.2__tar.gz

{curses_components-26.7.2 → curses_components-26.9.2}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: curses_components
-Version: 26.7.2
+Version: 26.9.2
 Summary: A reusable curses component library for terminal UI (TUI) applications.
 Author: Cobus Nel
 License-Expression: MIT
 Project-URL: Repository, https://github.com/cobusn/curses_components
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.13
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pyperclip
@@ -92,10 +92,27 @@ See examples/ for runnable demos:
 GridComponent key bindings
 --------------------------
 
+Grid extensions can display reusable popups through `show_popup`:
+
+    grid.show_popup('Messages', lines=['first line', 'second line'])
+    grid.show_popup('Results', rows=[('Name', 'Alice'), ('State', 'Active')])
+
+The popup inherits the grid's configured colors.
+
+Commands can be added with a handler that receives the grid and parsed
+arguments:
+
+    def show_current_column(grid, args):
+        column = grid.columns[grid.col_idx]
+        grid.show_popup(column, lines=[str(row.get(column, ''))
+                                       for row in grid.data])
+
+    grid.register_command('values', show_current_column)
+
 Navigation:   j/k/h/l or arrow keys, Home/End, Page Up/Down, ^/$
 Search:       / (substring), r/<pattern> (regex), n/N (next/previous)
 Input mode:   : (enter), q (quit), sort, filter, col, freeze, copy,
-              copyrow, export <file>
+              copyrow, count, export <file>
 Sorting:      sort col1 col2!   (! suffix = descending)
 Filtering:    filter <val>      (current column, wildcards supported)
               filter reset
@@ -127,7 +144,7 @@ EditorPopup also accepts bold=True (bright text) and bold_background=True.
 Dependencies
 ------------
 
-- Python 3.13+
+- Python 3.8+
 - pyperclip (for copy/copyrow commands in GridComponent)
 
 License

{curses_components-26.7.2 → curses_components-26.9.2}/README.md

@@ -77,10 +77,27 @@ See examples/ for runnable demos:
 GridComponent key bindings
 --------------------------
 
+Grid extensions can display reusable popups through `show_popup`:
+
+    grid.show_popup('Messages', lines=['first line', 'second line'])
+    grid.show_popup('Results', rows=[('Name', 'Alice'), ('State', 'Active')])
+
+The popup inherits the grid's configured colors.
+
+Commands can be added with a handler that receives the grid and parsed
+arguments:
+
+    def show_current_column(grid, args):
+        column = grid.columns[grid.col_idx]
+        grid.show_popup(column, lines=[str(row.get(column, ''))
+                                       for row in grid.data])
+
+    grid.register_command('values', show_current_column)
+
 Navigation:   j/k/h/l or arrow keys, Home/End, Page Up/Down, ^/$
 Search:       / (substring), r/<pattern> (regex), n/N (next/previous)
 Input mode:   : (enter), q (quit), sort, filter, col, freeze, copy,
-              copyrow, export <file>
+              copyrow, count, export <file>
 Sorting:      sort col1 col2!   (! suffix = descending)
 Filtering:    filter <val>      (current column, wildcards supported)
               filter reset
@@ -112,7 +129,7 @@ EditorPopup also accepts bold=True (bright text) and bold_background=True.
 Dependencies
 ------------
 
-- Python 3.13+
+- Python 3.8+
 - pyperclip (for copy/copyrow commands in GridComponent)
 
 License

{curses_components-26.7.2 → curses_components-26.9.2}/curses_components/__init__.py

@@ -1,7 +1,8 @@
 # SPDX-License-Identifier: MIT
 # Copyright (c) 2026 Cobus Nel
-__version__ = "26.7.2"
+__version__ = "26.9.2"
 
 from curses_components.editor import EditorPopup
+from curses_components.grid import CommandHandler, GridComponent
 from curses_components.popup import EditorHelpPopup, HelpPopup, ScrollablePopup
 from curses_components.theme import COLORS, resolve_color

{curses_components-26.7.2 → curses_components-26.9.2}/curses_components/editor.py

@@ -612,7 +612,12 @@ class EditorPopup:
             return None
 
         if verb == 'help':
-            EditorHelpPopup(self.stdscr).display()
+            EditorHelpPopup(
+                self.stdscr,
+                fg_color=self.fg_color,
+                bg_color=self.bg_color,
+                border_color=self.border_color,
+            ).display()
             return None
 
         self._status_msg = f'unknown command: {verb}'

{curses_components-26.7.2 → curses_components-26.9.2}/curses_components/grid.py

@@ -10,12 +10,14 @@ import json
 import logging
 import re
 import time
+from collections import Counter
+from typing import Protocol, Sequence
+
 import pyperclip
 
-from curses_components.popup import HelpPopup
+from curses_components.popup import HelpPopup, ScrollablePopup, TextPopup
 from curses_components.theme import resolve_color
 
-
 logging.basicConfig(filename='help_debug.log', level=logging.DEBUG)
 
 
@@ -23,6 +25,13 @@ class QuitApplication(Exception):
     """Custom exception to signal application exit."""
 
 
+class CommandHandler(Protocol):
+    """Public signature for commands registered by grid extensions."""
+
+    def __call__(self, grid: "GridComponent", args: Sequence[str]) -> None:
+        """Handle a command for the grid and its parsed arguments."""
+
+
 
 class GridComponent:
     """
@@ -64,6 +73,7 @@ class GridComponent:
             "col": self._cmd_col,
             "copy": self._cmd_copy,
             "copyrow": self._cmd_copyrow,
+            "count": self._cmd_count,
             "export": self._cmd_export,
             "filter": self._cmd_filter,
             "freeze": self._cmd_freeze,
@@ -73,6 +83,21 @@ class GridComponent:
             "sort": self._cmd_sort,
         }
 
+    def register_command(self, name: str, handler: CommandHandler) -> None:
+        """Register an extension command receiving ``(grid, args)``."""
+        if not isinstance(name, str):
+            raise TypeError("command name must be a string")
+        command_name = name.strip().lower()
+        if not command_name or any(char.isspace() for char in command_name):
+            raise ValueError("command name must be a non-empty single token")
+        if not callable(handler):
+            raise TypeError("command handler must be callable")
+
+        def invoke(args):
+            return handler(self, args)
+
+        self.commands[command_name] = invoke
+
     def display(self, data, columns=None, max_rows=10000):
         """
         Initializes the curses application and displays the grid.
@@ -164,6 +189,27 @@ class GridComponent:
         self.error_message = message
         self.error_message_expiry = time.time() + delay
 
+    def show_popup(self, title, *, rows=None, lines=None, key_col_width=20):
+        """Display a scrollable popup with text lines or two-column rows."""
+        if (rows is None) == (lines is None):
+            raise ValueError("provide exactly one of rows or lines")
+
+        popup_kwargs = {
+            "title": title,
+            "fg_color": self.fg_color,
+            "bg_color": self.bg_color,
+            "border_color": self.border_color,
+        }
+        if lines is not None:
+            TextPopup(self.stdscr, lines, **popup_kwargs).display()
+        else:
+            ScrollablePopup(
+                self.stdscr,
+                rows=rows,
+                key_col_width=key_col_width,
+                **popup_kwargs,
+            ).display()
+
     def _get_col_stats(self, col):
         """Returns (min, max, avg, count) for a numeric column over current data, or None."""
         values = [float(str(row.get(col, ''))) for row in self.data
@@ -372,6 +418,40 @@ class GridComponent:
             pyperclip.copy(json.dumps(row, ensure_ascii=False))
             self.show_error("Row copied as JSON", delay=0.8)
 
+    def _cmd_count(self, _cmds):
+        """Display counts of distinct raw values in the current column."""
+        if _cmds:
+            self.show_error("Usage: count")
+            return
+        if not self.data or not self.columns:
+            self.show_error("No data to count")
+            return
+
+        column = self.columns[self.col_idx]
+        values = [row.get(column, '') for row in self.data]
+        try:
+            counts = Counter(values)
+        except TypeError:
+            self.show_error("Cannot count unhashable values")
+            return
+        rows = [("Value", "Count"), ("", "")]
+        rows.extend(
+            (str(value), str(count))
+            for value, count in sorted(
+                counts.items(),
+                key=lambda item: (-item[1], str(item[0])),
+            )
+        )
+        key_col_width = min(
+            40,
+            max(24, max((len(str(value)) for value in counts), default=0) + 3),
+        )
+        self.show_popup(
+            f"{column} ({len(counts)} unique)",
+            rows=rows,
+            key_col_width=key_col_width,
+        )
+
     def _cmd_export(self, _cmds):
         """Handles the 'export' command, writing current data to a CSV file."""
         if not _cmds:
@@ -389,8 +469,11 @@ class GridComponent:
 
     def _cmd_help(self, _cmds):
         """Handles the 'help' command, displaying the help screen."""
-        help_screen = HelpPopup(self.stdscr)
-        help_screen.display()
+        self.show_popup(
+            HelpPopup.title,
+            rows=HelpPopup(self.stdscr).rows,
+            key_col_width=HelpPopup.key_col_width,
+        )
 
     def _cmd_dollar(self, _cmds):
         """Handles the '$' command, moving to the last row."""
@@ -662,8 +745,7 @@ class GridComponent:
                 else:
                     self.show_error("No mark set")
             elif key == ord('?'):
-                help_screen = HelpPopup(self.stdscr)
-                help_screen.display()
+                self._cmd_help([])
 
     def _get_visible_cols(self):
         """Returns a list of scrollable column names currently visible on screen."""

{curses_components-26.7.2 → curses_components-26.9.2}/curses_components/popup.py

@@ -3,6 +3,9 @@
 """Reusable curses popup components."""
 
 import curses
+from collections import Counter
+
+from curses_components.theme import resolve_color
 
 
 class ScrollablePopup:
@@ -22,16 +25,34 @@ class ScrollablePopup:
     title = ""
     key_col_width = 20  # characters reserved for the left column
 
-    def __init__(self, stdscr):
+    def __init__(self, stdscr, title=None, rows=None, key_col_width=None,
+                 fg_color=None, bg_color=None, border_color=None):
         self.stdscr = stdscr
+        if title is not None:
+            self.title = title
+        self._rows = rows
+        if key_col_width is not None:
+            self.key_col_width = key_col_width
+        self.fg_color = fg_color
+        self.bg_color = bg_color
+        self.border_color = border_color
         self.scroll_pos = 0
 
+    def _init_colors(self):
+        """Initialize color pairs used by the popup."""
+        bg = resolve_color(self.bg_color, -1)
+        fg = resolve_color(self.fg_color, -1)
+        border = resolve_color(self.border_color, -1)
+        curses.init_pair(5, fg, bg)
+        curses.init_pair(6, border, bg)
+
     @property
     def rows(self):
         """Return a list of (left, right) string tuples to display."""
-        return []
+        return self._rows or []
 
     def display(self):
+        self._init_colors()
         height, width = self.stdscr.getmaxyx()
         win_height = min(25, height - 2)
         win_width = min(80, width - 2)
@@ -44,23 +65,48 @@ class ScrollablePopup:
         max_scroll = max(0, len(content) - (win_height - 4))
 
         while True:
+            win.attrset(curses.color_pair(6))
             win.border()
             title = self.title
-            win.addstr(0, max(0, (win_width - len(title)) // 2), title, curses.A_REVERSE)
+            title_x = max(0, (win_width - len(title)) // 2)
+            win.addstr(
+                0,
+                title_x,
+                title[:max(0, win_width - title_x - 1)],
+                curses.color_pair(6) | curses.A_REVERSE,
+            )
 
             for i in range(1, win_height - 1):
-                win.addstr(i, 1, " " * (win_width - 2))
+                win.addstr(i, 1, " " * (win_width - 2), curses.color_pair(5))
 
             text_y = 2
             for left, right in content[self.scroll_pos:]:
                 if text_y >= win_height - 2:
                     break
-                win.addstr(text_y, 2, left, curses.A_BOLD)
+                left_width = max(0, self.key_col_width - 3)
+                right_width = max(0, win_width - self.key_col_width - 2)
+                win.addstr(
+                    text_y,
+                    2,
+                    left[:left_width],
+                    curses.color_pair(5) | curses.A_BOLD,
+                )
                 if right:
-                    win.addstr(text_y, self.key_col_width, right)
+                    win.addstr(
+                        text_y,
+                        self.key_col_width,
+                        right[:right_width],
+                        curses.color_pair(5),
+                    )
                 text_y += 1
 
-            win.addstr(win_height - 2, 2, "Press 'q' to close...")
+            footer = "Press 'q' to close..."
+            win.addstr(
+                win_height - 2,
+                2,
+                footer[:max(0, win_width - 4)],
+                curses.color_pair(5),
+            )
             win.noutrefresh()
             curses.doupdate()
 
@@ -73,6 +119,27 @@ class ScrollablePopup:
                 self.scroll_pos = min(max_scroll, self.scroll_pos + 1)
 
 
+class TextPopup(ScrollablePopup):
+    """Popup displaying one scrollable line of text per row."""
+
+    def __init__(self, stdscr, lines, **kwargs):
+        super().__init__(stdscr, **kwargs)
+        self.lines = [str(line) for line in lines]
+
+    @property
+    def rows(self):
+        return [(line, "") for line in self.lines]
+
+    def display(self):
+        original_key_col_width = self.key_col_width
+        screen_width = self.stdscr.getmaxyx()[1]
+        self.key_col_width = min(80, max(1, screen_width - 2))
+        try:
+            super().display()
+        finally:
+            self.key_col_width = original_key_col_width
+
+
 class HelpPopup(ScrollablePopup):
     """Help popup for GridComponent."""
 
@@ -106,6 +173,7 @@ class HelpPopup(ScrollablePopup):
             ("sort col1 col2!", "col1 asc, col2 desc (! = descending)"),
             ("copy", "Copy current cell value"),
             ("copyrow", "Copy current row as JSON"),
+            ("count", "Count distinct values in current column"),
             ("export <file>", "Export current data to CSV file"),
             ("ESC", "Exit input mode"),
             ("", ""),
@@ -131,6 +199,40 @@ class HelpPopup(ScrollablePopup):
         ]
 
 
+class ValueCountPopup(ScrollablePopup):
+    """Popup displaying the frequency of each value in a grid column."""
+
+    title = "Value Counts"
+
+    def __init__(self, stdscr, column, values, **colors):
+        super().__init__(stdscr, **colors)
+        self.column = column
+        self.counts = Counter(values)
+        self.key_col_width = min(
+            40,
+            max(
+                24,
+                max((len(str(value)) for value in self.counts), default=0) + 3,
+            ),
+        )
+
+    @property
+    def rows(self):
+        rows = [("Value", "Count"), ("", "")]
+        rows.extend(
+            (str(value), str(count))
+            for value, count in sorted(
+                self.counts.items(),
+                key=lambda item: (-item[1], str(item[0])),
+            )
+        )
+        return rows
+
+    def display(self):
+        self.title = f"{self.column} ({len(self.counts)} unique)"
+        super().display()
+
+
 class EditorHelpPopup(ScrollablePopup):
     """Help popup for EditorPopup."""
 

{curses_components-26.7.2 → curses_components-26.9.2}/curses_components.egg-info/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: curses_components
-Version: 26.7.2
+Version: 26.9.2
 Summary: A reusable curses component library for terminal UI (TUI) applications.
 Author: Cobus Nel
 License-Expression: MIT
 Project-URL: Repository, https://github.com/cobusn/curses_components
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.13
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pyperclip
@@ -92,10 +92,27 @@ See examples/ for runnable demos:
 GridComponent key bindings
 --------------------------
 
+Grid extensions can display reusable popups through `show_popup`:
+
+    grid.show_popup('Messages', lines=['first line', 'second line'])
+    grid.show_popup('Results', rows=[('Name', 'Alice'), ('State', 'Active')])
+
+The popup inherits the grid's configured colors.
+
+Commands can be added with a handler that receives the grid and parsed
+arguments:
+
+    def show_current_column(grid, args):
+        column = grid.columns[grid.col_idx]
+        grid.show_popup(column, lines=[str(row.get(column, ''))
+                                       for row in grid.data])
+
+    grid.register_command('values', show_current_column)
+
 Navigation:   j/k/h/l or arrow keys, Home/End, Page Up/Down, ^/$
 Search:       / (substring), r/<pattern> (regex), n/N (next/previous)
 Input mode:   : (enter), q (quit), sort, filter, col, freeze, copy,
-              copyrow, export <file>
+              copyrow, count, export <file>
 Sorting:      sort col1 col2!   (! suffix = descending)
 Filtering:    filter <val>      (current column, wildcards supported)
               filter reset
@@ -127,7 +144,7 @@ EditorPopup also accepts bold=True (bright text) and bold_background=True.
 Dependencies
 ------------
 
-- Python 3.13+
+- Python 3.8+
 - pyperclip (for copy/copyrow commands in GridComponent)
 
 License

{curses_components-26.7.2 → curses_components-26.9.2}/curses_components.egg-info/top_level.txt

@@ -1,3 +1,4 @@
+_resume
 attic
 build
 curses_components

{curses_components-26.7.2 → curses_components-26.9.2}/pyproject.toml

@@ -9,7 +9,7 @@ description = "A reusable curses component library for terminal UI (TUI) applica
 readme = "README.md"
 license = "MIT"
 authors = [{ name = "Cobus Nel" }]
-requires-python = ">=3.13"
+requires-python = ">=3.8"
 dependencies = ["pyperclip"]
 classifiers = [
     "Programming Language :: Python :: 3",