[Python-ideas] Deprecate dunder functions from operator module

[Steven D'Aprano]

(For the avoidance of all doubt, the following has nothing to do with 
dunder methods like int.__add__ etc., but only the functions in the 
operator module.)

The operator module contains various function versions of operators, 
e.g. operator.add for + , operator.sub for - , etc.

There are also dunder versions of each function, and according to the 
documentation:

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

    https://docs.python.org/3/library/operator.html

(except that's not quite right, because there are no functions __radd__ 
etc. matching the special class methods).

The existence of redundant dunder functions came as a complete surprise 
to me when I recently discovered it, and I daresay it will come as a 
surprise to many people. Having two versions in the operator module has 
been known to lead to confusion, e.g.:

https://mail.python.org/pipermail/tutor/2014-October/102877.html

All the third party documentation I've seen for the operator module 
refers to the dunderless versions.

I doubt that there is anyone who prefers to write operator.__add__ 
instead of operator.add, and Terry Reedy has kindly determined that 
(aside from tests) the standard library doesn't use any of the dunder 
versions.

https://mail.python.org/pipermail/python-list/2014-October/679226.html


I propose a few things:

* institute a policy that, in the event of a new function being added 
  to the operator module, only the dunderless version will be added;

* change the documentation to make it clear that the dunderless 
  versions should be used, rather than merely being "convenience" 
  functions;

* add a prominent note that the dunder versions exist for backwards 
  compatibility only and should not be used in new code.

At this point, I do NOT propose having the dunder versions of the 
functions raise a depreciation warning. I would be content for them to 
merely be documented as discouraged, and defer actual depreciation until 
Python 5000 or so. (But if there is a strong preference for actual 
deprecation, I won't argue against it.)

Thoughts?



-- 
Steven