Discourage operator.__dunder__ functions

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

On 4/13/2017 2:20 PM, Steven D'Aprano wrote:
I agree with revisiting this part of the doc, *and* with promoting the dunderless versions as the primary and currently preferred version.
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.
Again, this is a future policy comment.
It is a burden and, as you noted, a bit misleading.
-- Terry Jan Reedy

On 14 April 2017 at 04:20, Steven D'Aprano <steve@pearwood.info> wrote:
+1 from me, with this rationale. The specifics sounds pretty good to me, too - happy to review a PR if you put one together :) Cheers, Nick. P.S. To be completely honest, I'd forgotten the dunder names in operator were there :) -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia

On Sat, Apr 15, 2017 at 12:09:39AM +1000, Nick Coghlan wrote:
http://bugs.python.org/issue30085 For some reason, Github won't allow me to log in at the moment. It keeps insisting I need to enable cookies, even though I have. Perhaps it doesn't like my browser? I'll have to try on another computer with a different browser. Terry, you had some nice suggestions for wording. If you want to submit a PR, feel free to take over the issue. I probably won't get a chance to do any more on this for a week. -- Steve

Hi, I have opened a pull request at https://github.com/python/cpython/pull/1171 I am not sure of the wording used, and I'd love some feedback. Thanks! On Mon, Apr 17, 2017 at 8:10 AM Steven D'Aprano <steve@pearwood.info> wrote:

On Apr 13, 2017 14:25, "Steven D'Aprano" <steve@pearwood.info> 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: (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. What about going a step further and moving the __dunder__ functions to another section? 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. This would also have the benefit of making the existing function list simpler and clearer.

On 13.04.2017 20:20, Steven D'Aprano wrote:
- And finally, I fail to see how having to type an extra four characters is a "convenience".
Just for the sake of completeness: Re-usage of names is always a convenience. Developers can use a string variable to access dynamically both the real dunder method and the operator one. It's a frequently used pattern. Whether it's necessary here, is different matter. Sven

On 4/13/2017 2:20 PM, Steven D'Aprano wrote:
I agree with revisiting this part of the doc, *and* with promoting the dunderless versions as the primary and currently preferred version.
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.
Again, this is a future policy comment.
It is a burden and, as you noted, a bit misleading.
-- Terry Jan Reedy

On 14 April 2017 at 04:20, Steven D'Aprano <steve@pearwood.info> wrote:
+1 from me, with this rationale. The specifics sounds pretty good to me, too - happy to review a PR if you put one together :) Cheers, Nick. P.S. To be completely honest, I'd forgotten the dunder names in operator were there :) -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia

On Sat, Apr 15, 2017 at 12:09:39AM +1000, Nick Coghlan wrote:
http://bugs.python.org/issue30085 For some reason, Github won't allow me to log in at the moment. It keeps insisting I need to enable cookies, even though I have. Perhaps it doesn't like my browser? I'll have to try on another computer with a different browser. Terry, you had some nice suggestions for wording. If you want to submit a PR, feel free to take over the issue. I probably won't get a chance to do any more on this for a week. -- Steve

Hi, I have opened a pull request at https://github.com/python/cpython/pull/1171 I am not sure of the wording used, and I'd love some feedback. Thanks! On Mon, Apr 17, 2017 at 8:10 AM Steven D'Aprano <steve@pearwood.info> wrote:

On Apr 13, 2017 14:25, "Steven D'Aprano" <steve@pearwood.info> 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: (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. What about going a step further and moving the __dunder__ functions to another section? 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. This would also have the benefit of making the existing function list simpler and clearer.

On 13.04.2017 20:20, Steven D'Aprano wrote:
- And finally, I fail to see how having to type an extra four characters is a "convenience".
Just for the sake of completeness: Re-usage of names is always a convenience. Developers can use a string variable to access dynamically both the real dunder method and the operator one. It's a frequently used pattern. Whether it's necessary here, is different matter. Sven
participants (7)
-
Guido van Rossum
-
Nick Coghlan
-
Sanket Dasgupta
-
Steven D'Aprano
-
Sven R. Kunze
-
Terry Reedy
-
Todd