[issue15243] Misleading documentation for __prepare__
New submission from William Schwartz <wkschwartz@gmail.com>: Section 3.3.3.2. "Preparing the class namespace" of the documentation (http://docs.python.org/dev/reference/datamodel.html#preparing-the-class-name...) 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. ---------- assignee: docs@python components: Documentation, Tests messages: 164606 nosy: William.Schwartz, docs@python priority: normal severity: normal status: open title: Misleading documentation for __prepare__ type: behavior versions: Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15243> _______________________________________
William Schwartz <wkschwartz@gmail.com> added the comment: Attached a unittest script to demonstrate that __prepare__ is implicitly a staticmethod. ---------- Added file: http://bugs.python.org/file26245/test_metaclass.py _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15243> _______________________________________
Changes by Daniel Urban <urban.dani+py@gmail.com>: ---------- nosy: +daniel.urban _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15243> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- nosy: +eric.araujo, ncoghlan stage: -> needs patch versions: +Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15243> _______________________________________
Daniel Urban <urban.dani+py@gmail.com> added the comment: __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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15243> _______________________________________
William Schwartz <wkschwartz@gmail.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15243> _______________________________________
Daniel Urban <urban.dani+py@gmail.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15243> _______________________________________
Mark Lawrence added the comment: Does the documentation need amending, yes or no? ---------- components: -Tests nosy: +BreamoreBoy versions: +Python 3.4, Python 3.5 -Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15243> _______________________________________
Changes by Berker Peksag <berker.peksag@gmail.com>: ---------- keywords: +easy versions: +Python 3.6 -Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15243> _______________________________________
Changes by Mark Lawrence <breamoreboy@yahoo.co.uk>: ---------- nosy: -BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15243> _______________________________________
Jelle Zijlstra added the comment: I think the current documentation is correct and doesn't need changes. There is also already an example of a working __prepare__ method. ---------- nosy: +Jelle Zijlstra _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15243> _______________________________________
Berker Peksag added the comment: 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. ---------- nosy: +berker.peksag _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15243> _______________________________________
Jaysinh shukla added the comment: Submitting patch according to this (http://bugs.python.org/issue15243#msg268356) message. Thanks! ---------- keywords: +patch nosy: +jaysinh.shukla Added file: http://bugs.python.org/file43432/issue15243_diff_python3.5_3.6_v1.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15243> _______________________________________
Benjamin Edwards <benjaminedwards@live.co.uk> added the comment: Is this still open, does the patch still need a pull request? ---------- nosy: +benedwards14 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue15243> _______________________________________
Change by Brandt Bucher <brandtbucher@gmail.com>: ---------- nosy: +brandtbucher _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue15243> _______________________________________
Change by Alex <alexpclarkson@gmail.com>: ---------- pull_requests: +16632 stage: needs patch -> patch review pull_request: https://github.com/python/cpython/pull/17124 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue15243> _______________________________________
Change by Alex <alexpclarkson@gmail.com>: ---------- nosy: +alclarks _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue15243> _______________________________________
Berker Peksag <berker.peksag@gmail.com> added the comment: New changeset 7de617455ed788e6730c40cf854c4b72b0432194 by Berker Peksag (alclarks) in branch 'master': bpo-15243: Document __prepare__ as classmethod (GH-17124) https://github.com/python/cpython/commit/7de617455ed788e6730c40cf854c4b72b04... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue15243> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +17568 pull_request: https://github.com/python/cpython/pull/18185 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue15243> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +17569 pull_request: https://github.com/python/cpython/pull/18186 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue15243> _______________________________________
Berker Peksag <berker.peksag@gmail.com> added the comment: New changeset 321491a536c378227f9d574703f7c06f89c67dcf by Berker Peksag (Miss Islington (bot)) in branch '3.8': bpo-15243: Document __prepare__ as classmethod (GH-17124) https://github.com/python/cpython/commit/321491a536c378227f9d574703f7c06f89c... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue15243> _______________________________________
Berker Peksag <berker.peksag@gmail.com> added the comment: New changeset 548685e364af3d366d3aef924b2077ee6f8d13dc by Berker Peksag (Miss Islington (bot)) in branch '3.7': bpo-15243: Document __prepare__ as classmethod (GH-17124) https://github.com/python/cpython/commit/548685e364af3d366d3aef924b2077ee6f8... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue15243> _______________________________________
Change by Berker Peksag <berker.peksag@gmail.com>: ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed versions: +Python 3.7, Python 3.8, Python 3.9 -Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue15243> _______________________________________
participants (11)
-
Alex -
Benjamin Edwards
-
Berker Peksag
-
Brandt Bucher
-
Daniel Urban
-
Jaysinh shukla
-
Jelle Zijlstra
-
Mark Lawrence
-
miss-islington
-
William Schwartz
-
Éric Araujo