[Python-ideas] Discourage operator.__dunder__ functions

Terry Reedy tjreedy at udel.edu
Thu Apr 13 14:51:59 EDT 2017


On 4/13/2017 2:20 PM, Steven D'Aprano wrote:
> 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:

I agree with revisiting this part of the doc, *and* with promoting
the dunderless versions as the primary and currently preferred version.

> (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".

They are instance methods defined on classes rather than 'class 
methods'.  How about

"Many function names are those used for special methods, minus the 
double underscores."

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

Then we would have "variants without leading and trailing __ are also
provided for backward compatibility", which is wrong.  I presume that 
you mean "For backward compatibility, many of these have variants with 
the double underscores kept.

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

Literal 'notes' in the doc stand out too much for this.

My combined suggestion: 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)".

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

I think that this is implied in 'For backward compatibility'.  In any 
case, I don't think this belongs in the doc itself, but rather might be 
a comment in the module directed at future maintainers.

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

Again, this is a future policy comment.

> 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".

It is a burden and, as you noted, a bit misleading.

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

-- 
Terry Jan Reedy



More information about the Python-ideas mailing list