Python C API: PyEval_CallFunction?

Question

I found a function in the Python C API called PyEval_CallFunction that seems useful. This allows you to call Python, called, saying something like:

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

However, I can not find the official documentation for this feature. A google search brings up various unofficial guides that discuss this feature, but:

• The function is not documented in the official Python Docs, so I don’t even know what is supposed to be part of the public API.

• Search the Internet for incompatible usage policies. Some tutorials show Format string requires brackets around the type list, for example "(OiiO)" , while in other cases I see it without brackets. When I really try to execute a function in a real program, it seems to require brackets, otherwise a segmentation error.

I would like to use this feature because it is convenient. Does anyone know about this or know why this is not documented ? Is it part of the public API?

Answer 1

I could not find many references to it, but in the tutorial that you indicated, the following is mentioned:

The format of the string and the following arguments are Py_BuildValue (XXX, so I really should have described it now!). Call for example

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

equivalently

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

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

PyEval_CallObject itself is a macro around PyEval_CallObjectWithKeywords .

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

---

On the question "What is an open API?" here is the last post from Martin vs Lewis:

Just to emphasize and support Georg Explanation: The API is not defined through the documentation, but instead primarily through header files. All functions declared as PyAPI_FUNC and do not start with _Py are public APIs. There were a lot of undocumented APIs (before 1.4, there was no API documentation at all, just an extension module tutorial); More and more APIs are being documented these days.

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

Answer 2

The reason it is not documented is because you should use PyObject_CallFunction instead .

The PyEval_* family of functions are internal internal calls for the interpreter interpretation cycle. Relevant documented calls to PyObject_* include all statefulness checks on the secondary interpreter, argument checking, and stack protection.