classification
Title: doc Add "magic method" entry to Glossary
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: adelfino, docs@python, eric.araujo, fdrake, miss-islington, pablogsal, rhettinger, terry.reedy
Priority: normal Keywords: patch

Created on 2018-06-11 11:56 by adelfino, last changed 2019-03-27 06:44 by terry.reedy. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 7630 merged adelfino, 2018-06-11 11:57
PR 12574 merged miss-islington, 2019-03-27 01:21
PR 12575 merged miss-islington, 2019-03-27 01:21
Messages (16)
msg319300 - (view) Author: Andrés Delfino (adelfino) * (Python triager) Date: 2018-06-11 11:56
PR adds "magic method" to the glossary, and adds a mention in Data Model 3.3. Special method names.
msg319631 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-06-15 17:50
It is unclear what problem this issue is meant to serve.  If the reference manual uses 'magic method', I think it should be changed.  Special method names are obvious by their form and need not and should not be labelled.  I think doc policy issues should be discussed on pydev or python-ideas lists.
msg319634 - (view) Author: Andrés Delfino (adelfino) * (Python triager) Date: 2018-06-15 18:12
The original intention of the PR, as shown in this issue, was to add "magic method" in the Glossary as a synonym for "special method", and add "magic method" in Data model (so that people reading Data Model would understand what a "magic method" is).

Then I was requested some changes, and stated I wasn't sure about them.

I don't believe special methods should be explicitly declared in each mention.

The "problem" this PR intended to "solve" was to let people know what a "magic method" is, because as I see it, it has become pretty standard to use "special method" with no indication that it is a synonym of "magic method".
msg319635 - (view) Author: Andrés Delfino (adelfino) * (Python triager) Date: 2018-06-15 18:13
I'll update the PR so that it shows what the original intention was.
msg319638 - (view) Author: Pablo Galindo Salgado (pablogsal) * (Python committer) Date: 2018-06-15 18:28
Just for clarification. My question in the PR was:

>I think these are not the only occurrences of method referring to a 
>magic method. A quick grep reveals that there are more places where the 
>construction the __something__ method happens. Should we change these 
> too to __something__ special method?

This is because I was not sure if the intention of the PR was changing these everywhere or not. Sorry
if that was interpreted as a change request. :S
msg319639 - (view) Author: Fred Drake (fdrake) (Python committer) Date: 2018-06-15 18:34
A quick grep on the 3.7 branch indicates that the standard documentation includes each of the terms "magic method" and "special method" about the same number of times.  (I didn't check for instances that wrapped lines.)

Perhaps we should decide on just one of these terms and fix references that use the other.  I agree this can be a source of confusion, but having two terms for the same concept is a bug.

I don't think we need to change references to "the __something__ method", because those are specific.  We only need to decide on and consistently use the categorical term for these methods when referring to the entire category.
msg319640 - (view) Author: Andrés Delfino (adelfino) * (Python triager) Date: 2018-06-15 18:40
Terry:
I have updated the PR with the original intention. You'll see it is much simpler.

Pablo:
Don't worry! I take it as a mistake of my own.

Fred:
I believe synonyms aren't the best things to have, but, if used consistently, they don't pose a real problem. Plus, they are so common, that most probably "magic" will reappear.
msg319642 - (view) Author: Andrés Delfino (adelfino) * (Python triager) Date: 2018-06-15 18:43
For context, I opened this issue after Raymond's reasoning in #33825 (which I agreed with).
msg319644 - (view) Author: Andrés Delfino (adelfino) * (Python triager) Date: 2018-06-15 18:46
Sorry, for some reason the PR doesn't show the intended changes. I'm working on fixing it.
msg319649 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-06-15 19:11
Fred, did you intend to delete people from nosy?
msg319655 - (view) Author: Fred Drake (fdrake) (Python committer) Date: 2018-06-15 19:30
Indeed, I did not.  Fixed now.  I hope.
msg338931 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2019-03-27 01:21
New changeset f760610bddd7e8f8ac0914d5d59ef806bc16a73b by Éric Araujo (Andre Delfino) in branch 'master':
bpo-33832: Add "magic method" glossary entry (GH-7630)
https://github.com/python/cpython/commit/f760610bddd7e8f8ac0914d5d59ef806bc16a73b
msg338932 - (view) Author: miss-islington (miss-islington) Date: 2019-03-27 01:26
New changeset 6cbb4c0795099b79f0a7c7d20df4ba1c1ec0ac24 by Miss Islington (bot) in branch '2.7':
bpo-33832: Add "magic method" glossary entry (GH-7630)
https://github.com/python/cpython/commit/6cbb4c0795099b79f0a7c7d20df4ba1c1ec0ac24
msg338933 - (view) Author: miss-islington (miss-islington) Date: 2019-03-27 01:26
New changeset ead15795986972690217e52087eb946b8a5bbcda by Miss Islington (bot) in branch '3.7':
bpo-33832: Add "magic method" glossary entry (GH-7630)
https://github.com/python/cpython/commit/ead15795986972690217e52087eb946b8a5bbcda
msg338935 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2019-03-27 02:01
Thanks for the patch!
msg338942 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-03-27 06:44
Several hours ago, I read the unittest.mock doc, which uses 'magic methods' to explain MagicMock.  So I decided an entry really was needed.  Andrés, thanks for sticking with this,
History
Date User Action Args
2019-03-27 06:44:35terry.reedysetmessages: + msg338942
versions: - Python 3.6
2019-03-27 02:01:57eric.araujosetstatus: open -> closed
resolution: fixed
messages: + msg338935

stage: patch review -> resolved
2019-03-27 01:26:54miss-islingtonsetmessages: + msg338933
2019-03-27 01:26:17miss-islingtonsetnosy: + miss-islington
messages: + msg338932
2019-03-27 01:21:49miss-islingtonsetpull_requests: + pull_request12519
2019-03-27 01:21:39miss-islingtonsetpull_requests: + pull_request12518
2019-03-27 01:21:30eric.araujosetnosy: + eric.araujo
messages: + msg338931
2018-06-18 11:34:12adelfinosettitle: Make "magic methods" a little more discoverable in the docs -> doc Add "magic method" entry to Glossary
2018-06-15 19:34:34fdrakesetnosy: + pablogsal
2018-06-15 19:30:56fdrakesetnosy: + rhettinger
messages: + msg319655
2018-06-15 19:11:48terry.reedysetmessages: + msg319649
2018-06-15 18:46:11adelfinosetmessages: + msg319644
2018-06-15 18:43:48adelfinosetmessages: + msg319642
2018-06-15 18:40:40adelfinosetmessages: + msg319640
2018-06-15 18:34:17fdrakesetnosy: + fdrake, - rhettinger, pablogsal
messages: + msg319639
2018-06-15 18:30:51serhiy.storchakasetnosy: + rhettinger
2018-06-15 18:28:17pablogsalsetnosy: + pablogsal
messages: + msg319638
2018-06-15 18:13:26adelfinosetmessages: + msg319635
2018-06-15 18:12:57adelfinosetmessages: + msg319634
2018-06-15 17:50:07terry.reedysetnosy: + terry.reedy
messages: + msg319631
2018-06-11 11:57:36adelfinosetkeywords: + patch
stage: patch review
pull_requests: + pull_request7249
2018-06-11 11:56:31adelfinocreate