# HG changeset patch
# Parent  8c978cbe057c9566d34cd5e9823fa5868e6fc0f1
Issue #23674: Clarify super() documentation

* Change signature to super(subclass, self)
* Preceding subclasses in the MRO are skipped, not just *subclass* itself
* MRO is determined by self, not subclass
* Link to MRO glossary rather than getattr()
* Explain that unbound super objects are descriptors
* Bound super objects bind their methods to *self*
* *Subclass* should not be "object", and should remain in the MRO hierarchy
* Virtual subclassing is not relevant

diff -r 8c978cbe057c Doc/library/functions.rst
--- a/Doc/library/functions.rst	Sun Dec 06 03:29:54 2015 +0000
+++ b/Doc/library/functions.rst	Sun Dec 06 06:06:26 2015 +0000
@@ -1360,22 +1360,31 @@
    see :func:`math.fsum`\.  To concatenate a series of iterables, consider using
    :func:`itertools.chain`.
 
-.. function:: super([type[, object-or-type]])
+.. function:: super([subclass[, self]])
 
    Return a proxy object that delegates method calls to a parent or sibling
-   class of *type*.  This is useful for accessing inherited methods that have
-   been overridden in a class. The search order is same as that used by
-   :func:`getattr` except that the *type* itself is skipped.
+   class of *subclass*.  This is useful for accessing inherited methods that have
+   been overridden in a class. The search order is the usual
+   :term:`method resolution order` (MRO), except that searching starts with
+   the class after *subclass* in the MRO.  Classes that come beforehand,
+   including *subclass*, are skipped.  The *subclass* class should not be
+   :class:`object`, which is always at the end of the MRO.
 
-   The :attr:`~class.__mro__` attribute of the *type* lists the method
-   resolution search order used by both :func:`getattr` and :func:`super`.  The
+   The resolution search order is determined by
+   the :attr:`~class.__mro__` attribute of *self*.  The
    attribute is dynamic and can change whenever the inheritance hierarchy is
-   updated.
+   updated, however *subclass* should remain in this hierarchy.
 
-   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).
+   If *self* is an object, it must be a concrete instance of *subclass*.
+   If *self* is a type, it must be *subclass* or a concrete subclass
+   of *subclass* (this is useful for classmethods).  In both these cases,
+   the super object returned is bound, and getting a method from
+   this object binds the method to *self*.
+
+   If *self* is omitted, the super object returned is unbound.  An unbound
+   super object is a :term:`descriptor`.  If stored as a class attribute,
+   accessing it as an instance attribute will return a copy of the
+   super object bound to the instance.
 
    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
diff -r 8c978cbe057c Objects/typeobject.c
--- a/Objects/typeobject.c	Sun Dec 06 03:29:54 2015 +0000
+++ b/Objects/typeobject.c	Sun Dec 06 06:06:26 2015 +0000
@@ -7203,8 +7203,8 @@
     }
 
     PyErr_SetString(PyExc_TypeError,
-                    "super(type, obj): "
-                    "obj must be an instance or subtype of type");
+                    "super(subclass, self): "
+                    "self must be an instance or subtype of subclass");
     return NULL;
 }
 
@@ -7353,9 +7353,11 @@
 
 PyDoc_STRVAR(super_doc,
 "super() -> same as super(__class__, <first argument>)\n"
-"super(type) -> unbound super object\n"
-"super(type, obj) -> bound super object; requires isinstance(obj, type)\n"
-"super(type, type2) -> bound super object; requires issubclass(type2, type)\n"
+"super(subclass) -> unbound super object\n"
+"super(subclass, self) -> bound super object; requires\n"
+"    isinstance(self, subclass)\n"
+"super(subclass, cls) -> bound super object; requires\n"
+"    issubclass(cls, subclass)\n"
 "Typical use to call a cooperative superclass method:\n"
 "class C(B):\n"
 "    def meth(self, arg):\n"