This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Misleading documentation for __prepare__
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.9, Python 3.8, Python 3.7
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: JelleZijlstra, William.Schwartz, alclarks, benedwards14, berker.peksag, brandtbucher, daniel.urban, docs@python, eric.araujo, jaysinh.shukla, ncoghlan
Priority: normal Keywords: easy, patch

Created on 2012-07-03 15:08 by William.Schwartz, last changed 2022-04-11 14:57 by admin. This issue is now closed.

File name Uploaded Description Edit William.Schwartz, 2012-07-03 15:30 Test to demonstrate implicit staticmethodness of __prepare__
issue15243_diff_python3.5_3.6_v1.diff jaysinh.shukla, 2016-06-17 11:04 review
Pull Requests
URL Status Linked Edit
PR 17124 merged alclarks, 2019-11-12 14:59
PR 18185 merged miss-islington, 2020-01-25 18:50
PR 18186 merged miss-islington, 2020-01-25 18:50
Messages (13)
msg164606 - (view) Author: William Schwartz (William.Schwartz) * Date: 2012-07-03 15:08
Section "Preparing the class namespace" of the documentation ( 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.
msg164607 - (view) Author: William Schwartz (William.Schwartz) * Date: 2012-07-03 15:30
Attached a unittest script to demonstrate that __prepare__ is implicitly a staticmethod.
msg164685 - (view) Author: Daniel Urban (daniel.urban) * (Python triager) Date: 2012-07-05 16:47
__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.
msg164696 - (view) Author: William Schwartz (William.Schwartz) * Date: 2012-07-05 19:59
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/ to make it part of the narrative of the doctests.
msg164697 - (view) Author: Daniel Urban (daniel.urban) * (Python triager) Date: 2012-07-05 20:52
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.
msg221871 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-06-29 18:08
Does the documentation need amending, yes or no?
msg267459 - (view) Author: Jelle Zijlstra (JelleZijlstra) * (Python committer) Date: 2016-06-05 19:00
I think the current documentation is correct and doesn't need changes. There is also already an example of a working __prepare__ method.
msg268356 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-06-12 09:51
The documentation should mention that the __prepare__ method must be implemented as a classmethod (see msg164697 for the reference.)

The example at needs to be linked from the "Preparing the class namespace" section.
msg268719 - (view) Author: Jaysinh shukla (jaysinh.shukla) * Date: 2016-06-17 11:04
Submitting patch according to this ( message. Thanks!
msg355470 - (view) Author: Benjamin Edwards (benedwards14) * Date: 2019-10-27 15:06
Is this still open, does the patch still need a pull request?
msg360697 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2020-01-25 18:50
New changeset 7de617455ed788e6730c40cf854c4b72b0432194 by Berker Peksag (alclarks) in branch 'master':
bpo-15243: Document __prepare__ as classmethod (GH-17124)
msg360698 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2020-01-25 19:04
New changeset 321491a536c378227f9d574703f7c06f89c67dcf by Berker Peksag (Miss Islington (bot)) in branch '3.8':
bpo-15243: Document __prepare__ as classmethod (GH-17124)
msg360699 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2020-01-25 19:04
New changeset 548685e364af3d366d3aef924b2077ee6f8d13dc by Berker Peksag (Miss Islington (bot)) in branch '3.7':
bpo-15243: Document __prepare__ as classmethod (GH-17124)
Date User Action Args
2022-04-11 14:57:32adminsetgithub: 59448
2020-01-25 19:05:38berker.peksagsetstatus: open -> closed
stage: patch review -> resolved
resolution: fixed
versions: + Python 3.7, Python 3.8, Python 3.9, - Python 3.5, Python 3.6
2020-01-25 19:04:59berker.peksagsetmessages: + msg360699
2020-01-25 19:04:20berker.peksagsetmessages: + msg360698
2020-01-25 18:50:19miss-islingtonsetpull_requests: + pull_request17569
2020-01-25 18:50:13miss-islingtonsetpull_requests: + pull_request17568
2020-01-25 18:50:03berker.peksagsetmessages: + msg360697
2019-11-12 15:04:07alclarkssetnosy: + alclarks
2019-11-12 14:59:58alclarkssetstage: needs patch -> patch review
pull_requests: + pull_request16632
2019-11-04 16:53:25brandtbuchersetnosy: + brandtbucher
2019-10-27 15:06:42benedwards14setnosy: + benedwards14
messages: + msg355470
2016-06-17 11:04:37jaysinh.shuklasetfiles: + issue15243_diff_python3.5_3.6_v1.diff

nosy: + jaysinh.shukla
messages: + msg268719

keywords: + patch
2016-06-12 09:51:54berker.peksagsetnosy: + berker.peksag
messages: + msg268356
2016-06-05 19:00:54JelleZijlstrasetnosy: + JelleZijlstra
messages: + msg267459
2016-06-03 08:54:58BreamoreBoysetnosy: - BreamoreBoy
2016-06-03 04:22:56berker.peksagsetkeywords: + easy
versions: + Python 3.6, - Python 3.4
2016-06-03 04:21:51berker.peksaglinkissue17352 superseder
2014-06-29 18:08:31BreamoreBoysetversions: + Python 3.4, Python 3.5, - Python 3.2, Python 3.3
nosy: + BreamoreBoy

messages: + msg221871

components: - Tests
2012-07-05 20:52:19daniel.urbansetmessages: + msg164697
2012-07-05 19:59:06William.Schwartzsetmessages: + msg164696
2012-07-05 16:47:07daniel.urbansetmessages: + msg164685
2012-07-05 16:35:52eric.araujosetnosy: + ncoghlan, eric.araujo
stage: needs patch

versions: + Python 3.2
2012-07-03 17:25:37daniel.urbansetnosy: + daniel.urban
2012-07-03 15:30:12William.Schwartzsetfiles: +

messages: + msg164607
2012-07-03 15:08:37William.Schwartzcreate