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.

12 files changed, 21 insertions, 29 deletions

diff --git a/Include/internal/pycore_atomic.h b/Include/internal/pycore_atomic.h
index 336bc3f..1d5c562 100644
--- a/Include/internal/pycore_atomic.h
+++ b/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)
diff --git a/Include/internal/pycore_ceval.h b/Include/internal/pycore_ceval.h
index 30cd6c9..65537b1 100644
--- a/Include/internal/pycore_ceval.h
+++ b/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 *);
diff --git a/Include/internal/pycore_context.h b/Include/internal/pycore_context.h
index 5e1ba0d..f665ad5 100644
--- a/Include/internal/pycore_context.h
+++ b/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
diff --git a/Include/internal/pycore_gil.h b/Include/internal/pycore_gil.h
index 7de3163..8ebad37 100644
--- a/Include/internal/pycore_gil.h
+++ b/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!
diff --git a/Include/internal/pycore_initconfig.h b/Include/internal/pycore_initconfig.h
index 40831c4..4a1a111 100644
--- a/Include/internal/pycore_initconfig.h
+++ b/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;
diff --git a/Include/internal/pycore_object.h b/Include/internal/pycore_object.h
index 81548f8..500078d 100644
--- a/Include/internal/pycore_object.h
+++ b/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);
diff --git a/Include/internal/pycore_pylifecycle.h b/Include/internal/pycore_pylifecycle.h
index b0a98f5..d6f9ecc 100644
--- a/Include/internal/pycore_pylifecycle.h
+++ b/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. */
diff --git a/Include/internal/pycore_pymem.h b/Include/internal/pycore_pymem.h
index 22677d3..cba4b23 100644
--- a/Include/internal/pycore_pymem.h
+++ b/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 */
diff --git a/Include/internal/pycore_pystate.h b/Include/internal/pycore_pystate.h
index 8e5a022..91003db 100644
--- a/Include/internal/pycore_pystate.h
+++ b/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 */
diff --git a/Include/internal/pycore_traceback.h b/Include/internal/pycore_traceback.h
index bf4d7fe..8e58184 100644
--- a/Include/internal/pycore_traceback.h
+++ b/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:
 
diff --git a/Include/internal/pycore_tupleobject.h b/Include/internal/pycore_tupleobject.h
index 9fcfc5c..f95f16c 100644
--- a/Include/internal/pycore_tupleobject.h
+++ b/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);
diff --git a/Include/internal/pycore_warnings.h b/Include/internal/pycore_warnings.h
index 73e5350..9a72526 100644
--- a/Include/internal/pycore_warnings.h
+++ b/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. */