classification
Title: Make "dunder" method documentation easier to locate
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.9, Python 3.8
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: aeros, docs@python, javadmokhtari, miss-islington, nanjekyejoannah, rhettinger
Priority: low Keywords: easy, newcomer friendly, patch

Created on 2020-03-23 00:50 by aeros, last changed 2020-03-27 19:22 by nanjekyejoannah.

Pull Requests
URL Status Linked Edit
PR 19153 merged javadmokhtari, 2020-03-25 07:00
PR 19198 merged miss-islington, 2020-03-27 19:03
PR 19199 merged miss-islington, 2020-03-27 19:03
Messages (8)
msg364832 - (view) Author: Kyle Stanley (aeros) * (Python committer) Date: 2020-03-23 00:50
In a recent python-ideas thread, the rule of dunder methods being reserved for Python internal usage only was brought up (https://mail.python.org/archives/list/python-ideas@python.org/message/GMRPSSQW3SXNCP4WU7SYDINL67M2WLQI/), due to an author of a third party library using them without knowing better. Steven D'Aprano linked the following section of the docs that defines the rule: https://docs.python.org/3/reference/lexical_analysis.html#reserved-classes-of-identifiers. 

When I had attempted to search for the rule in the documentation (prior to the above discussion), I noticed that it was rather difficult to discover because it was written just as "System-defined names" with no mention of "dunder" (which is what the dev community typically refers to them as, at least in more recent history).

To make it easier for the average user and library maintainer to locate this section, I propose changing the first line to one of the following:

1) System-defined names, also known as "dunder" names.
2) System-defined names, informally known as "dunder" names.

I'm personally in favor of (1), but I could also see a reasonable argument for (2). If we can decide on the wording, it would make for a good first-time PR to the CPython docs.
msg364877 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-03-23 18:35
I vote for #2.   It improves findability while also recognizing that "dunder" isn't a formal term and lies somewhere between slang and jargon.
msg364893 - (view) Author: Kyle Stanley (aeros) * (Python committer) Date: 2020-03-23 20:04
> I vote for #2.   It improves findability while also recognizing that "dunder" isn't a formal term and lies somewhere between slang and jargon.

Yeah, I suppose it is a bit more of a slang or jargon term rather than something with a formal definition, so (2) is fine with me. Thanks for the feedback. 

I'll leave the issue open for a new contributor as it would be an easy PR to work on. But, if it doesn't receive any attention within a few months or so, I'll likely just add it myself since it would be useful to me for easily locating the section in the future.
msg364978 - (view) Author: Javad Mokhtari Koushyar (javadmokhtari) * Date: 2020-03-25 06:35
Hi, I'm ready to work on this.
msg365183 - (view) Author: Joannah Nanjekye (nanjekyejoannah) * (Python committer) Date: 2020-03-27 19:02
New changeset 5f9c131c099d6675d1a9d0228497865488afd548 by Javad Mokhtari in branch 'master':
bpo-40045: Make "dunder" method documentation easier to locate (#19153)
https://github.com/python/cpython/commit/5f9c131c099d6675d1a9d0228497865488afd548
msg365184 - (view) Author: Joannah Nanjekye (nanjekyejoannah) * (Python committer) Date: 2020-03-27 19:15
New changeset bb852266b77ffeeb09a42847c907829eec6d5cb5 by Miss Islington (bot) in branch '3.8':
bpo-40045: Make "dunder" method documentation easier to locate (GH-19153) (GH-19198)
https://github.com/python/cpython/commit/bb852266b77ffeeb09a42847c907829eec6d5cb5
msg365186 - (view) Author: Joannah Nanjekye (nanjekyejoannah) * (Python committer) Date: 2020-03-27 19:17
New changeset c3622b2dcc9278900a7e3cbef12edfa83a8728ed by Miss Islington (bot) in branch '3.7':
bpo-40045: Make "dunder" method documentation easier to locate (GH-19153) (GH-19199)
https://github.com/python/cpython/commit/c3622b2dcc9278900a7e3cbef12edfa83a8728ed
msg365187 - (view) Author: Joannah Nanjekye (nanjekyejoannah) * (Python committer) Date: 2020-03-27 19:22
I think this is resolved. Someone can re-open if they feel discontent. Thanks @javadmokhtari for the patch.
History
Date User Action Args
2020-03-27 19:22:40nanjekyejoannahsetmessages: + msg365187
stage: patch review -> resolved
2020-03-27 19:17:57nanjekyejoannahsetmessages: + msg365186
2020-03-27 19:15:17nanjekyejoannahsetmessages: + msg365184
2020-03-27 19:03:14miss-islingtonsetpull_requests: + pull_request18561
2020-03-27 19:03:06miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request18560
2020-03-27 19:02:57nanjekyejoannahsetnosy: + nanjekyejoannah
messages: + msg365183
2020-03-25 07:00:26javadmokhtarisetkeywords: + patch
stage: patch review
pull_requests: + pull_request18514
2020-03-25 06:35:08javadmokhtarisetnosy: + javadmokhtari
messages: + msg364978
2020-03-23 20:04:07aerossetmessages: + msg364893
2020-03-23 18:35:09rhettingersetnosy: + rhettinger
messages: + msg364877
2020-03-23 00:54:55aerossetpriority: normal -> low
2020-03-23 00:50:33aeroscreate