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

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

@@ -6,6 +6,19 @@ This project follows [Semantic Versioning](https://semver.org/).
 ## [Unreleased]
 
 ### Added
+- `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
+  app to shell out to a command or an editor and come back.  The pads survive
+  because `endwin()` restores the terminal without destroying the curses
+  SCREEN; `resume_curses()` refreshes the screen handle, backend, dimensions,
+  pad backgrounds and redraw bookkeeping.
+- Singleton-mode compatibility for the pre-2.0 start/stop pair:
+  `stop_curses()` now *suspends* the shared screen and `start_curses()`
+  resumes it, so `stop_curses(); ...; start_curses()` works again (this is what
+  efibootdude's write/reboot paths needed).  `ConsoleWindow.stop_all()` remains
+  the permanent teardown and is the atexit hook; per-instance windows keep
+  `stop_curses()` as a one-way teardown and use suspend/resume explicitly.
 - Per-window themes. `ConsoleWindow.theme` records the theme a window is on,
   `ConsoleWindowOpts(theme=...)` seeds it, and `ConsoleWindow.set_theme()`
   switches it: colours are reinstalled through the window's own backend (curses

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: console-window
-Version: 2.0.0.6
+Version: 2.0.0.7
 Summary: A robust curses wrapper for creating Text User Interfaces (TUIs).
 Author-email: Joe Defen <joedef@duck.com>
 Requires-Python: >=3.10
@@ -195,15 +195,36 @@ as `False`, so an options object need not pre-seed every action.
 
 * **`singleton=True` (default)** — the historical process-wide model. Every
   window draws through one shared screen, `ConsoleWindow.static_scr` and
-  `ConsoleWindow.static_win` are populated, and the unbound
-  `ConsoleWindow.stop_curses()` tears that screen down. Calling
-  `win.stop_curses()` on any singleton window does the same. A second window
-  reuses the first window's screen and backend.
+  `ConsoleWindow.static_win` are populated, and a second window reuses the
+  first window's screen and backend. `stop_curses()` here *suspends* the shared
+  screen and `start_curses()` resumes it (the pre-2.0 pair, kept working);
+  `ConsoleWindow.stop_all()` is the permanent teardown and the `atexit` hook.
 * **`singleton=False`** — per-instance windows. Each window owns its screen,
-  pads and teardown; `win.stop_curses()` stops only that window,
+  pads and teardown; `win.stop_curses()` stops only that window for good,
   `ConsoleWindow.stop_all()` stops every live window, and the unbound
   `ConsoleWindow.stop_curses()` is an error.
 
+### Pausing to run another program
+
+To shell out (an editor, a package manager, `efibootmgr`, a confirmation
+prompt) and then come back, suspend instead of stopping:
+
+```python
+win.suspend_curses()          # endwin(): the terminal is yours again
+try:
+    ... prints, input(), subprocess.run(...) ...
+finally:
+    win.resume_curses()       # reattaches a screen; the next render() repaints
+```
+
+`endwin()` restores the terminal without destroying the curses SCREEN, so the
+pads, the content model and the pick state all survive; resume refreshes the
+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()`.
+Only `stop_all()` is a permanent teardown.
+
 The first successful construction latches the mode for the whole process.
 Mixing the two values raises `AssertionError` rather than silently changing what
 teardown means. Use `singleton=False` in tests and in applications that create

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

@@ -176,15 +176,36 @@ as `False`, so an options object need not pre-seed every action.
 
 * **`singleton=True` (default)** — the historical process-wide model. Every
   window draws through one shared screen, `ConsoleWindow.static_scr` and
-  `ConsoleWindow.static_win` are populated, and the unbound
-  `ConsoleWindow.stop_curses()` tears that screen down. Calling
-  `win.stop_curses()` on any singleton window does the same. A second window
-  reuses the first window's screen and backend.
+  `ConsoleWindow.static_win` are populated, and a second window reuses the
+  first window's screen and backend. `stop_curses()` here *suspends* the shared
+  screen and `start_curses()` resumes it (the pre-2.0 pair, kept working);
+  `ConsoleWindow.stop_all()` is the permanent teardown and the `atexit` hook.
 * **`singleton=False`** — per-instance windows. Each window owns its screen,
-  pads and teardown; `win.stop_curses()` stops only that window,
+  pads and teardown; `win.stop_curses()` stops only that window for good,
   `ConsoleWindow.stop_all()` stops every live window, and the unbound
   `ConsoleWindow.stop_curses()` is an error.
 
+### Pausing to run another program
+
+To shell out (an editor, a package manager, `efibootmgr`, a confirmation
+prompt) and then come back, suspend instead of stopping:
+
+```python
+win.suspend_curses()          # endwin(): the terminal is yours again
+try:
+    ... prints, input(), subprocess.run(...) ...
+finally:
+    win.resume_curses()       # reattaches a screen; the next render() repaints
+```
+
+`endwin()` restores the terminal without destroying the curses SCREEN, so the
+pads, the content model and the pick state all survive; resume refreshes the
+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()`.
+Only `stop_all()` is a permanent teardown.
+
 The first successful construction latches the mode for the whole process.
 Mixing the two values raises `AssertionError` rather than silently changing what
 teardown means. Use `singleton=False` in tests and in applications that create

{console_window-2.0.0.6 → console_window-2.0.0.7}/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.6"
+__version__ = "2.0.0.7"
 
 from .context import Context
 from .header import HeaderLine, Span

{console_window-2.0.0.6 → console_window-2.0.0.7}/console_window/backend.py

@@ -313,6 +313,9 @@ class HeadlessBackend:
 
     def start(self, timeout_ms: int) -> Surface:
         self.screen.timeout(timeout_ms)
+        # A backend that has been (re)started is live again; resume paths rely
+        # on this, so a suspend/resume cycle does not leave ``stopped`` latched.
+        self.stopped = False
         return self.screen
 
     def newpad(self, rows: int, cols: int) -> Surface:

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

@@ -74,6 +74,14 @@ _PASSTHROUGH_EDITING_KEYS = frozenset({
 _WINDOWS: weakref.WeakValueDictionary = weakref.WeakValueDictionary()
 _WINDOW_IDS = itertools.count()
 
+# Windows that have left curses mode (endwin) but are still resumable.  A
+# strong reference is deliberate: the live registry is weak, and a suspended
+# window must survive until resume_curses()/start_curses() reattaches it.  The
+# screen itself is not kept here: in singleton mode the screen's owner stays
+# reachable through ``static_win``/``_static_backend`` (``static_scr`` is None
+# while suspended), and a per-instance window keeps its own backend handle.
+_SUSPENDED: list[ConsoleWindow] = []
+
 # None until the first ConsoleWindow is constructed.  The value is process-wide
 # and deliberately never reset: ConsoleWindow(singleton=...) must agree on every
 # construction or the assertion in __init__ fires.
@@ -136,6 +144,14 @@ class _StopCurses:
     ``ConsoleWindow.stop_curses()``; the per-instance model needs the bound
     window.  A descriptor distinguishes the two call shapes, which a plain
     method with ``self=None`` cannot do without lying to type checkers.
+
+    Semantics depend on the window model:
+
+    * singleton (the pre-2.0 model): ``stop_curses()`` *suspends* the shared
+      screen and ``start_curses()`` resumes it, which keeps the historical
+      stop/start pair working.  Use ``stop_all()`` for a permanent teardown.
+    * per-instance: ``stop_curses()`` is a permanent teardown; use
+      ``suspend_curses()``/``resume_curses()`` to pause and continue.
     """
 
     def __get__(self, obj: ConsoleWindow | None,
@@ -261,6 +277,11 @@ class ConsoleWindow:
         # drawing API is described by CursesSurface, which is only a cast target
         # (curses.window and HeadlessBackend's no-op surface both satisfy it at
         # runtime).  This keeps addstr/border/insstr/... type-checked.
+        if self.singleton and _SUSPENDED:
+            # A suspended shared screen must be resumed before another window
+            # can join it; otherwise the new window would draw into a terminal
+            # that is still in shell mode.
+            ConsoleWindow._resume_singleton()
         if self.singleton and ConsoleWindow.static_scr is not None:
             # Singleton mode: every instance draws through the process screen
             # and the backend that owns it, even if a different backend was
@@ -345,6 +366,10 @@ class ConsoleWindow:
         # created but unreachable (the view snapped back to the last pickable
         # row every frame).
         self.free_scroll = False
+        # True between suspend_curses() and resume_curses()/start_curses(): the
+        # terminal was handed back (endwin) but the pads and content model stay
+        # valid, so the window can be reattached to a screen later.
+        self.suspended = False
         self.rows, self.cols = 0, 0
         self.body_cols, self.body_rows = self.opts.body_cols, self.opts.body_rows
         self.scroll_view_size = 0  # no. viewable lines of the body
@@ -559,10 +584,76 @@ class ConsoleWindow:
     def _start_curses(self) -> CursesSurface:
         return self._init_screen(self._backend, self.theme)
 
+    def _attach_screen(self, scr: CursesSurface, backend: RenderBackend) -> None:
+        """Point this window at a (re)started screen and force a full repaint.
+
+        Used by resume_curses()/start_curses() after a suspend.  The content
+        model and pads survive ``endwin()``; only the screen handle, the
+        backend that owns it, the dimensions, the pad backgrounds and the
+        redraw bookkeeping have to be refreshed.
+        """
+        self._backend = backend
+        self.scr = scr
+        self.suspended = False
+        _register_window(self)
+        self.calc()  # dimensions + pad reallocation through the new backend
+        self._set_scr_timeout(self._scr_timeout_ms)
+        for ns in (self.head, self.body):
+            self._apply_pad_theme(cast(CursesSurface, ns.pad))
+        self._mark_pads_for_redraw()
+        self._pick_clear_pending = True
+
+    def suspend_curses(self) -> None:
+        """Leave curses mode without destroying this window.
+
+        ``endwin()`` restores the terminal but keeps the curses SCREEN (and
+        therefore the pads) alive, so the next :meth:`resume_curses` can
+        reattach a screen and the next ``render()`` repaints.  In singleton
+        mode all windows share one screen, so this suspends them together.
+        Use :meth:`stop_curses` when the window is finished for good.
+        """
+        if getattr(self, 'singleton', False):
+            ConsoleWindow._suspend_singleton()
+            return
+        scr = getattr(self, 'scr', None)
+        if scr is None or self.suspended:
+            return
+        try:
+            backend = getattr(self, '_backend', None) or CursesBackend()
+            backend.stop(scr)
+        finally:
+            self.scr = cast(CursesSurface, None)
+            self.suspended = True
+            _unregister_window(self)
+            signals.teardown_ctrl_c()
+
+    def resume_curses(self) -> CursesSurface | None:
+        """Re-enter curses after :meth:`suspend_curses`.
+
+        Returns the (new) screen, or None when the window was not suspended.
+        The next ``render()`` repaints from the preserved content model.
+        """
+        if getattr(self, 'singleton', False):
+            return ConsoleWindow._resume_singleton()
+        if not self.suspended:
+            return self.scr
+        backend = getattr(self, '_backend', None) or CursesBackend()
+        scr = self._init_screen(backend, self.theme)
+        self._attach_screen(scr, backend)
+        return scr
+
     @classmethod
     def start_curses(cls, backend: RenderBackend | None = None) -> CursesSurface:
         # Legacy class-level entry point: in singleton mode it shares the one
-        # process screen rather than starting a second terminal session.
+        # process screen rather than starting a second terminal session.  When
+        # windows were suspended by stop_curses()/suspend_curses(), this is the
+        # matching resume: every suspended window is reattached to the screen
+        # (the backend argument is ignored then -- the screen belongs to the
+        # backend that created it).
+        if _SINGLETON_MODE and _SUSPENDED:
+            scr = cls._resume_singleton()
+            if scr is not None:
+                return scr
         if _SINGLETON_MODE and cls.static_scr is not None:
             return cls.static_scr
         screen_backend = backend if backend is not None else CursesBackend()
@@ -573,6 +664,45 @@ class ConsoleWindow:
             cls._static_backend = screen_backend
         return scr
 
+    @classmethod
+    def _suspend_singleton(cls) -> None:
+        """Leave the shared screen, keeping every window resumable."""
+        scr = cls.static_scr
+        if scr is None:
+            return
+        backend = cls._static_backend or CursesBackend()
+        windows = list(_WINDOWS.values())
+        try:
+            backend.stop(scr)
+        finally:
+            cls.static_scr = None
+            for win in windows:
+                win.scr = cast(CursesSurface, None)
+                win.suspended = True
+                _unregister_window(win)
+                signals.teardown_ctrl_c()
+                if win not in _SUSPENDED:
+                    _SUSPENDED.append(win)
+            # static_win is deliberately kept: it is the anchor that
+            # start_curses()/resume_curses() uses to restore the theme and is
+            # replaced by the next singleton window construction.
+
+    @classmethod
+    def _resume_singleton(cls) -> CursesSurface | None:
+        """Re-enter the shared screen and reattach every suspended window."""
+        if not _SUSPENDED:
+            return cls.static_scr
+        backend = cls._static_backend or CursesBackend()
+        anchor = cls.static_win
+        scr = cls._init_screen(backend, anchor.theme if anchor is not None else None)
+        cls.static_scr = scr
+        cls._static_backend = backend
+        windows = list(_SUSPENDED)
+        del _SUSPENDED[:]
+        for win in windows:
+            win._attach_screen(scr, backend)  # pylint: disable=protected-access
+        return scr
+
     @staticmethod
     def _install_theme(backend: RenderBackend, scr: CursesSurface,
                        theme_name: str | None) -> str:
@@ -634,25 +764,31 @@ class ConsoleWindow:
             self._pick_clear_pending = True
 
     def _stop_instance(self) -> None:
-        """Stop this window (and, in singleton mode, the shared screen)."""
+        """Stop this window (and, in singleton mode, suspend the shared screen)."""
         if getattr(self, 'singleton', False):
-            self._stop_singleton()
+            # Backward compatibility: in singleton mode the legacy
+            # stop_curses()/start_curses() pair is a suspend/resume pair, so
+            # stop_curses() leaves the screen resumable.  stop_all() is the
+            # permanent teardown.
+            ConsoleWindow._suspend_singleton()
             return
 
         scr = getattr(self, 'scr', None)
         if scr is None:
+            self.suspended = False
             return
         try:
             backend = getattr(self, '_backend', None) or CursesBackend()
             backend.stop(scr)
         finally:
             self.scr = cast(CursesSurface, None)
+            self.suspended = False
             _unregister_window(self)
             signals.teardown_ctrl_c()
 
     @classmethod
     def _stop_legacy(cls) -> None:
-        """The pre-2.0 ``ConsoleWindow.stop_curses()`` call."""
+        """The pre-2.0 ``ConsoleWindow.stop_curses()`` call (suspends in singleton mode)."""
         assert _SINGLETON_MODE is not False, (
             'ConsoleWindow.stop_curses() without an instance is only valid '
             'in singleton mode; use win.stop_curses() or ConsoleWindow.stop_all()')
@@ -662,24 +798,31 @@ class ConsoleWindow:
 
     @classmethod
     def _stop_singleton(cls) -> None:
-        """Tear down the shared screen and mark every window stopped."""
+        """Tear down the shared screen and forget every window (including suspended)."""
         scr = ConsoleWindow.static_scr
-        if scr is None:
-            return
-        backend = ConsoleWindow._static_backend or CursesBackend()
         windows = list(_WINDOWS.values())
+        suspended = list(_SUSPENDED)
+        del _SUSPENDED[:]
         ConsoleWindow.static_scr = None
         ConsoleWindow.static_win = None
+        backend = ConsoleWindow._static_backend
         ConsoleWindow._static_backend = None
-        for win in windows:
+        for win in windows + suspended:
             win.scr = cast(CursesSurface, None)
+            win.suspended = False
+        if scr is None:
+            # Already in shell mode (all windows suspended); nothing to end,
+            # but the suspended windows still have to be forgotten.
+            for win in windows + suspended:
+                _unregister_window(win)
+            return
         try:
-            backend.stop(scr)
+            (backend or CursesBackend()).stop(scr)
         finally:
             # One teardown per window, matching the per-window setup in
             # _init_screen: the SIGINT handler is only restored once the last
             # live window is gone (AUDIT.md §3.1).
-            for win in windows:
+            for win in windows + suspended:
                 _unregister_window(win)
                 signals.teardown_ctrl_c()
 
@@ -704,6 +847,10 @@ class ConsoleWindow:
 
     @classmethod
     def stop_all(cls) -> None:
+        """Permanently tear down every window (the atexit hook)."""
+        if _SINGLETON_MODE:
+            cls._stop_singleton()
+            return
         for win in cls.active_windows():
             win.stop_curses()
 

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

@@ -259,7 +259,7 @@ def test_theme_broadcast_reaches_all_windows():
         second.stop_curses()
 
 
-def test_singleton_mode_shares_the_process_screen_and_tears_down_globally():
+def test_singleton_mode_shares_the_process_screen():
     # Singleton mode is process-wide, so prove it in a fresh interpreter rather
     # than perturb the per-instance mode this test session has latched.
     code = '''
@@ -276,7 +276,7 @@ assert ConsoleWindow.static_scr is first.scr
 assert second.scr is first.scr
 assert ConsoleWindow.static_win is second
 assert ConsoleWindow.primary_window() is second
-ConsoleWindow.stop_curses()   # the pre-2.0 unbound call
+ConsoleWindow.stop_all()   # permanent teardown
 assert first.scr is None and second.scr is None
 assert ConsoleWindow.static_scr is None and ConsoleWindow.static_win is None
 assert first_backend.stopped is True
@@ -285,6 +285,76 @@ assert ConsoleWindow.active_windows() == []
     subprocess.run([sys.executable, '-c', code], check=True)
 
 
+def test_singleton_stop_curses_suspends_and_start_curses_resumes():
+    # The pre-2.0 stop_curses()/start_curses() pair must keep working: in
+    # singleton mode it is a suspend/resume pair, not a one-way teardown.
+    code = '''
+from console_window.backend import HeadlessBackend
+from console_window.opts import ConsoleWindowOpts
+from console_window.window import ConsoleWindow
+
+first_backend = HeadlessBackend()
+first = ConsoleWindow(opts=ConsoleWindowOpts(body_rows=3, head_rows=2),
+                      backend=first_backend, singleton=True)
+second = ConsoleWindow(opts=ConsoleWindowOpts(body_rows=3, head_rows=2),
+                       backend=HeadlessBackend())
+first.add_body('kept across the suspend')
+old_screen = first.scr
+
+ConsoleWindow.stop_curses()   # the pre-2.0 unbound call: suspend
+assert first_backend.stopped is True
+assert first.scr is None and second.scr is None
+assert first.suspended and second.suspended
+assert ConsoleWindow.static_scr is None
+assert ConsoleWindow.active_windows() == []
+# static_win is kept as the resume anchor.
+assert ConsoleWindow.static_win is second
+
+scr = ConsoleWindow.start_curses()   # matching resume
+assert scr is not None
+assert ConsoleWindow.static_scr is scr
+assert first.scr is scr and second.scr is scr
+assert not first.suspended and not second.suspended
+assert first_backend.stopped is False
+assert ConsoleWindow.active_windows() == [first, second]
+# The content model and pads survived endwin().
+assert first.body.texts == ['kept across the suspend']
+assert first.body.pad is not None
+
+ConsoleWindow.stop_all()   # permanent teardown
+assert first.scr is None and second.scr is None
+assert ConsoleWindow.static_scr is None and ConsoleWindow.static_win is None
+assert ConsoleWindow.active_windows() == []
+'''
+    subprocess.run([sys.executable, '-c', code], check=True)
+
+
+def test_per_instance_suspend_and_resume_curses():
+    backend = HeadlessBackend()
+    win = _make(backend)
+    try:
+        win.add_body('kept across the suspend')
+        win.suspend_curses()
+        assert win.suspended is True
+        assert win.scr is None
+        assert backend.stopped is True
+        assert win not in ConsoleWindow.active_windows()
+
+        scr = win.resume_curses()
+        assert scr is not None
+        assert win.scr is scr
+        assert win.suspended is False
+        assert backend.stopped is False
+        assert win in ConsoleWindow.active_windows()
+        assert win.body.texts == ['kept across the suspend']
+        # A second resume is a no-op that returns the live screen.
+        assert win.resume_curses() is scr
+    finally:
+        win.stop_curses()
+    assert win.scr is None
+    assert win not in ConsoleWindow.active_windows()
+
+
 def test_mixing_singleton_modes_asserts():
     code = '''
 from console_window.backend import HeadlessBackend