[Python-ideas] Deprecate dunder functions from operator module

[Terry Reedy]

On 10/29/2014 8:53 PM, Steven D'Aprano wrote:
> (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.

I only determined before that 'operator.__' is never used except for 6 
tests.  I just grepped Lib/*.py for 'from operator import' and none of 
the 28 line imports a dunder version.

> 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?

I think the dunder versions should at least be deprecated in the doc, 
and possibly in the functions also. Could we also augment 2to3.

I went to
https://code.openhub.net/search
and searched for "from operator import" and in the first 160 Python 
hits, there were no dunders.  (Anyone else could continue checking from 
page 17.) Not counting 'attrgetter' and 'itemgetter' hits might leave 
100 non-dunder imports.

"from operator import mul" has 150 hits, while same with "__mul__" has 
one hit in a 'pythran' test/test_operator.py file.  For 'add' and 
'__add__', the numbers are 330 and 8.  For operator.add and 
operator.__add__, dunder use is more common: 2079 versus 187, but still 
under 10%

-- 
Terry Jan Reedy