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