5

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?

Channel72
  • 24,139
  • 32
  • 108
  • 180

2 Answers2

5

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

Reiner Gerecke
  • 11,936
  • 1
  • 49
  • 41
  • 1
    Note that, in the context of Martin's message, being "public" refers to APIs that we won't alter or remove without going through a deprecation process first. It doesn't mean calling an undocumented API is a good idea when a documented alternative is available. In the case of `PyEval_CallFunction`, the documented (and preferred) API is `PyObject_CallFunction` which includes additional steps that `PyEval_CallFunction` assumes have already been dealt with by the calling code. – ncoghlan Feb 10 '11 at 05:29
5

The reason it isn't documented is because you should be using PyObject_CallFunction instead.

The PyEval_* function family are the raw internal calls for the interpreter evaluation loop. The corresponding documented PyObject_* calls include all the additional interpreter state integrity checks, argument validation and stack protection.

ncoghlan
  • 40,168
  • 10
  • 71
  • 80