classification
Title: Discourage operator.__dunder__ functions
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: terry.reedy Nosy List: docs@python, ncoghlan, rhettinger, sanketdg, steven.daprano, terry.reedy
Priority: normal Keywords:

Created on 2017-04-17 02:27 by steven.daprano, last changed 2017-09-24 21:13 by terry.reedy. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 1171 merged sanketdg, 2017-04-18 19:45
PR 3736 merged python-dev, 2017-09-24 21:08
Messages (7)
msg291774 - (view) Author: Steven D'Aprano (steven.daprano) * (Python committer) Date: 2017-04-17 02:27
As discussed on the Python-Ideas mailing list, it is time to discourage the use of operator.__dunder__ functions. Not to remove them or deprecate them, just change the documentation to make it clear that the dunderless versions are preferred.

Guido +1'ed this suggestion, and there were no objections:

https://mail.python.org/pipermail/python-ideas/2017-April/045424.html
msg291991 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-04-20 18:33
My suggestion from the python-ideas thread:: 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)".



Raymond assigned the
msg291993 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-04-20 18:48
Raymond assigned the PR to himself, so I added him here as nosy and assignee.
msg292062 - (view) Author: Sanket Dasgupta (sanketdg) * Date: 2017-04-21 16:28
@terry, I have updated the same, thanks!
msg302220 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-09-14 22:38
Raymond, may someone else merge this?  I will add a blurb.
msg302878 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-09-24 18:29
New changeset 5b9299d8c72aeadccadd77e4b8132094ba9a1f96 by Terry Jan Reedy (Sanket Dasgupta) in branch 'master':
bpo-30085: Improve documentation for operator (#1171)
https://github.com/python/cpython/commit/5b9299d8c72aeadccadd77e4b8132094ba9a1f96
msg302886 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-09-24 21:13
New changeset d38caf68bb417232fb0ccecb5558d7d0ca4a9507 by Terry Jan Reedy (Miss Islington (bot)) in branch '3.6':
[3.6] bpo-30085: Improve documentation for operator (GH-1171) (#3736)
https://github.com/python/cpython/commit/d38caf68bb417232fb0ccecb5558d7d0ca4a9507
History
Date User Action Args
2017-09-24 21:13:17terry.reedysetmessages: + msg302886
2017-09-24 21:08:58python-devsetpull_requests: + pull_request3722
2017-09-24 18:30:04terry.reedysetstatus: open -> closed
resolution: fixed
stage: commit review -> resolved
2017-09-24 18:29:23terry.reedysetmessages: + msg302878
2017-09-24 17:39:46rhettingersetassignee: terry.reedy
2017-09-14 22:38:31terry.reedysetassignee: rhettinger -> (no value)
messages: + msg302220
2017-05-04 22:11:04terry.reedysetstage: commit review
type: enhancement
versions: + Python 3.7
2017-04-21 16:28:48sanketdgsetnosy: + sanketdg
messages: + msg292062
2017-04-20 18:48:47terry.reedysetmessages: + msg291993
2017-04-20 18:33:57terry.reedysetassignee: docs@python -> rhettinger

messages: + msg291991
nosy: + rhettinger
2017-04-18 19:45:51sanketdgsetpull_requests: + pull_request1301
2017-04-17 02:27:09steven.dapranocreate