Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc Add "magic method" entry to Glossary #78013

Closed
andresdelfino opened this issue Jun 11, 2018 · 16 comments
Closed

doc Add "magic method" entry to Glossary #78013

andresdelfino opened this issue Jun 11, 2018 · 16 comments
Labels
3.7 (EOL) end of life 3.8 only security fixes docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@andresdelfino
Copy link
Contributor

BPO 33832
Nosy @freddrake, @rhettinger, @terryjreedy, @merwok, @pablogsal, @andresdelfino, @miss-islington
PRs
  • bpo-33832: Add "magic method" entry to Glossary #7630
  • [3.7] bpo-33832: Add "magic method" glossary entry (GH-7630) #12574
  • [2.7] bpo-33832: Add "magic method" glossary entry (GH-7630) #12575
    		•

    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 = None
closed_at = <Date 2019-03-27.02:01:57.612>
created_at = <Date 2018-06-11.11:56:31.610>
labels = ['3.8', 'type-feature', '3.7', 'docs']
title = 'doc Add "magic method" entry to Glossary'
updated_at = <Date 2019-03-27.06:44:35.448>
user = 'https://github.com/andresdelfino'

    bugs.python.org fields:

    activity = <Date 2019-03-27.06:44:35.448>
actor = 'terry.reedy'
assignee = 'docs@python'
closed = True
closed_date = <Date 2019-03-27.02:01:57.612>
closer = 'eric.araujo'
components = ['Documentation']
creation = <Date 2018-06-11.11:56:31.610>
creator = 'adelfino'
dependencies = []
files = []
hgrepos = []
issue_num = 33832
keywords = ['patch']
message_count = 16.0
messages = ['319300', '319631', '319634', '319635', '319638', '319639', '319640', '319642', '319644', '319649', '319655', '338931', '338932', '338933', '338935', '338942']
nosy_count = 8.0
nosy_names = ['fdrake', 'rhettinger', 'terry.reedy', 'eric.araujo', 'docs@python', 'pablogsal', 'adelfino', 'miss-islington']
pr_nums = ['7630', '12574', '12575']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue33832'
versions = ['Python 2.7', 'Python 3.7', 'Python 3.8']
    @andresdelfino
    Copy link
    Contributor Author

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

    @andresdelfino andresdelfino added 3.8 only security fixes 3.7 (EOL) end of life labels Jun 11, 2018
    @andresdelfino andresdelfino added docs Documentation in the Doc dir type-feature A feature request or enhancement labels Jun 11, 2018
    @terryjreedy
    Copy link
    Member

    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.

    @andresdelfino
    Copy link
    Contributor Author

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

    @andresdelfino
    Copy link
    Contributor Author

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

    @pablogsal
    Copy link
    Member

    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

    @freddrake
    Copy link
    Member

    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.

    @andresdelfino
    Copy link
    Contributor Author

    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.

    @andresdelfino
    Copy link
    Contributor Author

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

    @andresdelfino
    Copy link
    Contributor Author

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

    @terryjreedy
    Copy link
    Member

    Fred, did you intend to delete people from nosy?

    @freddrake
    Copy link
    Member

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

    @andresdelfino andresdelfino changed the title Make "magic methods" a little more discoverable in the docs doc Add "magic method" entry to Glossary Jun 18, 2018
    @merwok
    Copy link
    Member

    merwok commented Mar 27, 2019

    New changeset f760610 by Éric Araujo (Andre Delfino) in branch 'master':
    bpo-33832: Add "magic method" glossary entry (GH-7630)
    f760610

    @miss-islington
    Copy link
    Contributor

    New changeset 6cbb4c0 by Miss Islington (bot) in branch '2.7':
    bpo-33832: Add "magic method" glossary entry (GH-7630)
    6cbb4c0

    @miss-islington
    Copy link
    Contributor

    New changeset ead1579 by Miss Islington (bot) in branch '3.7':
    bpo-33832: Add "magic method" glossary entry (GH-7630)
    ead1579

    @merwok
    Copy link
    Member

    merwok commented Mar 27, 2019

    Thanks for the patch!

    @merwok merwok closed this as completed Mar 27, 2019
    @terryjreedy
    Copy link
    Member

    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,

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    3.7 (EOL) end of life 3.8 only security fixes docs Documentation in the Doc dir type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    6 participants
    @freddrake @merwok @pablogsal @terryjreedy @miss-islington @andresdelfino