[issue40045] Make "dunder" method documentation easier to locate
New submission from Kyle Stanley <aeros167@gmail.com>: 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/GMRPSS...), 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-o.... 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. ---------- assignee: docs@python components: Documentation keywords: easy, newcomer friendly messages: 364832 nosy: aeros, docs@python priority: normal severity: normal status: open title: Make "dunder" method documentation easier to locate type: enhancement versions: Python 3.8, Python 3.9 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40045> _______________________________________
Change by Kyle Stanley <aeros167@gmail.com>: ---------- priority: normal -> low _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40045> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: I vote for #2. It improves findability while also recognizing that "dunder" isn't a formal term and lies somewhere between slang and jargon. ---------- nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40045> _______________________________________
Kyle Stanley <aeros167@gmail.com> added the comment:
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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40045> _______________________________________
Javad Mokhtari Koushyar <javadmokhtari@outlook.com> added the comment: Hi, I'm ready to work on this. ---------- nosy: +javadmokhtari _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40045> _______________________________________
Change by Javad Mokhtari Koushyar <javadmokhtari@outlook.com>: ---------- keywords: +patch pull_requests: +18514 stage: -> patch review pull_request: https://github.com/python/cpython/pull/19153 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40045> _______________________________________
Joannah Nanjekye <nanjekyejoannah@gmail.com> added the comment: 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/5f9c131c099d6675d1a9d0228497865488a... ---------- nosy: +nanjekyejoannah _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40045> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- nosy: +miss-islington nosy_count: 5.0 -> 6.0 pull_requests: +18560 pull_request: https://github.com/python/cpython/pull/19198 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40045> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +18561 pull_request: https://github.com/python/cpython/pull/19199 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40045> _______________________________________
Joannah Nanjekye <nanjekyejoannah@gmail.com> added the comment: 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/bb852266b77ffeeb09a42847c907829eec6... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40045> _______________________________________
Joannah Nanjekye <nanjekyejoannah@gmail.com> added the comment: 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/c3622b2dcc9278900a7e3cbef12edfa83a8... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40045> _______________________________________
Joannah Nanjekye <nanjekyejoannah@gmail.com> added the comment: I think this is resolved. Someone can re-open if they feel discontent. Thanks @javadmokhtari for the patch. ---------- stage: patch review -> resolved _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40045> _______________________________________
Hilit Oreny <hilit.oreny@gmail.com> added the comment: This issue has been resolved (thanks to @javadmokhtari and @nanjekyejoannah), but its Status is still "open" and the Resolution is blank... Members of Python triage team, please change the Status to "closed" and the Resolution to "fixed". Thank you! ---------- nosy: +HO _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40045> _______________________________________
Karthikeyan Singaravelan <tir.karthi@gmail.com> added the comment: Closing as fixed. Thanks Hilit. ---------- nosy: +xtreak resolution: -> fixed status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40045> _______________________________________
participants (7)
-
Hilit Oreny -
Javad Mokhtari Koushyar
-
Joannah Nanjekye
-
Karthikeyan Singaravelan
-
Kyle Stanley
-
miss-islington
-
Raymond Hettinger