<div dir="auto"><div><br><div class="gmail_extra"><br><div class="gmail_quote">On Apr 13, 2017 14:25, "Steven D'Aprano" <<a href="mailto:steve@pearwood.info">steve@pearwood.info</a>> wrote:<br type="attribution"><blockquote class="quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Notice that I said *discourage* rather than *deprecate*.<br>
<br>
Quoting the documentation:<br>
<br>
    The operator module exports a set of efficient functions<br>
    corresponding to the intrinsic operators of Python. For<br>
    example, operator.add(x, y) is equivalent to the expression<br>
    x+y. The function names are those used for special class<br>
    methods; variants without leading and trailing __ are also<br>
    provided for convenience.<br>
<br>
<a href="https://docs.python.org/3/library/operator.html" rel="noreferrer" target="_blank">https://docs.python.org/3/<wbr>library/operator.html</a><br>
<br>
I propose four simple documentation changes, and no code change:<br>
<br>
<br>
(1) The quoted paragraph is factually wrong to say:<br>
<br>
    "The function names are those used for special class methods"<br>
<br>
    We can fix that by changing it to:<br>
<br>
    "Some function names are those used for special class methods".<br>
<br>
<br>
(2) Replace the word "convenience" in the quoted paragraph by<br>
    "backward compatibility";<br>
<br>
<br>
(3) Add a note close to the top of the page that the non-dunder<br>
    names are preferred for new code.<br>
<br>
<br>
(4) And a note stating that existing dunder functions will<br>
    remain, but no new ones will be added.<br>
<br>
<br>
The existing dunder names will remain aliases to the non-dunder names;<br>
they will not be deprecated (maybe in Python 5000 *wink*). Those who<br>
really want to use them can continue to do so.<br>
<br>
Regarding point (1) above:<br>
<br>
- Not all operator functions have a dunder alias.<br>
<br>
- The dunder functions don't always correspond to a dunder method. For<br>
example, there is operator.__concat__ for sequence concatenation, but no<br>
str.__concat__ or list.__concat__ methods.<br>
<br>
- Even when the dunder function corresponds by name to the dunder<br>
method, they don't mean the same thing. For example, operator.__add__ is<br>
*not* the same as just calling the first argument's __add__ method.<br>
<br>
- And finally, I fail to see how having to type an extra four characters<br>
is a "convenience".<br>
<br>
<br>
Long ago, when the operator module was first introduced, there was a<br>
much stronger correspondence between the operator.__dunder__ functions<br>
and dunder methods. But I think that correspondence is now so weak that<br>
we should simply treat it as a historical artifact.</blockquote></div></div></div><div dir="auto"><br></div><div dir="auto">What about going a step further and moving the __dunder__ functions to another section? </div><div dir="auto"><br></div><div dir="auto">Perhaps it could have a statement saying that some of the functions also come in dunder versions, but that people are encouraged to use the regular version. Then you can just have a table with the normal version on the left and the equivalent dunder version (if any) on the right. </div><div dir="auto"><br></div><div dir="auto">This would also have the benefit of making the existing function list simpler and clearer.</div><div dir="auto"><br></div><div dir="auto"><div class="gmail_extra"><div class="gmail_quote"><blockquote class="quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><font color="#888888"><br></font></blockquote></div></div></div></div>