summaryrefslogtreecommitdiffstats
path: root/Doc/library
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/library')
-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]``.