From: Petr Viktorin <encukou@gmail.com>
Date: Mon, 7 Nov 2022 18:45:50 +0000 (+0100)
Subject: gh-96746: Docs: Clear up Py_TPFLAGS_DISALLOW_INSTANTIATION inheritance (GH-99002)
X-Git-Tag: v3.12.0a2~87
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=1438b779971605e516bd0a4051a704d6ffbbd58d;p=thirdparty%2FPython%2Fcpython.git

gh-96746: Docs: Clear up Py_TPFLAGS_DISALLOW_INSTANTIATION inheritance (GH-99002)

The flag is not inherited, but its effect -- a NULL tp_new -- is.

Drop hints for people who come here wanting to “disallow instantiation”.
---

diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 8ccdece3efc5..4c462f460567 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -1245,6 +1245,17 @@ and :c:type:`PyType_Type` effectively act as defaults.)
       **Inheritance:**
 
       This flag is not inherited.
+      However, subclasses will not be instantiable unless they provide a
+      non-NULL :c:member:`~PyTypeObject.tp_new` (which is only possible
+      via the C API).
+
+      .. note::
+
+         To disallow instantiating a class directly but allow instantiating
+         its subclasses (e.g. for an :term:`abstract base class`),
+         do not use this flag.
+         Instead, make :c:member:`~PyTypeObject.tp_new` only succeed for
+         subclasses.
 
       .. versionadded:: 3.10