bpo-30354: DOC: Update data model documentation to super() #1561
Conversation
|
@csabella, thanks for your PR! By analyzing the history of the files in this pull request, we identified @birkenfeld, @ncoghlan and @1st1 to be potential reviewers. |
csabella
changed the title
There was a problem hiding this comment.
One simple change request, where the switch to zero-arg super means the explicit self arg is no longer needed.
However, as far as I can tell, the current description of super binding in the descriptor section is just plain wrong - I can't see any interpretation where it's a reasonable description of how that works.
Perhaps it would make sense to leave that particular paragraph out of this PR, and instead file a new issue requesting clarification of that paragraph?
Doc/reference/datamodel.rst
Outdated
| @@ -1145,7 +1145,7 @@ Basic customization | |||
| class constructor expression. If a base class has an :meth:`__init__` | |||
| method, the derived class's :meth:`__init__` method, if any, must explicitly | |||
| call it to ensure proper initialization of the base class part of the | |||
| instance; for example: ``BaseClass.__init__(self, [args...])``. | |||
| instance; for example: ``super().__init__(self, [args...])``. | |||
There was a problem hiding this comment.
The switch to zero-arg super here means the explicit self is no longer needed in the call (whereas __new__ is implicitly a static method, so it still needs the explicit cls arg)
There was a problem hiding this comment.
Thanks for explaining! That's why I was reading this section in the first -- to understand super(), new, and init. :-) Your explanation makes it clearer. I've made this change.
Doc/reference/datamodel.rst
Outdated
| @@ -1578,8 +1578,8 @@ Class Binding | |||
| ``A.__dict__['x'].__get__(None, A)``. | |||
|
|
|||
| Super Binding | |||
| If ``a`` is an instance of :class:`super`, then the binding ``super(B, | |||
| obj).m()`` searches ``obj.__class__.__mro__`` for the base class ``A`` | |||
| If ``a`` is an instance of :class:`super`, then the binding ``super().m()`` | |||
There was a problem hiding this comment.
This should keep the explicit 2-arg form, and then add a follow-up sentence reminding readers how that relates to the zero-arg form (i.e. it's implicitly super(__class__, <first parameter>) when inside a class definition).
However, to make it clearer what's going on, it's probably worth breaking it up as a = super(B, obj); a.x(), rather than assuming the reader will automatically realise that the super() call is defining a and that m here is equivalent to x in the preceding examples.
There was a problem hiding this comment.
I've restored the 'super binding' section to its previous form. I didn't add any other lines based on your comment that the whole description may need clarification.
Doc/reference/datamodel.rst
Outdated
| If ``a`` is an instance of :class:`super`, then the binding ``super(B, | ||
| obj).m()`` searches ``obj.__class__.__mro__`` for the base class ``A`` | ||
| If ``a`` is an instance of :class:`super`, then the binding ``super().m()`` | ||
| searches ``obj.__class__.__mro__`` for the base class ``A`` | ||
| immediately preceding ``B`` and then invokes the descriptor with the call: |
There was a problem hiding this comment.
Hmm, this doesn't sound right, as super() looks at the base classes following the given class, not preceding it. It also doesn't necessarily use the immediately following class in the MRO, but rather the first one that defines the attribute of interest.
|
@csabella Can you prepare the backport to 3.5 and 3.6? Thanks. |
…H-1561) The data model section of the language reference was written well before the zero-argument form of super() was added. To avoid giving the impression that they're doing something unusual, this updates the description of `__new__` and `__init__` to use the zero-argument form. Patch by Cheryl Sabella. (cherry picked from commit 12b1c18)
…H-1561) The data model section of the language reference was written well before the zero-argument form of super() was added. To avoid giving the impression that they're doing something unusual, this updates the description of `__new__` and `__init__` to use the zero-argument form. Patch by Cheryl Sabella. (cherry picked from commit 12b1c18)
…1869) The data model section of the language reference was written well before the zero-argument form of super() was added. To avoid giving the impression that they're doing something unusual, this updates the description of `__new__` and `__init__` to use the zero-argument form. Patch by Cheryl Sabella. (cherry picked from commit 12b1c18)
…1868) The data model section of the language reference was written well before the zero-argument form of super() was added. To avoid giving the impression that they're doing something unusual, this updates the description of `__new__` and `__init__` to use the zero-argument form. Patch by Cheryl Sabella. (cherry picked from commit 12b1c18)
Update data model documentation to reflect the zero-argument form of super().