Py_TYPE

vstinner · vstinner · commit 431d36ab4421 · 2018-09-05T17:08:04.000+02:00
diff --git a/doc/bad_api.rst b/doc/bad_api.rst
@@ -73,11 +73,31 @@ Macros
 
 Border line:
 
-* ``Py_TYPE()``
 * ``Py_SETREF()``, ``Py_XSETREF()``: the caller has to manually increment the
   reference counter of the new value
 * ``N`` format of ``Py_BuildValue()``?
 
+
+.. _py-type:
+
+Py_TYPE() corner case
+=====================
+
+Technically, ``Py_TYPE()`` returns a borrowed reference to a ``PyTypeObject*``.
+In pratice, for heap types, an instance holds already a strong reference
+to the type in ``PyObject.ob_type``. For static types, instances use a borrowed
+reference, but static types are never destroyed.
+
+Hugh Fisher summarized:
+
+   It don't think it is  worth forcing every C extension module to be rewritten,
+   and incur a performance hit, to eliminate a rare bug from badly written
+   code.
+
+See the discussion on capi-sig: `Open questions about borrowed reference.
+<https://mail.python.org/mm3/archives/list/capi-sig@python.org/thread/V5EMBIIJFJGJGBQPLCFFXCHAUFNTA45H/>`_
+(Sept 2018).
+
 Borrowed references: PyEval_GetFuncName()
 =========================================
 
diff --git a/doc/new_api.rst b/doc/new_api.rst
@@ -34,15 +34,20 @@ New functions
   reference on the item
 * ``PySequence_Fast_GetItemRef()``
 * ``PyStructSequence_SetItemRef()``
-* ``Py_GetType()``: similar to ``Py_TYPE()`` but returns a strong reference
-* ``Py_TYPE_IS(ob, type)``: equivalent to ``Py_TYPE(ob) == type``
-* ``%T`` format for ``PyUnicode_FromFormat()``
 
 XXX private functions:
 
 * ``_Py_SET_TYPE()``: see :ref:`Implement a PyTypeObject in C <impl-pytype>`
 * ``_Py_SET_SIZE()``
 
+If we decide that :ref:`Py_TYPE() <py-type>` should go away, 3 more
+functions/features are needed:
+
+* ``Py_GetType()``: similar to ``Py_TYPE()`` but returns a strong reference
+* ``Py_TYPE_IS(ob, type)``: equivalent to ``Py_TYPE(ob) == type``
+* ``%T`` format for ``PyUnicode_FromFormat()``
+
+
 Non-goal
 ========
 
