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

console_window-2.1.2/README.md → console_window-2.2.0/PKG-INFO

@@ -1,3 +1,34 @@
+Metadata-Version: 2.4
+Name: console-window
+Version: 2.2.0
+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 
 
@@ -366,6 +397,72 @@ 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()`.
+* **The switches, with 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 and
+  `--no-color` draws the semantic roles with bold/reverse attributes instead of
+  colour. 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.
+
+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
+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.
+
 ## Versioning and Deprecation
 
 `console-window` follows semantic versioning: patch releases fix behaviour
@@ -418,3 +515,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.2/PKG-INFO → console_window-2.2.0/README.md

@@ -1,22 +1,3 @@
-Metadata-Version: 2.4
-Name: console-window
-Version: 2.1.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
-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 
 
@@ -385,6 +366,72 @@ 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()`.
+* **The switches, with 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 and
+  `--no-color` draws the semantic roles with bold/reverse attributes instead of
+  colour. 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.
+
+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
+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.
+
 ## Versioning and Deprecation
 
 `console-window` follows semantic versioning: patch releases fix behaviour
@@ -437,4 +484,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.2 → console_window-2.2.0}/console_window/__init__.py

@@ -1,8 +1,16 @@
 # 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.2"
+__version__ = "2.2.0"
 
+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
 from .keys import NAVIGATION_KEYS
 from .opts import ConsoleWindowOpts
@@ -15,18 +23,21 @@ 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
 
 __all__ = [
     'HOME_ST',
+    'MONO_ROLES',
     'NAVIGATION_KEYS',
     'BasicHelpScreen',
     'BasicTextScreen',
     'ConsoleWindow',
     'ConsoleWindowOpts',
     'Context',
+    'Glyph',
+    'Glyphs',
     'HeaderLine',
     'IncrementalSearchBar',
     'InlineConfirmation',
@@ -37,5 +48,10 @@ __all__ = [
     'Span',
     'TerminalTooSmallError',
     'Theme',
+    'ThemeStore',
+    'colors_enabled',
     'reset_ctrl_c',
+    'resolve_appearance',
+    'semantic_attr',
+    'set_colors_enabled',
 ]

console_window-2.2.0/console_window/appearance.py

@@ -0,0 +1,135 @@
+"""Semantic colour roles, and one resolver for the colour 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
+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
+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
+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
+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``
+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 colour 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 colour on or off for the whole process."""
+    global _COLORS_ENABLED  # one terminal, one process-wide switch
+    _COLORS_ENABLED = bool(enabled)
+
+
+def colors_enabled() -> bool:
+    """True while semantic roles resolve to colour 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 honoured even when ``NO_COLOR`` is set), the
+    ``NO_COLOR`` convention (any non-empty value disables colour, 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 colour is off.
+
+    With colour 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:  # terminal not initialised yet; never abort a redraw
+        return 0

console_window-2.2.0/console_window/cli.py

@@ -0,0 +1,178 @@
+"""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,
+so an app's ``main()`` gains two lines instead of sixty:
+
+    parser = cli.add_display_arguments(parser)
+    ...
+    cli.apply_display_arguments(opts, prog='myapp')
+
+``--ascii`` and ``--glyphs`` 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".
+
+``--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
+with :func:`console_window.appearance.resolve_appearance`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable, Mapping
+from typing import TextIO
+
+from . import appearance, glyphs
+from .glyphs import TerminalReport
+from .theme import Theme, ThemeStore
+
+__all__ = [
+    'add_display_arguments',
+    'apply_display_arguments',
+    'resolve_force_ascii',
+    'resolve_no_color',
+]
+
+_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``, ``--theme`` and ``--no-color`` 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}',
+    )
+    parser.add_argument(
+        '--no-color',
+        action='store_true',
+        default=None,
+        help=(
+            'draw the semantic roles with attributes instead of colour; wins '
+            'over --theme, and NO_COLOR does the same when the switch is absent'
+        ),
+    )
+    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 resolve_no_color(args: argparse.Namespace) -> bool:
+    """Map a parsed namespace to the ``--no-color`` switch (absent means off)."""
+    return bool(getattr(args, 'no_color', False))
+
+
+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, honour colour.
+
+    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
+    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
+    :func:`console_window.appearance.resolve_appearance`.
+
+    *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)
+
+    if resolve_no_color(args):
+        # Only the explicit flag is acted on; "absent" belongs to the caller.
+        appearance.set_colors_enabled(False)
+
+    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