As discussed on the Python-Ideas mailing list, it is time to discourage the use of operator.__dunder__ functions. Not to remove them or deprecate them, just change the documentation to make it clear that the dunderless versions are preferred.

Guido +1'ed this suggestion, and there were no objections:

https://mail.python.org/pipermail/python-ideas/2017-April/045424.html

My suggestion from the python-ideas thread:: replace the current

"The function names are those used for special class methods; variants without leading and trailing __ are also provided for convenience."

with

""Many function names are those used for special methods, minus the double underscores.  For backward compatibility, many of these have a variant with the double underscores kept.  We recommend using the dunderless form.  Note that operator.__add__(x, y), for instance, being the same as x + y, is not the same as x.__add__(y)."

Possibly add ", since the first two may result in calling y.__radd__(x)".



Raymond assigned the

Raymond assigned the PR to himself, so I added him here as nosy and assignee.

@terry, I have updated the same, thanks!

Raymond, may someone else merge this?  I will add a blurb.

New changeset 5b9299d8c72aeadccadd77e4b8132094ba9a1f96 by Terry Jan Reedy (Sanket Dasgupta) in branch 'master':
bpo-30085: Improve documentation for operator (#1171)
https://github.com/python/cpython/commit/5b9299d8c72aeadccadd77e4b8132094ba9a1f96

New changeset d38caf68bb417232fb0ccecb5558d7d0ca4a9507 by Terry Jan Reedy (Miss Islington (bot)) in branch '3.6':
[3.6] bpo-30085: Improve documentation for operator (GH-1171) (#3736)
https://github.com/python/cpython/commit/d38caf68bb417232fb0ccecb5558d7d0ca4a9507