Discourage operator.__dunder__ functions

[stevendaprano]

BPO	30085
Nosy	@rhettinger, @terryjreedy, @ncoghlan, @stevendaprano, @SanketDG
PRs	bpo-30085: Improve documentation for operator #1171 [3.6] bpo-30085: Improve documentation for operator (GH-1171) #3736

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/terryjreedy'
closed_at = <Date 2017-09-24.18:30:04.724>
created_at = <Date 2017-04-17.02:27:09.573>
labels = ['type-feature', '3.7', 'docs']
title = 'Discourage operator.__dunder__ functions'
updated_at = <Date 2017-09-24.21:13:17.867>
user = 'https://github.com/stevendaprano'

bugs.python.org fields:

activity = <Date 2017-09-24.21:13:17.867>
actor = 'terry.reedy'
assignee = 'terry.reedy'
closed = True
closed_date = <Date 2017-09-24.18:30:04.724>
closer = 'terry.reedy'
components = ['Documentation']
creation = <Date 2017-04-17.02:27:09.573>
creator = 'steven.daprano'
dependencies = []
files = []
hgrepos = []
issue_num = 30085
keywords = []
message_count = 7.0
messages = ['291774', '291991', '291993', '292062', '302220', '302878', '302886']
nosy_count = 6.0
nosy_names = ['rhettinger', 'terry.reedy', 'ncoghlan', 'steven.daprano', 'docs@python', 'sanketdg']
pr_nums = ['1171', '3736']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue30085'
versions = ['Python 3.7']

[stevendaprano]

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

[terryjreedy]

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

[terryjreedy]

Raymond assigned the PR to himself, so I added him here as nosy and assignee.

[SanketDG]

@terry, I have updated the same, thanks!

[terryjreedy]

Raymond, may someone else merge this? I will add a blurb.

[terryjreedy]

New changeset 5b9299d by Terry Jan Reedy (Sanket Dasgupta) in branch 'master':
bpo-30085: Improve documentation for operator (bpo-1171)
5b9299d