Skip to main content

console-window

console-window is a stdlib-only, single-dependency-free curses framework that is not a general widget toolkit. It is best understood as a keyboard-driven, full-screen "pager + selection engine + screen-stack router" built on raw curses pads. The genuinely novel ideas are:

  • a separate head pad / body pad split with a static header band;
  • a scroll position and an independent pick (cursor) position that stay synchronized;
  • a Context metadata object per line with an abut concept (keep N lines around the picked row visible — perfect for expandable/transient detail rows);
  • OptionSpinner scoped key bindings with last-writer-wins scope subtraction per screen.

The package abstracts away the complexities of managing curses pads, dynamic screen resizing, custom scroll/pick synchronization, and keyboard handling. Its strengths include:

  1. Zero runtime dependencies. The only requirements are the standard-library curses and curses.textpad modules — no third-party dependency tree and no associated supply-chain risk.
  2. Efficient rendering. Uses accumulated refreshes on the screen and pads with a single terminal update per frame, rather than flicker-prone full refreshes. A redraw path can recover the display from terminal corruption.
  3. Two-axis scroll/pick model. The scroll position and the pick (cursor) position are tracked independently and reconciled each frame. Most simple pagers conflate these; separating them is what enables kept-visible selection with context rows above and below.
  4. Per-line metadata plus an abut concept. Because context is attached to each line rather than parsed from text, and transient child rows auto-abut to their parent, expandable/transient detail rows stay attached to the row that produced them. "After trumps before" is a thoughtful touch.
  5. Non-pickable rows are first-class. Decorative separator and header lines are skipped by navigation and page movement, so they do not produce "dead" cursor stops; scrolling still reaches them, including a trailing block of them past the last pickable row.
  6. Scoped, self-subtracting key bindings. A later, narrower binding (e.g. ESC to clear a filter on one screen only) subtracts that screen from an earlier global binding. This is a real router, not a flat key map, and it actively rejects collisions with navigation keys.
  7. Convention-based dispatch. Actions map to matching handler methods on screen classes, keeping them free of central if key == ... towers.
  8. Resize resilience. Rendering retries during terminal resizes, dialogs drain resize events, and the window enforces a minimum size instead of crashing. The minimum starts at a small floor and is raised once, after the first screen is drawn, to fit that screen's header plus a few body rows.
  9. Inline confirmation is unusually complete. Tiered matching (exact, then case-insensitive, then abbreviation), an auto-calculated minimum abbreviation length, and six modes including identity matching and free text.
  10. Real, dogfooded apps. The API is validated by several downstream projects (listed below), not by theory.
  11. Headless, testable core. The layout math and a headless render backend let the whole engine be exercised without a TTY.
  12. Display-cell correctness. A small standard-library width engine accounts for wide CJK/emoji and zero-width combining marks, so layout and highlighting stay correct across the body, header, dialogs and the demos that exercise wide and combining text.

Installation

Install the package via pip:

pip install console-window

Development

Working on console-window itself — running the lettered demos, the demo curriculum, the test gate and the release gate — is covered in tests/README-DEV.md. None of it is needed to use the installed package.

Core Features (The "Secret Sauce")

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 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.
  • Intuitive Navigation: Provides built-in handling for common navigation keys (j/k, UP/DOWN, Page Up/Down, H/M/L for home/middle/last viewable line, etc.).
  • Dynamic Options Management (OptionSpinner): The companion class simplifies creation of application settings, allowing users to cycle values or input strings using single keypresses (e.g., a theme name, or a validated free-text range).
  • Blocking Popups: Includes fully implemented, blocking pop-up methods for user input (.answer()) and alerts (.alert()), handling the necessary temporary screen takeover and cursor management.

Usage

The shape of every app

A Screen owns its content and its pick/scroll position; the window owns the terminal, the pads and key routing. The loop is four calls, and rebuilding the whole page every pass is the sanctioned style:

from types import SimpleNamespace

from console_window import ConsoleWindow, ConsoleWindowOpts, Screen


class Pager(Screen):
    def draw_screen(self) -> None:
        self.add_header('hello - q or ESC to quit')
        for i in range(100):
            self.add_body(f'row {i}')


def main() -> None:
    # ConsoleWindow.__init__ performs the curses setup (no curses.wrapper needed).
    # No row sizing is required; max_rows is only a safety ceiling.
    win = ConsoleWindow(opts=ConsoleWindowOpts(head_line=True))
    app = SimpleNamespace(win=win)
    screen = Pager(app)
    try:
        while True:
            screen.clear()          # content reset for the new pass
            screen.draw_screen()    # add_header()/add_body() only
            win.render()            # pads repaint, doupdate() diffs
            key = win.prompt(seconds=0.5)   # key code, or None on timeout
            if key in (ord('q'), 27):
                break
    finally:
        win.stop_curses()


if __name__ == '__main__':
    main()

clear() is also what hands the screen to the window, which is why it comes first. The pick/scroll position, pick mode and free-scroll latch live on the screen and survive each pass, so a rebuild never loses the user's place. For more than one screen, subclass Screen and drive the screens with ScreenStack — activation is a pointer swap, so returning to a screen restores its position with no copying in the application.

Inline editing and key forwarding

InlineConfirmation is a curses-free line editor. start(..., initial='x') seeds the buffer with the caret at the end; LEFT/RIGHT, Home/End (and Ctrl-A/Ctrl-E), Backspace and Delete edit at the caret. The get_display_string(prompt='…') method returns the prompt plus the buffer and caret glyph, so wording and layout stay in the application, while cursor_pos (string index) and cursor_cell (terminal column, measured with textwidth) are available to callers that need them.

Passthrough widgets receive printable ASCII, navigation keys, Backspace, Delete, Home/End, ESC and the keys in handled_keys while passthrough_mode is True. For any additional application key, use the reversible context manager rather than mutating handled_keys by hand:

win.passthrough_mode = True
try:
    with win.temp_handled_keys(27):
        key = win.prompt(seconds=0.5)
finally:
    win.passthrough_mode = False

Only keys the context actually added are removed on exit, so a pre-existing binding is left in place and nested uses are safe.

Transient status on the separator row

status() declares a one-line message that is painted on the separator row — the row that also owns the scroll indicator — so the listing stays visible. Unlike flash(), which clears the whole screen, status() never takes over the display:

win.status('Backup tag failed', level='error', timeout=5.0)

The message appears on the next render()/prompt(); status() never renders by itself. Levels 'info', 'warn' and 'error' select an attribute from ConsoleWindow.STATUS_LEVELS (info dim, warn bold, error bold+reverse); an unknown level falls back to 'info' instead of raising, and attr= overrides the level for that message only. timeout=None keeps the message until it is replaced or cleared; any number expires it lazily at draw time. status('') and clear_status() remove it, and current_status returns (text, attr).

The exact rendering rule is: the text starts at column 0 of the separator row and is truncated to leave one blank cell between it and the scroll indicator. If the window currently has no separator row, the text is still stored and status() returns False (the message is deferred, not lost); a later resize reveals it. With head_line=False there is no separator row at all, so status() also warns once per episode instead of painting over the first body row.

In-place prompts

PromptLine is the window-independent state machine: text, an editable buffer, an optional hint and completion callbacks. It never runs the callbacks itself; take() returns (answer, on_confirm, on_cancel) after cancelling the widget. The window wraps it with a lifecycle that keeps key routing and passthrough consistent:

win.begin_prompt('Overwrite the tag?', mode='y',
                 on_confirm=lambda answer: apply(answer))
while win.prompt_active:
    key = win.prompt(seconds=0.5)
    if win.handle_prompt_key(key) == 'continue':
        continue          # swallow every key while a prompt is live
    break
win.render()

While prompt_active is true, route every key through handle_prompt_key() and swallow a 'continue' result, so no action key can fire underneath a live prompt. begin_prompt() turns passthrough_mode on and end_prompt() restores its previous value; completion callbacks run after the prompt is gone and passthrough is restored, so a callback may safely begin the next prompt (the "re-edit, then ENTER or ESC" re-ask path).

The display formats are fixed so applications do not have to reproduce them:

  • single-key modes Y/y: f'{prompt} [Press "{mode}" or ESC]', e.g. Really quit? [Press "y" or ESC];
  • every other mode: f'{prompt}: {buffer}{caret}{rest}', e.g. Value: 5│.

get_hint_string(width) returns the hint (truncated when a width is given), and get_choice_lines() returns one row per choice, marking the currently resolved one: ➤ alpha versus beta. Drawing is the application's choice: Screen.add_prompt_header() puts a screen-wide question in the header band, while Screen.add_prompt_lines() appends a bold prompt row and a dim hint row as Context(genre='TRANSIENT', pickable=False) from the application's own row loop. The window never learns which item the prompt belongs to.

Read-only text screens

BasicTextScreen is the small Screen for preformatted, scrollable text. It resolves app.win at call 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 normalized by set_text(), which is safe before or after the first draw; the loop still calls screen.clear() before draw_screen():

screen = BasicTextScreen(app, head='COMPARE',
                         lines=[('first difference', curses.A_BOLD),
                                'second difference'])
screen.set_text(lines=['replacement'])

lines items are str or (str, attr); head may be a str, a HeaderLine, or an iterable of either. There is no pick mode, no action handler and no spinner: ESC/back uses the default Screen.escape_ACTION (pop), which the application may override.

Taking navigation keys for the application

Navigation keys are reserved by default, but an app may take specific ones for itself without monkeypatching the module global. Declare the key codes on the window's options:

import curses
from console_window import ConsoleWindowOpts, OptionSpinner

opts = ConsoleWindowOpts(
    taken_nav_keys=[curses.KEY_LEFT, curses.KEY_RIGHT],
)
win = ConsoleWindow(opts=opts)
spin = OptionSpinner(stack=stack, nav_keys=opts.nav_keys)  # accept them in add_key()
spin.add_key('prev', '⬅ - previous', genre='action', keys=[curses.KEY_LEFT])

A taken key is withdrawn from navigation dispatch for that window only: it no longer scrolls, it is no longer advertised as navigation, and it takes the normal handled_keys/relax_handled_keys path on return. The generated navigation help removes the key from its action: keys chunk; when every key in a chunk is taken the chunk disappears, and a chunk that loses only some keys is space-padded so the rest of the line keeps its columns. There is no second App: line: the app documents its own bindings in its own screen. Text editing is unchanged — dialogs and widgets still use LEFT/RIGHT/HOME/END for the caret. Because ownership lives in ConsoleWindowOpts, two windows in one process can have different bindings; NAVIGATION_KEYS itself is never mutated. Taking every vertical key is allowed (and logged as "reduced navigation"), since the application is then responsible for its own scrolling.

taken_nav_keys used to accept a {key_code: label} mapping; that form is deprecated and only its keys are used. Pass a list of key codes instead.

ScreenStack.perform_actions() is the normal router: it walks the spinner 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. ScreenStack.is_curr() answers the screen test on its own. A missing flag reads as False, so an options object need not pre-seed every action.

Help body, built-in actions and the spinner

A spinner registers two actions before the application registers anything: quit (q, ^C) and escape (ESC, ^J, ENTER). They are printed once in the NavKeys: block, never in the option body. Screen supplies the default handlers — quit_ACTION() exits and escape_ACTION() pops one screen (a no-op at home) — and an app overrides either method as usual. The key sets are constructor arguments:

spin = OptionSpinner(stack=stack, quit_keys=(ord('q'), ord('Q'), 0x3))

A ScreenStack owns at most one spinner: the spinner injects itself as stack.spinner, and the stack assigns each screen its num and stack, so a help screen finds the spinner without scanning the application. Constructing a second spinner on the same stack raises ValueError.

The help body describes the screen the help was pushed from. It lists that screen's options -- global ones and those scoped to it -- under a Keys for '<screen>': heading. Its cycle and prompt options keep working while the help is shown, so a value can be changed without backing out; actions are listed for reference but do nothing until you return to their screen. The built-in quit and escape stay in the NavKeys: block. Nothing pushed (a stackless spinner, or a help screen that is the entry screen) means the complete option list under an All keys: heading, and when nothing applies the heading is omitted. OptionSpinner.help_subject(screen) names the described screen and options_for_screen(screen) is the scope test the body applies to it. A registration that would take a built-in key must name its screens explicitly (scope=...); an implicit registration raises, so a global option can no longer silently unbind q/^C/ESC.

The body is laid out for the width the window has when it draws, so a narrow terminal shows all of it instead of clipping the right edge. The value column is measured from the rows that screen actually lists -- an action's description sets no column, because nothing follows it -- and a row that would overflow wraps: values break between entries and continue under the column, a single value too long for one row is ellipsized, and comments wrap under the same column (or two cells in from the option, when the column leaves too little room for prose). The heading wraps the same way. When the column itself leaves fewer than eight cells to wrap values in, the layout degrades in two steps: the four-cell dot gap first, then a flat layout with the description on its own row and its values beneath it, indented two cells. A resize re-flows on the next draw.

Any extra_help_paragraphs() come last: BasicHelpScreen draws an ---------- Instructions ---------- separator and then each paragraph in the normal attribute, introduced by a ◆ bullet with the wrapped rows indented three cells. The built-in Fonts section follows that block; set BasicHelpScreen.font_section = False on a subclass to leave it out of one screen.

Singleton vs. per-instance windows

ConsoleWindow supports two process-wide models, selected by the constructor's singleton argument:

  • singleton=True (default) — the historical process-wide model. Every window draws through one shared screen, ConsoleWindow.static_scr and ConsoleWindow.static_win are populated, and a second window reuses the first window's screen and backend. stop_curses() here suspends the shared screen and start_curses() resumes it (the pre-2.0 pair, kept working); ConsoleWindow.stop_all() is the permanent teardown and the atexit hook.
  • singleton=False — per-instance windows. Each window owns its screen, pads and teardown; win.stop_curses() stops only that window for good, ConsoleWindow.stop_all() stops every live window, and the unbound ConsoleWindow.stop_curses() is an error.

Pausing to run another program

To shell out (an editor, a package manager, efibootmgr, a confirmation prompt) and then come back, suspend instead of stopping:

win.suspend_curses()          # endwin(): the terminal is yours again
try:
    ... prints, input(), subprocess.run(...) ...
finally:
    win.resume_curses()       # reattaches a screen; the next render() repaints

endwin() restores the terminal without destroying the curses SCREEN, so the pads, the content model and the pick state all survive; resume refreshes the screen handle, backend, dimensions, pad backgrounds and redraw bookkeeping. In singleton mode suspend_curses() suspends every window that shares the screen, and resume_curses() reattaches all of them. The legacy pair works the same way there: ConsoleWindow.stop_curses(); ...; ConsoleWindow.start_curses(). The pre-2.0 instance hook win._start_curses() is also supported: it reattaches that window (resuming a suspended screen) and returns the live screen, so the old win.stop_curses(); ...; win._start_curses() sequence keeps working. Only stop_all() is a permanent teardown.

The first successful construction latches the mode for the whole process. 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: choosing a width and a fallback

The UI is built around 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 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 registered symbols are rewritten. Grüße stays Grüße: the substitution table contains the catalog's characters, never arbitrary text, so letters, digits and unregistered code points pass through byte for byte. A registered typographic mark does follow the mode, which is the point of it — an em dash inside file content becomes -- on an ASCII terminal rather than a box. The eight spellings this library used to draw (⮞, ←, →, ↑, ↓, ○, □, ■) are upgraded to their replacements (➤, ⬅, ➡, ⬆, ⬇, ◯, ◻, ◼) in both modes, so text written against an older release renders from the font that has it — inside content as well. Registering an old code point yourself keeps it. 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.

  • A one-cell catalog. The registry carries eighty named text symbols, grouped as UI marks, frames, arrows, triangles, filled/hollow shape pairs, blocks and bars, status marks, math, currency and typography. Every one is a single cell wide in Unicode and is covered by the default monospace font on Debian, Ubuntu and Fedora (DejaVu Sans Mono). Glyphs.catalog() returns the set in the active spelling and Glyphs.catalog_rows(width) packs it into display rows; the theme picker page prints all of them, so that page doubles as the font check. Glyphs.catalog_entries() adds the name and family (Glyphs.group_of('infinity') is 'math') for a table or a grouped listing, and Glyphs.lookup() returns the whole Glyph. A character has exactly one fallback even when two names draw it (cursor_block and swatch are the same block). Every lookup accepts either the name or the Unicode visual: Glyphs.get('│') and Glyphs.get('cursor') are the same request.

  • A two-cell emoji family. Some rows need a mark that is seen: a status column, a prompt badge. The 'emoji' group is the same Glyph type, with a stricter width contract: every entry is a single East-Asian-Width W code point, so it measures two cells in this library and in the terminal, appending a variation selector cannot change that, and the ASCII spelling is two cells as well. Glyphs.glyphs_in_group('emoji') lists the family and Glyphs.get('ok') returns the emoji, or its two-cell text fallback after --ascii, so switching modes never moves a column. Glyphs.find_issues(text) reports the four ways a two-cell mark is unsafe (VS16-promoted, zero-width joiner, East-Asian Ambiguous, unapproved) and says what to use instead, which is the quickest development-time check for a prompt or a table.

  • Pick the family by the row, not by a preference for text over emoji. A dense status column that can spare only one cell uses the one-cell symbols; an alert or badge that should be seen uses the emoji. When the chosen emoji cannot be drawn, switch to its two-cell text fallback — or to a one-cell symbol if the layout can spare only one cell. Both choices keep the presentation and the width the row was measured for. --ascii is a compatibility switch, not the preferred look.

  • The font bill for both families, checked on the help page. The one-cell catalog is covered by the stock monospace face: all 80 names (78 distinct characters) are in DejaVu Sans Mono, each at exactly the font's cell advance, so the text family needs no patched font. The two-cell family needs one colour emoji font — Noto Color Emoji, Apple Color Emoji or Segoe UI Emoji — from mid-2019 or later: 🧲 is Emoji 11 (2018) and 🟢/🟡 are Emoji 12 (2019), everything else dates from 2016 or earlier. No single font covers both (DejaVu Sans Mono has none of the emoji; Noto Color Emoji has 13 of the 78 one-cell glyphs), which is why the fallback is one switch rather than per-app font code. Every help page now draws the whole catalog and every emoji with the unconditional advice to install those two families; ConsoleWindowOpts(help_fonts='once' | 'always' | 'never') decides how often (default 'once', the first help page the window shows), and a symbol registered by the app is checked against its family at registration time and named on the page if the font lacks it. The measurements are pinned by the test suite.

  • App vocabulary. Register what only your app draws:

    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:

    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 color theme, and --theme mono draws the semantic roles with bold/reverse attributes instead of color. A non-empty NO_COLOR selects mono when no explicit theme is given. 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 help.theme_paragraph() (and any prose of your own) from Screen.extra_help_paragraphs(); BasicHelpScreen adds the separator, the bullet and the wrapping. The symbol check is no longer part of that block: the first help page in a run gets the built-in Fonts section, later pages do not mention it, and ConsoleWindowOpts(help_fonts=...) can keep it on every page or turn it off.

Themes work the same way: Theme.create_picker_screen(base, cycle_key=None, store=None, note=None, captions=None, include_defaults=True) 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. Theme.list_all() includes mono, so the picker cycles it like any other theme; its swatches follow the same switch, so a picker opened on mono previews the monochrome hierarchy rather than a previous theme's colors.

captions renames or re-describes the semantic roles the picker shows, which is useful when the application's vocabulary differs from the library's. The mapping is role -> (label, usage), where a role can be a Theme constant or a stable name such as 'danger'; None or '' keeps the library text. With the default include_defaults=True, overrides replace captions in place and the library rows remain; with include_defaults=False the mapping is the whole list, in mapping order. Unknown or duplicate roles raise ValueError when the factory runs.

ThemeScreen = Theme.create_picker_screen(
    DemoScreen,
    cycle_key='t',
    captions={
        'danger':  ('FAILED',   'Boot or initramfs failed'),
        'warning': ('DEGRADED', ''),  # keep the library usage text
    },
)

Override swatch_attr() on a subclass to style swatches differently, swatch_rows() for dynamic captions (translation, for example), and theme_label() only if an application adds its own pseudo-theme.

The appearance layer is shared too. Appearance.semantic_attr(role) returns the installed color pair for a semantic role, or the matching attribute from Appearance.MONO_ROLES when color is off or the terminal reports no color support; a lookup that fails before initscr() degrades to plain text, so a redraw is never aborted by a color. Appearance.resolve_appearance(cli_theme=None, saved_theme='', environ=None) returns the theme to start with: an explicit --theme first, then the NO_COLOR convention (mono), then the remembered choice. Pass the result to Theme.set_active(), which records it and synchronizes Appearance.colors_enabled() / Appearance.set_colors_enabled(); applications select mono rather than flipping the switch themselves. Apps keep their preference file and any additional pseudo-themes; the library gives them the policy, not the storage.

Versioning and Deprecation

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.

Deprecated APIs remain supported indefinitely. A deprecation is a request to migrate, not a scheduled removal: deprecated functions and parameters keep working, and one is removed only when there is significant value in doing so (for example, the API is actively harmful or blocks a necessary redesign). Deprecated paths emit a DeprecationWarning where practical.


3.1.0 Breakages

Glyphs and marks are one Glyph type. The separate two-cell mark API is gone; an emoji is simply a Glyph in the 'emoji' group, and its two-cell width is enforced by the same constructor. The families are fixed by GLYPH_GROUPS; an application cannot invent a new group name.

  • Removed: SafeMark, BUILTIN_MARKS, validate_mark(), register_mark(), mark(), marks(), marks_probe_text() and marks_rows(). Use Glyph(..., group='emoji'), Glyphs.register(..., group='emoji'), Glyphs.get(), and Glyphs.glyphs_in_group('emoji').
  • Glyph.group must be one of GLYPH_GROUPS. New registrations join 'application'; 'emoji' selects the two-cell contract. The former one-cell 'marks' family is now 'status'.
  • catalog_entries(), catalog_items() and catalog_rows() take include_emoji= instead of include_marks=.
  • Lookups accept the visual: Glyphs.get(), unicode_of(), lookup() and group_of() take a registered name or the Unicode character. When several names draw the same character, the first registered wins.

3.1.0 also carries the changes planned for 3.0.1, which is not a separate release: ConsoleWindowOpts(taken_nav_keys=...) takes an ordered list of key codes (the {key_code: label} mapping is deprecated and only its keys are used), and a taken key is pruned from the generated navigation help instead of being repeated in a second App: block. Screen.add_fancy_header() documents its string markup form on its own terms; the markup string is recommended whenever it is unambiguous, the explicit HeaderLine/Span form when the text must stay literal, and no existing call needs to move.

3.0.0 Breakages

3.0.0 is the first release after the 2.x line, so every deliberate break from 2.x is collected here, each with its replacement. 3.1.0 consolidates the glyph and mark families; its breaks are listed above.

The Screen owns content. Content and the pick/scroll state moved from ConsoleWindow onto Screen, which removes one of the two drawing models:

  • win.add_header(), win.add_body(), win.add_fancy_header(), win.add_header_line(), win.add_prompt_header() and win.add_prompt_lines() are gone. Call them on the current Screen instead (self.add_body(...) inside draw_screen()). The window keeps head/body as read-only views.
  • win.draw(y, x, text, ...) is gone, with highlight_picked() and the deferred drawn span store. There is one drawing model: append rows with add_*(); a row's column placement is composed by the application with textwidth.string_width/ljust/truncate.
  • Content and pick/scroll state are per screen. win.pick_pos, win.scroll_pos, win.pick_mode, win.free_scroll and win.pick_range read and write the current screen; pick_range is no longer stored in ConsoleWindowOpts, so two screens can hold different ranges. last_pick_pos and _pick_clear_pending are gone with the incremental painter.
  • The loop is screen.clear(); screen.draw_screen(); win.render(); win.prompt(). Screen.clear() is what makes the screen current, so it must be the first call. ConsoleWindow.clear() still works and resets the current screen's content, but it no longer wipes the physical screen (the pads repaint themselves every frame).
  • head_line=False now has no side effects. It no longer paints a rule, a scroll indicator or a status line onto the body's first row, and in scroll mode the pick tracks the top of the viewport (pick_pos == scroll_pos).

Appearance and themes. There are renames for consistency and some simplifications:

  • appearance is now Appearance. This matches the rest of the package root (Theme, Glyphs, Context, …).
  • --no-color is gone. Select the real mono theme instead (--theme mono), or rely on the NO_COLOR environment convention. cli.resolve_no_color() and the no_color= / saved_colors= parameters of Appearance.resolve_appearance() were removed with it.
  • Appearance.resolve_appearance() returns one theme name, not (theme, colors). Apply it with Theme.set_active(); mono is the color-off state.
  • dark-mono / light-mono are now dark / light. The old names are still accepted as aliases by --theme, remembered preferences and Theme.resolve(), but Theme.list_all() lists only the canonical names.
  • mono is a theme. It installs only the terminal-default background and uses Appearance.MONO_ROLES for the semantic roles. It is terminal-global like any other theme install, because curses owns one color-pair table per terminal.

The built-in symbols are the heavier, font-safe forms. The library moved the symbols it draws itself to the heavier variant wherever one exists in the default monospace font:

  • The resolved-choice marker is ➤ (U+27A4), not ⮞ (U+2B9E). U+2B9E is absent from DejaVu Sans Mono — the default on Debian, Ubuntu and Fedora — so the marker was drawn by whichever fallback font had it, which can be wider than one cell. Glyphs.get('choice'), get_choice_lines() and InlineConfirmation follow the new form; the ASCII fallback is still >. An application that hardcoded ⮞ should use ➤, or register ⮞ itself to keep the old look.
  • The arrows are the black forms. ⬅/➡ replace ←/→ (including the help legend's labels for taken keys) and ⬆/⬇ replace ↑/↓. The light code points are no longer registered, so text containing them is not transliterated; CONSOLE_WINDOW_GLYPH_AUDIT=1 reports them.
  • The hollow shapes are the heavier pair. ◯ replaces ○, and ◻/◼ replace □/■. The hollow triangles △▽◁▷ keep their light form: Unicode has no heavy outline triangle.
  • Old spellings are upgraded in both modes. ⮞, ←, →, ↑, ↓, ○, □ and ■ are rewritten to ➤, ⬅, ➡, ⬆, ⬇, ◯, ◻ and ◼ before the text is measured, in Unicode mode as well as ASCII. An unmodified application therefore picks up the font-safe shapes; registering one of the old code points (register('choice', '⮞', '>')) keeps it instead.

The font check is built into the first help page. BasicHelpScreen has a Fonts section that shows the whole one-cell catalog, every emoji and the two font families to install when the terminal does not draw them. The rows are fixed-width blocks: five ten-cell blocks plus five | markers per row, with partial blocks padded with ., so a box, a blank or a shifted column breaks the alignment visibly. The symbols and the emoji each start on their own row and fill out the last row of their section, so the two families stay visibly separate. The section appears on the first help page of a run by default and later help pages do not mention it. Choose how often it appears with ConsoleWindowOpts(help_fonts='once' | 'always' | 'never') (a bool is accepted), or override it per screen with BasicHelpScreen.font_section.


License

MIT

Comparable and Competing Projects

console-window is a niche tool. For almost everyone, one of the projects below is the better choice — reach for console-window specifically when you want a dependency-free, keyboard-driven list/detail viewer in the "pager meets selection engine" style and you are comfortable building your own widgets on top of it.

Framework Model Widgets Dependencies Async/threads Wide chars Testing Learning curve Best for
console-window head/body pads + scroll/pick + screen stack you build views from your own classes; options, search bar, inline confirmation, dialogs none (stdlib) sync polling yes (stdlib cell width) pytest, TTY-free, render via a fake backend low keyboard list/detail viewers, "less-like" browsers
urwid canvas + widget tree, event loop rich (ListBox, Tree, Edit, Overlay, Columns/Pile) wcwidth event loops yes (via wcwidth) good (examples, docs) medium general full-screen apps
Textual DOM + CSS, async, reactive very rich; mouse, animations, web target rich, markdown-it, typing-extensions, … asyncio-first yes strong (pytest harness) medium–high modern, styled, ambitious TUIs
prompt_toolkit input-centric full-screen editing, completion, dialogs; limited layout widgets wcwidth yes yes strong medium REPLs, shells, rich input
npyscreen forms/fields form widgets (menus, multisets) stdlib curses no partial sparse low classic form-style admin TUIs
py_cui widget grid menus, scroll, forms stdlib curses no partial some low quick dashboards
asciimatics screens + effects widgets + animation engine pyfiglet, pillow no partial some low–medium animated/demo screens
blessed raw terminfo control none (primitives) jinxed (Windows) no partial some low custom low-level drawing
Rich text/print styling (+Live/Layout) none (not a TUI toolkit) markdown-it-py, pygments partial yes strong low pretty output/logs, not navigation

Where console-window wins: zero dependencies; a tiny conceptual surface; excellent selection/paging semantics (abut, pick vs. scroll, decorative-row skipping); a scoped key router; efficient pad blitting; and a model already proven across several real apps.

Where it loses to the big two (urwid / Textual): no widget library, no mouse, no CSS/layout language, no async, no documentation site, single-window only. Textual in particular offers a testing framework and a modern developer experience a solo project cannot match — at the cost of a dependency tree and a very different paradigm.

Closest functional peers: npyscreen (form/list admin TUIs) and py_cui (dashboard grids) — both stdlib-curses, both simpler and less maintained than Textual/urwid. console-window is differentiated by its pager-centric selection model, which those two lack.

Projects Using console-window

For more extensive examples, you can look at some projects using console-window:

  • efibootdude
    • simple wrapper for efibootmgr
    • one of the smaller projects
    • demonstrates a context sensitive available keys lines (i.e., first line) where the actions depend on current line.
  • dwipe
    • disk cleaner with parallel jobs and stamps wiped partitions
  • pmemstat
    • system/process memory monitor with rollups and hooks for zRAM
  • memfo
    • viewer of /proc/meminfo that shows historical values
  • vappman
    • convenince wrapper to mostly hide CLI of AppMan, a life-cycle manager for 2000+ AppImages

Metadata

Release files for console-window 3.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for console-window 3.1.0
File Size Uploaded Provenance Actions
console_window-3.1.0.tar.gz 158.6 kB Without provenance Details for console_window-3.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for console-window 3.1.0
File Interpreter ABI Platform Actions
console_window-3.1.0-py3-none-any.whl Python 3 none any Details for console_window-3.1.0-py3-none-any.whl

Total release size: 309.3 kB

Release files / console_window-3.1.0.tar.gz

Download URL console_window-3.1.0.tar.gz
Size 158.6 kB
Tags Source
SHA-256 checksum
How to use checksums
86bdc9ce70cc9439154c929d113b95a5363d75ef36c365c0f1ba3d2755ff1499
BLAKE2b-256 checksum
How to use checksums
1cb7f0740df87ce8dd8d3cf4112b4982e71c3c96a79060c0184db56012ae9caf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Release files / console_window-3.1.0-py3-none-any.whl

Download URL console_window-3.1.0-py3-none-any.whl
Size 150.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
217ebe5056932be6e7e4070f1d1b4ff66131ceb6a9b3c9ab631ceefbe8cba2e4
BLAKE2b-256 checksum
How to use checksums
98c5f3cdee2f0060997ca18fbe7b2adfe30e228171b879ea469524b7d8fec71a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Security for console-window 3.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page