Update Doc/extending/newtypes_tutorial.rst

Co-authored-by: Petr Viktorin <encukou@gmail.com>
python · encukou · Mar 24, 2025 · Mar 20, 2025 · Mar 24, 2025 · Mar 24, 2025
commit d3b5c48d31a79afec2574d350bd0933e7f75c6c6
diff --git a/Doc/extending/newtypes_tutorial.rst b/Doc/extending/newtypes_tutorial.rst
@@ -273,8 +273,28 @@ be an instance of a subclass.
 .. note::
    The explicit cast to ``CustomObject *`` above is needed because we defined
    ``Custom_dealloc`` to take a ``PyObject *`` argument, as the ``tp_dealloc``
-   function pointer expects to receive a ``PyObject *`` argument. Otherwise,
-   this would result in an undefined behaviour at runtime!
+   function pointer expects to receive a ``PyObject *`` argument.
+   By assigning to the the ``tp_dealloc`` slot of a type, we declare
+   that it can only be called with instances of our ``CustomObject``
+   class, so the cast to ``(CustomObject *)`` is safe.
+   This is object-oriented polymorphism, in C!
+
+   In existing code, or in previous versions of this tutorial,
+   you might see similar functions take a pointer to the subtype
+   object structure (``CustomObject*``) directly, like this::
+
+      Custom_dealloc(CustomObject *self)
+      {
+          Py_XDECREF(self->first);
+          Py_XDECREF(self->last);
+          Py_TYPE(self)->tp_free((PyObject *) self);
+      }
+      ...
+      .tp_dealloc = (destructor) Custom_dealloc,
+
+   This does the same thing on all architectures that CPython
+   supports, but according to the C standard, it invokes
+   undefined behavior.
 
 We want to make sure that the first and last names are initialized to empty
 strings, so we provide a ``tp_new`` implementation::