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

console_window-2.1.3/README.md → console_window-2.2.2/PKG-INFO

@@ -1,3 +1,34 @@
+Metadata-Version: 2.4
+Name: console-window
+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
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Terminals
+Classifier: Topic :: Software Development :: User Interfaces
+License-File: LICENSE
+Requires-Dist: pytest >= 7.0 ; extra == "dev"
+Requires-Dist: pytest-cov >= 4.0 ; extra == "dev"
+Requires-Dist: ruff >= 0.9 ; extra == "dev"
+Requires-Dist: build >= 1.2 ; extra == "dev"
+Requires-Dist: twine >= 7 ; extra == "dev"
+Requires-Dist: packaging >= 26 ; extra == "dev"
+Requires-Dist: tomli >= 2.0 ; extra == "dev" and ( python_version < "3.11")
+Requires-Dist: pytest >= 7.0 ; extra == "test"
+Requires-Dist: pytest-cov >= 4.0 ; extra == "test"
+Requires-Dist: tomli >= 2.0 ; extra == "test" and ( python_version < "3.11")
+Project-URL: Changelog, https://github.com/joedefen/console-window/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/joedefen/console-window
+Project-URL: Issues, https://github.com/joedefen/console-window/issues
+Project-URL: Repository, https://github.com/joedefen/console-window
+Provides-Extra: dev
+Provides-Extra: test
+
 
 # console-window 
 
@@ -45,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:
@@ -52,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`. 
@@ -90,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
@@ -269,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
@@ -314,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.
@@ -392,7 +439,7 @@ degrades by itself:
   or pass it with the window: `ConsoleWindowOpts(glyphs={'tick': ('✓', 'OK')},
   glyphs_probe=('tick',))`. Once registered, the glyph both degrades with
   `Glyphs.get('tick')` and appears in the font check via `Glyphs.probe_text()`.
-* **Two switches, no argparse boilerplate.** The bundled helper adds them:
+* **The switches, with no argparse boilerplate.** The bundled helper adds them:
 
   ```python
   parser = cli.add_display_arguments(argparse.ArgumentParser())
@@ -402,10 +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. 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
+  both are given. `--theme` seeds the first window's color theme and
+  `--no-color` draws the semantic roles with bold/reverse attributes instead of
+  color. Apps without argparse can use
+  `CONSOLE_WINDOW_GLYPHS=auto|ascii|unicode`, which outranks detection.
+* **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
@@ -418,11 +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 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. `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.
 
@@ -472,3 +537,4 @@ For more extensive examples, you can look at some projects using `console-window
   * viewer of /proc/meminfo that shows historical values
 * [vappman](https://github.com/joedefen/vappman)
   * convenince wrapper to mostly hide CLI of [AppMan](https://github.com/ivan-hc/AppMan), a life-cycle manager for 2000+ AppImages
+

console_window-2.1.3/PKG-INFO → console_window-2.2.2/README.md

@@ -1,22 +1,3 @@
-Metadata-Version: 2.4
-Name: console-window
-Version: 2.1.3
-Summary: A robust curses wrapper for creating Text User Interfaces (TUIs).
-Author-email: Joe Defen <joedef@duck.com>
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Topic :: Terminals
-Classifier: Topic :: Software Development :: User Interfaces
-License-File: LICENSE
-Project-URL: Changelog, https://github.com/joedefen/console-window/blob/main/CHANGELOG.md
-Project-URL: Homepage, https://github.com/joedefen/console-window
-Project-URL: Issues, https://github.com/joedefen/console-window/issues
-Project-URL: Repository, https://github.com/joedefen/console-window
-
 
 # console-window 
 
@@ -64,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:
@@ -71,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`. 
@@ -109,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
@@ -288,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
@@ -333,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.
@@ -411,7 +408,7 @@ degrades by itself:
   or pass it with the window: `ConsoleWindowOpts(glyphs={'tick': ('✓', 'OK')},
   glyphs_probe=('tick',))`. Once registered, the glyph both degrades with
   `Glyphs.get('tick')` and appears in the font check via `Glyphs.probe_text()`.
-* **Two switches, no argparse boilerplate.** The bundled helper adds them:
+* **The switches, with no argparse boilerplate.** The bundled helper adds them:
 
   ```python
   parser = cli.add_display_arguments(argparse.ArgumentParser())
@@ -421,10 +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. 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
+  both are given. `--theme` seeds the first window's color theme and
+  `--no-color` draws the semantic roles with bold/reverse attributes instead of
+  color. Apps without argparse can use
+  `CONSOLE_WINDOW_GLYPHS=auto|ascii|unicode`, which outranks detection.
+* **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
@@ -437,11 +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 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. `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.
 
@@ -491,4 +506,3 @@ For more extensive examples, you can look at some projects using `console-window
   * viewer of /proc/meminfo that shows historical values
 * [vappman](https://github.com/joedefen/vappman)
   * convenince wrapper to mostly hide CLI of [AppMan](https://github.com/ivan-hc/AppMan), a life-cycle manager for 2000+ AppImages
-

{console_window-2.1.3 → console_window-2.2.2}/console_window/__init__.py

@@ -1,7 +1,14 @@
 # Single source of truth for the package version: pyproject.toml declares
 # ``dynamic = ["version"]``, so flit reads this value instead of duplicating it.
-__version__ = "2.1.3"
+__version__ = "2.2.2"
 
+from .appearance import (
+    MONO_ROLES,
+    colors_enabled,
+    resolve_appearance,
+    semantic_attr,
+    set_colors_enabled,
+)
 from .context import Context
 from .glyphs import Glyph, Glyphs
 from .header import HeaderLine, Span
@@ -22,6 +29,7 @@ from .window import ConsoleWindow, TerminalTooSmallError
 
 __all__ = [
     'HOME_ST',
+    'MONO_ROLES',
     'NAVIGATION_KEYS',
     'BasicHelpScreen',
     'BasicTextScreen',
@@ -41,5 +49,9 @@ __all__ = [
     'TerminalTooSmallError',
     'Theme',
     'ThemeStore',
+    'colors_enabled',
     'reset_ctrl_c',
+    'resolve_appearance',
+    'semantic_attr',
+    'set_colors_enabled',
 ]

console_window-2.2.2/console_window/appearance.py

@@ -0,0 +1,137 @@
+"""Semantic color roles, and one resolver for the color switch.
+
+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 color
+numbers.  The library installs those pairs at startup and re-installs them
+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 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 normalizes that name to ``''`` plus ``saved_colors=False``
+before calling :func:`resolve_appearance`.
+"""
+
+from __future__ import annotations
+
+import curses
+import os
+from collections.abc import Mapping
+
+from .theme import Theme
+
+__all__ = [
+    'MONO_ROLES',
+    'colors_enabled',
+    'resolve_appearance',
+    'semantic_attr',
+    'set_colors_enabled',
+]
+
+# 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).
+MONO_ROLES: dict[int, int] = {
+    Theme.DANGER: curses.A_BOLD | curses.A_REVERSE,
+    Theme.ERROR: curses.A_BOLD | curses.A_REVERSE,
+    Theme.WARNING: curses.A_BOLD,
+    Theme.SUCCESS: curses.A_BOLD,
+    Theme.EMPHASIS: curses.A_BOLD,
+    Theme.INFO: curses.A_NORMAL,
+    Theme.PROGRESS: curses.A_NORMAL,
+    Theme.OLD_SUCCESS: curses.A_NORMAL,
+    Theme.HOTSWAP: curses.A_NORMAL,
+}
+
+# Process-wide switch, seeded at startup by --no-color / NO_COLOR.  One
+# terminal, so one decision.
+_COLORS_ENABLED = True
+
+
+def set_colors_enabled(enabled: bool) -> None:
+    """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 color pairs rather than attributes."""
+    return _COLORS_ENABLED
+
+
+def resolve_appearance(
+    cli_theme: str | None = None,
+    no_color: bool = False,
+    saved_theme: str | None = '',
+    saved_colors: bool = True,
+    environ: Mapping[str, str] | None = None,
+) -> tuple[str, bool]:
+    """Starting ``(theme, colors)`` from the switches, environment and memory.
+
+    Precedence, highest first: ``--no-color``, an explicit ``--theme`` (a
+    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
+    theme; ``''`` means "no explicit theme, keep the library default".  An
+    unknown name resolves to ``'default'``, exactly like :meth:`Theme.resolve`.
+
+    The result is a decision, not an action: call
+    :func:`set_colors_enabled` with the second value (or pass both on to
+    whatever applies themes) when the process should start that way.
+    """
+    env = os.environ if environ is None else environ
+
+    if no_color:
+        colors = False
+    elif cli_theme:
+        colors = True
+    elif env.get('NO_COLOR'):
+        colors = False
+    else:
+        colors = bool(saved_colors)
+
+    if cli_theme:
+        theme = Theme.resolve(cli_theme)
+    elif saved_theme:
+        theme = Theme.resolve(saved_theme)
+    else:
+        theme = ''
+    return theme, colors
+
+
+def semantic_attr(pair_id: int) -> int:
+    """Attribute for a :class:`Theme` role, or plain when color is off.
+
+    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
+    text.  The ``except`` is deliberately broad for that reason: a guarded
+    redraw is worth more than a precise exception list, and the fallback is
+    always the same.
+    """
+    if not _COLORS_ENABLED:
+        return MONO_ROLES.get(pair_id, curses.A_NORMAL)
+    try:
+        if not curses.has_colors():
+            return 0
+        return curses.color_pair(pair_id)
+    except Exception:  # pylint: disable=broad-exception-caught
+        # The terminal is not initialized yet; never abort a redraw.
+        return 0

{console_window-2.1.3 → 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