[docs] [issue28977] Document PyObject_CallFunction() special case more explicitly

STINNER Victor report at bugs.python.org
Fri Dec 16 03:07:54 EST 2016

STINNER Victor added the comment:

Serhiy: "O" is not the only special case. "S" and "N" unpack a tuple argument too. "O&" converter should return a tuple, otherwise it is an error. All other format codes are illegal for single argument.

Oh, I didn't know. I should update my documentation.

Serhiy: I would just deprecate this feature (in PyObject_CallFunction, not in Py_BuildValue). The behavior of PyObject_CallFunction with a single argument can be made more consistent and useful.

PyObject_CallFunction(func, "O", arg) should call func(arg). I don't want the "O" format (and "S" and "N").

What do you mean exactly by deprecating the feature? Emit a warning if and only if te format string is "O" (or "S" or "N") and Py_BuildValue() returns a tuple?

I guess that PyObject_CallFunction(func, "(O)", arg) doesn't need to be modified, it already always call func(arg), even if arg is a tuple.

I am also tempted to fix PyObject_CallFunction() (and similar functions) rather than documenting the special case, but I dislike the idea of a deprecation.

Let's say that calling PyObject_CallFunction(func, "O", arg) where arg is a tuple would emit a DeprecationWarning and call func(*arg) in Python 3.7, but call func(arg) with no warning in Python 3.8. I dislike this path because developers would try to make the warning quiet in Python 3.7, for example use "(O)" format string, which is less obvious and looks like a hack to me.

More and more applications use Python bleeding edge (the development branch, default), and more and more developers quickly test their application on the new Python stable release. Maybe we can "simply" fix the behaviour of PyObject_CallFunction() with no transition period:

* Python 3.6: PyObject_CallFunction(func, "O", arg) calls func(arg), or func(*arg) if arg is a tuple
* Python 3.7: PyObject_CallFunction(func, "O", arg) always calls func(arg)

The special case was never documented. In my experience, almost no developer rely on this feature. Most developers don't expect the feature and so write code which doesn't work with tuple arguments.


Python tracker <report at bugs.python.org>

More information about the docs mailing list