gh-152263: Add curses soft-label-key functions by serhiy-storchaka · Pull Request #152264 · python/cpython · GitHub

Wrap the X/Open Curses soft-label-key functions in the curses module. Soft labels are a row of labels along the bottom line of the screen, conventionally labelling a row of function keys, managed and refreshed independently of the standard window.

Added module-level functions:

slk_init(fmt=0) — reserve a screen line for the labels and choose their layout. Must be called before initscr() or newterm().
slk_set(labnum, label, justify) / slk_label(labnum) — set and query a label's text.
slk_refresh(), slk_noutrefresh(), slk_clear(), slk_restore(), slk_touch().
slk_attron(attr), slk_attroff(attr), slk_attrset(attr), slk_attr() — the chtype attribute functions.
slk_attr_on(attr), slk_attr_off(attr), slk_attr_set(attr, pair=0), slk_color(pair) — the attr_t/color-pair attribute functions.

slk_set uses slk_wset for wide-character labels when built against ncursesw. Tests drive their own pseudo-terminals (soft labels must be initialised before newterm()), and pass under UTF-8, Latin-1 and C locales.

Issue: Add curses soft-label-key (slk_*) functions #152263

Wrap the X/Open Curses soft-label-key functions: slk_init, slk_set, slk_label, slk_refresh, slk_noutrefresh, slk_clear, slk_restore, slk_touch, the chtype attribute functions slk_attron, slk_attroff, slk_attrset and slk_attr, and the attr_t functions slk_attr_on, slk_attr_off, slk_attr_set and slk_color. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Documentation build overview

📚 cpython-previews | 🛠️ Build #33359890 | 📁 Comparing 2facde8 against main (8eb6fb0)

🔍 Preview build

27 files changed · ± 26 modified · - 1 deleted

± Modified

- Deleted

library/asyncio-policy.html

I didn't know soft-label-key functions. Is it commonly used? I'm not sure that it's worth it to expose these functions.

Soft labels are a row of labels displayed along the bottom line of the screen, conventionally used to label a row of function keys

Would you be able to write a short demo so I can see how it does look like?

(I don't understand well the purpose of these functions.)

No, they are not often used. But they are the part of the Posix standard. Demo:

import curses

LABELS = ["Help", "Save", "Open", "Find", "Run", "Stop", "Setup", "Quit"]
def main(stdscr):
    for i, text in enumerate(LABELS):
        curses.slk_set(i + 1, text, 1) # 1 - center
    curses.slk_refresh()
    stdscr.addstr(0, 0, "Soft labels are on the bottom line. Press any key.")
    stdscr.getkey()
curses.slk_init(0) # 3-2-3 layout
curses.wrapper(main)

# Conflicts: # Doc/whatsnew/3.16.rst # Modules/clinic/_cursesmodule.c.h

refresh is a window method, not a module function; reference it as window.refresh so the documentation builds without warnings. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

# Conflicts: # Doc/whatsnew/3.16.rst # Modules/clinic/_cursesmodule.c.h

# Conflicts: # Modules/clinic/_cursesmodule.c.h

On Fedora 44, the example looks like:

3 is only supported on ncurses? If yes, can we reject 3 if the Python _curses module is not linked to ncurses?

I will test how out-of-range values are handled. Most likely you will get a curses.error.

Other implementations can also support them.

Would it be possible to move these functions in a new "Soft-label keys" section?

Yes. I just reorganized the docs (#152584), these functions will be in a separate section.

Co-authored-by: Victor Stinner <vstinner@python.org>

LGTM.

For slk_init(), I'm fine with not rejecting fmt=3 but just pass the value to curses.

For the doc, I didn't see the reorganized doc. Nice.

Ah, and good luck to solve the merge conflicts :-)

# Conflicts: # Doc/library/curses.rst # Doc/whatsnew/3.16.rst # Modules/clinic/_cursesmodule.c.h

…es curses Soft-label formats 2 and 3 are ncurses extensions; other curses implementations (such as NetBSD curses) reject them with an error. Require every format to work on ncurses, but tolerate the extended formats being unsupported elsewhere. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Thank you. This was peanuts in comparison with five PRs fighting for the same place in What's New, with flaky CI tests.

serhiy-storchaka requested a review from AA-Turner as a code owner June 26, 2026 11:35

bedevere-app Bot added the awaiting core review label Jun 26, 2026

bedevere-app Bot mentioned this pull request Jun 26, 2026

Add curses soft-label-key (slk_*) functions #152263

Closed

serhiy-storchaka and others added 5 commits June 26, 2026 20:02

Merge remote-tracking branch 'upstream/main' into curses-slk

b84ccee

# Conflicts: # Doc/whatsnew/3.16.rst # Modules/clinic/_cursesmodule.c.h

pythongh-152263 : Fix the slk_refresh() doc cross-reference

721fa9d

refresh is a window method, not a module function; reference it as window.refresh so the documentation builds without warnings. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Merge remote-tracking branch 'upstream/main' into curses-slk

2dbfe58

# Conflicts: # Doc/whatsnew/3.16.rst # Modules/clinic/_cursesmodule.c.h

Merge commit '3fa72d5c2e8188b5aca45e0c50349f9bdfda245f' into curses-slk

8151276

Merge remote-tracking branch 'upstream/main' into curses-slk

ef29195

# Conflicts: # Modules/clinic/_cursesmodule.c.h

vstinner reviewed Jun 29, 2026

View reviewed changes

Apply suggestions from code review

037ecd5

Co-authored-by: Victor Stinner <vstinner@python.org>

vstinner approved these changes Jun 29, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting core review labels Jun 29, 2026

serhiy-storchaka and others added 3 commits June 29, 2026 19:12

Merge remote-tracking branch 'upstream/main' into curses-slk

c4e11b8

# Conflicts: # Doc/library/curses.rst # Doc/whatsnew/3.16.rst # Modules/clinic/_cursesmodule.c.h

Move the Soft labels section after Windows and pads

75013a2

serhiy-storchaka merged commit 089e6f6 into python:main Jun 29, 2026
54 checks passed

bedevere-app Bot removed the awaiting merge label Jun 29, 2026

serhiy-storchaka deleted the curses-slk branch June 29, 2026 17:58

+                  fmt: int = 0
+                      Label layout: 0 = 3-2-3, 1 = 4-4 (8 labels each); 2 = 4-4-4,
+= 4-4-4 with an index line (12 labels each, ncurses extensions).


		.. _curses-slk:

		The following functions manage soft-label keys, a row of labels displayed

gh-152263: Add curses soft-label-key functions by serhiy-storchaka · Pull Request #152264 · python/cpython · GitHub

Repository navigation

gh-152263: Add curses soft-label-key functions - #152264

gh-152263: Add curses soft-label-key functions#152264serhiy-storchaka merged 10 commits intopython:mainpython/cpython:mainfrom serhiy-storchaka:curses-slkserhiy-storchaka/cpython:curses-slkCopy head branch name to clipboard

Conversation

serhiy-storchaka commented Jun 26, 2026

Uh oh!

read-the-docs-community Bot commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

vstinner commented Jun 26, 2026

Uh oh!

serhiy-storchaka commented Jun 26, 2026

Uh oh!

vstinner commented Jun 29, 2026

Uh oh!

vstinner Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vstinner Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

vstinner commented Jun 29, 2026

Uh oh!

Uh oh!

serhiy-storchaka commented Jun 29, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gh-152263: Add curses soft-label-key functions#152264
serhiy-storchaka merged 10 commits into
python:mainfrom
serhiy-storchaka:curses-slk

read-the-docs-community Bot commented Jun 26, 2026 •
edited
Loading