[C API] Move undocumented private _PyArg C API to pycore_modsupport.h internal C API

[vstinner]

If a 3rd party C extension uses one of these functions, we should consider adding a clean, documented and tested public function to replace it.

Private functions and structures:

• _PyArg_BadArgument()
• _PyArg_CheckPositional()
• _PyArg_NoKeywords()
• _PyArg_NoPositional()
• _PyArg_ParseStack()
• _PyArg_ParseStackAndKeywords()
• _PyArg_Parser structure
• _PyArg_UnpackKeywords()
• _PyArg_UnpackKeywordsWithVararg()
• _PyArg_UnpackStack()
• _Py_ANY_VARARGS()

Linked PRs

• gh-110964: Remove private _PyArg functions #110966
• gh-110964: clinic: refactor output_templates() #110982
• gh-110964: clinic: pass clinic argument to bad_argument() #110984

[vstinner]

Basically, these functions are only used by Argument Clinic.

_PyArg_ParseTupleAndKeywordsFast(), _PyArg_ParseStackAndKeywords(), _PyArg_UnpackKeywords() and _PyArg_UnpackKeywordsWithVararg() have a _PyArg_Parser argument which is not really used without using the internal C API anyway. AC generates complex code using internal header files:

#if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
#  include "pycore_gc.h"          // PyGC_Head
#  include "pycore_runtime.h"     // _Py_ID()
#endif

(...)

    #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)

    #define NUM_KEYWORDS 1
    static struct {
        PyGC_Head _this_is_not_used;
        PyObject_VAR_HEAD
        PyObject *ob_item[NUM_KEYWORDS];
    } _kwtuple = {
        .ob_base = PyVarObject_HEAD_INIT(&PyTuple_Type, NUM_KEYWORDS)
        .ob_item = { &_Py_ID(loop), },
    };
    #undef NUM_KEYWORDS
    #define KWTUPLE (&_kwtuple.ob_base.ob_base)

    #else  // !Py_BUILD_CORE
    #  define KWTUPLE NULL
    #endif  // !Py_BUILD_CORE

    static const char * const _keywords[] = {"loop", NULL};
    static _PyArg_Parser _parser = {
        .keywords = _keywords,
        .fname = "Future",
        .kwtuple = KWTUPLE,
    };
    #undef KWTUPLE

PyGC_Head and _Py_ID() API are part of the internal C API, and _Py_ID() must not be used outside Python code base, since we don't guarantee which identifiers are available or not.

[vstinner]

_PyArg_ParseStack(args, nargs, format, ...) is like PyArg_ParseTuple(args, format, ...) but for METH_FASTCALL and METH_VECTORCALL calling convention. We should provide an API like _PyArg_ParseStack() in the public API, but I don't know if this API is good or ,not.

These helper functions are used by AC. I don't know if it would make sense to make them public or not. They should not be complicated to rewrite if they are no longer usable in the public C API:

• _PyArg_BadArgument()
• _PyArg_CheckPositional()
• _PyArg_NoKeywords()
• _PyArg_NoPositional()
• _PyArg_ParseStack()
• _PyArg_UnpackStack()

[encukou]

I don't know if this API is good or ,not.

They're vararg functions that return borrowed references, which makes them C-specific and dependent on CPython implementation details. They're quite handy in C, but IMO they'll need a good deal of design work if we're to expose them properly.

[vstinner]

IMO they'll need a good deal of design work if we're to expose them properly.

Yeah, I agree with you.