Issue1163367
This issue tracker has been migrated to GitHub,
and is currently read-only.
For more information,
see the GitHub FAQs in the Python's Developer Guide.
Created on 2005-03-14 23:39 by bethard, last changed 2022-04-11 14:56 by admin. This issue is now closed.
Files | ||||
---|---|---|---|---|
File name | Uploaded | Description | Edit | |
super.diff | fdrake, 2006-07-31 04:29 | Fred's documentation patch; still needy. | ||
super.diff | fdrake, 2006-07-31 07:01 | Revised patch, describing both 2-arg forms. |
Messages (12) | |||
---|---|---|---|
msg24610 - (view) | Author: Steven Bethard (bethard) * | Date: 2005-03-14 23:39 | |
The current documentation for super is confusing. For instance, it says that it returns "the superclass of type" which is incorrect; it actually returns the next type in type's MRO. Well, to be truthful, it doesn't even do that; it returns a proxy object which makes that type's attributes available, but that's just another reason to fix the documentation. I suggest changing the wording to something like: """super(type[, object-or-type]) Return an object that exposes the attributes available through the type's superclasses, without exposing the attributes of the type itself. Attributes will be looked up using the normal resolution order, omitting the first class in the MRO (that is, the type itself). If the second argument is present, it should either be an instance of object, in which case isinstance(object-or-type, type) must be true, or it should be an instance of type, in which case issubclass(object-or-type, type) must be true. The typical use for this form of super is to call a cooperative superclass method: class C(B): def meth(self, arg): super(C, self).meth(arg) If the second argument to super is omitted, the super object returned will not expose any attributes directly. However, attributes will be accessible whenever the descriptor machinery is invoked, e.g. though explicit invocation of __get__. Note that super is undefined for implicit lookups using statements or operators such as "super(C, self)[name]". These must be spelled out with their explicit lookup, e.g. "super(C, self).__getitem__(name)". New in version 2.2. """ It's not perfect and I welcome suggestions for re-wording, but I think it's substantially more accurate about what super actually does. It also moves the "second argument omitted" situation to the end, since this is a vastly more uncommon use case. |
|||
msg24611 - (view) | Author: Georg Brandl (georg.brandl) * | Date: 2006-01-20 17:06 | |
Logged In: YES user_id=1188172 See also Bug #973579 (which I closed as duplicate) for alternative wording. |
|||
msg24612 - (view) | Author: Fred Drake (fdrake) | Date: 2006-07-29 20:40 | |
Logged In: YES user_id=3066 I'm not sure what the paragraph following the \end{verbatim} means. Can someone clarify? |
|||
msg24613 - (view) | Author: Steven Bethard (bethard) * | Date: 2006-07-31 03:25 | |
Logged In: YES user_id=945502 If you're talking about the following: """ Note that \function{super} is implemented as part of the binding process for explicit dotted attribute lookups such as \samp{super(C, self).__getitem__(name)}. Accordingly, \function{super} is undefined for implicit lookups using statements or operators such as \samp{super(C, self)[name]}. """ I believe it's trying to say that super works as if it only overrode __getattr__. Hence ``sup.XXX`` works, but not ``sup[...]``, ``sup(...)``, etc. That first sentence seems mostly unnecessary to me. As long as we say that the __XXX__ methods must be spelled out explicitly, I think we've got our bases covered. |
|||
msg24614 - (view) | Author: Fred Drake (fdrake) | Date: 2006-07-31 03:58 | |
Logged In: YES user_id=3066 That explanation doesn't deal with the difference between the 1- and 2-argument signatures. It can be cleaned up pretty heavily. I'll see if I can come up with a decent comment about 1-argument calls to super(). |
|||
msg24615 - (view) | Author: Fred Drake (fdrake) | Date: 2006-07-31 04:29 | |
Logged In: YES user_id=3066 Ok, after playing around a bit with the 1-arg variation and the 2nd-arg-is-a-type variation, I don't have a clue as to how either would be used. It someone can explain either of both of those, please post an explanation here, and I'll do any LaTeX conversions needed. I've attached what I have so far as a patch. |
|||
msg24616 - (view) | Author: Steven Bethard (bethard) * | Date: 2006-07-31 05:02 | |
Logged In: YES user_id=945502 The two-arg type form is intended for use with classmethods, e.g.:: >>> class C(object): ... @classmethod ... def f(cls): ... print 'C.f' ... >>> class D(C): ... @classmethod ... def f(cls): ... super(D, cls).f() ... print 'D.f' ... >>> D.f() C.f D.f I do make use of this occasionally, so I do think it should be documented. The one-arg form is intended to be used as a class attribute:: >>> class C(object): ... def f(self): ... print 'C.f' ... >>> class D(C): ... def f(self): ... self.super.f() ... print 'D.f' ... >>> D.super = super(D) >>> D().f() C.f D.f I don't know that we should really be advertising this one-arg form though. It requires modifying a class outside the definition or using some metaclass hackery to be usable. And it's misleading because it won't work, for example, with classmethods: >>> class C(object): ... @classmethod ... def f(cls): ... print 'C.f' ... >>> class D(C): ... @classmethod ... def f(cls): ... cls.super.f() ... print 'D.f' ... >>> D.super = super(D) >>> D().f() Traceback (most recent call last): File "<interactive input>", line 1, in ? File "<interactive input>", line 4, in f AttributeError: 'super' object has no attribute 'f' That's why I tried to gloss over it lightly. Personally I'd prefer that the one-arg form was just deprecated. It introduces a lot more problems than it solves. But if it has to be documented, it should probably say something like "A super object created with a single argument produces a descriptor object. This descriptor object makes the superclass methods available on the object returned by its __get__ method. The superclass methods are only available when __get__ is called with an instance (not a class)." |
|||
msg24617 - (view) | Author: Fred Drake (fdrake) | Date: 2006-07-31 07:01 | |
Logged In: YES user_id=3066 Thanks Steven; that helps a lot! I've attached a revised version of my patch that describes both 2-arg forms; I'll see about refining it further after I've had a bit of sleep, and time to play with the 1-arg form. |
|||
msg64235 - (view) | Author: Kent Johnson (kjohnson) * | Date: 2008-03-21 11:48 | |
This issue seems to have foundered on finding an explanation for the finer points of super(). Perhaps the glaring errors could at least be corrected, or the fine points could be omitted or glossed over? For example change the first sentence of the docs to "Returns a proxy for the type following 'type' in the method resolution order of 'object-or-type'." Perhaps link to these? http://chandlerproject.org/bin/view/Projects/UsingSuper http://fuhm.net/super-harmful/ |
|||
msg76887 - (view) | Author: Fred Drake (fdrake) | Date: 2008-12-04 15:19 | |
Clearly, I've not gotten to this; unassigning from myself. Probably a good thing, since I'm one of the people who probably don't use it correctly in all cases. |
|||
msg76919 - (view) | Author: Raymond Hettinger (rhettinger) * | Date: 2008-12-04 19:20 | |
I'll look at this further. Since it was originally posted, there have already been several improvements to the super() docs. FWIW, there will be no links to super-considered-harmful. Guido has frowned upon that document. Our documentation needs to be written in an affirmative manner, indicating what problems super() solves and how to use it well. This is far better than itemizing its misuses and suggesting that it is an anti-feature. |
|||
msg77114 - (view) | Author: Raymond Hettinger (rhettinger) * | Date: 2008-12-06 11:45 | |
Updated again in r67607. Hopefully, this one has been put to rest. If someone has further issues with the super() docs, please open a new report (preferably with suggested wording). |
History | |||
---|---|---|---|
Date | User | Action | Args |
2022-04-11 14:56:10 | admin | set | github: 41701 |
2008-12-06 11:45:37 | rhettinger | set | status: open -> closed resolution: fixed messages: + msg77114 |
2008-12-04 19:20:12 | rhettinger | set | assignee: rhettinger messages: + msg76919 nosy: + rhettinger |
2008-12-04 15:19:07 | fdrake | set | assignee: fdrake -> (no value) messages: + msg76887 |
2008-03-21 11:48:08 | kjohnson | set | nosy:
+ kjohnson messages: + msg64235 |
2005-03-14 23:39:38 | bethard | create |