New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
super
and descriptor clarification
#90340
Comments
I find super documentation confusing because it uses multiple variables that are never introduced. Once you understand super, the meaning of those variables gets easier to understand, but still, I believe that it would help the documentation to rephrase some sentences. In https://docs.python.org/3/reference/datamodel.html#invoking-descriptors you can read
It took me many reading to understand that Also, In https://docs.python.org/3/library/functions.html#super , you can read
On first reading, I have no idea what it means that a returned object is unbound. I know what "variable binding" mean, but it really does not seems to apply here. My current understanding, and I would love if someone can confirm it, is that the first sentence means that "contrary to the other cases, the returned value do not have to satisfy any bound". In this case, I believe that it would be far better to put the case with no second argument at the end of the paragraph, ensuring that "is unbound" makes sens to the reader since they already will have seen bounds. Any feedback welcome. |
I just realized that https://bugs.python.org/issue20751 already tackled some of my issues. While I still believe that some things can be improved, this mean that some of the critiques in my first messages are not entirely up to date. |
"a base class Also, I find it unclear what means " |
No. There can be other classes in the chain. The first to match the lookup wins.
Sorry, but I don't your proposed wording adds value. While you may feel that it is more precise, it just adds redundant words without adding information. FWIW, we do this all over the docs, letting parameter names such as *obj* and *type2* communicate that we're referring to an object or a type.
I took care of that in the other tracker issue. That said, it arguably made the docs worse rather than better because by far the dominant use case for super() is calling methods rather than doing attribute lookup. I only made the change to be consistent with the other attribute lookup examples.
ISTM that you're looking for a full tutorial with fully worked worked out examples rather than English text interspersed with code snippets. Consider reading the super-considered-super post for that purpose. As for the existing text, I've wrestled with it for years and think we've hit a local optimum. Expanding the text with more steps and descriptions of each step results in documentation that causes people's eyes to glaze over and to miss the main point of each sentence. Also, remember that the documentation is factored. The descriptor tutorial is primarily about descriptors. A super() call is just one of four ways to invoke a descriptor. From a descriptor howto point-of-view, all we want to communicate is that the attribute/method search starts at the next in the mro rather than the current instance. It is not the goal of that section to fully document or discuss super(). As for the main super() docs, that is the place talk about how super works; however, it is not the job of that section to explain the rest of Python (terms like bound, unbound, etc). In a way, the only job of this section is to differentiate how |
I do regret to have created a single bug, as I now realize that there are two issues that are less related than I first imagined. Is there a way to split a bug in two, so that both discussion can be discussed in different places. Actually, after more search abound "unbound method", I discovered in https://www.python.org/download/releases/3.0/whatsnew/ that this concept was supposed to be gone for good in 3.0 The notion is also used in a few other places in the documentation but as far as I can tell the only "definition" would be in https://docs.python.org/3.11/c-api/method.html#method-objects.
Actually, I was going to create a PR Arthur-Milchior@dd453ac before seeing your answer, and while less certain, I still believe it has merits |
I'm reluctant to give any more space to the least important case, one that rarely arises in practice. The text in the PR is wordy and IMO creates more confusion that it solves. Per the dev-guide, we mostly avoid "preachy" text. No, "it is recommended to avoid the single argument form". In the unlikely event that a person needs this, we are not recommending against it. It is in fact supported, tested, and mentioned in the documentation. And to the extend we care to nudge users in one direction or another, the traditional way to deemphasize a feature is spend less time and space talking about it :-) At this point, I recommend just letting it be. It feels like we're going down a rabbit hole here rather than solving problems that users actually have. These features are almost two decades old and the docs have been stable for a long time. If there were a significant communication issue here, we would have known long ago. To gain an appreciation for the challenges we face in documentation, take a look at the discussion in https://bugs.python.org/issue46173 . In the case of super(), more words don't make the docs better; it just adds more text that a user has to fight through to get the gestalt of what is going on. When I talk to advanced users of the language, they almost never think of super() in more detail than is covered in the docs; instead, they've grokked the central concept of next-in-mro and that it is commonly used in two ways either to call parent class or to implement cooperative multiple inheritance. Ideally, we want to lead readers to that same understanding. IMO, detailing the mechnanics of uncommon cases takes us in the opposite direction. |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: