console-window 2.0.0.7__tar.gz → 2.0.0.9__tar.gz

{console_window-2.0.0.7 → console_window-2.0.0.9}/CHANGELOG.md

@@ -6,6 +6,10 @@ This project follows [Semantic Versioning](https://semver.org/).
 ## [Unreleased]
 
 ### Added
+- `line_attr` on `add_fancy_header()`/`add_header_line()`: an attribute OR'd
+  into every span of the header (including plain spans and the raw line emitted
+  for `mode='Off'`), so a caller can dim a whole fancy header while keeping the
+  per-span bold/underline/reverse styling.
 - `suspend_curses()`/`resume_curses()` on `ConsoleWindow`: leave curses mode
   with `endwin()` while keeping the window (pads, content model, pick state)
   alive, then reattach a screen and repaint.  This is the supported way for an
@@ -135,6 +139,16 @@ This project follows [Semantic Versioning](https://semver.org/).
   No in-repo code used it.
 
 ### Fixed
+- `win._start_curses()` once again *reattaches* the window.  The 1.4.x
+  compatibility hook is still called in the wild (psistat's "dump event log"
+  path uses `self.window._start_curses()` to return from shell mode), but the
+  2.0 implementation only created and returned a screen, leaving `win.scr` as
+  `None`; the next `clear()`/`render()` then raised
+  `AttributeError: 'NoneType' object has no attribute 'clear'`.  It now resumes
+  a suspended window through `resume_curses()` (singleton mode reattaches every
+  window sharing the screen), so the pads and the content model survive, and
+  `clear()` while suspended resets the content model without dereferencing the
+  missing screen.
 - Starting a window on a terminal with fewer than 256 colours (including tmux's
   stock `TERM=screen`, whose terminfo entry has 8 colours) no longer crashes with
   `ValueError: Color number is greater than COLORS-1`. Theme installation now

{console_window-2.0.0.7 → console_window-2.0.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: console-window
-Version: 2.0.0.7
+Version: 2.0.0.9
 Summary: A robust curses wrapper for creating Text User Interfaces (TUIs).
 Author-email: Joe Defen <joedef@duck.com>
 Requires-Python: >=3.10
@@ -122,7 +122,9 @@ demonstrates:
   sizes.
 * **`flash()`** — transient, non-destructive status messages.
 * **Token-based headers** — `HeaderLine` (`text`, `bracket_key`, `key`, `extend`)
-  rendered with `add_header_line()`, rather than string markup.
+  rendered with `add_header_line()`, rather than string markup. Both header
+  helpers accept `line_attr`, an attribute OR'd into every span, so a whole
+  header can be dimmed (`curses.A_DIM`) without losing its per-span styling.
 * **`Ctrl-C` as an application key** — `ctrl_c_terminates=False` and
   `keys={0x3, ord('q')}` on the quit action. This works only while no live
   window in the process has requested terminating Ctrl-C: once any window uses
@@ -223,6 +225,9 @@ screen handle, backend, dimensions, pad backgrounds and redraw bookkeeping.
 In singleton mode `suspend_curses()` suspends every window that shares the
 screen, and `resume_curses()` reattaches all of them. The legacy pair works the
 same way there: `ConsoleWindow.stop_curses(); ...; ConsoleWindow.start_curses()`.
+The pre-2.0 instance hook `win._start_curses()` is also supported: it reattaches
+that window (resuming a suspended screen) and returns the live screen, so the
+old `win.stop_curses(); ...; win._start_curses()` sequence keeps working.
 Only `stop_all()` is a permanent teardown.
 
 The first successful construction latches the mode for the whole process.

{console_window-2.0.0.7 → console_window-2.0.0.9}/README.md

@@ -103,7 +103,9 @@ demonstrates:
   sizes.
 * **`flash()`** — transient, non-destructive status messages.
 * **Token-based headers** — `HeaderLine` (`text`, `bracket_key`, `key`, `extend`)
-  rendered with `add_header_line()`, rather than string markup.
+  rendered with `add_header_line()`, rather than string markup. Both header
+  helpers accept `line_attr`, an attribute OR'd into every span, so a whole
+  header can be dimmed (`curses.A_DIM`) without losing its per-span styling.
 * **`Ctrl-C` as an application key** — `ctrl_c_terminates=False` and
   `keys={0x3, ord('q')}` on the quit action. This works only while no live
   window in the process has requested terminating Ctrl-C: once any window uses
@@ -204,6 +206,9 @@ screen handle, backend, dimensions, pad backgrounds and redraw bookkeeping.
 In singleton mode `suspend_curses()` suspends every window that shares the
 screen, and `resume_curses()` reattaches all of them. The legacy pair works the
 same way there: `ConsoleWindow.stop_curses(); ...; ConsoleWindow.start_curses()`.
+The pre-2.0 instance hook `win._start_curses()` is also supported: it reattaches
+that window (resuming a suspended screen) and returns the live screen, so the
+old `win.stop_curses(); ...; win._start_curses()` sequence keeps working.
 Only `stop_all()` is a permanent teardown.
 
 The first successful construction latches the mode for the whole process.

{console_window-2.0.0.7 → console_window-2.0.0.9}/console_window/__init__.py

@@ -1,6 +1,6 @@
 # Single source of truth for the package version: pyproject.toml declares
 # ``dynamic = ["version"]``, so flit reads this value instead of duplicating it.
-__version__ = "2.0.0.7"
+__version__ = "2.0.0.9"
 
 from .context import Context
 from .header import HeaderLine, Span

{console_window-2.0.0.7 → console_window-2.0.0.9}/console_window/window.py

@@ -291,7 +291,7 @@ class ConsoleWindow:
             self._backend = ConsoleWindow._static_backend or self._backend
             self.scr = ConsoleWindow.static_scr
         else:
-            self.scr = self._start_curses()
+            self.scr = self._new_screen()
             if self.singleton:
                 ConsoleWindow.static_scr = self.scr
                 ConsoleWindow._static_backend = self._backend
@@ -581,9 +581,42 @@ class ConsoleWindow:
 
         return True
 
-    def _start_curses(self) -> CursesSurface:
+    def _new_screen(self) -> CursesSurface:
+        """Create and initialise a brand-new screen for this window."""
         return self._init_screen(self._backend, self.theme)
 
+    def _start_curses(self) -> CursesSurface:
+        """Re-enter curses for this window and return the live screen.
+
+        Pre-2.0 exposed ``_start_curses()`` as the "come back after
+        ``stop_curses()``" call, and applications (psistat among them) kept
+        calling it on the instance.  It therefore has to *reattach* the
+        window, not merely create a screen: the old implementation returned a
+        fresh screen without storing it, so ``self.scr`` stayed ``None`` and
+        the first ``clear()``/``render()`` after returning from shell mode
+        raised ``AttributeError: 'NoneType' object has no attribute 'clear'``.
+
+        A suspended window resumes through :meth:`resume_curses` (in singleton
+        mode that reattaches every window sharing the screen), so the pads and
+        the content model survive.  ``start_curses()`` remains the class-level
+        entry point for both models.
+        """
+        if self.suspended:
+            scr = self.resume_curses()
+            if scr is not None:
+                return scr
+        if self.scr is not None:
+            return self.scr
+        # Not suspended but screen-less: restart a screen and attach this
+        # window to it.  Singleton mode owns a process-wide screen, so reuse the
+        # class-level starter; per-instance windows create their own.
+        scr = ConsoleWindow.start_curses() if self.singleton else self._new_screen()
+        if self.scr is None:  # start_curses() may have reattached it already
+            backend = (ConsoleWindow._static_backend if self.singleton else None) \
+                or self._backend
+            self._attach_screen(scr, backend)
+        return scr
+
     def _attach_screen(self, scr: CursesSurface, backend: RenderBackend) -> None:
         """Point this window at a (re)started screen and force a full repaint.
 
@@ -952,7 +985,8 @@ class ConsoleWindow:
         self._add(self.body, text, attr, resume, context, is_body=True)
 
     def add_fancy_header(self, line: str | HeaderLine, mode: str = 'Underline',
-                         search_pattern_attr: int | None = None) -> None:
+                         search_pattern_attr: int | None = None,
+                         line_attr: int | None = None) -> None:
         """Add a header line with legacy ``[x]``/``KEY:``/``/pattern`` markup.
 
         String input is parsed unless ``mode='Off'``.  A :class:`HeaderLine`
@@ -960,44 +994,67 @@ class ConsoleWindow:
         treated as markup too: in every mode except ``'Off'`` they are removed,
         while the enclosed key keeps its ``KEY`` styling.  Use
         :meth:`add_header_line` when literal brackets are wanted.
+
+        *line_attr* is OR'd into the attribute of every span (and into the raw
+        line emitted for ``mode='Off'``), so a caller can, for example, dim a
+        whole header with ``line_attr=curses.A_DIM`` while keeping each span's
+        own bold/underline/reverse styling.
         """
         if isinstance(line, str):
             if mode == 'Off':
-                # Legacy: no markup processing, add the raw line unchanged.
-                self.add_header(line)
+                # Legacy: no markup processing, add the raw line unchanged
+                # (except for the caller's whole-line attribute).
+                self.add_header(line, attr=line_attr)
                 return
             spans = parse_fancy_header(line)
         else:
             spans = list(line)
             if mode != 'Off':
                 spans = strip_key_brackets(spans)
-        self._emit_header_spans(spans, mode, search_pattern_attr)
+        self._emit_header_spans(spans, mode, search_pattern_attr, line_attr)
 
     def add_header_line(self, header_line: HeaderLine | Iterable[Span],
                         mode: str = 'Underline',
-                        search_pattern_attr: int | None = None) -> None:
-        self._emit_header_spans(list(header_line), mode, search_pattern_attr)
+                        search_pattern_attr: int | None = None,
+                        line_attr: int | None = None) -> None:
+        """Render explicit header spans; see :meth:`add_fancy_header`.
+
+        *line_attr* is OR'd into every span's resolved attribute, including
+        plain spans, so the whole line can carry an extra style such as
+        ``curses.A_DIM``.
+        """
+        self._emit_header_spans(list(header_line), mode, search_pattern_attr,
+                                line_attr)
 
     @staticmethod
     def _resolve_header_attr(role: str, mode: str,
-                             search_pattern_attr: int | None) -> int | None:
+                             search_pattern_attr: int | None,
+                             line_attr: int | None = None) -> int | None:
         if mode == 'Off' or role == PLAIN:
-            return None
-        if role == LABEL:
-            return curses.A_BOLD
-        if role == SEARCH:
+            attr = None
+        elif role == LABEL:
+            attr = curses.A_BOLD
+        elif role == SEARCH:
             if search_pattern_attr is not None:
-                return search_pattern_attr
-            return curses.A_BOLD | curses.A_REVERSE
+                attr = search_pattern_attr
+            else:
+                attr = curses.A_BOLD | curses.A_REVERSE
         # KEY (and any unknown role) follows the mode's key styling.
-        if mode == 'Underline':
-            return curses.A_UNDERLINE | curses.A_BOLD
-        return curses.A_REVERSE
+        elif mode == 'Underline':
+            attr = curses.A_UNDERLINE | curses.A_BOLD
+        else:
+            attr = curses.A_REVERSE
+        if line_attr is not None:
+            attr = (attr or 0) | line_attr
+        return attr
 
     def _emit_header_spans(self, spans: Iterable[Span], mode: str,
-                           search_pattern_attr: int | None = None) -> None:
+                           search_pattern_attr: int | None = None,
+                           line_attr: int | None = None) -> None:
         result_sections = [
-            (span.text, self._resolve_header_attr(span.role, mode, search_pattern_attr))
+            (span.text,
+             self._resolve_header_attr(span.role, mode, search_pattern_attr,
+                                       line_attr))
             for span in spans
         ]
 
@@ -2149,7 +2206,12 @@ class ConsoleWindow:
         pad.refresh(scroll_top, 0, row0 + 1, col0 + 1, row0 + visible_rows, col9 - 1)
 
     def clear(self) -> None:
-        self.scr.clear()
+        # A suspended window has no screen handle until resume_curses()/
+        # start_curses(); the content model still has to be reset so the next
+        # repaint is complete.  Calling clear() while suspended used to raise
+        # AttributeError on self.scr.
+        if self.scr is not None:
+            self.scr.clear()
         # Viewport-sized pads: clearing costs one screenful, not one high-water
         # mark, and no shrink/grow decision is needed at a frame boundary.
         self.head.pad.clear()

{console_window-2.0.0.7 → console_window-2.0.0.9}/tests/test_backend.py

@@ -355,6 +355,84 @@ def test_per_instance_suspend_and_resume_curses():
     assert win not in ConsoleWindow.active_windows()
 
 
+def test_clear_while_suspended_only_resets_the_content_model():
+    # A suspended window has no screen, but clear() must still work: the next
+    # repaint after resume comes from the content model, not a stale screen.
+    backend = HeadlessBackend()
+    win = _make(backend)
+    try:
+        win.add_body('old row')
+        win.suspend_curses()
+        win.clear()  # regression: raised AttributeError on self.scr
+        assert win.body.texts == []
+        assert win.scr is None
+        win.add_body('new row')
+        scr = win._start_curses()
+        assert win.scr is scr
+        assert win.body.texts == ['new row']
+        win.clear()  # the live screen is cleared again
+        assert scr.calls_named('clear')
+    finally:
+        win.stop_curses()
+
+
+def test_legacy_instance_start_curses_reattaches_after_suspend():
+    # psistat's dump/return path calls self.window._start_curses() (the 1.4.x
+    # hook that was kept as a compatibility method).  It must leave the window
+    # usable, not create a screen and leave self.scr as None.
+    backend = HeadlessBackend()
+    win = _make(backend)
+    try:
+        win.add_body('kept across the dump')
+        win.suspend_curses()
+        assert win.scr is None and win.suspended
+
+        scr = win._start_curses()
+        assert scr is not None
+        assert win.scr is scr
+        assert win.suspended is False
+        assert win in ConsoleWindow.active_windows()
+        assert win.body.texts == ['kept across the dump']
+        win.clear()   # the call that crashed psistat after returning
+        assert scr.calls_named('clear')
+        win.add_body('after clear')
+    finally:
+        win.stop_curses()
+    assert win.scr is None
+
+
+def test_singleton_legacy_instance_start_curses_resumes_shared_screen():
+    # Same compatibility hook, but in the pre-2.0 singleton model, where
+    # stop_curses() suspends the shared screen rather than tearing it down.
+    code = '''
+from console_window.backend import HeadlessBackend
+from console_window.opts import ConsoleWindowOpts
+from console_window.window import ConsoleWindow
+
+backend = HeadlessBackend()
+win = ConsoleWindow(opts=ConsoleWindowOpts(body_rows=3, head_rows=2),
+                    backend=backend, singleton=True)
+win.add_body('kept across the dump')
+win.stop_curses()                 # pre-2.0 call: suspend
+assert win.scr is None and win.suspended
+
+scr = win._start_curses()         # psistat's "come back" call
+assert scr is not None
+assert win.scr is scr
+assert ConsoleWindow.static_scr is scr
+assert win.suspended is False
+assert win in ConsoleWindow.active_windows()
+assert win.body.texts == ['kept across the dump']
+win.clear()
+assert scr.calls_named('clear')
+win.add_body('after clear')
+
+ConsoleWindow.stop_all()          # permanent teardown
+assert win.scr is None and ConsoleWindow.static_scr is None
+'''
+    subprocess.run([sys.executable, '-c', code], check=True)
+
+
 def test_mixing_singleton_modes_asserts():
     code = '''
 from console_window.backend import HeadlessBackend

{console_window-2.0.0.7 → console_window-2.0.0.9}/tests/test_header.py

@@ -207,6 +207,48 @@ def test_add_fancy_header_headerline_preserves_explicit_roles():
         win.stop_curses()
 
 
+def test_add_fancy_header_line_attr_dims_every_run():
+    # line_attr is OR'd into each span's own style, so a dimmed legend keeps
+    # its underlined keys and its explicitly styled search field.
+    win = _make_window()
+    try:
+        win.add_fancy_header('[v]iew /pat', mode='Underline',
+                             search_pattern_attr=curses.A_BOLD,
+                             line_attr=curses.A_DIM)
+        assert win.head.texts[0] == 'view /pat'
+        attrs = [attr for attr, _count in win.head.text_attrs[0]]
+        assert all(attr & curses.A_DIM for attr in attrs)
+        assert KEY_ATTR | curses.A_DIM in attrs
+        assert curses.A_BOLD | curses.A_DIM in attrs
+    finally:
+        win.stop_curses()
+
+
+def test_add_fancy_header_line_attr_applies_in_off_mode():
+    # mode='Off' emits the raw string, but the whole-line attribute still
+    # applies (otherwise a caller could not dim it at all).
+    win = _make_window()
+    try:
+        win.add_fancy_header('[v]iew', mode='Off', line_attr=curses.A_DIM)
+        assert win.head.texts[0] == '[v]iew'
+        assert all(attr & curses.A_DIM
+                   for attr, _count in win.head.text_attrs[0])
+    finally:
+        win.stop_curses()
+
+
+def test_add_header_line_line_attr_dims_plain_spans():
+    win = _make_window()
+    try:
+        win.add_header_line(HeaderLine().text('plain').label('T'),
+                            mode='Underline', line_attr=curses.A_DIM)
+        attrs = [attr for attr, _count in win.head.text_attrs[0]]
+        assert curses.A_DIM in attrs             # the PLAIN run
+        assert curses.A_BOLD | curses.A_DIM in attrs  # the LABEL run
+    finally:
+        win.stop_curses()
+
+
 def test_string_reparse_drops_keys_the_legacy_grammar_cannot_spell():
     # str(line) is pure text, so the legacy scanner's two KEY rules ('[x]' and
     # 'UPPERCASE:') are all that survive a round trip.  'l:' and '?:' match
@@ -253,3 +295,15 @@ def test_token_and_string_paths_converge_for_legacy_spelled_keys():
 
 def test_resolve_header_attr_off_is_plain(role):
     assert ConsoleWindow._resolve_header_attr(role, 'Off', None) is None
+
+
+def test_resolve_header_attr_line_attr_combines_with_roles():
+    assert (ConsoleWindow._resolve_header_attr(
+                PLAIN, 'Underline', None, curses.A_DIM)
+            == curses.A_DIM)
+    assert (ConsoleWindow._resolve_header_attr(
+                KEY, 'Underline', None, curses.A_DIM)
+            == KEY_ATTR | curses.A_DIM)
+    assert (ConsoleWindow._resolve_header_attr(
+                SEARCH, 'Underline', curses.A_BOLD, curses.A_DIM)
+            == curses.A_BOLD | curses.A_DIM)