Address review

vstinner · Jan 20, 2021 · Dec 28, 2020 · Dec 28, 2020 · Jan 20, 2021 · Jan 20, 2021
commit acf0f7e1d3475a2bfa8c2c7835fc4f7b4bd4ec24
diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst
@@ -1210,35 +1210,64 @@ Using a "defining class" converter
 ----------------------------------
 
 Argument Clinic facilitates gaining access to the defining class of a method.
-This is useful for heap type methods that need to fetch module level state.
-Example from ``Modules/zlibmodule.c``::
+This is useful for :ref:`heap type <heap-types>` methods that need to fetch
+module level state.  Use :c:func:`PyType_FromModuleAndSpec` to associate a new
+heap type with a module.  You can now use :c:func:`PyType_GetModuleState` on
+the defining class to fetch the module state, for example from a module method.
+
+Example from ``Modules/zlibmodule.c``.  First, ``defining_class`` is added to
+the clinic input::
 
     /*[clinic input]
     zlib.Compress.compress
 
-        cls: defining_class
-        data: Py_buffer
-        /
-    ...
+      cls: defining_class
+      data: Py_buffer
+        Binary data to be compressed.
+      /
+
+
+After running the Argument Clinic tool, the following function signature is
+generated::
+
     [clinic start generated code]*/
     static PyObject *
-    zlib_Compress_compress_impl(...)
-    /*[clinic end generated code ...]*/
-    {
-        zlibstate *state = PyType_GetModuleState(cls)
+    zlib_Compress_compress_impl(compobject *self, PyTypeObject *cls,
+                                Py_buffer *data)
+    /*[clinic end generated code: output=6731b3f0ff357ca6 input=04d00f65ab01d260]*/
 
 
-Each method may only have one argument using this converter, and it must appear
-after ``self``, or, if ``self`` is not used, as the first argument. The argument
-will be of type ``PyTypeObject *``.
+The follwing code can now use ``PyType_GetModuleState(cls)`` to fetch the
+module state::
 
-When used, Argument Clinic will select ``METH_FASTCALL | METH_KEYWORDS |
-METH_METHOD`` as the calling convention. The argument will not appear in
+    zlibstate *state = PyType_GetModuleState(cls);
+
+
+Each method may only have one argument using this converter, and it must appear
+after ``self``, or, if ``self`` is not used, as the first argument.  The argument
+will be of type ``PyTypeObject *``.  The argument will not appear in the
 ``__text_signature__``.
 
 The ``defining_class`` converter is not compatible with ``__init__`` and ``__new__``
 methods, which cannot use the ``METH_METHOD`` convention.
 
+It is not possible to use ``defining_class`` with slot methods.  In order to
+fetch the module state from such methods, use ``_PyType_GetModuleByDef`` to
+look up the module and then :c:func:`PyModule_GetState` to fetch the module
+state.  Example from the `setattro` slot method in
+``Modules/_threadmodule.c``::
+
+    static int
+    local_setattro(localobject *self, PyObject *name, PyObject *v)
+    {
+        PyObject *module = _PyType_GetModuleByDef(Py_TYPE(self), &thread_module);
+        thread_module_state *state = get_thread_state(module);
+
+
+Note that ``_PyType_GetModuleByDef`` traverses the MRO cache, and therefore has
+performance impact.
+
+
 See also :pep:`573`.