[issue37176] super() docs don't say what super() does

[Raymond Hettinger]

Raymond Hettinger <raymond.hettinger at gmail.com> added the comment:

Yes, issue 23674 seems to be at least a partial duplicate.  We should just get this fixed and close both issues.

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.

One essential goal is that we need to overcome strong preconceptions about about what super() might do versus what it actually does.  Those with experience of super() in other languages tend to presume that it would be a keyword rather than a builtin type that needs to be instantiated, that it can only work within a class, that it has lower computational overhead than it does, that it only calls parents rather than siblings, that search order is controlled by the method using super() rather than the child instance, that operators will work, or that the search order is something is something other than the C3 algorithm.

The core challenge of documenting super() is that it is so different from what a person might imagine.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue37176>
_______________________________________