classification
Title: update docs: when creating classes a new dict is created for the final class object
Type: Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.4, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, emilyemorehouse, ethan.furman, python-dev, r.david.murray
Priority: normal Keywords: patch

Created on 2016-04-22 14:03 by ethan.furman, last changed 2016-06-03 00:07 by r.david.murray. This issue is now closed.

Files
File name Uploaded Description Edit
26829.patch emilyemorehouse, 2016-06-02 19:20 review
26829-v2.patch emilyemorehouse, 2016-06-02 22:11 review
26829-v3.patch emilyemorehouse, 2016-06-02 23:42 review
Messages (8)
msg264016 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2016-04-22 14:03
https://docs.python.org/3/reference/datamodel.html#creating-the-class-object

This section should mention that the final class is created with a new dict(), and all key/value pairs from the dict used during creation are copied over.
msg266925 - (view) Author: Emily Morehouse (emilyemorehouse) * (Python committer) Date: 2016-06-02 19:20
Super straight-forward -- this simply adds to the docs on creating the class object that the values used in creation are copied to the final object (including the namespace).
msg266940 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-06-02 20:10
Your suggested wording isn't correct, I'm afraid.  This subject is complex and somewhat obscure...I checked with Ethan to make sure my interpretation was correct.  The problem this issue is addressing is the fact that when type.__new__ is called (as in the metaclass example), whatever is passed in as the namespace has its *contents* copied into a new, standard python dict, and the original namespace object is discarded.  The metaclass example does this explicitly (by doing dict(namespace), but in fact type.__new__ does it implicitly (which IMO makes that example a bit confusing).

Also, that namespace is the only state.  The metaclass example obscures that by doing an attribute assignment after calling type.__new__, but that attribute assignment is actually updating the __dict__ of the new object ('result'), which is that new python dict containing the contents of namespace.
msg266973 - (view) Author: Emily Morehouse (emilyemorehouse) * (Python committer) Date: 2016-06-02 22:11
Second version of patch for this -- more clearly states the process and outcome for class creation. Also adds to https://docs.python.org/3.6/library/functions.html#type to clarify that the dictionary object is copied to a standard dict.
msg266987 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-06-02 23:29
I can't get the rietveld review tool to work from this network, so I'll do this in a comment.  This looks pretty good to me, but in the following:

  +It is important to note that during the creation of the class, a copy of the
  +namespace object is used in the final class object and the original namespace
  +object is discarded. More explicitly, this means that when ``type.__new__`` is
  +called, the object provided as the namespace parameter has its contents copied
  +to a standard Python dictionary.

I think it is more in keeping with the style of the rest of the doc to boil this down as much as possible.  We can drop the "It is important to note that", and just state the issue once, using the "more explicit" version.  I think borrowing your revised language from the type docs would work well here, by adding "which becomes the __dict__ of the class object" to the end of that sentence.
msg266992 - (view) Author: Emily Morehouse (emilyemorehouse) * (Python committer) Date: 2016-06-02 23:42
Trimmed down by keeping the more explicit explanation and taking into account suggestions.
msg266997 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-06-03 00:06
New changeset 754118f8b3ce by R David Murray in branch '3.5':
#26829: Clarify that namespace is copied to a new __dict__ in instance creation.
https://hg.python.org/cpython/rev/754118f8b3ce

New changeset 5a4ace14b350 by R David Murray in branch 'default':
Merge: #26829: Clarify that namespace is copied to a new __dict__ in instance creation.
https://hg.python.org/cpython/rev/5a4ace14b350
msg266998 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-06-03 00:07
Thanks, Emily.
History
Date User Action Args
2016-06-03 00:07:51r.david.murraysetstatus: open -> closed
resolution: fixed
messages: + msg266998

stage: resolved
2016-06-03 00:06:33python-devsetnosy: + python-dev
messages: + msg266997
2016-06-02 23:42:54emilyemorehousesetfiles: + 26829-v3.patch

messages: + msg266992
2016-06-02 23:29:38r.david.murraysetmessages: + msg266987
2016-06-02 22:11:39emilyemorehousesetfiles: + 26829-v2.patch

messages: + msg266973
2016-06-02 20:10:21r.david.murraysetnosy: + r.david.murray
messages: + msg266940
2016-06-02 19:20:18emilyemorehousesetfiles: + 26829.patch

nosy: + emilyemorehouse
messages: + msg266925

keywords: + patch
2016-04-22 14:03:54ethan.furmancreate