console-window 2.0.0.3__tar.gz → 2.0.0.5__tar.gz

{console_window-2.0.0.3 → console_window-2.0.0.5}/.github/workflows/ci.yml

@@ -19,9 +19,9 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install test dependencies
-        run: python -m pip install --upgrade pip pytest
-      - name: Run tests (TTY-free)
-        run: python -m pytest -q
+        run: python -m pip install pytest==9.1.1 pytest-cov==7.1.0
+      - name: Run tests (TTY-free) with coverage floor
+        run: python -m pytest -q --cov=console_window --cov-fail-under=80
 
   lint:
     name: ruff
@@ -31,9 +31,9 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.x"
+          python-version: "3.13"
       - name: Install ruff
-        run: python -m pip install ruff
+        run: python -m pip install ruff==0.17.0
       - name: Lint
         run: ruff check .
 
@@ -45,8 +45,22 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.x"
+          python-version: "3.13"
       - name: Install mypy
-        run: python -m pip install mypy
+        run: python -m pip install mypy==2.4.0
       - name: Type check
         run: python -m mypy
+
+  pylint:
+    name: pylint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install pylint
+        run: python -m pip install pylint==3.3.4
+      - name: Lint
+        run: python -m pylint console_window SampleApp.py runner --disable=C,R

console_window-2.0.0.5/AUDIT.md

@@ -0,0 +1,120 @@
+# `console-window` — Code & Design Audit
+
+**Audited:** 2026-10-22 (working tree on `4f48396`).
+**Scope:** the `console_window` package, its test suite, `SampleApp.py`, `runner`, packaging and CI. Competitive/ecosystem analysis is deliberately excluded (it is covered in [`README.md`](README.md:1)).
+**Method:** full source read of all 14 package modules plus the example and tests; `ruff`, `pylint`, `mypy`, `pytest` and `coverage` run locally; API reachability established by repo-wide call-site search, not by inference.
+
+| Metric | Value |
+| --- | --- |
+| Package size | 4,512 lines / 2,607 statements across 14 modules; stdlib-only, POSIX curses |
+| Example | [`SampleApp.py`](SampleApp.py:1) 520 lines; [`runner`](runner:1) 13 lines |
+| Tests | 302 tests, ~3,670 lines in 21 files — **all pass** (1.4 s) |
+| Coverage (`--source=console_window`) | **90%** overall; engine [`window.py`](console_window/window.py:1) **89%**, [`spinner.py`](console_window/spinner.py:1) **92%**, [`widgets.py`](console_window/widgets.py:1) **86%**, [`screens.py`](console_window/screens.py:1) **83%** |
+| `ruff check .` | clean (`E,F,W,I,B,C4,ANN,RUF,C901`) |
+| `pylint` | **10.00/10** with `C,R` disabled (0 warnings) |
+| Type checking | **mypy** configured for `console_window` and run in CI; clean (14 source files) |
+| CI gates ([`.github/workflows/ci.yml`](.github/workflows/ci.yml:1)) | tests on 3.10-3.13 with `--cov-fail-under=80`; `ruff`, `mypy` and `pylint --disable=C,R` jobs; every tool pinned (`pytest 9.1.1`, `pytest-cov 7.1.0`, `ruff 0.17.0`, `mypy 2.4.0`, `pylint 3.3.4`) |
+| Complexity (ruff `C901`, threshold 12) | worst is [`answer()`](console_window/window.py:1384) at **12**; next are [`parse_fancy_header()`](console_window/header.py:113) and [`perform_actions()`](console_window/screens.py:197) at **11** |
+
+Section numbers in older [`CHANGELOG.md`](CHANGELOG.md:1) entries and in source comments refer to earlier revisions of this document.
+
+## 1. Executive summary
+
+The library is small, dependency-free, and unusually disciplined for a single-author project: a real module split, a headless render backend, 302 fast TTY-free tests, a green linter and type checker, changelog and release metadata, and a worked example that is itself smoke-tested.
+
+There is no data-loss or security defect, and the interactive core is well covered. What is left is a small body of public surface with no consumer outside the test suite; the dialog retry policy is documented as an accepted limitation and every lint finding now states its reason. Highest-risk findings, in order:
+
+1. **Some public API has no consumer.** `ConsoleWindow.set_pick_range()`, `ConsoleWindow.draw()` and the `OptionSpinner.add()` tombstone are reached only from tests (§3.1).
+2. **The dialog retry policy is class-wide and discards input.** `answer()` spends the shared `render_retry_seconds` budget, and resize recovery drains every queued key. Both are now explicit, documented limitations rather than silent surprises (§3.2).
+
+## 2. Architecture as implemented
+
+| Module | Lines | Stmts | Cover | Role |
+| --- | --- | --- | --- | --- |
+| [`window.py`](console_window/window.py:1) | 2193 | 1271 | 89% | The engine: two pads + screen, add/draw/render/prompt/answer/alert/flash, navigation |
+| [`widgets.py`](console_window/widgets.py:1) | 337 | 231 | 86% | `InlineConfirmation`, `IncrementalSearchBar` (pure, no curses drawing) |
+| [`spinner.py`](console_window/spinner.py:1) | 339 | 215 | 92% | `OptionSpinner`: key → option registry, genre inference, scope subtraction, help body |
+| [`screens.py`](console_window/screens.py:1) | 248 | 161 | 83% | `Screen` base, `ScreenStack` router, `HOME_ST`, `BasicHelpScreen` |
+| [`theme.py`](console_window/theme.py:1) | 303 | 100 | 98% | 7 palettes, `set()`/`set_active()`, picker-screen factory |
+| [`textwidth.py`](console_window/textwidth.py:1) | 236 | 167 | 95% | Display-cell arithmetic: width, truncate, justify, wrap, wrap positions |
+| [`header.py`](console_window/header.py:1) | 162 | 110 | 97% | `Span`/`HeaderLine` token API + legacy `[x]`/`KEY:` string parser |
+| [`backend.py`](console_window/backend.py:1) | 282 | 128 | 88% | `Surface`/`RenderBackend` protocols, `CursesBackend`, `HeadlessBackend` |
+| [`geometry.py`](console_window/geometry.py:1) | 82 | 61 | 100% | Pure abut/indicator/pickable-row math |
+| [`opts.py`](console_window/opts.py:1) | 88 | 63 | 100% | `ConsoleWindowOpts` (`__slots__` + kwargs) |
+| [`context.py`](console_window/context.py:1) | 47 | 22 | 100% | Per-row `Context` (`genre`/`pickable`/`abut` + open kwargs) |
+| [`signals.py`](console_window/signals.py:1) | 144 | 63 | 87% | SIGINT policy: captured host handler, per-window setup/teardown, reset |
+| [`keys.py`](console_window/keys.py:1) | 18 | 3 | 100% | `NAVIGATION_KEYS` |
+| [`__init__.py`](console_window/__init__.py:1) | 33 | 12 | 100% | Re-exports + `__all__` |
+
+**Frame cycle.** `main_loop` → `screen.draw_screen()` (`clear()` + `add_header*`/`add_body` into the two pads) → `win.render()` → `fix_positions()` (clamp/scroll/pick, returns `indent`) → gutter/separator/indicator → `pnoutrefresh` both pads → `doupdate()` → `win.prompt()` (key read + built-in navigation) → `handle_key()` → `stack.perform_actions(spin)` (convention dispatch of `<attr>_ACTION`) → `clear()`.
+
+**Two data models, one window.** Layout/scroll/pick live in `SimpleNamespace`s (`self.head`, `self.body`) with parallel lists (`texts`, `text_attrs` run-length encoded, `contexts`, `row_cnt`); `Row Context` carries per-row semantics. `Screen` subclasses add routing and `*_ACTION` dispatch. `OptionSpinner` is the key/option registry, optionally scope-aware per screen with automatic scope subtraction ([`spinner.py:134`](console_window/spinner.py:134)).
+
+**The seam covers the drawing, input and colour paths.** `RenderBackend` abstracts `start`/`newpad`/`doupdate`/`curs_set`/`update_lines_cols`/`is_term_resized`/`has_colors`/`start_color`/`use_default_colors`/`init_pair`/`color_pair`/`stop`, and the dialogs, flash, resize checks and colour init all go through it.
+
+**Two window models over that seam.** `ConsoleWindow(singleton=True)` (the default) restores the historical process-wide screen: every instance shares one screen/backend, `static_scr`/`static_win` are populated, and `ConsoleWindow.stop_curses()` tears the process screen down. `singleton=False` keeps the per-instance model: each window owns its screen and teardown, and `stop_all()` is the multi-window hook. The first construction latches the mode process-wide; mixing values asserts.
+
+**Current shape.** Docstrings are reserved for public entry points whose call shape needs spelling out, while module- and algorithm-level explanation lives in comments; `_selftest.py` is folded into `SampleApp.py`; the pad-overflow contract is counted, warned about once per fill episode, and enforced in this project's suite; and the package version is single-sourced through `dynamic = ["version"]`.
+
+## 3. Findings
+
+### 3.1 🟡 Unreachable public surface
+
+No consumer outside the test suite for:
+
+| Symbol | Where | Note |
+| --- | --- | --- |
+| `ConsoleWindow.set_pick_range()` | [`window.py:609`](console_window/window.py:609) | The `pick_range` feature's only public entry point; called only by [`tests/test_interactive.py`](tests/test_interactive.py:434) |
+| `OptionSpinner.add()` | [`spinner.py:163`](console_window/spinner.py:163) | Retired tombstone that raises `NotImplementedError` pointing at `add_key()`; only [`tests/test_spinner.py`](tests/test_spinner.py:259) calls it, to assert the raise |
+| `ConsoleWindow.draw()` | [`window.py:863`](console_window/window.py:863) | Named as a model-writing entry point in [`README.md`](README.md:52), but no library or example code calls it; only tests do ([`tests/test_interactive.py`](tests/test_interactive.py:368), [`tests/test_overflow.py`](tests/test_overflow.py:152), [`tests/test_viewport_pad.py`](tests/test_viewport_pad.py:79), [`tests/test_widechars.py`](tests/test_widechars.py:129)) |
+
+`OptionSpinner.add()` keeps its old signature so pre-2.0 call sites fail at the call rather than at import, and its `NotImplementedError` names the replacement call. It is otherwise inert, so the only thing keeping it alive is its own regression test.
+
+`draw()` is the inverse case: the README presents it as part of the row-model API while every actual caller is a test, so the documentation promises a path the project never demonstrates.
+
+The former fourth row of this table, `SampleApp.do_key()`, has been **removed**: it had no caller at all because `main_loop` dispatches through `handle_key()`, which already forwards spinner keys itself.
+
+**Fix:** delete what no consumer needs, or promote it deliberately: give each survivor an exercising caller (the example or a documented snippet) alongside its test. For `OptionSpinner.add()`, either set a removal release or keep it explicitly documented as deprecated.
+
+### 3.2 ✅ `answer()` residual: documented limitations
+
+[`answer()`](console_window/window.py:1384) has one unambiguous meaning per outcome (`str` = submitted, `None` = user abort, `TerminalTooSmallError` = environment), and its recovery loop is bounded. Two narrow characteristics remain, and both are now stated where a maintainer will meet them rather than fixed:
+
+* **The retry budget is class-wide.** `answer()` spends the shared `render_retry_seconds` budget ([`window.py:1421`](console_window/window.py:1421), declared at [`window.py:160`](console_window/window.py:160)). The budget is read as `ConsoleWindow.render_retry_seconds`, so it applies to `render()` and `answer()` alike and must be tuned on the class; an instance assignment has no effect. This is accepted because the knob already exists, no consumer has asked for a different dialog budget, and a second option would add public surface for a ~2 s recovery policy. The attribute comment in [`window.py`](console_window/window.py:153) spells this out.
+* **Recovery discards queued keys.** [`_recover_from_resize()`](console_window/window.py:1750) drains **every** queued key, not only `KEY_RESIZE` ([`window.py:1767`](console_window/window.py:1767)). This is accepted because curses exposes no push-back API: preserving keys would mean replaying raw codes read after a failed redraw, where duplicates and partial escape sequences are indistinguishable from real input. The loss is bounded by `render_retry_seconds` (keys typed after recovery are read normally), and both the method docstring and [`answer()`](console_window/window.py:1384)'s docstring state the loss explicitly.
+
+**Resolution:** documented as accepted limitations; no behaviour change. Revisit only if an app needs an independent dialog budget or faithful key replay, which would justify the extra API and input-buffer plumbing.
+
+### 3.3 ✅ Lint findings now carry rationale
+
+`pylint` is **10.00/10** with `C,R` disabled. Each former warning now either states why it is deliberate or has been removed:
+
+* **protected access** — the registry helpers explain that the module owns `_registry_key` ([`window.py:97`](console_window/window.py:97), [`window.py:105`](console_window/window.py:105)); the `stop_curses` descriptor explains why it reaches the private implementations ([`window.py:147`](console_window/window.py:147), [`window.py:149`](console_window/window.py:149)); `Theme.set()` owns the internal default-colour step ([`theme.py:204`](console_window/theme.py:204)); the sample resets `filter_bar._text` because `IncrementalSearchBar` exposes only a read-only `text` property ([`SampleApp.py:402`](SampleApp.py:402)).
+* **unused arguments** — `_paint_alert()`'s dead `row9` parameter was removed (both call sites updated). The headless backend's protocol arguments ([`backend.py:255`](console_window/backend.py:255), [`backend.py:283`](console_window/backend.py:283)) and `DemoScreen.__init__`'s protocol `name` ([`SampleApp.py:244`](SampleApp.py:244)) are kept for signature compatibility and say so inline.
+* **not-callable** — [`screens.py:68`](console_window/screens.py:68) carries a `disable-next` noting that pylint cannot see through `getattr` + `callable()`.
+* **broad exceptions** — [`SampleApp.py:149`](SampleApp.py:149) explains the sample-data fallback; [`SampleApp.py:518`](SampleApp.py:518) explains the top-level demo guard that leaves the terminal usable.
+
+**Resolution:** resolved; no suppression is unexplained, and `pylint --disable=C,R` is clean.
+
+## 4. Prioritized recommendations
+
+**P1 — surface**
+
+1. Delete or promote the unreachable API and the `draw()` documentation mismatch (§3.1). (`SampleApp.do_key()` has already been deleted.)
+
+**P2 — hygiene**
+
+The §3.2 dialog residuals are closed as documented limitations and the §3.3 lint findings are annotated; reopen either only against a concrete consumer requirement.
+
+## 5. Reproduction
+
+```bash
+python3 -m ruff check .
+python3 -m pytest -q
+python3 -m pytest -q --cov=console_window --cov-fail-under=80   # the CI coverage gate
+python3 -m coverage run --source=console_window -m pytest -q && python3 -m coverage report -m
+python3 -m pylint console_window SampleApp.py runner --disable=C,R
+python3 -m mypy
+python3 -m ruff check --select C901 console_window SampleApp.py   # uses the ratchet in pyproject.toml
+python3 -W error::UserWarning -c "import SampleApp"   # exit path for the pad-overflow policy
+```

{console_window-2.0.0.3 → console_window-2.0.0.5}/CHANGELOG.md

@@ -6,6 +6,18 @@ This project follows [Semantic Versioning](https://semver.org/).
 ## [Unreleased]
 
 ### Added
+- 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
+  keeps one pair table per terminal, so installing a palette still affects the
+  shared screen) and that window's pads are repainted. `Theme.set()` remains the
+  process-wide switch and now relabels every live window. Startup, `Theme.set()`
+  and `set_theme()` install colours from the single `Theme.pair_specs()` list,
+  so the three paths cannot drift apart (AUDIT.md §3.1).
+- `reset_ctrl_c()` (also exported from the package root) restores the SIGINT
+  handler that was installed before the first window and clears the Ctrl-C
+  policy latch, for embedding applications that manage SIGINT themselves
+  (AUDIT.md §3.1).
 - `mypy` type checking for the library: `[tool.mypy]` in `pyproject.toml`
   checks `console_window` (`files`, `ignore_missing_imports`,
   `warn_unused_ignores`, `disallow_untyped_defs = false`) and a new `types` job
@@ -38,6 +50,36 @@ This project follows [Semantic Versioning](https://semver.org/).
   smoke-tested in CI (AUDIT.md §3.2).
 
 ### Changed
+- Every `pylint` warning now states why it is deliberate (AUDIT.md §3.3), taking
+  `pylint --disable=C,R` from 9.94/10 to **10.00/10**. Protected-access and
+  protocol-signature findings carry scoped disables with an adjacent reason,
+  `_paint_alert()`'s genuinely unused `row9` parameter was removed, and the
+  `getattr` + `callable()` call site uses `disable-next`. No runtime behaviour
+  changed.
+- The example's application class is now `SampleApp` (was `DemoApp`), matching
+  the module filename and the package name. The screen base class keeps its
+  `DemoScreen` name; only the app class and its construction site changed.
+- `answer()`'s recovery policy is now documented rather than implicit
+  (AUDIT.md §3.2): the retry loop deliberately shares the class-level
+  `render_retry_seconds`/`render_retry_interval` budget with `render()`, and
+  `_recover_from_resize()` deliberately discards every queued key. The budget
+  is read on the class, so tuning it on one instance has no effect, and keys
+  typed during the bounded recovery window are lost because curses offers no
+  push-back API. Both points are stated on the attributes, on `answer()` and on
+  the recovery method; no behaviour changed.
+- The SIGINT policy captures the handler that was installed before the library
+  first took the signal over instead of assuming `signal.default_int_handler`,
+  and restores it when the last live window stops rather than on the first
+  teardown, so one of several windows stopping cannot disarm the others.
+  Stopping every window ends the latch, so a later window can make Ctrl-C an
+  application key again; the latch still prevents a non-terminating window from
+  swallowing Ctrl-C while a terminating one is live (AUDIT.md §3.1).
+- The sample app's `THEMES` screen is now generated by
+  `Theme.create_picker_screen()` instead of duplicating the factory's header and
+  colour swatches. The generated screen applies the host's `opts.theme` before
+  drawing (so an ordinary `OptionSpinner` cycle binding keeps working) and
+  `spin_theme_ACTION()` starts from that option when present. The factory now has
+  direct tests in `tests/test_theme.py` (AUDIT.md §3.3).
 - Body and header pads are now viewport-sized blit buffers rather than content
   stores. `add_body()`, `add_header()` and `draw()` write the model only, and
   `render()` paints the visible page into pad row 0, so pad memory and the
@@ -73,7 +115,36 @@ This project follows [Semantic Versioning](https://semver.org/).
   (`tests/test_sample_app.py`) to match. The classes inside are still named
   `DemoApp`/`DemoScreen`.
 
+- `OptionSpinner.add()` is now a retired tombstone. Its comment handling sliced
+  the truncated value list with the pre-truncation index, so `comments` was
+  always empty; rather than register a half-configured option it raises
+  `NotImplementedError` naming `add_key()` and showing the replacement call.
+  No in-repo code used it.
+
 ### Fixed
+- `draw()` now routes rows at or past the `max_rows` content ceiling through the
+  same `rows_dropped` counter and once-per-fill warning as `add_body()` /
+  `add_header()`, with the warning attributed to the caller's line. Previously
+  an over-ceiling `draw()` returned silently while the rest of the overflow
+  contract reported nothing. The stale half of the audit finding (phantom rows,
+  missing contexts, lost attributes) had already been fixed by the
+  viewport-sized-pad model and is now documented in AUDIT.md §3.2.
+- `ScreenStack.act_in()` no longer raises `AttributeError` when the requested
+  action flag is absent; it returns `False` and leaves the options object
+  untouched. Its one-shot, current-screen semantics are now covered by
+  `tests/test_screens.py` and documented in the README (AUDIT.md §3.3).
+- `BasicHelpScreen.draw_screen()` resolves the window from `self.app.win` at
+  draw time instead of using the `app.win` value cached by `Screen.__init__`.
+  Applications that build their `Screen` objects before their `ConsoleWindow`
+  (including `SampleApp`) then get a working help screen instead of
+  `AttributeError: 'NoneType' object has no attribute 'set_pick_mode'` when
+  mixing `BasicHelpScreen` into an existing screen class.
+- `add_fancy_header()` now treats `HeaderLine.bracket_key()` delimiters as
+  markup in every mode except `'Off'`: the brackets are removed and the
+  enclosed span keeps its `KEY` styling. Previously a `HeaderLine` was emitted
+  verbatim, so it rendered identically to `add_header_line()`. The explicit
+  path still shows literal brackets, and declared span roles are preserved
+  rather than re-parsed from the rendered text.
 - Navigation keys are responsive again. Two 2.0.0 hot paths made a full
   redraw of a large list far slower than 1.4.3. `textwidth.truncate()` ran
   three `unicodedata` lookups per character on every row, and
@@ -169,6 +240,9 @@ This project follows [Semantic Versioning](https://semver.org/).
   and that both init paths agree (AUDIT.md §3.9).
 
 ### Removed
+- `SampleApp.do_key()`, a dead method with no caller: `main_loop` dispatches
+  through `handle_key()`, which already forwards spinner keys to
+  `spin.do_key()`. No behaviour changed (AUDIT.md §3.1).
 - `console_window/_selftest.py`, the TTY-only dev self-test. The old
   `python -m console_window._selftest` entry point is gone; the features it
   demonstrated — multi-row picking, a prompt-style option, forced

{console_window-2.0.0.3 → console_window-2.0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: console-window
-Version: 2.0.0.3
+Version: 2.0.0.5
 Summary: A robust curses wrapper for creating Text User Interfaces (TUIs).
 Author-email: Joe Defen <joedef@duck.com>
 Requires-Python: >=3.10
@@ -106,7 +106,11 @@ demonstrates:
 * **`InlineConfirmation`** — `SPACE` asks you to confirm with `y` before
   "processing" the picked row.
 * **Themes** — a `THEMES` screen of colour samples backed by
-  `Theme.list_all()` / `get_current()` / `set()`.
+  `Theme.list_all()` / `get_current()` / `set()`. The active theme is now
+  per-window state: `ConsoleWindowOpts(theme=...)` seeds `window.theme`,
+  `window.set_theme()` switches it (and re-initialises the terminal's colour
+  pairs, which curses keeps per terminal rather than per window), and
+  `Theme.set()` remains the process-wide switch.
 * **Dialogs** — `a` calls `answer()` for text input, `l` calls `alert()`, and `n`
   drives `answer()` from an `OptionSpinner` option (`add_key(..., prompt=...)`).
   `answer()` returns `None` only when the user aborts; if the terminal cannot
@@ -116,10 +120,13 @@ demonstrates:
 * **Token-based headers** — `HeaderLine` (`text`, `bracket_key`, `key`, `extend`)
   rendered with `add_header_line()`, rather than string markup.
 * **`Ctrl-C` as an application key** — `ctrl_c_terminates=False` and
-  `keys={0x3, ord('q')}` on the quit action. This works only while no window in
-  the process has requested terminating Ctrl-C: once any window uses the default
-  (`ctrl_c_terminates=True`), terminating Ctrl-C is latched for the process
-  lifetime and cannot be undone.
+  `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
+  the default (`ctrl_c_terminates=True`), terminating Ctrl-C is latched for as
+  long as a window depends on it. The handler that was installed before the
+  first window is captured and restored when the last window stops, and
+  `reset_ctrl_c()` does the same deliberately for an embedding application that
+  manages SIGINT itself.
 * **Full-repaint recovery** — `r` toggles `render(redraw=True)`, the path that
   repaints after terminal corruption.
 * **Multi-row picking** — `p` sets `pick_size` (1–3) via
@@ -169,6 +176,14 @@ For anything beyond a single list, subclass `Screen` and drive it with
 `ScreenStack` — that is what the sample app does, and it is the paradigm the
 library is designed around.
 
+`ScreenStack.perform_actions()` is the normal router: it walks the spinner
+options, honours their scopes, and calls the matching `<attr>_ACTION` method.
+For apps that dispatch an action themselves, `ScreenStack.act_in(action,
+screens=None)` is the low-level single-flag variant: it clears that flag from
+`stack.obj` and returns whether it was set and the current screen matched.
+`ScreenStack.is_curr()` answers the screen test on its own. A missing flag reads
+as `False`, so an options object need not pre-seed every action.
+
 ### Singleton vs. per-instance windows
 
 `ConsoleWindow` supports two process-wide models, selected by the constructor's
@@ -200,8 +215,7 @@ Deprecated APIs remain supported **indefinitely**. A deprecation is a request to
 migrate, not a scheduled removal: deprecated functions and parameters keep
 working, and one is removed only when there is significant value in doing so
 (for example, the API is actively harmful or blocks a necessary redesign).
-Deprecated paths emit a `DeprecationWarning` where practical, and every removal
-is recorded in [`CHANGELOG.md`](CHANGELOG.md:1).
+Deprecated paths emit a `DeprecationWarning` where practical.
 
 ## License
 MIT

{console_window-2.0.0.3 → console_window-2.0.0.5}/README.md

@@ -87,7 +87,11 @@ demonstrates:
 * **`InlineConfirmation`** — `SPACE` asks you to confirm with `y` before
   "processing" the picked row.
 * **Themes** — a `THEMES` screen of colour samples backed by
-  `Theme.list_all()` / `get_current()` / `set()`.
+  `Theme.list_all()` / `get_current()` / `set()`. The active theme is now
+  per-window state: `ConsoleWindowOpts(theme=...)` seeds `window.theme`,
+  `window.set_theme()` switches it (and re-initialises the terminal's colour
+  pairs, which curses keeps per terminal rather than per window), and
+  `Theme.set()` remains the process-wide switch.
 * **Dialogs** — `a` calls `answer()` for text input, `l` calls `alert()`, and `n`
   drives `answer()` from an `OptionSpinner` option (`add_key(..., prompt=...)`).
   `answer()` returns `None` only when the user aborts; if the terminal cannot
@@ -97,10 +101,13 @@ demonstrates:
 * **Token-based headers** — `HeaderLine` (`text`, `bracket_key`, `key`, `extend`)
   rendered with `add_header_line()`, rather than string markup.
 * **`Ctrl-C` as an application key** — `ctrl_c_terminates=False` and
-  `keys={0x3, ord('q')}` on the quit action. This works only while no window in
-  the process has requested terminating Ctrl-C: once any window uses the default
-  (`ctrl_c_terminates=True`), terminating Ctrl-C is latched for the process
-  lifetime and cannot be undone.
+  `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
+  the default (`ctrl_c_terminates=True`), terminating Ctrl-C is latched for as
+  long as a window depends on it. The handler that was installed before the
+  first window is captured and restored when the last window stops, and
+  `reset_ctrl_c()` does the same deliberately for an embedding application that
+  manages SIGINT itself.
 * **Full-repaint recovery** — `r` toggles `render(redraw=True)`, the path that
   repaints after terminal corruption.
 * **Multi-row picking** — `p` sets `pick_size` (1–3) via
@@ -150,6 +157,14 @@ For anything beyond a single list, subclass `Screen` and drive it with
 `ScreenStack` — that is what the sample app does, and it is the paradigm the
 library is designed around.
 
+`ScreenStack.perform_actions()` is the normal router: it walks the spinner
+options, honours their scopes, and calls the matching `<attr>_ACTION` method.
+For apps that dispatch an action themselves, `ScreenStack.act_in(action,
+screens=None)` is the low-level single-flag variant: it clears that flag from
+`stack.obj` and returns whether it was set and the current screen matched.
+`ScreenStack.is_curr()` answers the screen test on its own. A missing flag reads
+as `False`, so an options object need not pre-seed every action.
+
 ### Singleton vs. per-instance windows
 
 `ConsoleWindow` supports two process-wide models, selected by the constructor's
@@ -181,8 +196,7 @@ Deprecated APIs remain supported **indefinitely**. A deprecation is a request to
 migrate, not a scheduled removal: deprecated functions and parameters keep
 working, and one is removed only when there is significant value in doing so
 (for example, the API is actively harmful or blocks a necessary redesign).
-Deprecated paths emit a `DeprecationWarning` where practical, and every removal
-is recorded in [`CHANGELOG.md`](CHANGELOG.md:1).
+Deprecated paths emit a `DeprecationWarning` where practical.
 
 ## License
 MIT

{console_window-2.0.0.3 → console_window-2.0.0.5}/SampleApp.py

@@ -8,6 +8,7 @@ import traceback
 from types import SimpleNamespace
 
 from console_window import (
+    BasicHelpScreen,
     ConsoleWindow,
     ConsoleWindowOpts,
     Context,
@@ -28,7 +29,7 @@ THEME_ST = 3
 SCREEN_NAMES = ('MAIN', 'HELP', 'HISTORY', 'THEMES')
 
 
-class DemoApp:
+class SampleApp:
     def __init__(self, backend=None, singleton=True):
         self.win = None
         self.spin = None
@@ -108,6 +109,7 @@ class DemoApp:
                      genre='action', scope={MAIN_ST})
         spin.add_key('alert_demo', 'l - alert demo',
                      genre='action', scope={MAIN_ST})
+        spin.add_key('show_keys', 'K - show keys (demo mode)', genre='action')
 
         # Folded in from the retired dev self-test.
         # Scoped to MAIN and HELP, like view_mode/sort_by, so the keys keep
@@ -144,8 +146,10 @@ class DemoApp:
                                 'home': home,
                                 'line': line.strip()
                             })
-        except Exception:
-            # Fallback sample data
+        except Exception:  # pylint: disable=broad-exception-caught
+            # The example must run on any host: a malformed/absent passwd file
+            # is not an error worth aborting the demo for, so fall back to the
+            # fixed sample rows below.
             self.items = [
                 {'username': 'demo1', 'uid': '1001', 'home': '/home/demo1',
                  'line': 'demo1:x:1001:1001::/home/demo1:/bin/bash'},
@@ -213,13 +217,6 @@ class DemoApp:
                 if self.filter_text in item['username'].lower() or
                    self.filter_text in item['home'].lower()]
 
-    def do_key(self, key):
-        if not key:
-            return
-        # handle Inline confirmation / filter
-        if key in self.spin.keys:
-            self.spin.do_key(key, self.win)
-
     def main_loop(self):
         while True:
             current_screen = self.screens[self.stack.curr.num]
@@ -235,9 +232,11 @@ class DemoApp:
 
 
 class DemoScreen(Screen):
-    app: DemoApp
+    app: SampleApp
 
-    def __init__(self, name, app):
+    def __init__(self, name, app):  # pylint: disable=unused-argument
+        # ``name`` is part of the screen protocol (ThemeScreen passes 'THEMES'),
+        # but Screen identifies a screen by its stack number, not a label.
         super().__init__(app)
         self.app = app
 
@@ -262,6 +261,7 @@ class DemoScreen(Screen):
         sys.exit(0)
 
 class MainScreen(DemoScreen):
+    header_cnt = 0
     def __init__(self, app):
         super().__init__('MAIN', app)
 
@@ -337,20 +337,39 @@ class MainScreen(DemoScreen):
         else:
             line.text('/')
 
-        # Show spinner keys
+        header_test = self.header_cnt % 3
+        self.header_cnt += 1
+
+        # Show spinner keys.
+        #
+        # Every key below is spelled with bracket_key(), because the third
+        # strategy round-trips the line through str() and the legacy string
+        # scanner, which only knows two KEY spellings: '[x]' (exactly one
+        # character between brackets) and 'UPPERCASE:' (one or more capitals
+        # followed by a colon).  An unbracketed key('l') or key('?') keeps its
+        # KEY role in the token paths, but str(line) is just text: 'l:alrtDemo'
+        # and '?:help' fail both legacy rules, so the re-parse would render the
+        # same characters with no styling.  Bracket-spelling them makes all
+        # three strategies produce the same runs.  (key('SPC') is fine: it is
+        # the 'UPPERCASE:' form.)
         line.text(' ').bracket_key('v').text(f'iew={app.opts.view_mode}')
         line.text(' ').bracket_key('s').text(f'ort={app.opts.sort_by}')
         line.text(' ').bracket_key('a').text('nsDemo')
-        line.text(' ').key('l').text(':alrtDemo')
+        line.text(' ').bracket_key('l').text(':alrtDemo')
         line.text(' ').key('SPC').text(':process')
-        line.text(' ').bracket_key('p').text(f'ick={app.opts.pick_size}')
+        # line.text(' ').bracket_key('p').text(f'ick={app.opts.pick_size}')
         line.text(' ').bracket_key('n').text(f'ame={app.opts.name or "-"}')
-        line.text(' ').key('r').text('edraw')
-        line.text(' ').key('z').text(':stress')
-        line.text(' ').bracket_key('t').text('hemes')
-        line.text(' ').bracket_key('h').text('ist')
-        line.text(' ').key('?').text(':help')
-        app.win.add_header_line(line, mode='Underline')
+        # line.text(' ').key('r').text('edraw')
+        # line.text(' ').key('z').text(':stress')
+        # line.text(' ').bracket_key('t').text('hemes')
+        # line.text(' ').bracket_key('h').text('ist')
+        line.text(' ').bracket_key('?').text(':help')
+        if header_test == 0:  # tokens, emitted verbatim (brackets are literal)
+            app.win.add_header_line(line, mode='Underline')
+        elif header_test == 1:  # tokens, brackets treated as markup only
+            app.win.add_fancy_header(line, mode='Underline')
+        else:  # str(line) re-parsed by the legacy scanner (lossy by design)
+            app.win.add_fancy_header(str(line), mode='Underline')
 
         # Column headers
         view_mode = app.opts.view_mode
@@ -370,7 +389,10 @@ class MainScreen(DemoScreen):
 
     def clear_filter_ACTION(self):
         app = self.app
-        app.filter_bar._text = ''
+        # IncrementalSearchBar exposes only a read-only ``text`` property, so
+        # the example resets the buffer directly rather than growing the widget
+        # API for a single demo action.
+        app.filter_bar._text = ''  # pylint: disable=protected-access
         app.filter_text = ''
         app.win.pick_pos = 0
 
@@ -425,20 +447,24 @@ class MainScreen(DemoScreen):
         win = app.win
         app.stack.push(THEME_ST, win.pick_pos)
 
+    def show_keys_ACTION(self):
+        """ Show last key for demo"""
+        self.app.win.set_demo_mode(enabled=None) # toggle it
+
 
-class HelpScreen(DemoScreen):
+class HelpScreen(DemoScreen, BasicHelpScreen):
     def __init__(self, app):
         super().__init__('HELP', app)
 
-    def draw_screen(self):
-        app = self.app
-        app.win.set_pick_mode(False)
+#   def draw_screen(self):
+#       app = self.app
+#       app.win.set_pick_mode(False)
 
-        spinner = self.get_spinner()
-        if spinner:
-            # Use built-in help display
-            spinner.show_help_nav_keys(app.win)
-            spinner.show_help_body(app.win)
+#       spinner = self.get_spinner()
+#       if spinner:
+#           # Use built-in help display
+#           spinner.show_help_nav_keys(app.win)
+#           spinner.show_help_body(app.win)
 
 
 class HistoryScreen(DemoScreen):
@@ -472,53 +498,19 @@ class HistoryScreen(DemoScreen):
                            'SPACE on an item to process it.')
 
 
-class ThemeScreen(DemoScreen):
+class ThemeScreen(Theme.create_picker_screen(DemoScreen)):
+    """THEMES screen supplied by Theme.create_picker_screen()."""
+
     def __init__(self, app):
         super().__init__('THEMES', app)
 
-    def draw_screen(self):
-        app = self.app
-        win = app.win
-        win.set_pick_mode(False)
-        if app.opts.theme != Theme.get_current():
-            Theme.set(app.opts.theme)
-
-        theme = app.opts.theme
-        win.add_header(f'COLOR THEMES: [t]heme={theme}',
-                          attr=cs.A_BOLD)
-        win.add_header('  ESC:return', attr=cs.A_DIM, resume=True)
-
-        win.add_body('Color samples:')
-        win.add_body('')
-
-        # Color samples
-        color_samples = [
-            (Theme.DANGER, 'DANGER', 'Destructive operations'),
-            (Theme.SUCCESS, 'SUCCESS', 'Completed operations'),
-            (Theme.WARNING, 'WARNING', 'Warnings and cautions'),
-            (Theme.INFO, 'INFO', 'Informational messages'),
-            (Theme.EMPHASIS, 'EMPHASIS', 'Emphasized text'),
-            (Theme.ERROR, 'ERROR', 'Error messages'),
-            (Theme.PROGRESS, 'PROGRESS', 'Progress indicators'),
-        ]
-
-        for color_id, label, description in color_samples:
-            line = f'  {label:<12} ████████  {description}'
-            win.add_body(line, attr=cs.color_pair(color_id))
-
-    def theme_screen(self):
-        themes = Theme.list_all()
-        current = Theme.get_current()
-        idx = themes.index(current) if current in themes else -1
-        next_theme = themes[(idx + 1) % len(themes)]
-        Theme.set(next_theme)
-
 def main(backend=None, singleton=True):
     try:
-        app = DemoApp(backend=backend, singleton=singleton)
+        app = SampleApp(backend=backend, singleton=singleton)
         app.main_loop()
-    except Exception as bummer:
-        # Leave the terminal usable no matter how we failed.
+    except Exception as bummer:  # pylint: disable=broad-exception-caught
+        # Top-level demo guard: no matter how the app failed, leave the terminal
+        # usable and show the error instead of dying with a broken screen.
         win = ConsoleWindow.primary_window()
         if win:
             win.stop_curses()

{console_window-2.0.0.3 → console_window-2.0.0.5}/console_window/__init__.py

@@ -1,12 +1,13 @@
 # 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.3"
+__version__ = "2.0.0.5"
 
 from .context import Context
 from .header import HeaderLine, Span
 from .keys import NAVIGATION_KEYS
 from .opts import ConsoleWindowOpts
 from .screens import HOME_ST, BasicHelpScreen, Screen, ScreenStack
+from .signals import reset_ctrl_c
 from .spinner import OptionSpinner
 from .theme import Theme
 from .widgets import IncrementalSearchBar, InlineConfirmation
@@ -28,4 +29,5 @@ __all__ = [
     'Span',
     'TerminalTooSmallError',
     'Theme',
+    'reset_ctrl_c',
 ]