API functions not working as expected

[Kirk McDonald]

.... for reasons that are obvious in retrospect. Specifically, I am
talking about the PyNumber_InPlace* family of functions. For example,
the docs for InPlaceAdd say:

PyObject* PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)
Return value: New reference.
Returns the result of adding o1 and o2, or NULL on failure. The
operation is done in-place when o1 supports it. This is the equivalent
of the Python statement "o1 += o2".

But, of course, numbers are immutable. None of them support in-place
addition. This is not the same as o1 += o2, as o1 is not actually
changed when using this function.

Am I missing something here? Is there, in fact, no point to these
InPlace* functions?

-Kirk McDonald

 

[John Machin]

... for reasons that are obvious in retrospect. Specifically, I am
talking about the PyNumber_InPlace* family of functions. For example,
the docs for InPlaceAdd say:

PyObject* PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)
Return value: New reference.
Returns the result of adding o1 and o2, or NULL on failure. The
operation is done in-place when o1 supports it. This is the equivalent
of the Python statement "o1 += o2".

But, of course, numbers are immutable. None of them support in-place
addition. This is not the same as o1 += o2, as o1 is not actually
changed when using this function.

Am I missing something here? Is there, in fact, no point to these
InPlace* functions?

Well, I guess it all depends on your expectations ...

I've never used any of those functions, but after a quick perusal of the
manual, here's my expectation:

Looking at the heading of the manual section ("Number protocol"), I take
that to mean that the contents relate to operations on objects which
support some of the (mostly) binary operators usually associated with
numbers.

I expect that PyNumber_Add will work with numbers, strings, lists, and more.

I expect that PyNumber_InPlaceAdd will work like PyNumber_Add for
numbers and strings, and do o1.extend(o2) for lists.

I expect a similar story with PyNumber_(InPlace)?Or and sets.

By the way, I also have an expectation that the core devs don't waste
their time and talents writing, testing and documenting pointless
functions. Any suspicions that I may have had to the contrary over the
time since I was first pointed at Python 1.5.1 have proved to be wrong
and founded on my own ignorance.

HTH,
John