bpo-38353: Cleanup includes in the internal C API (GH-16548)

Use forward declaration of types to avoid includes in the internal C
API. Add also comment to justify other includes.

Include/internal/pycore_atomic.h

@@ -8,8 +8,7 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
-#include "dynamic_annotations.h"
-
+#include "dynamic_annotations.h"   /* _Py_ANNOTATE_MEMORY_ORDER */
 #include "pyconfig.h"
 
 #if defined(HAVE_STD_ATOMIC)

Include/internal/pycore_ceval.h

@@ -8,9 +8,9 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
-#include "pycore_atomic.h"
-#include "pycore_pystate.h"
-#include "pythread.h"
+/* Forward declarations */
+typedef struct pyruntimestate _PyRuntimeState;
+struct _ceval_runtime_state;
 
 PyAPI_FUNC(void) _Py_FinishPendingCalls(_PyRuntimeState *runtime);
 PyAPI_FUNC(void) _PyEval_Initialize(struct _ceval_runtime_state *);

Include/internal/pycore_context.h

@@ -5,7 +5,7 @@
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
-#include "pycore_hamt.h"
+#include "pycore_hamt.h"   /* PyHamtObject */
 
 struct _pycontextobject {
     PyObject_HEAD

Include/internal/pycore_gil.h

@@ -8,8 +8,8 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
-#include "pycore_condvar.h"
-#include "pycore_atomic.h"
+#include "pycore_atomic.h"    /* _Py_atomic_address */
+#include "pycore_condvar.h"   /* PyCOND_T */
 
 #ifndef Py_HAVE_CONDVAR
 #  error You need either a POSIX-compatible or a Windows system!

Include/internal/pycore_initconfig.h

@@ -8,7 +8,8 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
-#include "pycore_pystate.h"   /* _PyRuntimeState */
+/* Forward declaration */
+typedef struct pyruntimestate _PyRuntimeState;
 
 /* --- PyStatus ----------------------------------------------- */
 
@@ -60,7 +61,7 @@ PyAPI_FUNC(PyObject*) _PyWideStringList_AsList(const PyWideStringList *list);
 
 /* --- _PyArgv ---------------------------------------------------- */
 
-typedef struct {
+typedef struct _PyArgv {
     Py_ssize_t argc;
     int use_bytes_argv;
     char * const *bytes_argv;

Include/internal/pycore_object.h

@@ -8,7 +8,7 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
-#include "pycore_pystate.h"   /* _PyRuntime */
+#include "pycore_pystate.h"   /* _PyRuntime.gc */
 
 PyAPI_FUNC(int) _PyType_CheckConsistency(PyTypeObject *type);
 PyAPI_FUNC(int) _PyUnicode_CheckConsistency(PyObject *op, int check_content);

Include/internal/pycore_pylifecycle.h

@@ -8,8 +8,9 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
-#include "pycore_initconfig.h"   /* _PyArgv */
-#include "pycore_pystate.h"      /* _PyRuntimeState */
+/* Forward declarations */
+typedef struct _PyArgv _PyArgv;
+typedef struct pyruntimestate _PyRuntimeState;
 
 /* True if the main interpreter thread exited due to an unhandled
  * KeyboardInterrupt exception, suggesting the user pressed ^C. */

Include/internal/pycore_pymem.h

@@ -8,8 +8,7 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
-#include "objimpl.h"
-#include "pymem.h"
+#include "pymem.h"   /* PyMemAllocatorName */
 
 
 /* GC runtime state */

Include/internal/pycore_pystate.h

@@ -8,16 +8,9 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
-#include "cpython/initconfig.h"
-#include "fileobject.h"
-#include "pystate.h"
-#include "pythread.h"
-#include "sysmodule.h"
-
-#include "pycore_gil.h"   /* _gil_runtime_state  */
-#include "pycore_pathconfig.h"
-#include "pycore_pymem.h"
-#include "pycore_warnings.h"
+#include "pycore_gil.h"       /* struct _gil_runtime_state  */
+#include "pycore_pymem.h"     /* struct _gc_runtime_state */
+#include "pycore_warnings.h"  /* struct _warnings_runtime_state */
 
 
 /* ceval state */

Include/internal/pycore_traceback.h

@@ -8,7 +8,8 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
-#include "pystate.h"   /* PyInterpreterState */
+/* Forward declaration */
+typedef struct _is PyInterpreterState;
 
 /* Write the Python traceback into the file 'fd'. For example:
 

Include/internal/pycore_tupleobject.h

@@ -8,7 +8,7 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
-#include "tupleobject.h"
+#include "tupleobject.h"   /* _PyTuple_CAST() */
 
 #define _PyTuple_ITEMS(op) (_PyTuple_CAST(op)->ob_item)
 PyAPI_FUNC(PyObject *) _PyTuple_FromArray(PyObject *const *, Py_ssize_t);

Include/internal/pycore_warnings.h

@@ -8,8 +8,6 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
-#include "object.h"
-
 struct _warnings_runtime_state {
     /* Both 'filters' and 'onceregistry' can be set in warnings.py;
        get_warnings_attr() will reset these variables accordingly. */

Modules/main.c

@@ -2,6 +2,7 @@
 
 #include "Python.h"
 #include "pycore_initconfig.h"
+#include "pycore_pathconfig.h"
 #include "pycore_pylifecycle.h"
 #include "pycore_pymem.h"
 #include "pycore_pystate.h"

Objects/unicodeobject.c

@@ -40,9 +40,10 @@ OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
 #define PY_SSIZE_T_CLEAN
 #include "Python.h"
-#include "pycore_initconfig.h"
 #include "pycore_fileutils.h"
+#include "pycore_initconfig.h"
 #include "pycore_object.h"
+#include "pycore_pathconfig.h"
 #include "pycore_pylifecycle.h"
 #include "pycore_pystate.h"
 #include "ucnhash.h"

PC/getpathp.c

@@ -80,7 +80,8 @@
 
 
 #include "Python.h"
-#include "pycore_initconfig.h"
+#include "pycore_initconfig.h"   /* PyStatus */
+#include "pycore_pathconfig.h"   /* _PyPathConfig */
 #include "pycore_pystate.h"
 #include "osdefs.h"
 #include <wchar.h>

Python/import.c

@@ -4,6 +4,7 @@
 
 #include "Python-ast.h"
 #undef Yield   /* undefine macro conflicting with <winbase.h> */
+#include "pycore_initconfig.h"
 #include "pycore_pyerrors.h"
 #include "pycore_pyhash.h"
 #include "pycore_pylifecycle.h"