console-window 2.2.0__tar.gz → 2.2.2__tar.gz

{console_window-2.2.0 → console_window-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: console-window
-Version: 2.2.0
+Version: 2.2.2
 Summary: A robust curses wrapper for creating Text User Interfaces (TUIs).
 Author-email: Joe Defen <joedef@duck.com>
 Requires-Python: >=3.10
@@ -76,6 +76,17 @@ no install or build step required:
 (`runner` executes `SampleApp` as `__main__`, so live edits are picked
 up immediately. The equivalent one-off is `python3 SampleApp.py`.)
 
+The sample takes the same display switches as any app built on the library:
+
+```bash
+./runner --no-color          # or NO_COLOR=1 ./runner
+./runner --theme nord
+```
+
+`--no-color` starts in the monochrome mode that the `THEMES` picker also offers
+as its `mono` choice, so `t` on the `THEMES` screen can turn color back on (or
+off again) without restarting.
+
 ## Core Features (The "Secret Sauce")
 
 The wrapper handles several advanced terminal interaction patterns automatically:
@@ -83,7 +94,7 @@ The wrapper handles several advanced terminal interaction patterns automatically
   * **Viewport-Sized Pads:** Separate `head` and `body` pads give the static header band and the independently scrolling body, but the pads are blit buffers sized to the terminal rather than content stores. `add_body()`/`add_header()`/`draw()` write the model, and `render()` paints the visible page into pad row 0, so pad memory and per-frame `clear()` cost stay constant no matter how many rows an app adds. Row counts need no configuration at all: `opts.body_rows` / `opts.head_rows` are advisory hints only, and `opts.max_rows` (default `32767`, `None` for unlimited) is the single content ceiling.
   * **Loud Content Limits:** A row added past `opts.max_rows` is discarded, but no longer quietly: the first discarded row of each fill episode emits a `UserWarning` naming the namespace and the option to change, and every discarded row is counted in `ConsoleWindow.rows_dropped`. It stays non-fatal — run `python -W error::UserWarning` if you would rather it killed the app.
   * **Seamless Resizing:** Automatically detects terminal size changes (`KEY_RESIZE`) and recalculates layout dimensions, with robust error handling to prevent common `curses.error` crashes during resizing.
-  * **Graceful Colour Degradation:** Themes are written against the 256-colour xterm palette, but installation asks the backend how many colours the terminal actually exposes. A 256-colour terminal gets the theme's literal specs; 16-, 88- and 8-colour terminals get the nearest available palette entry, with a contrast guard so a pair never collapses to `fg == bg`; below 8 colours (or with no colour support) the theme falls back to attributes. `-1` is only emitted when `use_default_colors()` succeeds, and `COLOR_PAIRS` is respected. Stock tmux (`TERM=screen`, 8 colours) therefore works instead of raising `ValueError: Color number is greater than COLORS-1`.
+  * **Graceful Color Degradation:** Themes are written against the 256-color xterm palette, but installation asks the backend how many colors the terminal actually exposes. A 256-color terminal gets the theme's literal specs; 16-, 88- and 8-color terminals get the nearest available palette entry, with a contrast guard so a pair never collapses to `fg == bg`; below 8 colors (or with no color support) the theme falls back to attributes. `-1` is only emitted when `use_default_colors()` succeeds, and `COLOR_PAIRS` is respected. Stock tmux (`TERM=screen`, 8 colors) therefore works instead of raising `ValueError: Color number is greater than COLORS-1`.
   * **Scroll & Pick Synchronization:** The `Window` class manages **scroll position** and a separate **pick position** (highlighted row) simultaneously.
     * When using pick mode, scrolling automatically tracks the highlighted element to keep it visible in `.pick_pos`.
     * To use that value, you must separately be able to associate `.pick_pos` to its value by, say, keeping an array of values for every added line to the `body`. 
@@ -121,15 +132,20 @@ demonstrates:
   `handle_prompt_key()`, and `N` edits a note in the header band with the
   buffered text mode. Both use `PromptLine` underneath; completion callbacks
   run after passthrough is restored, so they can report with `status()`.
-* **Themes** — a `THEMES` screen of colour samples backed by
+* **Themes** — a `THEMES` screen of color samples backed by
   `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
+  `window.set_theme()` switches it (and re-initializes the terminal's color
   pairs, which curses keeps per terminal rather than per window), and
   `Theme.set()` remains the process-wide switch. Theme names are semantic:
-  asking for `nord` on an 8-colour terminal installs the closest supported
+  asking for `nord` on an 8-color terminal installs the closest supported
   representation rather than raising, and startup, `set_theme()` and
-  `Theme.set()` all share `Theme.install()`.
+  `Theme.set()` all share `Theme.install()`. The demo's picker also offers a
+  `mono` choice that is not a palette: selecting it calls
+  `appearance.set_colors_enabled(False)` and the swatches switch from color
+  pairs to the bold/reverse attribute hierarchy — the same thing `--no-color`
+  does at startup. While color is off the header names `mono`, not the palette
+  still installed underneath, so one choice has one name.
 * **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
@@ -300,7 +316,7 @@ loop. The window never learns which item the prompt belongs to.
 `BasicTextScreen` is the small `Screen` for preformatted, scrollable text. It
 resolves `app.win` at draw time, disables pick mode, adds each header before the
 body, and adds each line with `add_body()` and no `Context` (so normal
-navigation scrolls it). Content is normalised by `set_text()`, which is safe
+navigation scrolls it). Content is normalized by `set_text()`, which is safe
 before or after the first draw:
 
 ```python
@@ -345,7 +361,7 @@ vertical key is allowed (and logged as "reduced navigation"), since the
 application is then responsible for its own scrolling.
 
 `ScreenStack.perform_actions()` is the normal router: it walks the spinner
-options, honours their scopes, and calls the matching `<attr>_ACTION` method.
+options, honors 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.
@@ -433,11 +449,11 @@ degrades by itself:
 
   `--ascii` forces the fallback (`--ascii=no` forces the full set) and
   `--glyphs {auto,ascii,unicode}` is its symmetric spelling; `--glyphs` wins if
-  both are given. `--theme` seeds the first window's colour theme and
+  both are given. `--theme` seeds the first window's color theme and
   `--no-color` draws the semantic roles with bold/reverse attributes instead of
-  colour. Apps without argparse can use
+  color. Apps without argparse can use
   `CONSOLE_WINDOW_GLYPHS=auto|ascii|unicode`, which outranks detection.
-* **The mode is process-wide**, like the colour-pair table, because there is one
+* **The mode is process-wide**, like the color-pair table, because there is one
   terminal. `ConsoleWindowOpts(ascii=...)` seeds it and `win.ascii_mode` reads
   it; a window constructed later never reverts an explicit choice.
 * **Help screens can explain it for you.** Return
@@ -450,22 +466,28 @@ Themes work the same way: `Theme.create_picker_screen(base, cycle_key=None,
 store=None, note=None)` discovers the key you bound to `spin_theme` for its hint
 line, remembers the choice through any object with `load()`/`save()`, and
 `Theme.initial(cli_theme, store)` returns the theme a new process should start
-on. The library never opens a file.
+on. The library never opens a file. Its swatches follow the shared color
+switch, so a picker opened while color is off previews the monochrome
+hierarchy rather than a previous theme's colors; override `swatch_attr()` on a
+subclass to style swatches differently, and `theme_label()` to name an app
+pseudo-theme such as `mono` in the header.
 
 The appearance layer is shared too. `console_window.appearance.semantic_attr(role)`
-returns the installed colour pair for a semantic role, or the matching attribute
-from `MONO_ROLES` when colour is off; it degrades to plain text when the terminal
-has no colour or curses has not been initialised, so a redraw is never aborted by
-a colour. `set_colors_enabled()` / `colors_enabled()` hold the process-wide
+returns the installed color pair for a semantic role, or the matching attribute
+from `MONO_ROLES` when color is off; it degrades to plain text when the terminal
+has no color or curses has not been initialized, so a redraw is never aborted by
+a color. `set_colors_enabled()` / `colors_enabled()` hold the process-wide
 switch, and `resolve_appearance(cli_theme=None, no_color=False, saved_theme='',
 saved_colors=True, environ=None)` returns the `(theme, colors)` to start with:
 `--no-color` first, then an explicit `--theme`, then `NO_COLOR`, then the
 remembered choice. Apps keep their preference file and their own pseudo-themes;
-the library gives them the policy, not the storage.
+the library gives them the policy, not the storage. `SampleApp`'s `mono` choice
+is the worked example of that split: it lives in the app, flips the switch, and
+leaves the installed palette untouched.
 
 ## Versioning and Deprecation
 
-`console-window` follows semantic versioning: patch releases fix behaviour
+`console-window` follows semantic versioning: patch releases fix behavior
 without changing the public API, minor releases add functionality, and major
 releases may make incompatible changes.
 

{console_window-2.2.0 → console_window-2.2.2}/README.md

@@ -45,6 +45,17 @@ no install or build step required:
 (`runner` executes `SampleApp` as `__main__`, so live edits are picked
 up immediately. The equivalent one-off is `python3 SampleApp.py`.)
 
+The sample takes the same display switches as any app built on the library:
+
+```bash
+./runner --no-color          # or NO_COLOR=1 ./runner
+./runner --theme nord
+```
+
+`--no-color` starts in the monochrome mode that the `THEMES` picker also offers
+as its `mono` choice, so `t` on the `THEMES` screen can turn color back on (or
+off again) without restarting.
+
 ## Core Features (The "Secret Sauce")
 
 The wrapper handles several advanced terminal interaction patterns automatically:
@@ -52,7 +63,7 @@ The wrapper handles several advanced terminal interaction patterns automatically
   * **Viewport-Sized Pads:** Separate `head` and `body` pads give the static header band and the independently scrolling body, but the pads are blit buffers sized to the terminal rather than content stores. `add_body()`/`add_header()`/`draw()` write the model, and `render()` paints the visible page into pad row 0, so pad memory and per-frame `clear()` cost stay constant no matter how many rows an app adds. Row counts need no configuration at all: `opts.body_rows` / `opts.head_rows` are advisory hints only, and `opts.max_rows` (default `32767`, `None` for unlimited) is the single content ceiling.
   * **Loud Content Limits:** A row added past `opts.max_rows` is discarded, but no longer quietly: the first discarded row of each fill episode emits a `UserWarning` naming the namespace and the option to change, and every discarded row is counted in `ConsoleWindow.rows_dropped`. It stays non-fatal — run `python -W error::UserWarning` if you would rather it killed the app.
   * **Seamless Resizing:** Automatically detects terminal size changes (`KEY_RESIZE`) and recalculates layout dimensions, with robust error handling to prevent common `curses.error` crashes during resizing.
-  * **Graceful Colour Degradation:** Themes are written against the 256-colour xterm palette, but installation asks the backend how many colours the terminal actually exposes. A 256-colour terminal gets the theme's literal specs; 16-, 88- and 8-colour terminals get the nearest available palette entry, with a contrast guard so a pair never collapses to `fg == bg`; below 8 colours (or with no colour support) the theme falls back to attributes. `-1` is only emitted when `use_default_colors()` succeeds, and `COLOR_PAIRS` is respected. Stock tmux (`TERM=screen`, 8 colours) therefore works instead of raising `ValueError: Color number is greater than COLORS-1`.
+  * **Graceful Color Degradation:** Themes are written against the 256-color xterm palette, but installation asks the backend how many colors the terminal actually exposes. A 256-color terminal gets the theme's literal specs; 16-, 88- and 8-color terminals get the nearest available palette entry, with a contrast guard so a pair never collapses to `fg == bg`; below 8 colors (or with no color support) the theme falls back to attributes. `-1` is only emitted when `use_default_colors()` succeeds, and `COLOR_PAIRS` is respected. Stock tmux (`TERM=screen`, 8 colors) therefore works instead of raising `ValueError: Color number is greater than COLORS-1`.
   * **Scroll & Pick Synchronization:** The `Window` class manages **scroll position** and a separate **pick position** (highlighted row) simultaneously.
     * When using pick mode, scrolling automatically tracks the highlighted element to keep it visible in `.pick_pos`.
     * To use that value, you must separately be able to associate `.pick_pos` to its value by, say, keeping an array of values for every added line to the `body`. 
@@ -90,15 +101,20 @@ demonstrates:
   `handle_prompt_key()`, and `N` edits a note in the header band with the
   buffered text mode. Both use `PromptLine` underneath; completion callbacks
   run after passthrough is restored, so they can report with `status()`.
-* **Themes** — a `THEMES` screen of colour samples backed by
+* **Themes** — a `THEMES` screen of color samples backed by
   `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
+  `window.set_theme()` switches it (and re-initializes the terminal's color
   pairs, which curses keeps per terminal rather than per window), and
   `Theme.set()` remains the process-wide switch. Theme names are semantic:
-  asking for `nord` on an 8-colour terminal installs the closest supported
+  asking for `nord` on an 8-color terminal installs the closest supported
   representation rather than raising, and startup, `set_theme()` and
-  `Theme.set()` all share `Theme.install()`.
+  `Theme.set()` all share `Theme.install()`. The demo's picker also offers a
+  `mono` choice that is not a palette: selecting it calls
+  `appearance.set_colors_enabled(False)` and the swatches switch from color
+  pairs to the bold/reverse attribute hierarchy — the same thing `--no-color`
+  does at startup. While color is off the header names `mono`, not the palette
+  still installed underneath, so one choice has one name.
 * **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
@@ -269,7 +285,7 @@ loop. The window never learns which item the prompt belongs to.
 `BasicTextScreen` is the small `Screen` for preformatted, scrollable text. It
 resolves `app.win` at draw time, disables pick mode, adds each header before the
 body, and adds each line with `add_body()` and no `Context` (so normal
-navigation scrolls it). Content is normalised by `set_text()`, which is safe
+navigation scrolls it). Content is normalized by `set_text()`, which is safe
 before or after the first draw:
 
 ```python
@@ -314,7 +330,7 @@ vertical key is allowed (and logged as "reduced navigation"), since the
 application is then responsible for its own scrolling.
 
 `ScreenStack.perform_actions()` is the normal router: it walks the spinner
-options, honours their scopes, and calls the matching `<attr>_ACTION` method.
+options, honors 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.
@@ -402,11 +418,11 @@ degrades by itself:
 
   `--ascii` forces the fallback (`--ascii=no` forces the full set) and
   `--glyphs {auto,ascii,unicode}` is its symmetric spelling; `--glyphs` wins if
-  both are given. `--theme` seeds the first window's colour theme and
+  both are given. `--theme` seeds the first window's color theme and
   `--no-color` draws the semantic roles with bold/reverse attributes instead of
-  colour. Apps without argparse can use
+  color. Apps without argparse can use
   `CONSOLE_WINDOW_GLYPHS=auto|ascii|unicode`, which outranks detection.
-* **The mode is process-wide**, like the colour-pair table, because there is one
+* **The mode is process-wide**, like the color-pair table, because there is one
   terminal. `ConsoleWindowOpts(ascii=...)` seeds it and `win.ascii_mode` reads
   it; a window constructed later never reverts an explicit choice.
 * **Help screens can explain it for you.** Return
@@ -419,22 +435,28 @@ Themes work the same way: `Theme.create_picker_screen(base, cycle_key=None,
 store=None, note=None)` discovers the key you bound to `spin_theme` for its hint
 line, remembers the choice through any object with `load()`/`save()`, and
 `Theme.initial(cli_theme, store)` returns the theme a new process should start
-on. The library never opens a file.
+on. The library never opens a file. Its swatches follow the shared color
+switch, so a picker opened while color is off previews the monochrome
+hierarchy rather than a previous theme's colors; override `swatch_attr()` on a
+subclass to style swatches differently, and `theme_label()` to name an app
+pseudo-theme such as `mono` in the header.
 
 The appearance layer is shared too. `console_window.appearance.semantic_attr(role)`
-returns the installed colour pair for a semantic role, or the matching attribute
-from `MONO_ROLES` when colour is off; it degrades to plain text when the terminal
-has no colour or curses has not been initialised, so a redraw is never aborted by
-a colour. `set_colors_enabled()` / `colors_enabled()` hold the process-wide
+returns the installed color pair for a semantic role, or the matching attribute
+from `MONO_ROLES` when color is off; it degrades to plain text when the terminal
+has no color or curses has not been initialized, so a redraw is never aborted by
+a color. `set_colors_enabled()` / `colors_enabled()` hold the process-wide
 switch, and `resolve_appearance(cli_theme=None, no_color=False, saved_theme='',
 saved_colors=True, environ=None)` returns the `(theme, colors)` to start with:
 `--no-color` first, then an explicit `--theme`, then `NO_COLOR`, then the
 remembered choice. Apps keep their preference file and their own pseudo-themes;
-the library gives them the policy, not the storage.
+the library gives them the policy, not the storage. `SampleApp`'s `mono` choice
+is the worked example of that split: it lives in the app, flips the switch, and
+leaves the installed palette untouched.
 
 ## Versioning and Deprecation
 
-`console-window` follows semantic versioning: patch releases fix behaviour
+`console-window` follows semantic versioning: patch releases fix behavior
 without changing the public API, minor releases add functionality, and major
 releases may make incompatible changes.
 

{console_window-2.2.0 → console_window-2.2.2}/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.2.0"
+__version__ = "2.2.2"
 
 from .appearance import (
     MONO_ROLES,

{console_window-2.2.0 → console_window-2.2.2}/console_window/appearance.py

@@ -1,26 +1,26 @@
-"""Semantic colour roles, and one resolver for the colour switch.
+"""Semantic color roles, and one resolver for the color switch.
 
-Colour here is decoration, never information.  Every role degrades to an
-attribute when colour is off, so the same hierarchy survives on a monochrome
+Color here is decoration, never information.  Every role degrades to an
+attribute when color is off, so the same hierarchy survives on a monochrome
 terminal or under ``--no-color``.  Applications kept writing this layer twice:
 the role-to-attribute mapping, the process-wide switch seeded by ``--no-color``
 or ``NO_COLOR``, and a lookup that must never abort a redraw.  It now lives
 here.
 
-The role ids are :class:`Theme`'s semantic pairs rather than literal colour
+The role ids are :class:`Theme`'s semantic pairs rather than literal color
 numbers.  The library installs those pairs at startup and re-installs them
-whenever a theme is applied, so changing the active theme recolours the whole UI
+whenever a theme is applied, so changing the active theme recolors the whole UI
 without an edit to any draw code.
 
 ``--no-color`` is a per-run switch, not a saved preference: it replaces the
 pairs with the attributes in :data:`MONO_ROLES` for this process.  Picking a
-theme from the colour-theme screen is a request for colour, so the caller can
+theme from the color-theme screen is a request for color, so the caller can
 lift the switch again -- :func:`resolve_appearance` does that when it sees an
 explicit theme.
 
 Nothing application-specific belongs in this module: preference files, app
 vocabulary and app pseudo-themes stay with the application.  An app that has a
-``mono`` pseudo-theme normalises that name to ``''`` plus ``saved_colors=False``
+``mono`` pseudo-theme normalizes that name to ``''`` plus ``saved_colors=False``
 before calling :func:`resolve_appearance`.
 """
 
@@ -40,7 +40,7 @@ __all__ = [
     'set_colors_enabled',
 ]
 
-# Role -> attribute used when colour is off.  The hierarchy is kept with
+# Role -> attribute used when color is off.  The hierarchy is kept with
 # emphasis instead of hue: the destructive roles are bold+reverse, warnings,
 # successes and emphasis are bold, and the informational roles carry nothing
 # (their surrounding structure already distinguishes them).
@@ -62,13 +62,14 @@ _COLORS_ENABLED = True
 
 
 def set_colors_enabled(enabled: bool) -> None:
-    """Turn semantic colour on or off for the whole process."""
-    global _COLORS_ENABLED  # one terminal, one process-wide switch
+    """Turn semantic color on or off for the whole process."""
+    # One terminal, so one process-wide switch.
+    global _COLORS_ENABLED  # pylint: disable=global-statement
     _COLORS_ENABLED = bool(enabled)
 
 
 def colors_enabled() -> bool:
-    """True while semantic roles resolve to colour pairs rather than attributes."""
+    """True while semantic roles resolve to color pairs rather than attributes."""
     return _COLORS_ENABLED
 
 
@@ -82,8 +83,8 @@ def resolve_appearance(
     """Starting ``(theme, colors)`` from the switches, environment and memory.
 
     Precedence, highest first: ``--no-color``, an explicit ``--theme`` (a
-    statement of intent, so it is honoured even when ``NO_COLOR`` is set), the
-    ``NO_COLOR`` convention (any non-empty value disables colour, per
+    statement of intent, so it is honored even when ``NO_COLOR`` is set), the
+    ``NO_COLOR`` convention (any non-empty value disables color, per
     no-color.org), then the remembered choice.
 
     ``cli_theme``/``saved_theme`` are returned resolved to a known library
@@ -115,9 +116,9 @@ def resolve_appearance(
 
 
 def semantic_attr(pair_id: int) -> int:
-    """Attribute for a :class:`Theme` role, or plain when colour is off.
+    """Attribute for a :class:`Theme` role, or plain when color is off.
 
-    With colour off the role becomes an attribute from :data:`MONO_ROLES`.
+    With color off the role becomes an attribute from :data:`MONO_ROLES`.
     Otherwise both ``curses.has_colors()`` and ``curses.color_pair()`` can raise
     before ``initscr()`` (``color_pair()`` refuses to run until then), and a
     failed lookup must never abort a redraw, so any failure degrades to plain
@@ -131,5 +132,6 @@ def semantic_attr(pair_id: int) -> int:
         if not curses.has_colors():
             return 0
         return curses.color_pair(pair_id)
-    except Exception:  # terminal not initialised yet; never abort a redraw
+    except Exception:  # pylint: disable=broad-exception-caught
+        # The terminal is not initialized yet; never abort a redraw.
         return 0

{console_window-2.2.0 → console_window-2.2.2}/console_window/backend.py

@@ -92,10 +92,10 @@ class RenderBackend(Protocol):
         ...
 
     def colors(self) -> int:
-        """Number of colours the terminal supports (0 when unknown/none)."""
+        """Number of colors the terminal supports (0 when unknown/none)."""
 
     def color_pairs(self) -> int:
-        """Size of the terminal's colour-pair table."""
+        """Size of the terminal's color-pair table."""
 
     def start_color(self) -> None:
         ...
@@ -115,12 +115,12 @@ class RenderBackend(Protocol):
 
 class CursesBackend:
     # Curses exposes COLORS/COLOR_PAIRS only after start_color(), so the values
-    # are captured there.  Before that, colours()/color_pairs() fall back to the
+    # are captured there.  Before that, colors()/color_pairs() fall back to the
     # module globals (valid once initscr() has run) and finally to a conservative
     # default so a caller never sees a bogus zero-capability terminal merely
     # because it constructed a second backend for an already-running curses
     # session.
-    _FALLBACK_COLOR_PAIRS = 64  # the ncurses floor for a colour terminal
+    _FALLBACK_COLOR_PAIRS = 64  # the ncurses floor for a color terminal
 
     def __init__(self) -> None:
         self._colors = 0
@@ -156,7 +156,7 @@ class CursesBackend:
     def has_colors(self) -> bool:
         try:
             return bool(curses.has_colors())
-        except curses.error:  # curses not initialised yet
+        except curses.error:  # curses not initialized yet
             return False
 
     def colors(self) -> int:
@@ -176,7 +176,7 @@ class CursesBackend:
             pairs = 0
         if pairs > 0:
             return pairs
-        # A colour-capable terminal always has at least the ncurses minimum;
+        # A color-capable terminal always has at least the ncurses minimum;
         # reporting 0 here would make a theme install silently do nothing.
         return self._FALLBACK_COLOR_PAIRS if self.colors() > 0 else 0
 
@@ -184,7 +184,7 @@ class CursesBackend:
         try:
             curses.start_color()
         except curses.error:
-            # No colour support after all: degrade to monochrome instead of
+            # No color support after all: degrade to monochrome instead of
             # letting the caller crash during startup.
             self._colors = 0
             self._color_pairs = 0
@@ -289,8 +289,8 @@ class HeadlessBackend:
         self.pads: list[_NoopSurface] = []
         self.stopped = False
         # ``colors`` used to be a bare bool.  It still accepts one (True means a
-        # 256-colour terminal, False means none) but now also accepts the exact
-        # count, so the low-colour degradation paths are unit-testable without a
+        # 256-color terminal, False means none) but now also accepts the exact
+        # count, so the low-color degradation paths are unit-testable without a
         # real terminal.
         if isinstance(colors, bool):
             self._colors = 256 if colors else 0

{console_window-2.2.0 → console_window-2.2.2}/console_window/cli.py

@@ -1,8 +1,8 @@
 """Argument-parser boilerplate for the display options.
 
 Every curses app ends up writing the same four switches: a way to force the
-plain-ASCII symbol set, a way to pick a colour theme, a way to turn semantic
-colour off, and a way to print what was detected.  This module supplies them,
+plain-ASCII symbol set, a way to pick a color theme, a way to turn semantic
+color off, and a way to print what was detected.  This module supplies them,
 so an app's ``main()`` gains two lines instead of sixty:
 
     parser = cli.add_display_arguments(parser)
@@ -15,7 +15,7 @@ optional boolean (``--ascii``, ``--ascii=no``) and ``--glyphs`` accepts a mode
 "absent" everywhere means *detect*, never "assume Unicode".
 
 ``--no-color`` is the appearance switch.  :func:`apply_display_arguments` acts on
-it, and an app that remembers a colour preference can settle the whole decision
+it, and an app that remembers a color preference can settle the whole decision
 with :func:`console_window.appearance.resolve_appearance`.
 """
 
@@ -101,7 +101,7 @@ def add_display_arguments(
         action='store_true',
         default=None,
         help=(
-            'draw the semantic roles with attributes instead of colour; wins '
+            'draw the semantic roles with attributes instead of color; wins '
             'over --theme, and NO_COLOR does the same when the switch is absent'
         ),
     )
@@ -139,17 +139,17 @@ def apply_display_arguments(
     environ: Mapping[str, str] | None = None,
     stream: TextIO | None = None,
 ) -> TerminalReport:
-    """Set the glyph mode, print the report's notes, seed the theme, honour colour.
+    """Set the glyph mode, print the report's notes, seed the theme, honor color.
 
     Call this once, *before* any window is created, so the mode is decided while
     nothing has been drawn.  Returns the :class:`~console_window.glyphs.
     TerminalReport` so a caller can react to ``ascii_required`` (for example by
     printing a warning of its own).
 
-    An explicit ``--no-color`` turns the process-wide colour switch off here; an
+    An explicit ``--no-color`` turns the process-wide color switch off here; an
     absent switch is left alone, so an app with a remembered preference is free
     to call ``set_colors_enabled()`` with its own decision.  The two halves of
-    that decision -- the theme to install and whether colour is on -- come from
+    that decision -- the theme to install and whether color is on -- come from
     :func:`console_window.appearance.resolve_appearance`.
 
     *printer* is a callable taking one string; pass ``sys.stderr.write`` style

{console_window-2.2.0 → console_window-2.2.2}/console_window/glyphs.py

@@ -132,7 +132,7 @@ BUILTIN_GLYPHS: dict[str, Glyph] = {
     'nav_prev': Glyph('\u2190', '<-'),       # help legend, "left arrow"
     'nav_next': Glyph('\u2192', '->'),       # help legend, "right arrow"
     'bullet': Glyph('\u00b7', '.'),          # help-list bullet
-    'swatch': Glyph('\u2588', '#'),          # theme colour swatch
+    'swatch': Glyph('\u2588', '#'),          # theme color swatch
     # The message-box frame.  `curses.textpad.rectangle()` already draws with
     # ACS line art, but a message box painted by hand needs its own fallback;
     # registering the corners keeps the ASCII mode invariant ("every painted
@@ -178,7 +178,13 @@ def _reset_state() -> None:
     _audited.clear()
 
 
-def register(name: str, unicode_text: str, ascii_text: str, *, probe: bool = False) -> None:
+def register(
+    name: str,
+    unicode_text: str,
+    ascii_text: str,
+    *,
+    probe: bool = False,  # pylint: disable=redefined-outer-name
+) -> None:
     """Teach the library one decorative glyph.
 
     *ascii_text* must be plain ASCII (it may be empty).  ``probe=True`` adds the
@@ -196,7 +202,7 @@ def register(name: str, unicode_text: str, ascii_text: str, *, probe: bool = Fal
 def register_many(
     mapping: Mapping[str, Glyph | tuple[str, str] | list[str]],
     *,
-    probe: Iterable[str] = (),
+    probe: Iterable[str] = (),  # pylint: disable=redefined-outer-name
 ) -> None:
     """Register a whole table at once.
 

{console_window-2.2.0 → console_window-2.2.2}/console_window/help.py

@@ -1,7 +1,7 @@
 """Ready-made help-screen paragraphs for the display features.
 
 A help screen is where a user goes when the display looks wrong, so the two
-things that most often look wrong -- the colour theme and the symbol set --
+things that most often look wrong -- the color theme and the symbol set --
 deserve standard wording.  Keeping the wording here means every app that uses
 this library says the same true thing, and an app that adds a theme picker
 does not have to re-explain what ``t`` does.

{console_window-2.2.0 → console_window-2.2.2}/console_window/opts.py

@@ -207,7 +207,7 @@ class ConsoleWindowOpts:
         self.relax_handled_keys = kwargs.get('relax_handled_keys', True)
         # Per-window theme (ConsoleWindow.theme).  None means "inherit whatever
         # theme is current when this window starts", which is the pre-existing
-        # process-default behaviour.
+        # process-default behavior.
         self.theme = kwargs.get('theme')
         # Glyph mode and app vocabulary.  The mode itself is process state (one
         # terminal); the option only seeds it, exactly as ``theme`` seeds the

{console_window-2.2.0 → console_window-2.2.2}/console_window/screens.py

@@ -300,7 +300,7 @@ class BasicTextScreen(Screen):
     objects before the ConsoleWindow exists (BasicHelpScreen relies on the same
     rule).  ``lines`` items are ``str`` or ``(str, attr)``; ``head`` is a
     ``str``, a :class:`HeaderLine`, or an iterable of either.  Content is
-    normalised by :meth:`set_text`, so ``draw_screen()`` is a flat loop and
+    normalized by :meth:`set_text`, so ``draw_screen()`` is a flat loop and
     nothing is cached across draws.
 
     There is no pick mode, no action handling and no spinner.  ESC/back stays

{console_window-2.2.0 → console_window-2.2.2}/console_window/spinner.py

@@ -76,7 +76,7 @@ class OptionSpinner:
         return getattr(ns.obj, ns.attr, None)
 
     def normalize(self, attr: str) -> object:
-        """Initialise a missing option to its first value (or '' for a prompt).
+        """Initialize a missing option to its first value (or '' for a prompt).
 
         This is the only path that writes while an option is being registered;
         ordinary reads (help rendering, key handling) use get_value() and stay
@@ -265,7 +265,7 @@ class OptionSpinner:
     @staticmethod
     def show_help_nav_keys(win: ConsoleWindow) -> None:
         # Render from the live window so its own opts.taken_nav_keys are
-        # honoured: keys the app owns are not advertised as navigation.
+        # honored: keys the app owns are not advertised as navigation.
         for line in win.nav_help_lines():
             win.add_header(line)
 

{console_window-2.2.0 → console_window-2.2.2}/console_window/theme.py

@@ -46,11 +46,11 @@ def _discover_cycle_key(screen: object, fallback: str = 't') -> str:
     return fallback
 
 # --- palette model -----------------------------------------------------------
-# Standard xterm palette model.  0..15 are the ANSI/base colours, 16..231 the
-# 6x6x6 colour cube with the levels below, and 232..255 the grayscale ramp
+# Standard xterm palette model.  0..15 are the ANSI/base colors, 16..231 the
+# 6x6x6 color cube with the levels below, and 232..255 the grayscale ramp
 # ``8 + 10 * n``.  The RGB values are the conventional xterm ones; exact
 # fidelity is not required because the result only picks the closest entry a
-# low-colour terminal can actually display.
+# low-color terminal can actually display.
 _ANSI_RGB: tuple[tuple[int, int, int], ...] = (
     (0, 0, 0),        # 0 black
     (128, 0, 0),      # 1 red
@@ -99,12 +99,12 @@ def _rgb_distance(left: tuple[int, int, int],
 
 
 def nearest_palette_index(index: int, colors: int) -> int:
-    """Map 256-colour *index* to the nearest entry a *colors*-terminal has.
+    """Map 256-color *index* to the nearest entry a *colors*-terminal has.
 
     Entries 0..15 are the base palette, so the search is restricted to
-    ``0 .. min(colors, 16) - 1``.  A 256-colour terminal gets *index* back
+    ``0 .. min(colors, 16) - 1``.  A 256-color terminal gets *index* back
     unchanged (exact theme specs, no visual regression).  Returns ``-1`` when
-    the terminal has no usable colours at all.
+    the terminal has no usable colors at all.
     """
     if colors >= 256:
         return index
@@ -148,10 +148,10 @@ def resolve_color_pair(fg: int, bg: int, colors: int,
 
     ``-1`` is passed through only when :meth:`RenderBackend.use_default_colors`
     succeeded; otherwise it is replaced with concrete defaults (fg 7, bg 0).
-    On terminals with fewer than 256 colours each index is mapped to the
+    On terminals with fewer than 256 colors each index is mapped to the
     nearest available palette entry.  If the mapping would collapse the pair to
     ``fg == bg`` the foreground is moved to the most contrasting entry.  Returns
-    ``None`` when no legible pair exists (e.g. a 1-colour terminal), in which
+    ``None`` when no legible pair exists (e.g. a 1-color terminal), in which
     case the caller falls back to attributes and installs nothing.
     """
     if colors <= 0:
@@ -166,7 +166,7 @@ def resolve_color_pair(fg: int, bg: int, colors: int,
         if bg != -1:
             bg = nearest_palette_index(bg, colors)
     # A pair of terminal defaults is left alone: the terminal guarantees a
-    # legible default combination, and preserving (-1, -1) keeps the 256-colour
+    # legible default combination, and preserving (-1, -1) keeps the 256-color
     # path byte-for-byte identical to the theme spec.
     if fg != -1 and bg != -1 and fg == bg:
         partner = _contrast_partner(bg, colors)
@@ -195,10 +195,10 @@ class Theme:
     # to be the bare literal ``8`` in two places.
     DEFAULT_BG = 8
 
-    # The semantic roles, in initialisation order.  Both startup
-    # (ConsoleWindow._init_screen) and Theme.set() reinitialise exactly this set,
+    # The semantic roles, in initialization order.  Both startup
+    # (ConsoleWindow._init_screen) and Theme.set() reinitialize exactly this set,
     # so the two paths cannot drift apart: startup used to omit OLD_SUCCESS,
-    # leaving it on an uninitialised pair until a theme change.
+    # leaving it on an uninitialized pair until a theme change.
     SEMANTIC_PAIRS: ClassVar[tuple[int, ...]] = (
         DANGER, SUCCESS, OLD_SUCCESS, WARNING, INFO, EMPHASIS, ERROR, PROGRESS, HOTSWAP,
     )
@@ -337,7 +337,8 @@ class Theme:
         if cli_theme is None and store is not None:
             try:
                 remembered = store.load()
-            except Exception:  # a broken prefs file must not kill start-up
+            # A broken prefs file must not kill start-up.
+            except Exception:  # pylint: disable=broad-exception-caught
                 logger.warning('theme store could not be read; using the default',
                                exc_info=True)
         return cls.resolve(cli_theme or remembered)
@@ -349,7 +350,7 @@ class Theme:
         ``DEFAULT_BG`` comes first (the screen and pad background), then the
         semantic roles in ``SEMANTIC_PAIRS`` order.  Startup
         (``ConsoleWindow._init_screen``), :meth:`set` and
-        ``ConsoleWindow.set_theme`` all install colours through :meth:`install`
+        ``ConsoleWindow.set_theme`` all install colors through :meth:`install`
         from this one list, so the paths cannot drift apart.
         """
         theme = cls.THEMES[cls.resolve(theme_name)]
@@ -369,13 +370,13 @@ class Theme:
     @classmethod
     def install(cls, backend: RenderBackend,
                 theme_name: str | None = None) -> str:
-        """Install *theme_name*'s colours through *backend*, degrading safely.
+        """Install *theme_name*'s colors through *backend*, degrading safely.
 
         This is the single installation path used by startup
         (``ConsoleWindow._init_screen``), ``ConsoleWindow.set_theme()`` and
-        :meth:`set`.  It consults the backend's colour capability instead of the
-        ``curses`` globals: on a 256-colour terminal the theme's literal specs
-        are used unchanged, while fewer colours are mapped to the nearest
+        :meth:`set`.  It consults the backend's color capability instead of the
+        ``curses`` globals: on a 256-color terminal the theme's literal specs
+        are used unchanged, while fewer colors are mapped to the nearest
         available palette entry and ``-1`` is only emitted when the terminal
         accepted ``use_default_colors()``.  Pair ids beyond ``COLOR_PAIRS`` and
         pairs with no legible mapping are skipped rather than raising.  Returns
@@ -403,10 +404,10 @@ class Theme:
         # Late import to avoid a circular import at module load time.
         from .window import ConsoleWindow
 
-        # Colour pairs are terminal-global, so a live window's backend is the
+        # Color pairs are terminal-global, so a live window's backend is the
         # authoritative seam.  Without one, fall back to curses itself, but go
         # through CursesBackend so this method never calls curses.init_pair()
-        # directly (that path used to bypass every low-colour guard).
+        # directly (that path used to bypass every low-color guard).
         win = ConsoleWindow.primary_window()
         backend = getattr(win, '_backend', None) if win is not None else None
         if backend is None:
@@ -471,7 +472,7 @@ class Theme:
                              note: str | None = None) -> type:
         """Build a theme-picker screen class on top of *base_class*.
 
-        The generated screen renders the current theme, a set of labelled colour
+        The generated screen renders the current theme, a set of labeled color
         swatches, and an action (``spin_theme_ACTION``) that cycles themes.  The
         host application is expected to expose ``win``, and may expose
         ``opts.theme``: when present, that option is treated as the selected
@@ -485,6 +486,15 @@ class Theme:
         ``store.save()`` after each cycle, and a failing store is logged rather
         than raised.  *note* is one extra dim line (for example "the choice is
         remembered for the next start").
+
+        Swatches are painted through the appearance layer rather than
+        ``curses.color_pair()``, so a picker opened while color is off shows the
+        monochrome role hierarchy instead of re-painting a previous theme's
+        colors.  A host that wants a different swatch style can subclass the
+        generated screen and override its ``swatch_attr()`` hook, and a host
+        with its own pseudo-theme (``mono``, say) can override
+        ``theme_label()`` so the header names the choice the user made rather
+        than the palette left installed underneath it.
         """
         swatch = glyphs.get('swatch') * 8
 
@@ -504,7 +514,7 @@ class Theme:
 
                 # Name the theme this window is on (default when unset).
                 current_theme = cls.theme_of(win)
-                display_theme = current_theme if current_theme else '(default)'
+                display_theme = self.theme_label(current_theme)
                 hint_key = cycle_key or _discover_cycle_key(self)
 
                 # Add header showing current theme
@@ -531,11 +541,41 @@ class Theme:
                     # is a registered glyph, so a terminal that cannot draw U+2588
                     # shows '#' blocks instead of nine empty cells.
                     line = f'{label:12} {swatch}  {description}'
-                    attr = curses.color_pair(color_id)
-                    win.add_body(line, attr=attr)
+                    win.add_body(line, attr=self.swatch_attr(color_id))
                 if note:
                     win.add_body(note, attr=curses.A_DIM)
 
+            def theme_label(self, theme_name: str | None) -> str:
+                """Header label for the theme the window is on.
+
+                The picker names the palette it is previewing.  A host with its
+                own pseudo-theme can override this to name the mode actually in
+                effect -- for example ``mono`` while color is off -- so the
+                header and the swatches tell one story instead of two.
+
+                This is a hook, like :meth:`swatch_attr`.
+                """
+                return theme_name if theme_name else '(default)'
+
+            @staticmethod
+            def swatch_attr(color_id: int) -> int:
+                """Attribute for one role's swatch in the picker.
+
+                Delegates to :func:`console_window.appearance.semantic_attr`, so
+                the swatch obeys the same process-wide color switch as every
+                other semantic role.  With color off the role's monochrome
+                attribute carries the hierarchy (bold+reverse, bold, plain) and
+                the preview shows the real no-color appearance; with color on
+                it is the installed pair.
+
+                This is a hook: a host may subclass the generated screen and
+                override it to style swatches differently.
+                """
+                # Late import: appearance imports Theme at module load time.
+                from .appearance import semantic_attr
+
+                return semantic_attr(color_id)
+
             def spin_theme_ACTION(self) -> None:
                 win = self.app.win
                 vals = cls.list_all()
@@ -551,7 +591,8 @@ class Theme:
                 if store is not None:
                     try:
                         store.save(value)
-                    except Exception:  # persistence never breaks a cycle
+                    # Persistence never breaks a cycle.
+                    except Exception:  # pylint: disable=broad-exception-caught
                         logger.warning('could not remember theme %r', value,
                                        exc_info=True)
 

{console_window-2.2.0 → console_window-2.2.2}/console_window/window.py

@@ -181,7 +181,7 @@ def render_nav_help(effective: Iterable[int],
 # dedented triple-quoted string: editing the indentation can no longer change
 # what the help screen renders.  ``ConsoleWindow.nav_keys`` remains the joined
 # string for callers that want the whole blurb at once; live windows render
-# through ``nav_help_lines()`` so their own ``taken_nav_keys`` are honoured.
+# through ``nav_help_lines()`` so their own ``taken_nav_keys`` are honored.
 NAV_KEY_LINES: tuple[str, ...] = render_nav_help(NAVIGATION_KEYS)
 
 # Editing keys that passthrough mode hands to the application unchanged, in
@@ -200,7 +200,7 @@ _PASSTHROUGH_EDITING_KEYS = frozenset({
 
 # Compact demo-mode names for the keys whose plain curses name would be
 # unwieldy or ambiguous in the header indicator.  Printable keys are handled
-# separately (centred with spaces), so this table only covers the rest.
+# separately (centered with spaces), so this table only covers the rest.
 _DEMO_KEY_LABELS: dict[int, str] = {
     27: 'ESC',
     ord('\t'): 'TAB',
@@ -659,11 +659,11 @@ class ConsoleWindow:
             glyphs.ensure_policy()
 
     def set_theme(self, theme_name: str) -> bool:
-        """Make *theme_name* this window's theme and install its colours.
+        """Make *theme_name* this window's theme and install its colors.
 
-        Returns False for an unknown theme, or when the backend has no colour
-        support (the choice is still recorded, so a later colour-capable start
-        uses it).  Colour pairs are per-terminal, so installing a palette
+        Returns False for an unknown theme, or when the backend has no color
+        support (the choice is still recorded, so a later color-capable start
+        uses it).  Color pairs are per-terminal, so installing a palette
         necessarily also affects any other window drawing on the same screen —
         that is a curses constraint, not a choice.  What is per-window is the
         selection: it is used at startup, when pads are reallocated, and
@@ -686,9 +686,9 @@ class ConsoleWindow:
         return True
 
     def _apply_pad_theme(self, pad: CursesSurface) -> None:
-        # A freshly created pad has no background, so re-apply the theme colour
+        # A freshly created pad has no background, so re-apply the theme color
         # after every reallocation; otherwise a resize leaves the new pad on the
-        # terminal default instead of the configured background.  The colour
+        # terminal default instead of the configured background.  The color
         # comes from *this window's* theme, not the process default.
         if not self._backend.has_colors():
             return
@@ -696,7 +696,7 @@ class ConsoleWindow:
         if ('default_fg' in theme and 'default_bg' in theme
                 and Theme.DEFAULT_BG < self._backend.color_pairs()):
             # Theme.install() has already installed this pair with either the
-            # literal values or the low-colour mapping, so bkgd() never sees a
+            # literal values or the low-color mapping, so bkgd() never sees a
             # stale/out-of-range pair.
             pad.bkgd(' ', self._backend.color_pair(Theme.DEFAULT_BG))
 
@@ -815,7 +815,7 @@ class ConsoleWindow:
         return True
 
     def _new_screen(self) -> CursesSurface:
-        """Create and initialise a brand-new screen for this window."""
+        """Create and initialize a brand-new screen for this window."""
         return self._init_screen(self._backend, self.theme)
 
     def _start_curses(self) -> CursesSurface:
@@ -972,11 +972,11 @@ class ConsoleWindow:
     @staticmethod
     def _install_theme(backend: RenderBackend, scr: CursesSurface,
                        theme_name: str | None) -> str:
-        """Install *theme_name*'s colours into the terminal's pair table.
+        """Install *theme_name*'s colors into the terminal's pair table.
 
-        Colour pairs are per-terminal (one table, not one per window), so both
+        Color pairs are per-terminal (one table, not one per window), so both
         startup and ``set_theme()`` call this; the caller decides *whose*
-        theme wins.  The actual installation (including low-colour mapping and
+        theme wins.  The actual installation (including low-color mapping and
         ``-1`` resolution) lives in :meth:`Theme.install`, which ``Theme.set()``
         uses too, so the two entry points cannot diverge.  Returns the resolved
         theme name.
@@ -984,7 +984,7 @@ class ConsoleWindow:
         name = Theme.install(backend, theme_name)
         theme = Theme.THEMES[name]
         # Can't change pair 0, so the screen background is set directly.  The
-        # pair has just been installed above (with mapped values on low-colour
+        # pair has just been installed above (with mapped values on low-color
         # terminals), so this never references a stale or out-of-range pair.
         if ('default_fg' in theme and 'default_bg' in theme
                 and Theme.DEFAULT_BG < backend.color_pairs()):
@@ -998,11 +998,11 @@ class ConsoleWindow:
         signals.setup_ctrl_c()
         scr = cast(CursesSurface, backend.start(ConsoleWindow.timeout_ms))
 
-        # Initialize color support with theme.  Every colour call goes through
-        # the backend, so a non-curses backend that reports colours can use it.
+        # Initialize color support with theme.  Every color call goes through
+        # the backend, so a non-curses backend that reports colors can use it.
         if backend.has_colors():
             # start_color() is where a curses backend captures COLORS and
-            # COLOR_PAIRS; Theme.install() then enables default colours (and
+            # COLOR_PAIRS; Theme.install() then enables default colors (and
             # remembers whether -1 is usable) before resolving each pair.
             backend.start_color()
             # The window's own theme (per-window since AUDIT.md §3.1) or the
@@ -2541,7 +2541,7 @@ class ConsoleWindow:
     def _alert_scroll_target(key: int, scroll_top: int, visible_rows: int,
                              max_scroll: int) -> int:
         # "vim"-style scroll commands, matching the navigation family prompt()
-        # honours.  Any other key is not a scroll command and leaves the view put.
+        # honors.  Any other key is not a scroll command and leaves the view put.
         if key in (ord('k'), curses.KEY_UP):
             target = scroll_top - 1
         elif key in (ord('j'), curses.KEY_DOWN):

{console_window-2.2.0 → console_window-2.2.2}/pyproject.toml

@@ -94,7 +94,7 @@ omit = ["tests/*"]
 
 [tool.coverage.report]
 # Measured at 90.69% when the shared release gate was adopted.  The floor is a
-# ratchet against new code arriving without a test, not a target to optimise;
+# ratchet against new code arriving without a test, not a target to optimize;
 # raise it when the number rises, never lower it.
 fail_under = 90
 show_missing = true