curses: incorrect and incomplete documentation of the reading functions #156234

The documentation of the curses functions that read input and window contents contains errors and omissions.

Wrong types: window.instr() and window.getstr() are documented as returning a string, and their n as a number of characters, while they return a bytes object and n limits the number of bytes. instr() also mentions a trailing NUL, which a bytes object does not have. window.getkey() returns a str, not a "multibyte string". unctrl() returns a bytes object, not a string.

It is not said whether an integer standing for a character is an encoded byte (as in window.addch() and ungetch()) or a character code (as in unget_wch(), which does not accept a key code).

Omissions with respect to X/Open Curses: special keys are only translated to the KEY_* constants in keypad mode, which is not the default; the window is refreshed before a read; a read can also time out, not only be non-blocking.

Linked PRs

• gh-156234: Fix and rewrite the curses documentation on reading #156235
• [3.15] gh-156234: Fix and rewrite the curses documentation on reading (GH-156235) #156279
• [3.14] gh-156234: Fix and rewrite the curses documentation on reading (GH-156235) #156280
• [3.13] gh-156234: Fix and rewrite the curses documentation on reading (GH-156235) #156281