[Python-ideas] PEP: Hide implementation details in the C API

[Victor Stinner]

> Step 3: first pass of implementation detail removal
> ---------------------------------------------------
>
> Modify the ``python`` API:
>
> * Add a new ``API`` subdirectory in the Python source code which will
>   "implement" the Python C API
> * Replace macros with functions. The implementation of new functions
>   will be written in the ``API/`` directory. For example, Py_INCREF()
>   becomes the function ``void Py_INCREF(PyObject *op)`` and its
>   implementation will be written in the ``API`` directory.
> * Slowly remove more and more implementation details from this API.

When I discussed this issue with Serhiy Storchaka, he didn't see the
purpose of the API directory. I started to implement the PEP in my
"capi2" fork of CPython:
https://github.com/haypo/cpython/tree/capi2

See https://github.com/haypo/cpython/tree/capi2/API for examples of C
code to "implement the C API".

Just one example, the macro

#define PyUnicode_IS_READY(op) (((PyASCIIObject*)op)->state.ready)

is replaced with a function:

int
PyUnicode_IS_READY(const PyObject *op)
{
   return ((PyASCIIObject*)op)->state.ready;
}

So the header file doesn't have to expose the PyASCIIObject,
PyCompactUnicodeObject and PyUnicodeObject structures. I was already
able to remove the PyUnicodeObject structure without breaking the C
extensions of the stdib.

I don't want to pollute Objects/unicodeobject.c with such "wrapper"
functions. In the future, the implementation of API/ can evolve a lot.

Victor