Steven D'Aprano <steve+python@pearwood.info> added the comment: The docs do say what super does: it returns "a proxy object that delegates method calls to a parent or sibling class of type", just as you quoted. That concise description is (almost) completely accurate and precise. (I say *almost* because it's not just method calls that it works with, but any attribute lookup.) What more do you want? That's not a rhetorical question. I'm not saying that the docs are perfect or cannot be improved, but they look pretty good to me: they tell you what super does, they tell you why you might use it, and show how to use it. What's missing? (Again, not a rhetorical question.) I understand that super is a very advanced corner of the language: there's a lot of necessary technical jargon in the docs: - One already needs to have a good understanding of what super *does* in order to make sense of the sentence describing what it *is*, so there's an element of circular reasoning needed. - The reader needs to understand that super isn't magical, it just returns an object like any other function, and understand what "proxy object" means, as well as delegation. - And have an understanding of how inheritance and the MRO work in Python, and the difference between bound and unbound methods/proxies. But to the experienced reader who knows these concepts, I'm having a hard time seeing what you believe is missing from the docs. Perhaps there ought to be a "gentle guide to super" somewhere, and the docs could link to that? ---------- nosy: +steven.daprano _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37176> _______________________________________

Steven D'Aprano <steve+python@pearwood.info> added the comment: The docs do say what super does: it returns "a proxy object that delegates method calls to a parent or sibling class of type", just as you quoted. That concise description is (almost) completely accurate and precise. (I say *almost* because it's not just method calls that it works with, but any attribute lookup.) What more do you want? That's not a rhetorical question. I'm not saying that the docs are perfect or cannot be improved, but they look pretty good to me: they tell you what super does, they tell you why you might use it, and show how to use it. What's missing? Again, not a rhetorical question. I understand that super is a very advanced corner of the language: there's a lot of necessary technical jargon in the docs, e.g.: - One already needs to have a good understanding of what super *does* in order to make sense of the sentence describing what it *is*, so there's an element of circular reasoning needed. - The reader needs to understand that super isn't magical, it just returns an object like any other function, and understand what "proxy object" means, as well as delegation. - And have an understanding of how inheritance and the MRO work in Python, and the difference between bound and unbound methods/proxies. I think that to the experienced reader who knows these concepts, the docs should be pretty clear and complete. I'm having a hard time seeing what you believe is missing from the docs. Can you explain further? Perhaps there ought to be a "gentle guide to super" somewhere, and the docs could link to that? ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37176> _______________________________________

Jeroen Demeyer <J.Demeyer@UGent.be> added the comment:

What more do you want?

Mainly: it says "a parent or sibling class of *type*" but it doesn't explain which class it actually uses. And the sentence "The __mro__ attribute of the type lists the method resolution search order used by both getattr() and super()" is even wrong or at least confusing: what matters is not the MRO of the type (the first argument to super()) but the MRO of the object (the second argument to super()). The zero-argument form super() is not explained at all.

Perhaps there ought to be a "gentle guide to super" somewhere, and the docs could link to that?

There are plenty of guides like that and in fact that docs already link to https://rhettinger.wordpress.com/2011/05/26/super-considered-super/ ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37176> _______________________________________

Jeroen Demeyer <J.Demeyer@UGent.be> added the comment:

Only one of the two arguments is called "type". The other is called "object-or-type".

I'm having problems with the first word of "a parent or sibling class of type". The most important part of super() is to *which* class that attribute lookups are delegated to and this is not explained.

The __mro__ attribute is on the type, not the instance:

Sorry for that. I meant to say: And the sentence "The __mro__ attribute of the type lists the method resolution search order used by both getattr() and super()" is even wrong or at least confusing: what matters is not the MRO of the type (the first argument to super()) but the MRO of ***the type of*** the object (the second argument to super()).

Yes it is. Look at the example given:

An example is not an explanation. But it's true, this is the least of my problems with this doc. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37176> _______________________________________

Steven D'Aprano <steve+python@pearwood.info> added the comment: On Fri, Jun 07, 2019 at 09:57:11AM +0000, Jeroen Demeyer wrote:

I'm having problems with the first word of "a parent or sibling class of type".

The first word is "a". Did you mean something else or did you mean it literally? If the second case, we have to talk about *a* parent class rather than *the* parent class, since Python supports multiple inheritance and a class can have more than one parent class.

The most important part of super() is to *which* class that attribute lookups are delegated to and this is not explained.

Lookups are delegated to a parent or sibling class, exactly as the documentation says. Which class that is (whether a parent or sibling) can only be determined at runtime.

And the sentence "The __mro__ attribute of the type lists the method resolution search order used by both getattr() and super()" is even wrong or at least confusing: what matters is not the MRO of the type (the first argument to super()) but the MRO of ***the type of*** the object (the second argument to super()).

I believe that is still wrong. What matters is the __mro__ attribute of the first argument. It matters because that is how the MRO actually is searched. The MRO of the second argument is not relevant, except to the degree that it overlaps with the __mro__ attribute of the first. And it will always overlaps, because the second argument must be an instance or subclass of the first. But not necessarily *directly* of the first: object > Parent > A > B > C > D > E > F > instance = F() If the method is defined in class C, then the super call in C should be written: class C(B): def method(self, arg): super().method(arg) # like super(C, self).method(arg) and the lookup will start at C.__mro__[1], namely B, precisely as expected. If it started back at the type of the instance (self), namely class F, the C.method would recursively call itself over and over and over again. If you don't believe me, you can simulate super() working the way you suggest by doing this: # -----%<----- class A(object): def method(self): print("from class A") class B(A): def method(self): print("bad method") # This is bad, don't do it! super(type(self), self).method() class C(B): pass C().method() # -----%<----- For multiple inheritance: class C(B, X, Y, Z): ... we can't generally tell in advance which will be looked at next, since that depends on the precise details of the inheritance diagram. But whatever the class is, at this point, it is still the __mro__ of C that is used, not the MRO of the instance. The bottom line: what matters is <first argument>.__mro__, exactly as documented. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37176> _______________________________________

Jeroen Demeyer <J.Demeyer@UGent.be> added the comment:

What matters is the __mro__ attribute of the first argument. It matters because that is how the MRO actually is searched.

I'm sorry to say that you're wrong here. super() looks at the MRO of the type of the object (the second argument) (*). It has to do that in order to support diamonds. Consider a diamond like D / \ B C \ / A (with A as common base class). Now super(B, D()).attr will look in the MRO of D (which is D, B, C, A) and therefore delegate to C.attr. In this case, C does not even appear in the MRO of B. (*) To be pedantic: in the special case that the second argument is a type itself, it looks at the MRO of the second argument. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37176> _______________________________________

Géry <gery.ogam@gmail.com> added the comment: @Jeroen Demeyer

I'm sorry to say that you're wrong here. super() looks at the MRO of the type of the object (the second argument) (*).

Exactly! It is funny because I was about to open the same issue this weekend. The documentation of super() is wrong here. ---------- nosy: +maggyero _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37176> _______________________________________

Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: Please make a concrete proposal (a PR or somesuch). That will make it much easier to determine whether a particular bit of word-smithing is a improvement. Of the issues discussed so far, these are the most promising: * Document how the zero argument form of super() infers its arguments. * Be clear that it is the mro of type(self) that determines the search path and that the role of super() is to the next in the mro after the current class. ---------- versions: -Python 2.7, Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37176> _______________________________________

Change by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- assignee: docs@python -> rhettinger _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37176> _______________________________________

Martin Panter <vadmium+py@gmail.com> added the comment: Some of the problems brought up here (which sibling or subclass, and which parameter’s MRO) also came up a few years ago in Issue 23674. ---------- nosy: +martin.panter _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37176> _______________________________________

Jeroen Demeyer <J.Demeyer@UGent.be> added the comment:

Some of the problems brought up here (which sibling or subclass, and which parameter’s MRO) also came up a few years ago in Issue 23674.

Indeed. I would actually say that these two issues are duplicates of each other. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37176> _______________________________________

Steven D'Aprano <steve+python@pearwood.info> added the comment: On Sat, Jun 08, 2019 at 09:14:18PM +0000, Raymond Hettinger wrote:

Ideally, the text can also be made more compact. Having eight paragraphs sends an implicit message that this is too complex to understand and that it should be avoided.

But it is complex -- as you point out, there are *at least* seven potential misapprehensions here. super does a lot: there are at least four ways to call it (zero-argument form, unbound super, class+instance and class+subclass). And as the old "super considered harmful" versus "super considered super" debate shows, there are pitfalls in multiple inheritance that people run into. The challenge here is that for 95% of cases (plucking a number from thin air) using super is simple: just follow the example in the docs. But the remaining troublesome cases can be very troublesome, and people running into those cases do need to understand the gory details.

One essential goal is that we need to overcome strong preconceptions about about what super() might do versus what it actually does. [...]

Here's two more that you missed: - that you should call super with super(type(self), self); - that unbound super objects dispatch to unbound methods. At some point or another over the last decade I've misunderstood super to do almost all of those things. As this thread shows, I thought I had understood it but I still misunderstood the role of the class calling super. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37176> _______________________________________

Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: I've add PR 15564 to clarify some known ambiguities for the super() docs including a specific example "what it actually does". ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37176> _______________________________________