diff -r 654ec6ed3225 Doc/c-api/object.rst --- a/Doc/c-api/object.rst Thu Dec 15 09:14:25 2016 +0100 +++ b/Doc/c-api/object.rst Thu Dec 15 09:34:31 2016 +0100 @@ -272,11 +272,20 @@ Object Protocol Call a callable Python object *callable*, with a variable number of C arguments. The C arguments are described using a :c:func:`Py_BuildValue` style format - string. The format can be *NULL*, indicating that no arguments are provided. + string. - Returns the result of the call on success, or *NULL* on failure. + If *format* is ``"O"`` and the argument is a tuple, the tuple is unpacked as + ``callable(*arg)``. Use the format string ``"(O)"`` to avoid unpacking if + there is a single argument. - This is the equivalent of the Python expression: ``callable(*args)``. + The format can be *NULL*, indicating that no arguments are provided. + + Returns the result of the call on success, or raise an exception and return + *NULL* on failure. + + This is the equivalent of the Python expression: ``callable(arg1, arg2, + ...)``, or ``callable(*arg)`` if *format* is ``"O"`` and the argument is + a tuple. Note that if you only pass :c:type:`PyObject \*` args, :c:func:`PyObject_CallFunctionObjArgs` is a faster alternative. diff -r 654ec6ed3225 Include/abstract.h --- a/Include/abstract.h Thu Dec 15 09:14:25 2016 +0100 +++ b/Include/abstract.h Thu Dec 15 09:34:31 2016 +0100 @@ -367,16 +367,21 @@ PyAPI_FUNC(PyObject *) _Py_CheckFunction PyAPI_FUNC(PyObject *) PyObject_CallObject(PyObject *callable, PyObject *args); -/* Call a callable Python object, callable, with a variable number of C - arguments. The C arguments are described using a mkvalue-style format - string. +/* Call a callable Python object 'callable' with a variable number of C + arguments. The C arguments are described using a Py_BuildValue() style + format string. + + If 'format' is "O" and the argument is a tuple, the tuple is unpacked as + callable(*arg). Use the format string "(O)" to avoid unpacking if there is a + single argument. The format may be NULL, indicating that no arguments are provided. - Returns the result of the call on success, or NULL on failure. + Returns the result of the call on success, or raise an exception and return + NULL on failure. - This is the equivalent of the Python expression: - callable(arg1, arg2, ...). */ + This is the equivalent of the Python expression: callable(arg1, arg2, ...), + or callable(*arg) if format is "O" and the argument is a tuple. */ PyAPI_FUNC(PyObject *) PyObject_CallFunction(PyObject *callable, const char *format, ...);