Python C API: PyEval_CallFunction?

Question

I've discovered a function in the Python C API named PyEval_CallFunction which seems to be useful. It allows you to invoke a Python callable by saying something like:

PyEval_CallFunction(obj, "OOO", a, b, c);

However, I can't find any official documentation on this function. A google search brings up various unofficial tutorials which discuss this function, but:

1. The function isn't documented in the official Python docs, so I don't know if it's even something that is supposed to be part of the public API.

2. Searching the web turns up inconsistent usage policies. Some tutorials indicate the format string needs parenthesis around the type list, like "(OiiO)", whereas other times I see it used without the parenthesis. When I actually try the function in a real program, it seems to require the parenthesis, otherwise it segfaults.

I'd like to use this function because it's convenient. Does anyone know anything about this, or know why it isn't documented? Is it part of the public API?

Answer 1

I couldn't find many references to it either, but the tutorial you linked to mentions this:

The string format and the following arguments are as for Py_BuildValue (XXX so i really should have described that by now!). A call such as

PyEval_CallFunction(obj, "iii", a, b, c);

is equivalent to

PyEval_CallObject(obj, Py_BuildValue("iii", a, b, c));

I suppose PyEval_CallFunction is not public API, as its value seems rather limited. There is not much of a difference between these two. But then again, I'm not really involved in python extensions, so this is just my view on this.

PyEval_CallObject itself is just a macro around PyEval_CallObjectWithKeywords.

#define PyEval_CallObject(func,arg) \
        PyEval_CallObjectWithKeywords(func, arg, (PyObject *)NULL)

---

On the matter of "What is public API?" here is a recent message from Martin v. Löwis:

Just to stress and support Georg's explanation: the API is not defined through the documentation, but instead primarily through the header files. All functions declared as PyAPI_FUNC and not starting with _Py are public API. There used to be a lot of undocumented API (up to 1.4, there was no API documentation at all, only the extension module tutorial); these days, more and more API gets documented.

http://mail.python.org/pipermail/python-dev/2011-February/107973.html