New submission from Arthur Milchior <art...@milchior.fr>:
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 > If a is an instance of super, then the binding super(B, obj).m() searches > obj.__class__.__mro__ for the base class A immediately following B and then > invokes the descriptor with the call: A.__dict__['m'].__get__(obj, > obj.__class__). It took me many reading to understand that `obj` is supposed to be a new variable; and also why `a` only appear once in the line. I believe it'd be better to explicitly state "We consider the case where a = super(B, obj), with `obj` an instance of B." Also, `super(B, obj).m()` seems to indicate that the method `m` is called. While ` A.__dict__['m'].__get__(obj, obj.__class__)` does not seems to call this method. Hence, I believe that the parentheses should be removed after `m` (and either `m` should be renamed to `x`, or we should state explicitly that we are not considered `a.x` anymore, contrary to the previous cases) In https://docs.python.org/3/library/functions.html#super , you can read > If the second argument is omitted, the super object returned is unbound. If > the second argument is an object, isinstance(obj, type) must be true. If the > second argument is a type, issubclass(type2, type) must be true (this is > useful for classmethods). 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. Also, it may help clarify to write "is an object `obj`" and "is a type `type2`" so that it get clear what `obj` and `type2` means. Any feedback welcome. ---------- assignee: docs@python components: Documentation messages: 409201 nosy: Arthur-Milchior, docs@python priority: normal severity: normal status: open title: `super` and descriptor clarification type: enhancement versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue46182> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
