There are currently undocumented PyEval_Call* equivalents to a number of the PyObject_Call* functions.

Since there are resources out there on the web that direct people to use the currently undocumented PyEval functions, it would be good to document those properly, and recommend people typically use the PyObject_Call* variants instead (as the latter include all the stack and interpreter state integrity protection code, while the PyEval variants assume that has all already been handled).

Removed the easy tag, since this may involve some python-dev discussion as to where to put them in C API docs (they don't really fit in any of the current sections).

Perhaps an "advanced APIs" section, for things that most C extensions or embedding applications really shouldn't be using.

IMO, it would probably have been better if these APIs had been private from the start. Is there any use case for calling them from 3rd-party code?

There may be some legitimate use cases when embedding Python and you *know* that the checks performed by the PyObject_* versions aren't needed.

It may also be historical - the PyEval versions may predate the PyObject ones.

@Nick I assume that this still needs doing.  msg128249 says you've removed the easy tag but it still shows in the keywords list.

The PyEval_Call*() APIs indeed predate the PyObject_Call*() ones. The PyObject_Call*() APIs came into existence when the abstract layer was added in Python 1.3.

The PyObject_Call*() APIs lacked a way to call an object with keyword arguments for a long time. I guess that's what most people continued to use the PyEval_Call*() ones. The latter also provide better protection against wrong parameters. The interpreter itself used them interchangeably.

I think PyObject_Call* APIs should be preferred.

As discussed in #29548, we can't remove or deprecate PyEval_Call*.
But I don't think it's worth enough to document them.
How about keep them undocumented?

While they are undocumented there is no a place for adding the recommendation of using corresponding PyObject_Call* functions and describing the way of porting from PyEval_Call* functions to PyObject_Call* functions.

In PR 75, I added a comment in Include/ceval.h, right before PyEval_Call* APIs.

https://github.com/python/cpython/pull/75/files#diff-da3df9def5eca3595399b0a5a7698eac

These functions are now officially deprecated, see PR 14804. So I think that this issue can be closed.