Uniformize argument names of "call" functions

Issue #28838: Rename parameters of the "calls" functions of the Python C API.

* Rename 'callable_object' and 'func' to 'callable': any Python callable object
  is accepted, not only Python functions
* Rename 'method' and 'nameid' to 'name' (method name)
* Rename 'o' to 'obj'
* Move, fix and update documentation of PyObject_CallXXX() functions
  in abstract.h
* Update also the documentaton of the C API (update parameter names)

2 files changed, 83 insertions, 75 deletions

diff --git a/Objects/abstract.c b/Objects/abstract.c
index a6a58db..4cd9636 100644
--- a/Objects/abstract.c
+++ b/Objects/abstract.c
@@ -2173,24 +2173,24 @@ PyMapping_Values(PyObject *o)
 /* XXX PyCallable_Check() is in object.c */
 
 PyObject *
-PyObject_CallObject(PyObject *o, PyObject *a)
+PyObject_CallObject(PyObject *callable, PyObject *args)
 {
-    return PyEval_CallObjectWithKeywords(o, a, NULL);
+    return PyEval_CallObjectWithKeywords(callable, args, NULL);
 }
 
 PyObject*
-_Py_CheckFunctionResult(PyObject *func, PyObject *result, const char *where)
+_Py_CheckFunctionResult(PyObject *callable, PyObject *result, const char *where)
 {
     int err_occurred = (PyErr_Occurred() != NULL);
 
-    assert((func != NULL) ^ (where != NULL));
+    assert((callable != NULL) ^ (where != NULL));
 
     if (result == NULL) {
         if (!err_occurred) {
-            if (func)
+            if (callable)
                 PyErr_Format(PyExc_SystemError,
                              "%R returned NULL without setting an error",
-                             func);
+                             callable);
             else
                 PyErr_Format(PyExc_SystemError,
                              "%s returned NULL without setting an error",
@@ -2206,10 +2206,10 @@ _Py_CheckFunctionResult(PyObject *func, PyObject *result, const char *where)
         if (err_occurred) {
             Py_DECREF(result);
 
-            if (func) {
+            if (callable) {
                 _PyErr_FormatFromCause(PyExc_SystemError,
                         "%R returned a result with an error set",
-                        func);
+                        callable);
             }
             else {
                 _PyErr_FormatFromCause(PyExc_SystemError,
@@ -2227,7 +2227,7 @@ _Py_CheckFunctionResult(PyObject *func, PyObject *result, const char *where)
 }
 
 PyObject *
-PyObject_Call(PyObject *func, PyObject *args, PyObject *kwargs)
+PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)
 {
     ternaryfunc call;
     PyObject *result;
@@ -2239,21 +2239,21 @@ PyObject_Call(PyObject *func, PyObject *args, PyObject *kwargs)
     assert(PyTuple_Check(args));
     assert(kwargs == NULL || PyDict_Check(kwargs));
 
-    call = func->ob_type->tp_call;
+    call = callable->ob_type->tp_call;
     if (call == NULL) {
         PyErr_Format(PyExc_TypeError, "'%.200s' object is not callable",
-                     func->ob_type->tp_name);
+                     callable->ob_type->tp_name);
         return NULL;
     }
 
     if (Py_EnterRecursiveCall(" while calling a Python object"))
         return NULL;
 
-    result = (*call)(func, args, kwargs);
+    result = (*call)(callable, args, kwargs);
 
     Py_LeaveRecursiveCall();
 
-    return _Py_CheckFunctionResult(func, result, NULL);
+    return _Py_CheckFunctionResult(callable, result, NULL);
 }
 
 PyObject*
@@ -2277,7 +2277,7 @@ _PyStack_AsTuple(PyObject **stack, Py_ssize_t nargs)
 }
 
 PyObject *
-_PyObject_FastCallDict(PyObject *func, PyObject **args, Py_ssize_t nargs,
+_PyObject_FastCallDict(PyObject *callable, PyObject **args, Py_ssize_t nargs,
                        PyObject *kwargs)
 {
     ternaryfunc call;
@@ -2288,7 +2288,7 @@ _PyObject_FastCallDict(PyObject *func, PyObject **args, Py_ssize_t nargs,
        caller loses its exception */
     assert(!PyErr_Occurred());
 
-    assert(func != NULL);
+    assert(callable != NULL);
     assert(nargs >= 0);
     assert(nargs == 0 || args != NULL);
     assert(kwargs == NULL || PyDict_Check(kwargs));
@@ -2297,20 +2297,20 @@ _PyObject_FastCallDict(PyObject *func, PyObject **args, Py_ssize_t nargs,
         return NULL;
     }
 
-    if (PyFunction_Check(func)) {
-        result = _PyFunction_FastCallDict(func, args, nargs, kwargs);
+    if (PyFunction_Check(callable)) {
+        result = _PyFunction_FastCallDict(callable, args, nargs, kwargs);
     }
-    else if (PyCFunction_Check(func)) {
-        result = _PyCFunction_FastCallDict(func, args, nargs, kwargs);
+    else if (PyCFunction_Check(callable)) {
+        result = _PyCFunction_FastCallDict(callable, args, nargs, kwargs);
     }
     else {
         PyObject *tuple;
 
         /* Slow-path: build a temporary tuple */
-        call = func->ob_type->tp_call;
+        call = callable->ob_type->tp_call;
         if (call == NULL) {
             PyErr_Format(PyExc_TypeError, "'%.200s' object is not callable",
-                         func->ob_type->tp_name);
+                         callable->ob_type->tp_name);
             goto exit;
         }
 
@@ -2319,10 +2319,10 @@ _PyObject_FastCallDict(PyObject *func, PyObject **args, Py_ssize_t nargs,
             goto exit;
         }
 
-        result = (*call)(func, tuple, kwargs);
+        result = (*call)(callable, tuple, kwargs);
         Py_DECREF(tuple);
 
-        result = _Py_CheckFunctionResult(func, result, NULL);
+        result = _Py_CheckFunctionResult(callable, result, NULL);
     }
 
 exit:
@@ -2331,9 +2331,10 @@ exit:
     return result;
 }
 
-/* Positional arguments are obj followed args. */
+/* Positional arguments are obj followed args:
+   call callable(obj, *args, **kwargs) */
 PyObject *
-_PyObject_Call_Prepend(PyObject *func,
+_PyObject_Call_Prepend(PyObject *callable,
                        PyObject *obj, PyObject *args, PyObject *kwargs)
 {
     PyObject *small_stack[8];
@@ -2361,7 +2362,7 @@ _PyObject_Call_Prepend(PyObject *func,
               &PyTuple_GET_ITEM(args, 0),
               argcount * sizeof(PyObject *));
 
-    result = _PyObject_FastCallDict(func,
+    result = _PyObject_FastCallDict(callable,
                                     stack, argcount + 1,
                                     kwargs);
     if (stack != small_stack) {
@@ -2452,7 +2453,7 @@ _PyStack_UnpackDict(PyObject **args, Py_ssize_t nargs, PyObject *kwargs,
 }
 
 PyObject *
-_PyObject_FastCallKeywords(PyObject *func, PyObject **stack, Py_ssize_t nargs,
+_PyObject_FastCallKeywords(PyObject *callable, PyObject **stack, Py_ssize_t nargs,
                            PyObject *kwnames)
 {
     PyObject *kwdict, *result;
@@ -2465,12 +2466,12 @@ _PyObject_FastCallKeywords(PyObject *func, PyObject **stack, Py_ssize_t nargs,
        be unique: these are implemented in Python/ceval.c and
        _PyArg_ParseStack(). */
 
-    if (PyFunction_Check(func)) {
-        return _PyFunction_FastCallKeywords(func, stack, nargs, kwnames);
+    if (PyFunction_Check(callable)) {
+        return _PyFunction_FastCallKeywords(callable, stack, nargs, kwnames);
     }
 
-    if (PyCFunction_Check(func)) {
-        return _PyCFunction_FastCallKeywords(func, stack, nargs, kwnames);
+    if (PyCFunction_Check(callable)) {
+        return _PyCFunction_FastCallKeywords(callable, stack, nargs, kwnames);
     }
 
     if (nkwargs > 0) {
@@ -2483,7 +2484,7 @@ _PyObject_FastCallKeywords(PyObject *func, PyObject **stack, Py_ssize_t nargs,
         kwdict = NULL;
     }
 
-    result = _PyObject_FastCallDict(func, stack, nargs, kwdict);
+    result = _PyObject_FastCallDict(callable, stack, nargs, kwdict);
     Py_XDECREF(kwdict);
     return result;
 }
@@ -2558,19 +2559,19 @@ _PyObject_CallFunction_SizeT(PyObject *callable, const char *format, ...)
 }
 
 static PyObject*
-callmethod(PyObject* func, const char *format, va_list va, int is_size_t)
+callmethod(PyObject* callable, const char *format, va_list va, int is_size_t)
 {
     PyObject *args, *result;
 
-    assert(func != NULL);
+    assert(callable != NULL);
 
-    if (!PyCallable_Check(func)) {
-        type_error("attribute of type '%.200s' is not callable", func);
+    if (!PyCallable_Check(callable)) {
+        type_error("attribute of type '%.200s' is not callable", callable);
         return NULL;
     }
 
     if (!format || !*format) {
-        return _PyObject_CallNoArg(func);
+        return _PyObject_CallNoArg(callable);
     }
 
     if (is_size_t) {
@@ -2583,98 +2584,104 @@ callmethod(PyObject* func, const char *format, va_list va, int is_size_t)
         return NULL;
     }
 
-    result = call_function_tail(func, args);
+    result = call_function_tail(callable, args);
     Py_DECREF(args);
     return result;
 }
 
 PyObject *
-PyObject_CallMethod(PyObject *o, const char *name, const char *format, ...)
+PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)
 {
     va_list va;
-    PyObject *func = NULL;
+    PyObject *callable = NULL;
     PyObject *retval = NULL;
 
-    if (o == NULL || name == NULL) {
+    if (obj == NULL || name == NULL) {
         return null_error();
     }
 
-    func = PyObject_GetAttrString(o, name);
-    if (func == NULL)
+    callable = PyObject_GetAttrString(obj, name);
+    if (callable == NULL)
         return NULL;
 
     va_start(va, format);
-    retval = callmethod(func, format, va, 0);
+    retval = callmethod(callable, format, va, 0);
     va_end(va);
-    Py_DECREF(func);
+
+    Py_DECREF(callable);
     return retval;
 }
 
 PyObject *
-_PyObject_CallMethodId(PyObject *o, _Py_Identifier *name,
+_PyObject_CallMethodId(PyObject *obj, _Py_Identifier *name,
                        const char *format, ...)
 {
     va_list va;
-    PyObject *func = NULL;
+    PyObject *callable = NULL;
     PyObject *retval = NULL;
 
-    if (o == NULL || name == NULL) {
+    if (obj == NULL || name == NULL) {
         return null_error();
     }
 
-    func = _PyObject_GetAttrId(o, name);
-    if (func == NULL)
+    callable = _PyObject_GetAttrId(obj, name);
+    if (callable == NULL)
         return NULL;
 
     va_start(va, format);
-    retval = callmethod(func, format, va, 0);
+    retval = callmethod(callable, format, va, 0);
     va_end(va);
-    Py_DECREF(func);
+
+    Py_DECREF(callable);
     return retval;
 }
 
 PyObject *
-_PyObject_CallMethod_SizeT(PyObject *o, const char *name,
+_PyObject_CallMethod_SizeT(PyObject *obj, const char *name,
                            const char *format, ...)
 {
     va_list va;
-    PyObject *func = NULL;
+    PyObject *callable = NULL;
     PyObject *retval;
 
-    if (o == NULL || name == NULL) {
+    if (obj == NULL || name == NULL) {
         return null_error();
     }
 
-    func = PyObject_GetAttrString(o, name);
-    if (func == NULL)
+    callable = PyObject_GetAttrString(obj, name);
+    if (callable == NULL)
         return NULL;
+
     va_start(va, format);
-    retval = callmethod(func, format, va, 1);
+    retval = callmethod(callable, format, va, 1);
     va_end(va);
-    Py_DECREF(func);
+
+    Py_DECREF(callable);
     return retval;
 }
 
 PyObject *
-_PyObject_CallMethodId_SizeT(PyObject *o, _Py_Identifier *name,
+_PyObject_CallMethodId_SizeT(PyObject *obj, _Py_Identifier *name,
                              const char *format, ...)
 {
     va_list va;
-    PyObject *func = NULL;
+    PyObject *callable = NULL;
     PyObject *retval;
 
-    if (o == NULL || name == NULL) {
+    if (obj == NULL || name == NULL) {
         return null_error();
     }
 
-    func = _PyObject_GetAttrId(o, name);
-    if (func == NULL) {
+    callable = _PyObject_GetAttrId(obj, name);
+    if (callable == NULL) {
         return NULL;
     }
+
     va_start(va, format);
-    retval = callmethod(func, format, va, 1);
+    retval = callmethod(callable, format, va, 1);
     va_end(va);
-    Py_DECREF(func);
+
+    Py_DECREF(callable);
     return retval;
 }
 
@@ -2756,20 +2763,21 @@ PyObject_CallMethodObjArgs(PyObject *callable, PyObject *name, ...)
 }
 
 PyObject *
-_PyObject_CallMethodIdObjArgs(PyObject *callable,
-        struct _Py_Identifier *name, ...)
+_PyObject_CallMethodIdObjArgs(PyObject *obj,
+                              struct _Py_Identifier *name, ...)
 {
     PyObject *small_stack[5];
     PyObject **stack;
+    PyObject *callable;
     Py_ssize_t nargs;
     PyObject *result;
     va_list vargs;
 
-    if (callable == NULL || name == NULL) {
+    if (obj == NULL || name == NULL) {
         return null_error();
     }
 
-    callable = _PyObject_GetAttrId(callable, name);
+    callable = _PyObject_GetAttrId(obj, name);
     if (callable == NULL)
         return NULL;
 
diff --git a/Objects/typeobject.c b/Objects/typeobject.c
index f3e718b..0fcdd7d 100644
--- a/Objects/typeobject.c
+++ b/Objects/typeobject.c
@@ -1425,15 +1425,15 @@ _PyObject_LookupSpecial(PyObject *self, _Py_Identifier *attrid)
    as lookup_method to cache the interned name string object. */
 
 static PyObject *
-call_method(PyObject *o, _Py_Identifier *nameid, const char *format, ...)
+call_method(PyObject *obj, _Py_Identifier *name, const char *format, ...)
 {
     va_list va;
     PyObject *func = NULL, *retval;
 
-    func = lookup_maybe(o, nameid);
+    func = lookup_maybe(obj, name);
     if (func == NULL) {
         if (!PyErr_Occurred())
-            PyErr_SetObject(PyExc_AttributeError, nameid->object);
+            PyErr_SetObject(PyExc_AttributeError, name->object);
         return NULL;
     }
 
@@ -1465,12 +1465,12 @@ call_method(PyObject *o, _Py_Identifier *nameid, const char *format, ...)
 /* Clone of call_method() that returns NotImplemented when the lookup fails. */
 
 static PyObject *
-call_maybe(PyObject *o, _Py_Identifier *nameid, const char *format, ...)
+call_maybe(PyObject *obj, _Py_Identifier *name, const char *format, ...)
 {
     va_list va;
     PyObject *func = NULL, *retval;
 
-    func = lookup_maybe(o, nameid);
+    func = lookup_maybe(obj, name);
     if (func == NULL) {
         if (!PyErr_Occurred())
             Py_RETURN_NOTIMPLEMENTED;