[Python-ideas] Discourage operator.__dunder__ functions

[Steven D'Aprano]

Notice that I said *discourage* rather than *deprecate*.

Quoting the documentation:

    The operator module exports a set of efficient functions
    corresponding to the intrinsic operators of Python. For 
    example, operator.add(x, y) is equivalent to the expression 
    x+y. 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

I propose four simple documentation changes, and no code change:


(1) The quoted paragraph is factually wrong to say:

    "The function names are those used for special class methods"

    We can fix that by changing it to:

    "Some function names are those used for special class methods".


(2) Replace the word "convenience" in the quoted paragraph by 
    "backward compatibility";


(3) Add a note close to the top of the page that the non-dunder 
    names are preferred for new code.


(4) And a note stating that existing dunder functions will 
    remain, but no new ones will be added.


The existing dunder names will remain aliases to the non-dunder names; 
they will not be deprecated (maybe in Python 5000 *wink*). Those who 
really want to use them can continue to do so.

Regarding point (1) above:

- Not all operator functions have a dunder alias.

- The dunder functions don't always correspond to a dunder method. For 
example, there is operator.__concat__ for sequence concatenation, but no 
str.__concat__ or list.__concat__ methods.

- Even when the dunder function corresponds by name to the dunder 
method, they don't mean the same thing. For example, operator.__add__ is 
*not* the same as just calling the first argument's __add__ method.

- And finally, I fail to see how having to type an extra four characters 
is a "convenience".


Long ago, when the operator module was first introduced, there was a 
much stronger correspondence between the operator.__dunder__ functions 
and dunder methods. But I think that correspondence is now so weak that 
we should simply treat it as a historical artifact.



-- 
Steve