gh-107211: No longer export internal functions (4) (#107217)

No longer export these 2 internal C API functions:

* _PyEval_SignalAsyncExc()
* _PyEval_SignalReceived()

Add also comments explaining why some internal functions have to be
exported, and update existing comments.

13 files changed, 29 insertions, 15 deletions

diff --git a/Include/internal/pycore_atexit.h b/Include/internal/pycore_atexit.h
index fc5cb6d..3966df7 100644
--- a/Include/internal/pycore_atexit.h
+++ b/Include/internal/pycore_atexit.h
@@ -51,6 +51,7 @@ struct atexit_state {
     int callback_len;
 };
 
+// Export for '_xxinterpchannels' shared extension
 PyAPI_FUNC(int) _Py_AtExit(
     PyInterpreterState *interp,
     atexit_datacallbackfunc func,
diff --git a/Include/internal/pycore_ceval.h b/Include/internal/pycore_ceval.h
index ea5b99e..05b7380 100644
--- a/Include/internal/pycore_ceval.h
+++ b/Include/internal/pycore_ceval.h
@@ -23,13 +23,14 @@ struct _ceval_runtime_state;
 extern void _Py_FinishPendingCalls(PyThreadState *tstate);
 extern void _PyEval_InitState(PyInterpreterState *, PyThread_type_lock);
 extern void _PyEval_FiniState(struct _ceval_state *ceval);
-PyAPI_FUNC(void) _PyEval_SignalReceived(PyInterpreterState *interp);
+extern void _PyEval_SignalReceived(PyInterpreterState *interp);
+// Export for '_testinternalcapi' shared extension
 PyAPI_FUNC(int) _PyEval_AddPendingCall(
     PyInterpreterState *interp,
     int (*func)(void *),
     void *arg,
     int mainthreadonly);
-PyAPI_FUNC(void) _PyEval_SignalAsyncExc(PyInterpreterState *interp);
+extern void _PyEval_SignalAsyncExc(PyInterpreterState *interp);
 #ifdef HAVE_FORK
 extern PyStatus _PyEval_ReInitThreads(PyThreadState *tstate);
 #endif
@@ -122,6 +123,7 @@ static inline int _Py_MakeRecCheck(PyThreadState *tstate) {
 }
 #endif
 
+// Export for _Py_EnterRecursiveCall()
 PyAPI_FUNC(int) _Py_CheckRecursiveCall(
     PyThreadState *tstate,
     const char *where);
diff --git a/Include/internal/pycore_code.h b/Include/internal/pycore_code.h
index 62a943b..bcdf864 100644
--- a/Include/internal/pycore_code.h
+++ b/Include/internal/pycore_code.h
@@ -262,7 +262,6 @@ extern int _PyStaticCode_Init(PyCodeObject *co);
 
 #ifdef Py_STATS
 
-
 #define STAT_INC(opname, name) do { if (_py_stats) _py_stats->opcode_stats[opname].specialization.name++; } while (0)
 #define STAT_DEC(opname, name) do { if (_py_stats) _py_stats->opcode_stats[opname].specialization.name--; } while (0)
 #define OPCODE_EXE_INC(opname) do { if (_py_stats) _py_stats->opcode_stats[opname].execution_count++; } while (0)
@@ -274,7 +273,7 @@ extern int _PyStaticCode_Init(PyCodeObject *co);
 #define EVAL_CALL_STAT_INC_IF_FUNCTION(name, callable) \
     do { if (_py_stats && PyFunction_Check(callable)) _py_stats->call_stats.eval_calls[name]++; } while (0)
 
-// Export for stdlib '_opcode' shared extension
+// Export for '_opcode' shared extension
 PyAPI_FUNC(PyObject*) _Py_GetSpecializationStats(void);
 
 #else
diff --git a/Include/internal/pycore_initconfig.h b/Include/internal/pycore_initconfig.h
index 67ca8ca..0945bb0 100644
--- a/Include/internal/pycore_initconfig.h
+++ b/Include/internal/pycore_initconfig.h
@@ -122,6 +122,7 @@ extern PyStatus _PyPreCmdline_Read(_PyPreCmdline *cmdline,
 
 /* --- PyPreConfig ----------------------------------------------- */
 
+// Export for '_testembed' program
 PyAPI_FUNC(void) _PyPreConfig_InitCompatConfig(PyPreConfig *preconfig);
 extern void _PyPreConfig_InitFromConfig(
     PyPreConfig *preconfig,
@@ -146,6 +147,7 @@ typedef enum {
     _PyConfig_INIT_ISOLATED = 3
 } _PyConfigInitEnum;
 
+// Export for '_testembed' program
 PyAPI_FUNC(void) _PyConfig_InitCompatConfig(PyConfig *config);
 extern PyStatus _PyConfig_Copy(
     PyConfig *config,
diff --git a/Include/internal/pycore_interp.h b/Include/internal/pycore_interp.h
index 260614e..522ce4a 100644
--- a/Include/internal/pycore_interp.h
+++ b/Include/internal/pycore_interp.h
@@ -238,6 +238,7 @@ extern int _PyInterpreterState_IDInitref(PyInterpreterState *);
 extern int _PyInterpreterState_IDIncref(PyInterpreterState *);
 extern void _PyInterpreterState_IDDecref(PyInterpreterState *);
 
+// Export for '_xxsubinterpreters' shared extension
 PyAPI_FUNC(PyObject*) _PyInterpreterState_GetMainModule(PyInterpreterState *);
 
 extern const PyConfig* _PyInterpreterState_GetConfig(PyInterpreterState *interp);
@@ -253,7 +254,9 @@ extern const PyConfig* _PyInterpreterState_GetConfig(PyInterpreterState *interp)
    The caller must hold the GIL.
 
    Once done with the configuration, PyConfig_Clear() must be called to clear
-   it. */
+   it.
+
+   Export for '_testinternalcapi' shared extension. */
 PyAPI_FUNC(int) _PyInterpreterState_GetConfigCopy(
     struct PyConfig *config);
 
@@ -271,7 +274,9 @@ PyAPI_FUNC(int) _PyInterpreterState_GetConfigCopy(
 
    Return 0 on success. Raise an exception and return -1 on error.
 
-   The configuration should come from _PyInterpreterState_GetConfigCopy(). */
+   The configuration should come from _PyInterpreterState_GetConfigCopy().
+
+   Export for '_testinternalcapi' shared extension. */
 PyAPI_FUNC(int) _PyInterpreterState_SetConfig(
     const struct PyConfig *config);
 
diff --git a/Include/internal/pycore_interp_id.h b/Include/internal/pycore_interp_id.h
index 34c96df..8c6f831 100644
--- a/Include/internal/pycore_interp_id.h
+++ b/Include/internal/pycore_interp_id.h
@@ -10,16 +10,16 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
-// Export for the _xxsubinterpreters shared extension
+// Export for '_xxsubinterpreters' shared extension
 PyAPI_DATA(PyTypeObject) _PyInterpreterID_Type;
 
-// Export for the _xxsubinterpreters shared extension
+// Export for '_xxsubinterpreters' shared extension
 PyAPI_FUNC(PyObject*) _PyInterpreterID_New(int64_t);
 
-// Export for the _xxinterpchannels shared extension
+// Export for '_xxinterpchannels' shared extension
 PyAPI_FUNC(PyObject*) _PyInterpreterState_GetIDObject(PyInterpreterState *);
 
-// Export for the _testinternalcapi shared extension
+// Export for '_testinternalcapi' shared extension
 PyAPI_FUNC(PyInterpreterState*) _PyInterpreterID_LookUp(PyObject *);
 
 #ifdef __cplusplus
diff --git a/Include/internal/pycore_namespace.h b/Include/internal/pycore_namespace.h
index 9423547..f165cf1 100644
--- a/Include/internal/pycore_namespace.h
+++ b/Include/internal/pycore_namespace.h
@@ -12,6 +12,7 @@ extern "C" {
 
 extern PyTypeObject _PyNamespace_Type;
 
+// Export for '_testmultiphase' shared extension
 PyAPI_FUNC(PyObject*) _PyNamespace_New(PyObject *kwds);
 
 #ifdef __cplusplus
diff --git a/Include/internal/pycore_object.h b/Include/internal/pycore_object.h
index c65c21c..6bf9dc2 100644
--- a/Include/internal/pycore_object.h
+++ b/Include/internal/pycore_object.h
@@ -434,7 +434,8 @@ extern PyObject ** _PyObject_ComputedDictPointer(PyObject *);
 extern void _PyObject_FreeInstanceAttributes(PyObject *obj);
 extern int _PyObject_IsInstanceDictEmpty(PyObject *);
 
-PyAPI_FUNC(PyObject *) _PyObject_LookupSpecial(PyObject *, PyObject *);
+// Export for 'math' shared extension
+PyAPI_FUNC(PyObject*) _PyObject_LookupSpecial(PyObject *, PyObject *);
 
 extern int _PyObject_IsAbstract(PyObject *);
 
diff --git a/Include/internal/pycore_pathconfig.h b/Include/internal/pycore_pathconfig.h
index b8deaa0..729f3e0 100644
--- a/Include/internal/pycore_pathconfig.h
+++ b/Include/internal/pycore_pathconfig.h
@@ -8,6 +8,7 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
+// Export for '_testinternalcapi' shared extension
 PyAPI_FUNC(void) _PyPathConfig_ClearGlobal(void);
 extern PyStatus _PyPathConfig_ReadGlobal(PyConfig *config);
 extern PyStatus _PyPathConfig_UpdateGlobal(const PyConfig *config);
diff --git a/Include/internal/pycore_pylifecycle.h b/Include/internal/pycore_pylifecycle.h
index fb28652..b4d5b1f 100644
--- a/Include/internal/pycore_pylifecycle.h
+++ b/Include/internal/pycore_pylifecycle.h
@@ -103,6 +103,7 @@ PyAPI_FUNC(int) _Py_IsInterpreterFinalizing(PyInterpreterState *interp);
 
 /* Random */
 extern int _PyOS_URandom(void *buffer, Py_ssize_t size);
+// Export for '_random' shared extension
 PyAPI_FUNC(int) _PyOS_URandomNonblock(void *buffer, Py_ssize_t size);
 
 /* Legacy locale support */
diff --git a/Include/internal/pycore_pymem.h b/Include/internal/pycore_pymem.h
index 017a60a..6b51137 100644
--- a/Include/internal/pycore_pymem.h
+++ b/Include/internal/pycore_pymem.h
@@ -10,14 +10,14 @@ extern "C" {
 
 // Try to get the allocators name set by _PyMem_SetupAllocators().
 // Return NULL if unknown.
-// Export for shared _testinternalcapi extension.
+// Export for '_testinternalcapi' shared extension.
 PyAPI_FUNC(const char*) _PyMem_GetCurrentAllocatorName(void);
 
 // strdup() using PyMem_RawMalloc()
 extern char* _PyMem_RawStrdup(const char *str);
 
 // strdup() using PyMem_Malloc().
-// Export for shared _pickle extension.
+// Export for '_pickle ' shared extension.
 PyAPI_FUNC(char*) _PyMem_Strdup(const char *str);
 
 // wcsdup() using PyMem_RawMalloc()
diff --git a/Include/internal/pycore_structseq.h b/Include/internal/pycore_structseq.h
index 6f5dfc1..5cff165 100644
--- a/Include/internal/pycore_structseq.h
+++ b/Include/internal/pycore_structseq.h
@@ -11,7 +11,8 @@ extern "C" {
 
 /* other API */
 
-PyAPI_FUNC(PyTypeObject *) _PyStructSequence_NewType(
+// Export for '_curses' shared extension
+PyAPI_FUNC(PyTypeObject*) _PyStructSequence_NewType(
     PyStructSequence_Desc *desc,
     unsigned long tp_flags);
 
diff --git a/Include/internal/pycore_typeobject.h b/Include/internal/pycore_typeobject.h
index bf32667..2ad2ada 100644
--- a/Include/internal/pycore_typeobject.h
+++ b/Include/internal/pycore_typeobject.h
@@ -114,7 +114,7 @@ extern static_builtin_state * _PyStaticType_GetState(PyInterpreterState *, PyTyp
 extern void _PyStaticType_ClearWeakRefs(PyInterpreterState *, PyTypeObject *type);
 extern void _PyStaticType_Dealloc(PyInterpreterState *, PyTypeObject *);
 
-// Export for 'math' shared extension
+// Export for 'math' shared extension via _PyType_IsReady() function
 PyAPI_FUNC(PyObject *) _PyType_GetDict(PyTypeObject *);
 extern PyObject * _PyType_GetBases(PyTypeObject *type);
 extern PyObject * _PyType_GetMRO(PyTypeObject *type);