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

Misleading documentation for __prepare__ #59448

Closed
wkschwartz mannequin opened this issue Jul 3, 2012 · 13 comments
Closed

Misleading documentation for __prepare__ #59448

wkschwartz mannequin opened this issue Jul 3, 2012 · 13 comments
Labels
3.7 (EOL) end of life 3.8 only security fixes 3.9 only security fixes docs Documentation in the Doc dir easy type-bug An unexpected behavior, bug, or error

Comments

@wkschwartz
Copy link
Mannequin

wkschwartz mannequin commented Jul 3, 2012

BPO 15243
Nosy @ncoghlan, @merwok, @durban, @berkerpeksag, @wkschwartz, @JelleZijlstra, @ultimatecoder, @brandtbucher, @benedwards14, @alclarks
PRs
  • bpo-15243: Specify __prepare__ should be a classmethod #17124
  • [3.8] bpo-15243: Document __prepare__ as classmethod (GH-17124) #18185
  • [3.7] bpo-15243: Document __prepare__ as classmethod (GH-17124) #18186
    		•
    Files
  • test_metaclass.py: Test to demonstrate implicit staticmethodness of prepare
  • issue15243_diff_python3.5_3.6_v1.diff
    		•

    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 2020-01-25.19:05:38.747>
created_at = <Date 2012-07-03.15:08:37.739>
labels = ['easy', 'type-bug', '3.8', '3.9', '3.7', 'docs']
title = 'Misleading documentation for __prepare__'
updated_at = <Date 2020-01-25.19:05:38.746>
user = 'https://github.com/wkschwartz'

    bugs.python.org fields:

    activity = <Date 2020-01-25.19:05:38.746>
actor = 'berker.peksag'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-01-25.19:05:38.747>
closer = 'berker.peksag'
components = ['Documentation']
creation = <Date 2012-07-03.15:08:37.739>
creator = 'William.Schwartz'
dependencies = []
files = ['26245', '43432']
hgrepos = []
issue_num = 15243
keywords = ['patch', 'easy']
message_count = 13.0
messages = ['164606', '164607', '164685', '164696', '164697', '221871', '267459', '268356', '268719', '355470', '360697', '360698', '360699']
nosy_count = 11.0
nosy_names = ['ncoghlan', 'eric.araujo', 'daniel.urban', 'docs@python', 'berker.peksag', 'William.Schwartz', 'JelleZijlstra', 'jaysinh.shukla', 'brandtbucher', 'benedwards14', 'alclarks']
pr_nums = ['17124', '18185', '18186']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue15243'
versions = ['Python 3.7', 'Python 3.8', 'Python 3.9']
    @wkschwartz
    Copy link
    Mannequin Author

    wkschwartz mannequin commented Jul 3, 2012

    Section 3.3.3.2. "Preparing the class namespace" of the documentation (http://docs.python.org/dev/reference/datamodel.html#preparing-the-class-namespace) states that "If the metaclass has a prepare attribute, it is called as namespace = metaclass.__prepare__(name, bases, **kwds)...." This isn't quite true. By just defining a __prepare__ method in a metaclass, the interpreter calls it as it would a static method -- there is no implicit first argument referring to metaclass as the documentation implies. The documentation should be amended to say that users can decorate __prepare__ as a class method to get metaclass passed in as the implicit first argument.

    @wkschwartz wkschwartz mannequin added the tests Tests in the Lib/test dir label Jul 3, 2012
    @wkschwartz wkschwartz mannequin assigned docspython Jul 3, 2012
    @wkschwartz wkschwartz mannequin added docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error labels Jul 3, 2012
    @wkschwartz
    Copy link
    Mannequin Author

    wkschwartz mannequin commented Jul 3, 2012

    Attached a unittest script to demonstrate that __prepare__ is implicitly a staticmethod.

    @durban
    Copy link
    Mannequin

    durban mannequin commented Jul 5, 2012

    __prepare__ is not implicitly a staticmethod, and it is called exactly as documented (also in types.prepare_class). There is no implicit first argument because the method is called on the (meta)class object.

    @wkschwartz
    Copy link
    Mannequin Author

    wkschwartz mannequin commented Jul 5, 2012

    Daniel, Good point. However it would still be useful for documentation to point out that __prepare__ can be passed the metaclass as the implicit first argument by being decorated by classmethod.

    I'll post a small patch when I get a chance to add a sentence saying as much in the documentation and reorganize the test cases in Lib/test/test_metaclass.py to make it part of the narrative of the doctests.

    @durban
    Copy link
    Mannequin

    durban mannequin commented Jul 5, 2012

    Actually the docs contained a similar sentence ("If the metaclass has a :meth:`__prepare__` attribute (usually implemented as a class or static method), ..."), but it was removed in befd56673c80 when Nick rewrote this section.

    @BreamoreBoy
    Copy link
    Mannequin

    BreamoreBoy mannequin commented Jun 29, 2014

    Does the documentation need amending, yes or no?

    @BreamoreBoy BreamoreBoy mannequin removed the tests Tests in the Lib/test dir label Jun 29, 2014
    @JelleZijlstra
    Copy link
    Member

    I think the current documentation is correct and doesn't need changes. There is also already an example of a working __prepare__ method.

    @berkerpeksag
    Copy link
    Member

    The documentation should mention that the __prepare__ method must be implemented as a classmethod (see msg164697 for the reference.)

    The example at https://docs.python.org/dev/reference/datamodel.html#metaclass-example needs to be linked from the "Preparing the class namespace" section.

    @ultimatecoder
    Copy link
    Mannequin

    ultimatecoder mannequin commented Jun 17, 2016

    Submitting patch according to this (http://bugs.python.org/issue15243#msg268356) message. Thanks!

    @benedwards14
    Copy link
    Mannequin

    benedwards14 mannequin commented Oct 27, 2019

    Is this still open, does the patch still need a pull request?

    @berkerpeksag
    Copy link
    Member

    New changeset 7de6174 by Berker Peksag (alclarks) in branch 'master':
    bpo-15243: Document __prepare__ as classmethod (GH-17124)
    7de6174

    @berkerpeksag
    Copy link
    Member

    New changeset 321491a by Berker Peksag (Miss Islington (bot)) in branch '3.8':
    bpo-15243: Document __prepare__ as classmethod (GH-17124)
    321491a

    @berkerpeksag
    Copy link
    Member

    New changeset 548685e by Berker Peksag (Miss Islington (bot)) in branch '3.7':
    bpo-15243: Document __prepare__ as classmethod (GH-17124)
    548685e

    @berkerpeksag berkerpeksag added 3.7 (EOL) end of life 3.8 only security fixes 3.9 only security fixes labels Jan 25, 2020
    @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 3.9 only security fixes docs Documentation in the Doc dir easy type-bug An unexpected behavior, bug, or error
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    2 participants
    @berkerpeksag @JelleZijlstra