Curtsies: Curses-like Terminal Wrapper

0.4.3 · active · verified Wed Apr 15

Curtsies is a Python library designed for interactive terminal applications, offering full-screen window management, user input handling, and formatted text rendering with colors and styles. It enables developers to create dynamic terminal interfaces like text editors or games. The current version is 0.4.3, and it has a moderate release cadence, with recent updates focusing on Python version compatibility and minor feature enhancements.

Warnings

breaking Python 3.7, 3.8, and 3.9 are no longer supported. Users on these Python versions must upgrade to Python 3.10 or newer, or stick to an older curtsies version.
Fix: Upgrade your Python environment to 3.10+ or pin `curtsies<0.4.3`.
breaking Curtsies switched its backend from `curses` to `blessed` in version 0.4.0. While largely compatible, subtle behavioral changes or reliance on `curses`-specific features might break existing code.
Fix: Review your application's terminal interaction, especially if you were previously interacting directly with the underlying `curses` library functionality. Test thoroughly after upgrading.
breaking Python 3.6 support was dropped in version 0.4.0. Users on Python 3.6 must upgrade or use an older `curtsies` version.
Fix: Upgrade your Python environment to 3.7+ (preferably 3.10+) or pin `curtsies<0.4.0`.
gotcha Application crashes can leave the terminal in a 'messed up' state (e.g., no echo, strange characters). This is common for `curses`-like libraries.
Fix: Always wrap your `curtsies` code within `with FullscreenWindow() as window:` and `with Input() as input_generator:` context managers to ensure proper terminal restoration. For debugging, consider using `python -m curtsies.events` or `reset` command in your terminal if it gets stuck.
gotcha The `Input` class can return keypresses named differently depending on the `keynames` parameter. The default 'curtsies' might differ from 'curses' or 'plain', leading to unexpected input handling if not explicitly specified.
Fix: If integrating with `curses`-compatible code or needing specific key names, initialize `Input` with `keynames='curses'` or `keynames='plain'`. Always test input handling on various terminal emulators.

Install

pip install curtsies Install stable version

Imports

FullscreenWindow
```
from curtsies import FullscreenWindow
```
Input
```
from curtsies import Input
```
FSArray
```
from curtsies import FSArray
```

fmtfuncs

from curtsies.fmtfuncs import red, bold, on_blue

Quickstart

This example initializes a full-screen terminal window, displays an instruction message, and then continuously captures user input. Pressing the escape key exits the application. Pressing space clears the screen, and other key presses are rendered randomly on the screen with different colors. This demonstrates basic window management, formatted text, and input handling.

import random
import sys
from curtsies import FullscreenWindow, Input, FSArray
from curtsies.fmtfuncs import red, bold, green, on_blue, yellow

print(yellow('This prints normally, not to the alternate screen'))

with FullscreenWindow() as window:
    a = FSArray(window.height, window.width)
    msg = red(on_blue(bold('Press escape to exit, space to clear.')))
    a[0:1, 0:msg.width] = [msg]
    window.render_to_terminal(a)

    with Input() as input_generator:
        for c in input_generator:
            if c == '<ESC>':
                break
            elif c == '<SPACE>':
                a = FSArray(window.height, window.width)
            else:
                s = repr(c)
                row = random.choice(range(window.height))
                column = random.choice(range(window.width - len(s)))
                color = random.choice([red, green, on_blue, yellow])
                a[row, column:column + len(s)] = [color(s)]
            window.render_to_terminal(a)

view raw JSON →