Skip to content

Commit 2d0eb65

Browse files
vstinnervstinner
committed
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)
1 parent 8907204 commit 2d0eb65

File tree

7 files changed

+211
-179
lines changed

7 files changed

+211
-179
lines changed

‎Doc/c-api/object.rst‎

Lines changed: 46 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -244,63 +244,82 @@ Object Protocol
244244
and ``0`` otherwise. This function always succeeds.
245245
246246
247-
.. c:function:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw)
247+
.. c:function:: PyObject* PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)
248248
249-
Call a callable Python object *callable_object*, with arguments given by the
250-
tuple *args*, and named arguments given by the dictionary *kw*. If no named
251-
arguments are needed, *kw* may be *NULL*. *args* must not be *NULL*, use an
252-
empty tuple if no arguments are needed. Returns the result of the call on
253-
success, or *NULL* on failure. This is the equivalent of the Python expression
254-
``callable_object(*args, **kw)``.
249+
Call a callable Python object *callable*, with arguments given by the
250+
tuple *args*, and named arguments given by the dictionary *kwargs*.
255251
252+
*args* must not be *NULL*, use an empty tuple if no arguments are needed.
253+
If no named arguments are needed, *kwargs* can be *NULL*.
256254
257-
.. c:function:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)
255+
Returns the result of the call on success, or *NULL* on failure.
258256
259-
Call a callable Python object *callable_object*, with arguments given by the
260-
tuple *args*. If no arguments are needed, then *args* may be *NULL*. Returns
261-
the result of the call on success, or *NULL* on failure. This is the equivalent
262-
of the Python expression ``callable_object(*args)``.
257+
This is the equivalent of the Python expression:
258+
``callable(*args, **kwargs)``.
259+
260+
261+
.. c:function:: PyObject* PyObject_CallObject(PyObject *callable, PyObject *args)
262+
263+
Call a callable Python object *callable*, with arguments given by the
264+
tuple *args*. If no arguments are needed, then *args* can be *NULL*.
265+
266+
Returns the result of the call on success, or *NULL* on failure.
267+
268+
This is the equivalent of the Python expression: ``callable(*args)``.
263269
264270
265271
.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...)
266272
267273
Call a callable Python object *callable*, with a variable number of C arguments.
268274
The C arguments are described using a :c:func:`Py_BuildValue` style format
269-
string. The format may be *NULL*, indicating that no arguments are provided.
270-
Returns the result of the call on success, or *NULL* on failure. This is the
271-
equivalent of the Python expression ``callable(*args)``. Note that if you only
272-
pass :c:type:`PyObject \*` args, :c:func:`PyObject_CallFunctionObjArgs` is a
273-
faster alternative.
275+
string. The format can be *NULL*, indicating that no arguments are provided.
276+
277+
Returns the result of the call on success, or *NULL* on failure.
278+
279+
This is the equivalent of the Python expression: ``callable(*args)``.
280+
281+
Note that if you only pass :c:type:`PyObject \*` args,
282+
:c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.
274283
275284
.. versionchanged:: 3.4
276285
The type of *format* was changed from ``char *``.
277286
278287
279-
.. c:function:: PyObject* PyObject_CallMethod(PyObject *o, const char *method, const char *format, ...)
288+
.. c:function:: PyObject* PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)
280289
281-
Call the method named *method* of object *o* with a variable number of C
290+
Call the method named *name* of object *obj* with a variable number of C
282291
arguments. The C arguments are described by a :c:func:`Py_BuildValue` format
283-
string that should produce a tuple. The format may be *NULL*, indicating that
284-
no arguments are provided. Returns the result of the call on success, or *NULL*
285-
on failure. This is the equivalent of the Python expression ``o.method(args)``.
292+
string that should produce a tuple.
293+
294+
The format can be *NULL*, indicating that no arguments are provided.
295+
296+
Returns the result of the call on success, or *NULL* on failure.
297+
298+
This is the equivalent of the Python expression:
299+
``obj.name(arg1, arg2, ...)``.
300+
286301
Note that if you only pass :c:type:`PyObject \*` args,
287302
:c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
288303
289304
.. versionchanged:: 3.4
290-
The types of *method* and *format* were changed from ``char *``.
305+
The types of *name* and *format* were changed from ``char *``.
291306
292307
293308
.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
294309
295310
Call a callable Python object *callable*, with a variable number of
296311
:c:type:`PyObject\*` arguments. The arguments are provided as a variable number
297-
of parameters followed by *NULL*. Returns the result of the call on success, or
298-
*NULL* on failure.
312+
of parameters followed by *NULL*.
313+
314+
Returns the result of the call on success, or *NULL* on failure.
315+
316+
This is the equivalent of the Python expression:
317+
``callable(arg1, arg2, ...)``.
299318
300319
301-
.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL)
320+
.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ..., NULL)
302321
303-
Calls a method of the object *o*, where the name of the method is given as a
322+
Calls a method of the Python object *obj*, where the name of the method is given as a
304323
Python string object in *name*. It is called with a variable number of
305324
:c:type:`PyObject\*` arguments. The arguments are provided as a variable number
306325
of parameters followed by *NULL*. Returns the result of the call on success, or

‎Include/abstract.h‎

Lines changed: 67 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -265,14 +265,16 @@ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*/
265265
This function always succeeds.
266266
*/
267267

268-
PyAPI_FUNC(PyObject *) PyObject_Call(PyObject *callable_object,
269-
PyObject *args, PyObject *kwargs);
268+
/* Call a callable Python object 'callable' with arguments given by the
269+
tuple 'args' and keywords arguments given by the dictionary 'kwargs'.
270270
271-
/*
272-
Call a callable Python object, callable_object, with
273-
arguments and keywords arguments. The 'args' argument can not be
274-
NULL.
275-
*/
271+
'args' must not be *NULL*, use an empty tuple if no arguments are
272+
needed. If no named arguments are needed, 'kwargs' can be NULL.
273+
274+
This is the equivalent of the Python expression:
275+
callable(*args, **kwargs). */
276+
PyAPI_FUNC(PyObject *) PyObject_Call(PyObject *callable,
277+
PyObject *args, PyObject *kwargs);
276278

277279
#ifndef Py_LIMITED_API
278280
PyAPI_FUNC(PyObject*) _PyStack_AsTuple(
@@ -306,7 +308,7 @@ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*/
306308
PyObject **kwnames,
307309
PyObject *func);
308310

309-
/* Call the callable object func with the "fast call" calling convention:
311+
/* Call the callable object 'callable' with the "fast call" calling convention:
310312
args is a C array for positional arguments (nargs is the number of
311313
positional arguments), kwargs is a dictionary for keyword arguments.
312314
@@ -315,11 +317,11 @@ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*/
315317
316318
Return the result on success. Raise an exception on return NULL on
317319
error. */
318-
PyAPI_FUNC(PyObject *) _PyObject_FastCallDict(PyObject *func,
320+
PyAPI_FUNC(PyObject *) _PyObject_FastCallDict(PyObject *callable,
319321
PyObject **args, Py_ssize_t nargs,
320322
PyObject *kwargs);
321323

322-
/* Call the callable object func with the "fast call" calling convention:
324+
/* Call the callable object 'callable' with the "fast call" calling convention:
323325
args is a C array for positional arguments followed by values of
324326
keyword arguments. Keys of keyword arguments are stored as a tuple
325327
of strings in kwnames. nargs is the number of positional parameters at
@@ -335,7 +337,7 @@ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*/
335337
Return the result on success. Raise an exception and return NULL on
336338
error. */
337339
PyAPI_FUNC(PyObject *) _PyObject_FastCallKeywords
338-
(PyObject *func,
340+
(PyObject *callable,
339341
PyObject **args,
340342
Py_ssize_t nargs,
341343
PyObject *kwnames);
@@ -346,55 +348,54 @@ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*/
346348
#define _PyObject_CallNoArg(func) \
347349
_PyObject_FastCallDict((func), NULL, 0, NULL)
348350

349-
PyAPI_FUNC(PyObject *) _PyObject_Call_Prepend(PyObject *func,
351+
PyAPI_FUNC(PyObject *) _PyObject_Call_Prepend(PyObject *callable,
350352
PyObject *obj, PyObject *args,
351353
PyObject *kwargs);
352354

353-
PyAPI_FUNC(PyObject *) _Py_CheckFunctionResult(PyObject *func,
355+
PyAPI_FUNC(PyObject *) _Py_CheckFunctionResult(PyObject *callable,
354356
PyObject *result,
355357
const char *where);
356358
#endif /* Py_LIMITED_API */
357359

358-
PyAPI_FUNC(PyObject *) PyObject_CallObject(PyObject *callable_object,
360+
/* Call a callable Python object 'callable', with arguments given by the
361+
tuple 'args'. If no arguments are needed, then 'args' can be *NULL*.
362+
363+
Returns the result of the call on success, or *NULL* on failure.
364+
365+
This is the equivalent of the Python expression:
366+
callable(*args) */
367+
PyAPI_FUNC(PyObject *) PyObject_CallObject(PyObject *callable,
359368
PyObject *args);
360369

361-
/*
362-
Call a callable Python object, callable_object, with
363-
arguments given by the tuple, args. If no arguments are
364-
needed, then args may be NULL. Returns the result of the
365-
call on success, or NULL on failure. This is the equivalent
366-
of the Python expression: o(*args).
367-
*/
370+
/* Call a callable Python object, callable, with a variable number of C
371+
arguments. The C arguments are described using a mkvalue-style format
372+
string.
368373
369-
PyAPI_FUNC(PyObject *) PyObject_CallFunction(PyObject *callable_object,
374+
The format may be NULL, indicating that no arguments are provided.
375+
376+
Returns the result of the call on success, or NULL on failure.
377+
378+
This is the equivalent of the Python expression:
379+
callable(arg1, arg2, ...) */
380+
PyAPI_FUNC(PyObject *) PyObject_CallFunction(PyObject *callable,
370381
const char *format, ...);
371382

372-
/*
373-
Call a callable Python object, callable_object, with a
374-
variable number of C arguments. The C arguments are described
375-
using a mkvalue-style format string. The format may be NULL,
376-
indicating that no arguments are provided. Returns the
377-
result of the call on success, or NULL on failure. This is
378-
the equivalent of the Python expression: o(*args).
379-
*/
383+
/* Call the method named 'name' of object 'obj' with a variable number of
384+
C arguments. The C arguments are described by a mkvalue format string.
380385
386+
The format can be NULL, indicating that no arguments are provided.
381387
382-
PyAPI_FUNC(PyObject *) PyObject_CallMethod(PyObject *o,
383-
const char *method,
384-
const char *format, ...);
388+
Returns the result of the call on success, or NULL on failure.
385389
386-
/*
387-
Call the method named m of object o with a variable number of
388-
C arguments. The C arguments are described by a mkvalue
389-
format string. The format may be NULL, indicating that no
390-
arguments are provided. Returns the result of the call on
391-
success, or NULL on failure. This is the equivalent of the
392-
Python expression: o.method(args).
393-
*/
390+
This is the equivalent of the Python expression:
391+
obj.name(arg1, arg2, ...) */
392+
PyAPI_FUNC(PyObject *) PyObject_CallMethod(PyObject *obj,
393+
const char *name,
394+
const char *format, ...);
394395

395396
#ifndef Py_LIMITED_API
396-
PyAPI_FUNC(PyObject *) _PyObject_CallMethodId(PyObject *o,
397-
_Py_Identifier *method,
397+
PyAPI_FUNC(PyObject *) _PyObject_CallMethodId(PyObject *obj,
398+
_Py_Identifier *name,
398399
const char *format, ...);
399400

400401
/*
@@ -406,44 +407,45 @@ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*/
406407
PyAPI_FUNC(PyObject *) _PyObject_CallFunction_SizeT(PyObject *callable,
407408
const char *format,
408409
...);
409-
PyAPI_FUNC(PyObject *) _PyObject_CallMethod_SizeT(PyObject *o,
410+
PyAPI_FUNC(PyObject *) _PyObject_CallMethod_SizeT(PyObject *obj,
410411
const char *name,
411412
const char *format,
412413
...);
413414
#ifndef Py_LIMITED_API
414-
PyAPI_FUNC(PyObject *) _PyObject_CallMethodId_SizeT(PyObject *o,
415-
_Py_Identifier *name,
416-
const char *format,
417-
...);
415+
PyAPI_FUNC(PyObject *) _PyObject_CallMethodId_SizeT(PyObject *obj,
416+
_Py_Identifier *name,
417+
const char *format,
418+
...);
418419
#endif /* !Py_LIMITED_API */
419420

421+
/* Call a callable Python object 'callable' with a variable number of C
422+
arguments. The C arguments are provided as PyObject* values, terminated
423+
by a NULL.
424+
425+
Returns the result of the call on success, or NULL on failure.
426+
427+
This is the equivalent of the Python expression:
428+
callable(arg1, arg2, ...) */
420429
PyAPI_FUNC(PyObject *) PyObject_CallFunctionObjArgs(PyObject *callable,
421430
...);
422431

423432
/*
424-
Call a callable Python object, callable_object, with a
425-
variable number of C arguments. The C arguments are provided
426-
as PyObject * values, terminated by a NULL. Returns the
427-
result of the call on success, or NULL on failure. This is
428-
the equivalent of the Python expression: o(*args).
433+
Call the method named 'name' of object 'obj' with a variable number of
434+
C arguments. The C arguments are provided as PyObject *
435+
values, terminated by NULL. Returns the result of the call
436+
on success, or NULL on failure. This is the equivalent of
437+
the Python expression: obj.name(args).
429438
*/
430439

431-
432-
PyAPI_FUNC(PyObject *) PyObject_CallMethodObjArgs(PyObject *o,
433-
PyObject *method, ...);
440+
PyAPI_FUNC(PyObject *) PyObject_CallMethodObjArgs(PyObject *obj,
441+
PyObject *name,
442+
...);
434443
#ifndef Py_LIMITED_API
435-
PyAPI_FUNC(PyObject *) _PyObject_CallMethodIdObjArgs(PyObject *o,
436-
struct _Py_Identifier *method,
444+
PyAPI_FUNC(PyObject *) _PyObject_CallMethodIdObjArgs(PyObject *obj,
445+
struct _Py_Identifier *name,
437446
...);
438447
#endif /* !Py_LIMITED_API */
439448

440-
/*
441-
Call the method named m of object o with a variable number of
442-
C arguments. The C arguments are provided as PyObject *
443-
values, terminated by NULL. Returns the result of the call
444-
on success, or NULL on failure. This is the equivalent of
445-
the Python expression: o.method(args).
446-
*/
447449

448450

449451
/* Implemented elsewhere:

‎Include/ceval.h‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,18 @@ extern "C" {
88
/* Interface to random parts in ceval.c */
99

1010
PyAPI_FUNC(PyObject *) PyEval_CallObjectWithKeywords(
11-
PyObject *func, PyObject *args, PyObject *kwargs);
11+
PyObject *callable,
12+
PyObject *args,
13+
PyObject *kwargs);
1214

1315
/* Inline this */
14-
#define PyEval_CallObject(func,arg) \
15-
PyEval_CallObjectWithKeywords(func, arg, (PyObject *)NULL)
16+
#define PyEval_CallObject(callable, arg) \
17+
PyEval_CallObjectWithKeywords(callable, arg, (PyObject *)NULL)
1618

17-
PyAPI_FUNC(PyObject *) PyEval_CallFunction(PyObject *obj,
19+
PyAPI_FUNC(PyObject *) PyEval_CallFunction(PyObject *callable,
1820
const char *format, ...);
1921
PyAPI_FUNC(PyObject *) PyEval_CallMethod(PyObject *obj,
20-
const char *methodname,
22+
const char *name,
2123
const char *format, ...);
2224

2325
#ifndef Py_LIMITED_API

0 commit comments

Comments
 (0)