Last years, more and more interdependencies have been added. Examples:

• pybuffer.h uses PyObject before it's defined by object.h (included later).
• object.h must forward declare PyModuleDef since it's used before it's defined by moduleobject.h (included after object.h).
• object.h uses struct PyMethodDef which is defined later by methodobject.h (included after object.h). object.h has to use struct PyMethodDef instead of PyMethodDef to solve the interdpendency issue.

This PR cleans up header files by moving forward declarations at the top of Python.h.

With this PR, it becomes possible to use type names like PyObject or PyModuleDef rather than using structure names like struct _object or struct PyModuleDef. I didn't make this change in this PR to keep it easier to review. I created GH-31528 draft PR (see the second commit of this PR) to use type names.

cc @benjaminp @erlend-aasland @corona10

If you don't want to go this way, I wrote the bare minimum fix for the clang compiler warning: GH-31539.

But as I wrote in my previous comment, IMO it's now time to cleanup these forward declarations to have a sane way to fix this issuse in a single place. There are too many scattered forward declarations in the Python C API.

If you don't want to go this way, I wrote the bare minimum fix for the clang compiler warning: #31539.

Defining types in multiple header files is tricky. At my first attempt, I defined PyObject inside #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030b0000 and it didn't work when building xxlimited35 which targets the limited C API version 3.5...

This looks nice and clean. AFAICS, there is no downside; approved post-merge :)