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