Module operator: docstring of in-place operators seems misleading

Documentation
1

Similar issue, Doc strings for built-in, in-place operators are misleading · Issue #91134 · python/cpython, was closed as not planned, so I want to discuss here before bothering core dev time.

For example, this is current docstring of operator.iadd:

>>> from operator import *
>>> help(iadd)
Help on built-in function iadd in module _operator:

iadd(a, b, /)
    Same as a += b.

>>>

However, in fact, iadd(a, b) is NOT same as a += b; a = iadd(a, b) is THE same as a += b.

Library document, operator — Standard operators as functions — Python 3.14.0 documentation, explains this as detail as possible.

Is it worth to fix docstring? or, would it waste of time/manpower as better document already exists?

2 Likes
2

I don’t think this is worth changing.
All functions in the operator modules return something, so it’s fine that the docstrings say iadd is like += and the reader knows to write c = iadd(a, b).
It is a property of the in-place methods that a may be modified too (e.g. a list is modified, but not a string), not a property of the operator module functions.

1 Like