API functions not working as expected

[John Machin]

On 16/06/2006 9:51 AM, Kirk McDonald wrote:
> ... 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