classification
Title: Misleading documentation for __prepare__
Type: behavior Stage: needs patch
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Jelle Zijlstra, William.Schwartz, berker.peksag, 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 2016-06-17 11:04 by jaysinh.shukla.

Files
File name Uploaded Description Edit
test_metaclass.py 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
Messages (9)
msg164606 - (view) Author: William Schwartz (William.Schwartz) Date: 2012-07-03 15:08
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.
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/test_metaclass.py 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 (Jelle Zijlstra) * (Python triager) 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 https://docs.python.org/dev/reference/datamodel.html#metaclass-example 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 (http://bugs.python.org/issue15243#msg268356) message. Thanks!
History
Date User Action Args
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:54Jelle Zijlstrasetnosy: + Jelle Zijlstra
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: + test_metaclass.py

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