Extending and Embedding Python, Release 3.9.5 Chapter 2. Creating extensions without third party tools 12 (continues on next page) (continued from previous page) } return result; } int arg; PyObject *arglist; PyObject *result; ... arg =123 ; ... /* Time to call the callback */ arglist =Py_BuildValue( "(i) ", arg); result=PyObject_CallObject(my_callback, arglist); Py_DECREF(arglist); if (result==NULL ) return NULL ; /* Pass error back */ ...use result... Py_DECREF(result); PyObject *arglist; ... arglist =Py_BuildValue( "(l) ", eventcode); result=PyObject_CallObject(my_callback, arglist); Depending on the desired interface to the Python callback function, you may also have to provide an argument list to$_{PyObject_CallObject()}$ . In some cases the argument list is also provided by the Python program, through the same interface that specified the callback function. It can then be saved and used in the same manner as the function object. In other cases, you may have to construct a new tuple to pass as the argument list. The simplest way to do this is to call$_{Py_BuildValue()}$ . For example, if you want to pass an integral event code, you might use the following code: Before you do this, however, it is important to check that the return value isn’t$_{NULL}$ . If it is, the Python function terminated by raising an exception. If the C code that called$_{PyObject_CallObject()}$ is called from Python, it should now return an error indication to its Python caller, so the interpreter can print a stack trace, or the calling Python code can handle the exception. If this is not possible or desirable, the exception should be cleared by calling PyErr_Clear() . For example: The return value of$_{PyObject_CallObject()}$ is “new”: either it is a brand new object, or it is an existing object whose reference count has been incremented. So, unless you want to save it in a global variable, you should somehow Py_DECREF() the result, even (especially!) if you are not interested in its value. PyObject_CallObject() returns a Python object pointer: this is the return value of the Python func- tion. PyObject_CallObject() is “reference-count-neutral” with respect to its arguments. In the exam- ple a new tuple was created to serve as the argument list, which is Py_DECREF() -ed immediately after the PyObject_CallObject() call. This function must be registered with the interpreter using the METH_VARARGS flag; this is described in section The Module’s Method Table and Initialization Function . The PyArg_ParseTuple() function and its arguments are documented in section Extracting Parameters in Extension Functions . The macros Py_XINCREF() and Py_XDECREF() increment/decrement the reference count of an object and are safe in the presence of NULL pointers (but note that temp will not be NULL in this context). More info on them in section Reference Counts . Later, when it is time to call the function, you call the C function$_{PyObject_CallObject()}$ . This function has two arguments, both pointers to arbitrary Python objects: the Python function, and the argument list. The argument list must always be a tuple object, whose length is the number of arguments. To call the Python function with no ar- guments, pass in NULL , or an empty tuple; to call it with one argument, pass a singleton tuple. Py_BuildValue() returns a tuple when its format string consists of zero or more format codes between parentheses. For example: