python_doc_md/Advanced/c-api/curses.md

Curses C API

curses{.interpreted-text role="mod"} exposes a small C interface for extension modules. Consumers must include the header file py_curses.h{.interpreted-text role="file"} (which is not included by default by Python.h{.interpreted-text role="file"}) and import_curses{.interpreted-text role="c:func"} must be invoked, usually as part of the module initialisation function, to populate PyCurses_API{.interpreted-text role="c:var"}.

:::: warning ::: title Warning :::

Neither the C API nor the pure Python curses{.interpreted-text role="mod"} module are compatible with subinterpreters. ::::

Import the curses C API. The macro does not need a semi-colon to be called.

On success, populate the PyCurses_API{.interpreted-text role="c:var"} pointer.

On failure, set PyCurses_API{.interpreted-text role="c:var"} to NULL and set an exception. The caller must check if an error occurred via PyErr_Occurred{.interpreted-text role="c:func"}:

import_curses();  // semi-colon is optional but recommended
if (PyErr_Occurred()) { /* cleanup */ }

Dynamically allocated object containing the curses C API. This variable is only available once import_curses{.interpreted-text role="c:macro"} succeeds.

PyCurses_API[0] corresponds to PyCursesWindow_Type{.interpreted-text role="c:data"}.

PyCurses_API[1], PyCurses_API[2], and PyCurses_API[3] are pointers to predicate functions of type int (*)(void).

When called, these predicates return whether curses.setupterm{.interpreted-text role="func"}, curses.initscr{.interpreted-text role="func"}, and curses.start_color{.interpreted-text role="func"} have been called respectively.

See also the convenience macros PyCursesSetupTermCalled{.interpreted-text role="c:macro"}, PyCursesInitialised{.interpreted-text role="c:macro"}, and PyCursesInitialisedColor{.interpreted-text role="c:macro"}.

:::: note ::: title Note :::

The number of entries in this structure is subject to changes. Consider using PyCurses_API_pointers{.interpreted-text role="c:macro"} to check if new fields are available or not. ::::

The number of accessible fields (4) in PyCurses_API{.interpreted-text role="c:var"}. This number is incremented whenever new fields are added.

The heap type <heap-types>{.interpreted-text role="ref"} corresponding to curses.window{.interpreted-text role="class"}.

Return true if op is a curses.window{.interpreted-text role="class"} instance, false otherwise.

The following macros are convenience macros expanding into C statements. In particular, they can only be used as macro; or macro, but not macro() or macro();.

Macro checking if curses.setupterm{.interpreted-text role="func"} has been called.

The macro expansion is roughly equivalent to:

{
    typedef int (*predicate_t)(void);
    predicate_t was_setupterm_called = (predicate_t)PyCurses_API[1];
    if (!was_setupterm_called()) {
        return NULL;
    }
}

Macro checking if curses.initscr{.interpreted-text role="func"} has been called.

The macro expansion is roughly equivalent to:

{
    typedef int (*predicate_t)(void);
    predicate_t was_initscr_called = (predicate_t)PyCurses_API[2];
    if (!was_initscr_called()) {
        return NULL;
    }
}

Macro checking if curses.start_color{.interpreted-text role="func"} has been called.

The macro expansion is roughly equivalent to:

{
    typedef int (*predicate_t)(void);
    predicate_t was_start_color_called = (predicate_t)PyCurses_API[3];
    if (!was_start_color_called()) {
        return NULL;
    }
}

Internal data

The following objects are exposed by the C API but should be considered internal-only.

Name of the curses capsule to pass to PyCapsule_Import{.interpreted-text role="c:func"}.

Internal usage only. Use import_curses{.interpreted-text role="c:macro"} instead.