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

{console_window-2.1.1 → console_window-2.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: console-window
-Version: 2.1.1
+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
@@ -385,6 +385,60 @@ Mixing the two values raises `AssertionError` rather than silently changing what
 teardown means. Use `singleton=False` in tests and in applications that create
 independent windows (for example, one real window plus a headless one).
 
+### Symbols on terminals that cannot draw them
+
+The UI is built around a handful of non-ASCII symbols (`│`, `⮞`, `█`, `←`, `→`,
+`·`, box drawing). A terminal that cannot encode them does not fail loudly: it
+paints a box, or nothing, and the row quietly loses its meaning. `console-window`
+therefore keeps every decorative symbol in one registry, in two spellings, and
+degrades by itself:
+
+* **No code change.** A window detects the terminal when it is constructed — a
+  non-UTF-8 output encoding or `TERM=dumb` selects the ASCII spellings — and
+  text handed to `add_header()` / `add_body()` / `draw()` / `status()` /
+  `flash()` is transliterated before it is measured, so widths and the
+  run-length attribute counts stay correct.
+* **Only decoration is rewritten.** `Grüße` stays `Grüße`: the substitution table
+  contains registered glyphs, never arbitrary text. Set
+  `CONSOLE_WINDOW_GLYPH_AUDIT=1` to log each decorative code point you use but
+  did not register, with the exact `register()` call to add.
+* **App vocabulary.** Register what only your app draws:
+
+  ```python
+  Glyphs.register_many({'tick': ('✓', 'OK')}, probe=('tick',))
+  ```
+
+  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:
+
+  ```python
+  parser = cli.add_display_arguments(argparse.ArgumentParser())
+  opts = parser.parse_args()
+  cli.apply_display_arguments(opts, prog='myapp')
+  ```
+
+  `--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
+  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
+  `help.theme_paragraph()` from `Screen.extra_help_paragraphs()` and set
+  `show_display_notes = True` on a `BasicHelpScreen` subclass to append the font
+  check (Unicode mode) or the way back to the full set (ASCII mode). Both are
+  off by default, so an upgrading app's help output is unchanged.
+
+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.
+
 ## Versioning and Deprecation
 
 `console-window` follows semantic versioning: patch releases fix behaviour

{console_window-2.1.1 → console_window-2.1.3}/README.md

@@ -366,6 +366,60 @@ Mixing the two values raises `AssertionError` rather than silently changing what
 teardown means. Use `singleton=False` in tests and in applications that create
 independent windows (for example, one real window plus a headless one).
 
+### Symbols on terminals that cannot draw them
+
+The UI is built around a handful of non-ASCII symbols (`│`, `⮞`, `█`, `←`, `→`,
+`·`, box drawing). A terminal that cannot encode them does not fail loudly: it
+paints a box, or nothing, and the row quietly loses its meaning. `console-window`
+therefore keeps every decorative symbol in one registry, in two spellings, and
+degrades by itself:
+
+* **No code change.** A window detects the terminal when it is constructed — a
+  non-UTF-8 output encoding or `TERM=dumb` selects the ASCII spellings — and
+  text handed to `add_header()` / `add_body()` / `draw()` / `status()` /
+  `flash()` is transliterated before it is measured, so widths and the
+  run-length attribute counts stay correct.
+* **Only decoration is rewritten.** `Grüße` stays `Grüße`: the substitution table
+  contains registered glyphs, never arbitrary text. Set
+  `CONSOLE_WINDOW_GLYPH_AUDIT=1` to log each decorative code point you use but
+  did not register, with the exact `register()` call to add.
+* **App vocabulary.** Register what only your app draws:
+
+  ```python
+  Glyphs.register_many({'tick': ('✓', 'OK')}, probe=('tick',))
+  ```
+
+  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:
+
+  ```python
+  parser = cli.add_display_arguments(argparse.ArgumentParser())
+  opts = parser.parse_args()
+  cli.apply_display_arguments(opts, prog='myapp')
+  ```
+
+  `--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
+  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
+  `help.theme_paragraph()` from `Screen.extra_help_paragraphs()` and set
+  `show_display_notes = True` on a `BasicHelpScreen` subclass to append the font
+  check (Unicode mode) or the way back to the full set (ASCII mode). Both are
+  off by default, so an upgrading app's help output is unchanged.
+
+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.
+
 ## Versioning and Deprecation
 
 `console-window` follows semantic versioning: patch releases fix behaviour

{console_window-2.1.1 → console_window-2.1.3}/SampleApp.py

@@ -20,6 +20,13 @@ from console_window import (
     ScreenStack,
     Theme,
 )
+from console_window import help as help_text
+
+#: The demo's own vocabulary: a glyph the library does not know about.  It is
+#: handed to the window (not registered globally) to show the option route; the
+#: registered fallback means ``\u2713`` degrades to ``OK`` automatically.
+DEMO_GLYPHS = {'tick': ('\u2713', 'OK')}
+DEMO_PROBE = ('tick', 'cursor', 'choice', 'scroll_prev', 'scroll_next')
 
 # Screen IDs
 MAIN_ST = 0
@@ -67,6 +74,9 @@ class SampleApp:
         # Configure console window
         win_opts = ConsoleWindowOpts(
             head_line=True,
+            # Symbol set: one app glyph plus the font check the HELP screen shows.
+            glyphs=DEMO_GLYPHS,
+            glyphs_probe=DEMO_PROBE,
             # No row sizing needed: the pads are viewport-sized and rows live in
             # the model, so the 'z' stress mode's 2000 filler rows need no
             # option.  max_rows is only a safety ceiling (32767 by default).
@@ -498,9 +508,15 @@ class MainScreen(DemoScreen):
 
 
 class HelpScreen(DemoScreen, BasicHelpScreen):
+    # Show the library's font-check / ASCII-fallback note under our own text.
+    show_display_notes = True
+
     def __init__(self, app):
         super().__init__('HELP', app)
 
+    def extra_help_paragraphs(self):
+        return (help_text.theme_paragraph(open_key='T', cycle_key='t'),)
+
 #   def draw_screen(self):
 #       app = self.app
 #       app.win.set_pick_mode(False)
@@ -545,13 +561,22 @@ class HistoryScreen(DemoScreen):
         self.text_screen.draw_screen()
 
 
-class ThemeScreen(Theme.create_picker_screen(DemoScreen)):
+class ThemeScreen(Theme.create_picker_screen(DemoScreen, cycle_key='t')):
     """THEMES screen supplied by Theme.create_picker_screen()."""
 
     def __init__(self, app):
         super().__init__('THEMES', app)
 
 def main(backend=None, singleton=True):
+    # The same two lines every console-window app needs for --ascii/--theme.
+    import argparse
+
+    from console_window import cli
+
+    parser = cli.add_display_arguments(argparse.ArgumentParser(prog='SampleApp'))
+    opts = parser.parse_args()
+    cli.apply_display_arguments(opts, prog='SampleApp')
+
     try:
         app = SampleApp(backend=backend, singleton=singleton)
         app.main_loop()

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

@@ -1,8 +1,9 @@
 # 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.1"
+__version__ = "2.1.3"
 
 from .context import Context
+from .glyphs import Glyph, Glyphs
 from .header import HeaderLine, Span
 from .keys import NAVIGATION_KEYS
 from .opts import ConsoleWindowOpts
@@ -15,7 +16,7 @@ from .screens import (
 )
 from .signals import reset_ctrl_c
 from .spinner import OptionSpinner
-from .theme import Theme
+from .theme import Theme, ThemeStore
 from .widgets import IncrementalSearchBar, InlineConfirmation, PromptLine
 from .window import ConsoleWindow, TerminalTooSmallError
 
@@ -27,6 +28,8 @@ __all__ = [
     'ConsoleWindow',
     'ConsoleWindowOpts',
     'Context',
+    'Glyph',
+    'Glyphs',
     'HeaderLine',
     'IncrementalSearchBar',
     'InlineConfirmation',
@@ -37,5 +40,6 @@ __all__ = [
     'Span',
     'TerminalTooSmallError',
     'Theme',
+    'ThemeStore',
     'reset_ctrl_c',
 ]

console_window-2.1.3/console_window/cli.py

@@ -0,0 +1,145 @@
+"""Argument-parser boilerplate for the display options.
+
+Every curses app ends up writing the same three switches: a way to force the
+plain-ASCII symbol set, a way to pick a colour theme, 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)
+    ...
+    cli.apply_display_arguments(opts, prog='myapp')
+
+The two switches are deliberately symmetric.  ``--ascii`` accepts an optional
+boolean (``--ascii``, ``--ascii=no``) and ``--glyphs`` accepts a mode
+(``auto``, ``ascii``, ``unicode``); ``--glyphs`` wins when both are given, and
+"absent" everywhere means *detect*, never "assume Unicode".
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable, Mapping
+from typing import TextIO
+
+from . import glyphs
+from .glyphs import TerminalReport
+from .theme import Theme, ThemeStore
+
+__all__ = ['add_display_arguments', 'apply_display_arguments', 'resolve_force_ascii']
+
+_TRUE_WORDS = frozenset({'1', 'true', 'yes', 'y', 'on'})
+_FALSE_WORDS = frozenset({'0', 'false', 'no', 'n', 'off'})
+_MODES = ('auto', 'ascii', 'unicode')
+
+
+def _bool_argument(value: str) -> bool:
+    """argparse ``type=`` for ``--ascii=VALUE``; bare ``--ascii`` uses ``const``."""
+    lowered = value.strip().lower()
+    if lowered in _TRUE_WORDS:
+        return True
+    if lowered in _FALSE_WORDS:
+        return False
+    raise argparse.ArgumentTypeError(
+        f'expected a boolean (yes/no, true/false, on/off), got {value!r}'
+    )
+
+
+def add_display_arguments(
+    parser: argparse.ArgumentParser,
+    *,
+    theme_store: ThemeStore | None = None,
+    prog: str | None = None,
+) -> argparse.ArgumentParser:
+    """Add ``--ascii``, ``--glyphs`` and ``--theme`` to *parser*.
+
+    Returns *parser* so a call site can wrap its own construction.  *theme_store*
+    is accepted for symmetry with :func:`apply_display_arguments` (an app that
+    passes one here is one that remembers the choice); it does not change the
+    switches.  *prog* only shapes the help text.
+    """
+    name = prog or parser.prog or 'this program'
+    remembered = ' (remembered for the next start)' if theme_store is not None else ''
+    parser.add_argument(
+        '--ascii',
+        nargs='?',
+        const=True,
+        default=None,
+        type=_bool_argument,
+        metavar='BOOL',
+        help=(
+            f'use plain-ASCII symbols; --ascii=no forces the Unicode set. '
+            f'Without the switch {name} detects the terminal'
+        ),
+    )
+    parser.add_argument(
+        '--glyphs',
+        choices=_MODES,
+        default=None,
+        help=(
+            'symbol mode: auto detects the terminal, ascii forces the fallback, '
+            'unicode forces the full set (same thing as --ascii / --ascii=no)'
+        ),
+    )
+    parser.add_argument(
+        '--theme',
+        choices=Theme.list_all(),
+        default=None,
+        help=f'color theme{remembered}',
+    )
+    return parser
+
+
+def resolve_force_ascii(args: argparse.Namespace) -> bool | None:
+    """Map a parsed namespace to ``force_ascii``: True, False or None (detect)."""
+    mode = getattr(args, 'glyphs', None)
+    if mode == 'ascii':
+        return True
+    if mode == 'unicode':
+        return False
+    if mode == 'auto':
+        return None
+    flag = getattr(args, 'ascii', None)
+    if flag is None or isinstance(flag, bool):
+        return flag
+    raise TypeError(
+        f'args.ascii must be None or a bool (it is {flag!r}); parse it with '
+        'add_display_arguments() or pass a bool'
+    )
+
+
+def apply_display_arguments(
+    args: argparse.Namespace,
+    *,
+    printer: Callable[[str], object] = print,
+    prog: str = '',
+    environ: Mapping[str, str] | None = None,
+    stream: TextIO | None = None,
+) -> TerminalReport:
+    """Set the glyph mode, print the report's notes, seed the theme.
+
+    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).
+
+    *printer* is a callable taking one string; pass ``sys.stderr.write`` style
+    wrappers through ``lambda line: print(line, file=...)`` if needed.
+    """
+    report = glyphs.apply_policy(
+        resolve_force_ascii(args),
+        environ=environ,
+        stream=sys.stdout if stream is None else stream,
+    )
+    for note in report.notes:
+        printer(f'{prog}: {note}' if prog else note)
+
+    theme = getattr(args, 'theme', None)
+    if theme:
+        if theme in Theme.list_all():
+            # No window exists yet, so record the choice for the first one.
+            Theme.set_active(theme)
+        else:
+            message = f'unknown theme {theme!r}; keeping {Theme.resolve(None)!r}'
+            printer(f'{prog}: {message}' if prog else message)
+    return report