summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorRaymond Hettinger <python@rcn.com>2008-09-19 08:07:48 (GMT)
committerRaymond Hettinger <python@rcn.com>2008-09-19 08:07:48 (GMT)
commit3134f14b1aa7a06242fc25775a0a46e4370c434a (patch)
treec99fba8f05942da9843ded607a0b948b6fc77672
parent5aaa3e579dc58b95bd6090c0e9ee717d6835623b (diff)
downloadcpython-3134f14b1aa7a06242fc25775a0a46e4370c434a.zip
cpython-3134f14b1aa7a06242fc25775a0a46e4370c434a.tar.gz
cpython-3134f14b1aa7a06242fc25775a0a46e4370c434a.tar.bz2
Improve docs for super().
-rw-r--r--Doc/library/functions.rst19
1 files changed, 18 insertions, 1 deletions
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 26587b8..9e97bbe 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1216,13 +1216,28 @@ available. They are listed here in alphabetical order.
.. function:: super(type[, object-or-type])
Return a "super" object that acts like the superclass of *type*.
+
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. :func:`super` only works for
:term:`new-style class`\es.
- A typical use for calling a cooperative superclass method is::
+ There are two typical use cases for "super". In a class hierarchy with
+ single inheritance, "super" can be used to refer to parent classes without
+ naming them explicitly, thus making the code more maintainable. This use
+ closely parallels the use of "super" in other programming languages.
+
+ The second use case is to support cooperative multiple inheritence in a
+ dynamic execution environment. This use case is unique to Python and is
+ not found in statically compiled languages or languages that only support
+ single inheritance. This makes in possible to implement "diamond diagrams"
+ where multiple base classes implement the same method. Good design dictates
+ that this method have the same calling signature in every case (because the
+ order of parent calls is determined at runtime and because that order adapts
+ to changes in the class hierarchy).
+
+ For both use cases, a typical superclass call looks like this::
class C(B):
def meth(self, arg):
@@ -1230,6 +1245,8 @@ available. They are listed here in alphabetical order.
Note that :func:`super` is implemented as part of the binding process for
explicit dotted attribute lookups such as ``super(C, self).__getitem__(name)``.
+ It does so by implementing its own :meth:`__getattribute__` method for searching
+ parent classes in a predictable order that supports cooperative multiple inheritance.
Accordingly, :func:`super` is undefined for implicit lookups using statements or
operators such as ``super(C, self)[name]``.