PEP 580: Reword section on cc_parent (GH-775)

pep-0580.rst

@@ -122,39 +122,36 @@ Parent
 ------
 
 The ``cc_parent`` field (accessed for example by a ``__parent__``
-or ``__objclass__`` descriptor from Python code) can be any Python object.
-For methods of extension types, this is set to the class.
-For functions of modules, this is set to the module.
-However, custom classes are free to set ``cc_parent`` to whatever they want,
-it can also be ``NULL``.
-It is only used by the C call protocol if the ``CCALL_OBJCLASS`` flag is set.
+or ``__objclass__`` descriptor from Python code) can be any Python
+object, or NULL.
+Custom classes are free to set ``cc_parent`` to whatever they want.
+It is only used by the C call protocol if the
+``CCALL_OBJCLASS`` flag is set.
 
-The parent serves multiple purposes: for methods of extension types
-(more precisely, when the flag ``CCALL_OBJCLASS`` is set),
-it is used for type checks like the following::
+For methods of extension types, ``cc_parent`` points to the class
+that defines the method (which may be a superclass of ``type(self)``).
+This is currently is non-trivial to retreive from a method's code.
+(In the future, this can be used to access the module state via
+the defining class. See the rationale of PEP 573 for details.)
+
+When the flag ``CCALL_OBJCLASS`` is set (as it will be for methods of
+extension types), ``cc_parent`` is used for type checks like the following::
 
     >>> list.append({}, "x")
     Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
     TypeError: descriptor 'append' requires a 'list' object but received a 'dict'
 
-PEP 573 specifies that every function should have access to the
-module in which it is defined.
-It is recommended to use the parent for this,
-which works directly for functions of a module.
-For methods, this works indirectly through the class,
-assuming that the class has a pointer to the module.
-
-The parent would also typically be used to implement ``__qualname__``.
-The new C API function ``PyCCall_GenericGetQualname()`` does exactly that.
-
-**NOTE**: for functions of modules,
-the parent is exactly the same as ``__self__``.
+For functions of modules, ``cc_parent`` is set to the module.
+Currently, this is exactly the same as ``__self__``.
 However, using ``__self__`` for the module is a quirk of the current implementation:
 in the future, we want to allow functions which use ``__self__``
 in the normal way, for implementing methods.
 Such functions can still use ``cc_parent`` instead to refer to the module.
 
+The parent would also typically be used to implement ``__qualname__``.
+The new C API function ``PyCCall_GenericGetQualname()`` does exactly that.
+
 Using tp_print
 --------------