add internal apis of curses

Author: shihai1991

Doc/whatsnew/3.12.rst

@@ -980,6 +980,12 @@ New Features
   to replace the legacy-api :c:func:`PyErr_Display`. (Contributed by
   Irit Katriel in :gh:`102755`).
 
+* Convert the ``PyCurses_API`` C API (``_curses._C_API`` capsule) from a pointer
+  array to a structure(``PyCurses_C_API``) in pycore_curses.h. ``PyCursesWindow_Type``,
+  ``PyCursesSetupTermCalled``, ``PyCursesInitialised``, ``PyCursesInitialisedColor``
+  be moved into internal APIs and the public API will be deprecated in 3.14.
+  (Contributed by Hai Shi in :gh:`87175`).
+
 Porting to Python 3.12
 ----------------------
 

Include/internal/pycore_curses.h

@@ -0,0 +1,46 @@
+#ifndef Py_INTERNAL_CURSES_H
+#define Py_INTERNAL_CURSES_H
+
+#ifndef Py_BUILD_CORE
+#  error "this header requires Py_BUILD_CORE define"
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct {
+    PyTypeObject *window_type;
+    int (*setup_term_called)(void);
+    int (*initialized)(void);
+    int (*initialized_color)(void);
+} PyCurses_CAPI;
+
+#ifdef CURSES_MODULE
+/* This section is used when compiling _cursesmodule.c */
+
+#else
+/* This section is used in modules that use the _cursesmodule API */
+
+static PyCurses_CAPI *PyCurses_C_API;
+
+#undef PyCursesWindow_Type
+#undef PyCursesSetupTermCalled
+#undef PyCursesInitialised
+#undef PyCursesInitialisedColor
+#define PyCursesWindow_Type (*PyCurses_C_API->window_type)
+#define PyCursesSetupTermCalled  {if (!PyCurses_C_API->setup_term_called()) return NULL;}
+#define PyCursesInitialised      {if (!PyCurses_C_API->initialized()) return NULL;}
+#define PyCursesInitialisedColor {if (!PyCurses_C_API->initialized_color()) return NULL;}
+
+#undef import_curses
+#define import_curses() \
+    PyCurses_C_API = PyCapsule_Import(PyCurses_CAPSULE_NAME, 1);
+
+#endif
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* !Py_INTERNAL_CURSES_H */

Include/py_curses.h

@@ -54,6 +54,8 @@
 extern "C" {
 #endif
 
+#define PyCurses_API_pointers 4
+
 /* Type declarations */
 
 typedef struct {
@@ -62,13 +64,6 @@ typedef struct {
     char *encoding;
 } PyCursesWindowObject;
 
-typedef struct {
-    PyTypeObject *window_type;
-    int (*setup_term_called)(void);
-    int (*initialized)(void);
-    int (*initialized_color)(void);
-} PyCurses_CAPI;
-
 #define PyCursesWindow_Check(v) Py_IS_TYPE((v), &PyCursesWindow_Type)
 
 #define PyCurses_CAPSULE_NAME "_curses._C_API"
@@ -80,15 +75,16 @@ typedef struct {
 #else
 /* This section is used in modules that use the _cursesmodule API */
 
-static PyCurses_CAPI *PyCurses_API;
+Py_DEPRECATED(3.14) static void **PyCurses_API;
 
-#define PyCursesWindow_Type (*PyCurses_API->window_type)
-#define PyCursesSetupTermCalled  {if (!PyCurses_API->setup_term_called()) return NULL;}
-#define PyCursesInitialised      {if (!PyCurses_API->initialized()) return NULL;}
-#define PyCursesInitialisedColor {if (!PyCurses_API->initialized_color()) return NULL;}
+/* Those macros will be deprecated in 3.14 and moved into internal APIs.  */
+#define PyCursesWindow_Type (*_PyType_CAST(PyCurses_API[0]))
+#define PyCursesSetupTermCalled  {if (! ((int (*)(void))PyCurses_API[1]) () ) return NULL;}
+#define PyCursesInitialised      {if (! ((int (*)(void))PyCurses_API[2]) () ) return NULL;}
+#define PyCursesInitialisedColor {if (! ((int (*)(void))PyCurses_API[3]) () ) return NULL;}
 
 #define import_curses() \
-    PyCurses_API = PyCapsule_Import(PyCurses_CAPSULE_NAME, 1);
+    PyCurses_API = (void **)PyCapsule_Import(PyCurses_CAPSULE_NAME, 1);
 
 #endif
 

Makefile.pre.in

@@ -1671,6 +1671,7 @@ PYTHON_HEADERS= \
 		$(srcdir)/Include/internal/pycore_compile.h \
 		$(srcdir)/Include/internal/pycore_condvar.h \
 		$(srcdir)/Include/internal/pycore_context.h \
+        $(srcdir)/Include/internal/pycore_curses.h \
 		$(srcdir)/Include/internal/pycore_dict.h \
 		$(srcdir)/Include/internal/pycore_dict_state.h \
 		$(srcdir)/Include/internal/pycore_descrobject.h \

Misc/NEWS.d/next/C API/2023-05-17-00-59-26.gh-issue-87175.VpxNNY.rst

@@ -0,0 +1,2 @@
+Convert the ``PyCurses_API`` C API (``_curses._C_API`` capsule) from a pointer array to a structure(``PyCurses_C_API``) in pycore_curses.h.
+``PyCursesWindow_Type``, ``PyCursesSetupTermCalled``, ``PyCursesInitialised``, ``PyCursesInitialisedColor`` be moved into internal APIs and the public API will be deprecated in 3.14.

Misc/NEWS.d/next/Core and Builtins/2021-01-26-19-19-57.bpo-43009.NYkINR.rst

@@ -10,9 +10,14 @@ static const char PyCursesVersion[] = "2.1";
 
 /* Includes */
 
+#ifndef Py_BUILD_CORE_BUILTIN
+#  define Py_BUILD_CORE_MODULE 1
+#endif
+
 #include "Python.h"
 
 #include "py_curses.h"
+#include "pycore_curses.h"
 
 #include <panel.h>
 

Modules/_curses_panel.c

@@ -116,6 +116,7 @@ static const char PyCursesVersion[] = "2.2";
 
 #define CURSES_MODULE
 #include "py_curses.h"
+#include "pycore_curses.h"
 
 #if defined(HAVE_TERM_H) || defined(__sgi)
 /* For termname, longname, putp, tigetflag, tigetnum, tigetstr, tparm

Modules/_cursesmodule.c

@@ -209,6 +209,7 @@
     <ClInclude Include="..\Include\internal\pycore_compile.h" />
     <ClInclude Include="..\Include\internal\pycore_condvar.h" />
     <ClInclude Include="..\Include\internal\pycore_context.h" />
+    <ClInclude Include="..\Include\internal\pycore_curses.h" />
     <ClInclude Include="..\Include\internal\pycore_descrobject.h" />
     <ClInclude Include="..\Include\internal\pycore_dict.h" />
     <ClInclude Include="..\Include\internal\pycore_dict_state.h" />

PCbuild/pythoncore.vcxproj

@@ -534,6 +534,9 @@
     <ClInclude Include="..\Include\internal\pycore_context.h">
       <Filter>Include\internal</Filter>
     </ClInclude>
+    <ClInclude Include="..\Include\internal\pycore_curses.h">
+      <Filter>Include\internal</Filter>
+    </ClInclude>
     <ClInclude Include="..\Include\internal\pycore_descrobject.h">
       <Filter>Include\internal</Filter>
     </ClInclude>