gh-152233: Add curses complexchar type and wide-character cell reads

[serhiy-storchaka]

Add the immutable curses.complexchar type: a styled wide-character cell — a spacing character optionally followed by combining characters, plus attributes and a color pair. The color pair is stored separately rather than packed into a chtype via COLOR_PAIR(), so it is not limited to the values that fit alongside the attribute bits. str(cc) returns the text; the read-only attr and pair attributes return its rendition.

Add the window methods in_wch() and getbkgrnd() — the wide-character counterparts of inch() and getbkgd() — which return a complexchar. (inch()/getbkgd() can only return a packed chtype, so these fill a real gap; this resolves the long-standing gh-83395 request for in_wch.)

The existing character-cell methods (addch, insch, echochar, bkgd, bkgdset, border, box, hline, vline) now also accept a complexchar. A complexchar already carries its own rendition, so passing one together with an explicit attr argument raises TypeError.

Only the reads get a dedicated wide method: a read returns a complexchar instead of a packed chtype, which is a genuine behavioural difference (mirroring getch()/get_wch()). Writes do not differ, so rather than adding parallel add_wch/ins_wch/… methods, the existing writers simply accept a complexchar.

This is the first of two changes for the cchar_t API (gh-152233); a follow-up adds the complexstr cell-array type and the array read/write methods.

• Issue: Add the cchar_t (complex character) API to the curses module #152233

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33320243 | 📁 Comparing 7e7c8a9 against main (285d96d)

  🔍 Preview build  

3 files changed

± library/curses.html
± whatsnew/3.16.html
± whatsnew/changelog.html