gh-107211: No longer export internal functions (5) (#108423)

No longer export _PyCompile_AstOptimize() internal C API function.

Change comment style to "// comment" and add comment explaining why
other functions have to be exported.

Author: vstinner

Include/internal/pycore_bytesobject.h

@@ -28,34 +28,37 @@ PyAPI_FUNC(PyObject*) _PyBytes_DecodeEscape(const char *, Py_ssize_t,
 extern PyObject* _PyBytes_Join(PyObject *sep, PyObject *x);
 
 
-/* Substring Search.
-
-   Returns the index of the first occurrence of
-   a substring ("needle") in a larger text ("haystack").
-   If the needle is not found, return -1.
-   If the needle is found, add offset to the index.
-*/
-
+// Substring Search.
+//
+// Returns the index of the first occurrence of
+// a substring ("needle") in a larger text ("haystack").
+// If the needle is not found, return -1.
+// If the needle is found, add offset to the index.
+//
+// Export for 'mmap' shared extension.
 PyAPI_FUNC(Py_ssize_t)
 _PyBytes_Find(const char *haystack, Py_ssize_t len_haystack,
               const char *needle, Py_ssize_t len_needle,
               Py_ssize_t offset);
 
-/* Same as above, but search right-to-left */
+// Same as above, but search right-to-left.
+// Export for 'mmap' shared extension.
 PyAPI_FUNC(Py_ssize_t)
 _PyBytes_ReverseFind(const char *haystack, Py_ssize_t len_haystack,
                      const char *needle, Py_ssize_t len_needle,
                      Py_ssize_t offset);
 
 
-/** Helper function to implement the repeat and inplace repeat methods on a buffer
- *
- * len_dest is assumed to be an integer multiple of len_src.
- * If src equals dest, then assume the operation is inplace.
- *
- * This method repeately doubles the number of bytes copied to reduce
- * the number of invocations of memcpy.
- */
+// Helper function to implement the repeat and inplace repeat methods on a
+// buffer.
+//
+// len_dest is assumed to be an integer multiple of len_src.
+// If src equals dest, then assume the operation is inplace.
+//
+// This method repeately doubles the number of bytes copied to reduce
+// the number of invocations of memcpy.
+//
+// Export for 'array' shared extension.
 PyAPI_FUNC(void)
 _PyBytes_Repeat(char* dest, Py_ssize_t len_dest,
     const char* src, Py_ssize_t len_src);
@@ -91,7 +94,9 @@ typedef struct {
 /* Initialize a bytes writer
 
    By default, the overallocation is disabled. Set the overallocate attribute
-   to control the allocation of the buffer. */
+   to control the allocation of the buffer.
+
+   Export _PyBytesWriter API for '_pickle' shared extension. */
 PyAPI_FUNC(void) _PyBytesWriter_Init(_PyBytesWriter *writer);
 
 /* Get the buffer content and reset the writer.

Include/internal/pycore_call.h

@@ -22,8 +22,8 @@ extern "C" {
 #define _PY_FASTCALL_SMALL_STACK 5
 
 
-// Export for 'math' shared extension, function used
-// via inlined _PyObject_VectorcallTstate() function.
+// Export for 'math' shared extension, used via _PyObject_VectorcallTstate()
+// static inline function.
 PyAPI_FUNC(PyObject*) _Py_CheckFunctionResult(
     PyThreadState *tstate,
     PyObject *callable,
@@ -120,8 +120,8 @@ _PyObject_CallMethodIdOneArg(PyObject *self, _Py_Identifier *name, PyObject *arg
 // Call callable using tp_call. Arguments are like PyObject_Vectorcall(),
 // except that nargs is plainly the number of arguments without flags.
 //
-// Export for 'math' shared extension, function used
-// via inlined _PyObject_VectorcallTstate() function.
+// Export for 'math' shared extension, used via _PyObject_VectorcallTstate()
+// static inline function.
 PyAPI_FUNC(PyObject*) _PyObject_MakeTpCall(
     PyThreadState *tstate,
     PyObject *callable,

Include/internal/pycore_ceval.h

@@ -23,12 +23,14 @@ extern void _Py_FinishPendingCalls(PyThreadState *tstate);
 extern void _PyEval_InitState(PyInterpreterState *, PyThread_type_lock);
 extern void _PyEval_FiniState(struct _ceval_state *ceval);
 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);
+
 extern void _PyEval_SignalAsyncExc(PyInterpreterState *interp);
 #ifdef HAVE_FORK
 extern PyStatus _PyEval_ReInitThreads(PyThreadState *tstate);
@@ -122,7 +124,8 @@ static inline int _Py_MakeRecCheck(PyThreadState *tstate) {
 }
 #endif
 
-// Export for _Py_EnterRecursiveCall()
+// Export for '_json' shared extension, used via _Py_EnterRecursiveCall()
+// static inline function.
 PyAPI_FUNC(int) _Py_CheckRecursiveCall(
     PyThreadState *tstate,
     const char *where);

Include/internal/pycore_compile.h

@@ -20,7 +20,7 @@ PyAPI_FUNC(PyCodeObject*) _PyAST_Compile(
     struct _arena *arena);
 
 /* AST optimizations */
-PyAPI_FUNC(int) _PyCompile_AstOptimize(
+extern int _PyCompile_AstOptimize(
     struct _mod *mod,
     PyObject *filename,
     PyCompilerFlags *flags,
@@ -107,18 +107,21 @@ int _PyCompile_ConstCacheMergeOne(PyObject *const_cache, PyObject **obj);
 // Export for '_testinternalcapi' shared extension
 PyAPI_FUNC(PyObject*) _PyCompile_CleanDoc(PyObject *doc);
 
+// Export for '_testinternalcapi' shared extension
 PyAPI_FUNC(PyObject*) _PyCompile_CodeGen(
         PyObject *ast,
         PyObject *filename,
         PyCompilerFlags *flags,
         int optimize,
         int compile_mode);
 
+// Export for '_testinternalcapi' shared extension
 PyAPI_FUNC(PyObject*) _PyCompile_OptimizeCfg(
         PyObject *instructions,
         PyObject *consts,
         int nlocals);
 
+// Export for '_testinternalcapi' shared extension
 PyAPI_FUNC(PyCodeObject*)
 _PyCompile_Assemble(_PyCompile_CodeUnitMetadata *umd, PyObject *filename,
                     PyObject *instructions);

Include/internal/pycore_complexobject.h

@@ -10,8 +10,8 @@ extern "C" {
 
 #include "pycore_unicodeobject.h" // _PyUnicodeWriter
 
-/* Operations on complex numbers from complexmodule.c */
-
+// Operations on complex numbers.
+// Export functions for 'cmath' shared extension.
 PyAPI_FUNC(Py_complex) _Py_c_sum(Py_complex, Py_complex);
 PyAPI_FUNC(Py_complex) _Py_c_diff(Py_complex, Py_complex);
 PyAPI_FUNC(Py_complex) _Py_c_neg(Py_complex);

Include/internal/pycore_fileutils.h

@@ -35,8 +35,10 @@ typedef enum {
     _Py_ERROR_OTHER
 } _Py_error_handler;
 
+// Export for '_testinternalcapi' shared extension
 PyAPI_FUNC(_Py_error_handler) _Py_GetErrorHandler(const char *errors);
 
+// Export for '_testinternalcapi' shared extension
 PyAPI_FUNC(int) _Py_DecodeLocaleEx(
     const char *arg,
     wchar_t **wstr,
@@ -45,6 +47,7 @@ PyAPI_FUNC(int) _Py_DecodeLocaleEx(
     int current_locale,
     _Py_error_handler errors);
 
+// Export for '_testinternalcapi' shared extension
 PyAPI_FUNC(int) _Py_EncodeLocaleEx(
     const wchar_t *text,
     char **str,
@@ -98,23 +101,27 @@ struct _Py_stat_struct {
 #  define _Py_stat_struct stat
 #endif
 
+// Export for 'mmap' shared extension
 PyAPI_FUNC(int) _Py_fstat(
     int fd,
     struct _Py_stat_struct *status);
 
+// Export for 'mmap' shared extension
 PyAPI_FUNC(int) _Py_fstat_noraise(
     int fd,
     struct _Py_stat_struct *status);
 
+// Export for '_tkinter' shared extension
 PyAPI_FUNC(int) _Py_stat(
     PyObject *path,
     struct stat *status);
 
-// Export for 'select' shared extension (Solaris newDevPollObject() uses it)
+// Export for 'select' shared extension (Solaris newDevPollObject())
 PyAPI_FUNC(int) _Py_open(
     const char *pathname,
     int flags);
 
+// Export for '_posixsubprocess' shared extension
 PyAPI_FUNC(int) _Py_open_noraise(
     const char *pathname,
     int flags);
@@ -128,12 +135,13 @@ extern Py_ssize_t _Py_read(
     void *buf,
     size_t count);
 
-// Export for 'select' shared extension (Solaris devpoll_flush() uses it)
+// Export for 'select' shared extension (Solaris devpoll_flush())
 PyAPI_FUNC(Py_ssize_t) _Py_write(
     int fd,
     const void *buf,
     size_t count);
 
+// Export for '_posixsubprocess' shared extension
 PyAPI_FUNC(Py_ssize_t) _Py_write_noraise(
     int fd,
     const void *buf,
@@ -165,12 +173,15 @@ extern wchar_t* _Py_wgetcwd(
 
 extern int _Py_get_inheritable(int fd);
 
+// Export for '_socket' shared extension
 PyAPI_FUNC(int) _Py_set_inheritable(int fd, int inheritable,
                                     int *atomic_flag_works);
 
+// Export for '_posixsubprocess' shared extension
 PyAPI_FUNC(int) _Py_set_inheritable_async_safe(int fd, int inheritable,
                                                int *atomic_flag_works);
 
+// Export for '_socket' shared extension
 PyAPI_FUNC(int) _Py_dup(int fd);
 
 extern int _Py_get_blocking(int fd);
@@ -180,6 +191,7 @@ extern int _Py_set_blocking(int fd, int blocking);
 #ifdef MS_WINDOWS
 extern void* _Py_get_osfhandle_noraise(int fd);
 
+// Export for '_testconsole' shared extension
 PyAPI_FUNC(void*) _Py_get_osfhandle(int fd);
 
 extern int _Py_open_osfhandle_noraise(void *handle, int flags);
@@ -234,6 +246,7 @@ extern int _Py_GetLocaleconvNumeric(
     PyObject **decimal_point,
     PyObject **thousands_sep);
 
+// Export for '_posixsubprocess' (on macOS)
 PyAPI_FUNC(void) _Py_closerange(int first, int last);
 
 extern wchar_t* _Py_GetLocaleEncoding(void);
@@ -262,7 +275,10 @@ extern int _Py_add_relfile(wchar_t *dirname,
                            const wchar_t *relfile,
                            size_t bufsize);
 extern size_t _Py_find_basename(const wchar_t *filename);
+
+// Export for '_testinternalcapi' shared extension
 PyAPI_FUNC(wchar_t*) _Py_normpath(wchar_t *path, Py_ssize_t size);
+
 extern wchar_t *_Py_normpath_and_size(wchar_t *path, Py_ssize_t size, Py_ssize_t *length);
 
 // The Windows Games API family does not provide these functions

Include/internal/pycore_genobject.h

@@ -13,6 +13,7 @@ extern void _PyGen_Finalize(PyObject *self);
 
 // Export for '_asyncio' shared extension
 PyAPI_FUNC(int) _PyGen_SetStopIterationValue(PyObject *);
+
 // Export for '_asyncio' shared extension
 PyAPI_FUNC(int) _PyGen_FetchStopIterationValue(PyObject **);
 

Include/internal/pycore_hashtable.h

@@ -70,6 +70,11 @@ struct _Py_hashtable_t {
     _Py_hashtable_allocator_t alloc;
 };
 
+// Export _Py_hashtable functions for '_testinternalcapi' shared extension
+PyAPI_FUNC(_Py_hashtable_t *) _Py_hashtable_new(
+    _Py_hashtable_hash_func hash_func,
+    _Py_hashtable_compare_func compare_func);
+
 /* Hash a pointer (void*) */
 PyAPI_FUNC(Py_uhash_t) _Py_hashtable_hash_ptr(const void *key);
 
@@ -78,10 +83,6 @@ PyAPI_FUNC(int) _Py_hashtable_compare_direct(
     const void *key1,
     const void *key2);
 
-PyAPI_FUNC(_Py_hashtable_t *) _Py_hashtable_new(
-    _Py_hashtable_hash_func hash_func,
-    _Py_hashtable_compare_func compare_func);
-
 PyAPI_FUNC(_Py_hashtable_t *) _Py_hashtable_new_full(
     _Py_hashtable_hash_func hash_func,
     _Py_hashtable_compare_func compare_func,

Include/internal/pycore_import.h

@@ -14,7 +14,9 @@ extern "C" {
 
 extern int _PyImport_IsInitialized(PyInterpreterState *);
 
+// Export for 'pyexpat' shared extension
 PyAPI_FUNC(int) _PyImport_SetModule(PyObject *name, PyObject *module);
+
 extern int _PyImport_SetModuleString(const char *name, PyObject* module);
 
 extern void _PyImport_AcquireLock(PyInterpreterState *interp);
@@ -28,7 +30,10 @@ extern int _PyImport_FixupBuiltin(
 extern int _PyImport_FixupExtensionObject(PyObject*, PyObject *,
                                           PyObject *, PyObject *);
 
+// Export for many shared extensions, like '_json'
 PyAPI_FUNC(PyObject*) _PyImport_GetModuleAttr(PyObject *, PyObject *);
+
+// Export for many shared extensions, like '_datetime'
 PyAPI_FUNC(PyObject*) _PyImport_GetModuleAttrString(const char *, const char *);
 
 
@@ -187,11 +192,9 @@ struct _module_alias {
     const char *orig;                 /* ASCII encoded string */
 };
 
-// Export for test_ctypes
+// Export these 3 symbols for test_ctypes
 PyAPI_DATA(const struct _frozen*) _PyImport_FrozenBootstrap;
-// Export for test_ctypes
 PyAPI_DATA(const struct _frozen*) _PyImport_FrozenStdlib;
-// Export for test_ctypes
 PyAPI_DATA(const struct _frozen*) _PyImport_FrozenTest;
 
 extern const struct _module_alias * _PyImport_FrozenAliases;

Include/internal/pycore_initconfig.h

@@ -124,6 +124,7 @@ extern PyStatus _PyPreCmdline_Read(_PyPreCmdline *cmdline,
 
 // Export for '_testembed' program
 PyAPI_FUNC(void) _PyPreConfig_InitCompatConfig(PyPreConfig *preconfig);
+
 extern void _PyPreConfig_InitFromConfig(
     PyPreConfig *preconfig,
     const PyConfig *config);
@@ -149,6 +150,7 @@ typedef enum {
 
 // Export for '_testembed' program
 PyAPI_FUNC(void) _PyConfig_InitCompatConfig(PyConfig *config);
+
 extern PyStatus _PyConfig_Copy(
     PyConfig *config,
     const PyConfig *config2);
@@ -163,16 +165,16 @@ extern PyStatus _PyConfig_SetPyArgv(
     PyConfig *config,
     const _PyArgv *args);
 
-PyAPI_FUNC(PyObject*) _PyConfig_AsDict(const PyConfig *config);
-PyAPI_FUNC(int) _PyConfig_FromDict(PyConfig *config, PyObject *dict);
 
 extern void _Py_DumpPathConfig(PyThreadState *tstate);
 
-PyAPI_FUNC(PyObject*) _Py_Get_Getpath_CodeObject(void);
-
 
 /* --- Function used for testing ---------------------------------- */
 
+// Export these functions for '_testinternalcapi' shared extension
+PyAPI_FUNC(PyObject*) _PyConfig_AsDict(const PyConfig *config);
+PyAPI_FUNC(int) _PyConfig_FromDict(PyConfig *config, PyObject *dict);
+PyAPI_FUNC(PyObject*) _Py_Get_Getpath_CodeObject(void);
 PyAPI_FUNC(PyObject*) _Py_GetConfigsAsDict(void);
 
 #ifdef __cplusplus