Bugs item #1163367, was opened at 2005-03-14 16:39
Message generated for change (Comment added) made by bediviere
You can respond by visiting:
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1163367&group_id=5470
Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: Documentation
Group: Python 2.4
Status: Open
Resolution: None
Priority: 5
Submitted By: Steven Bethard (bediviere)
Assigned to: Fred L. Drake, Jr. (fdrake)
Summary: correct/clarify documentation for super
Initial Comment:
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.
----------------------------------------------------------------------
>Comment By: Steven Bethard (bediviere)
Date: 2006-07-30 21:25
Message:
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.
----------------------------------------------------------------------
Comment By: Fred L. Drake, Jr. (fdrake)
Date: 2006-07-29 14:40
Message:
Logged In: YES
user_id=3066
I'm not sure what the paragraph following the \end{verbatim}
means. Can someone clarify?
----------------------------------------------------------------------
Comment By: Georg Brandl (birkenfeld)
Date: 2006-01-20 10:06
Message:
Logged In: YES
user_id=1188172
See also Bug #973579 (which I closed as duplicate) for
alternative wording.
----------------------------------------------------------------------
You can respond by visiting:
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1163367&group_id=5470
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
