[issue33832] Make "magic methods" a little more discoverable in the docs

[Fred L. Drake, Jr.]

Change by Fred L. Drake, Jr. :


--
nosy: +pablogsal

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue33832] Make "magic methods" a little more discoverable in the docs

[Fred L. Drake, Jr.]

Fred L. Drake, Jr.  added the comment:

Indeed, I did not.  Fixed now.  I hope.

--
nosy: +rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue33832] Make "magic methods" a little more discoverable in the docs

[Terry J. Reedy]

Terry J. Reedy  added the comment:

Fred, did you intend to delete people from nosy?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue33832] Make "magic methods" a little more discoverable in the docs

[Andrés Delfino]

Andrés Delfino  added the comment:

Sorry, for some reason the PR doesn't show the intended changes. I'm working on 
fixing it.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue33832] Make "magic methods" a little more discoverable in the docs

[Andrés Delfino]

Andrés Delfino  added the comment:

For context, I opened this issue after Raymond's reasoning in #33825 (which I 
agreed with).

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue33832] Make "magic methods" a little more discoverable in the docs

[Andrés Delfino]

Andrés Delfino  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue33832] Make "magic methods" a little more discoverable in the docs

[Pablo Galindo Salgado]

Pablo Galindo Salgado  added the comment:

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

--
nosy: +pablogsal

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue33832] Make "magic methods" a little more discoverable in the docs

[Fred L. Drake, Jr.]

Fred L. Drake, Jr.  added the comment:

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.

--
nosy: +fdrake -pablogsal, rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue33832] Make "magic methods" a little more discoverable in the docs

[Serhiy Storchaka]

Change by Serhiy Storchaka :


--
nosy: +rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue33832] Make "magic methods" a little more discoverable in the docs

[Andrés Delfino]

Andrés Delfino  added the comment:

I'll update the PR so that it shows what the original intention was.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue33832] Make "magic methods" a little more discoverable in the docs

[Andrés Delfino]

Andrés Delfino  added the comment:

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".

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue33832] Make "magic methods" a little more discoverable in the docs

[Terry J. Reedy]

Terry J. Reedy  added the comment:

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.

--
nosy: +terry.reedy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue33832] Make "magic methods" a little more discoverable in the docs

[Andrés Delfino]

Change by Andrés Delfino :


--
keywords: +patch
pull_requests: +7249
stage:  -> patch review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue33832] Make "magic methods" a little more discoverable in the docs

[Andrés Delfino]

New submission from Andrés Delfino :

PR adds "magic method" to the glossary, and adds a mention in Data Model 3.3. 
Special method names.

--
assignee: docs@python
components: Documentation
messages: 319300
nosy: adelfino, docs@python
priority: normal
severity: normal
status: open
title: Make "magic methods" a little more discoverable in the docs
type: enhancement
versions: Python 2.7, Python 3.6, Python 3.7, Python 3.8

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com