Steven D'Aprano <steve+pyt...@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 <rep...@bugs.python.org> <https://bugs.python.org/issue37176> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com