Apply suggestions from code review

Co-authored-by: Petr Viktorin <encukou@gmail.com>
python · encukou · May 20, 2025 · Oct 19, 2024 · Oct 25, 2024 · Oct 25, 2024
commit da3593ca400fe94fb8b247c029737979e8b75888
diff --git a/Doc/c-api/allocation.rst b/Doc/c-api/allocation.rst
@@ -23,6 +23,8 @@ Allocating Objects on the Heap

   In general, consider this function to be a low-level routine. Use
   :c:member:`~PyTypeObject.tp_alloc` where possible.
+   For implementing :c:member:`!tp_alloc` for your type, prefer
+   :c:func:`PyType_GenericAlloc` or :c:func:`PyObject_New`.

   .. note::

@@ -35,7 +37,7 @@ Allocating Objects on the Heap
   This does everything :c:func:`PyObject_Init` does, and also initializes the
   length information for a variable-size object.

-   .. warning::
+   .. note::

      This function only initializes some of the object's memory.  It does not
      zero the rest.
@@ -63,15 +65,15 @@ Allocating Objects on the Heap
   This cannot be used for objects with :c:macro:`Py_TPFLAGS_HAVE_GC` set in
   :c:member:`~PyTypeObject.tp_flags`; use :c:macro:`PyObject_GC_New` instead.

-   Memory allocated by this function must be freed with :c:func:`PyObject_Free`
+   Memory allocated by this macro must be freed with :c:func:`PyObject_Free`
   (usually called via the object's :c:member:`~PyTypeObject.tp_free` slot).

-   .. warning::
+   .. note::

      The returned memory is not guaranteed to have been completely zeroed
      before it was initialized.

-   .. warning::
+   .. note::

      This macro does not construct a fully initialized object of the given
      type; it merely allocates memory and prepares it for further
@@ -116,12 +118,12 @@ Allocating Objects on the Heap
   Memory allocated by this function must be freed with :c:func:`PyObject_Free`
   (usually called via the object's :c:member:`~PyTypeObject.tp_free` slot).

-   .. warning::
+   .. note::

      The returned memory is not guaranteed to have been completely zeroed
      before it was initialized.

-   .. warning::
+   .. note::

      This macro does not construct a fully initialized object of the given
      type; it merely allocates memory and prepares it for further

diff --git a/Doc/c-api/gcsupport.rst b/Doc/c-api/gcsupport.rst
@@ -64,7 +64,7 @@ rules:
   :c:func:`PyType_GenericAlloc` is preferred over a custom function that
   simply calls this macro.

-   Memory allocated by this function must be freed with
+   Memory allocated by this macro must be freed with
   :c:func:`PyObject_GC_Del` (usually called via the object's
   :c:member:`~PyTypeObject.tp_free` slot).

@@ -88,7 +88,7 @@ rules:
   :c:func:`PyType_GenericAlloc` is preferred over a custom function that
   simply calls this macro.

-   Memory allocated by this function must be freed with
+   Memory allocated by this macro must be freed with
   :c:func:`PyObject_GC_Del` (usually called via the object's
   :c:member:`~PyTypeObject.tp_free` slot).


diff --git a/Doc/c-api/lifecycle.rst b/Doc/c-api/lifecycle.rst
@@ -151,7 +151,7 @@ that must be true for *B* to occur after *A*.
   * When the garbage collector discovers a :term:`cyclic isolate` and all of
     the objects in the group have already been marked as *finalized*, the
     garbage collector clears one or more of the uncleared objects in the group
-     (possibly concurrently, but with the :term:`GIL` held) by calling each's
+     (possibly concurrently) by calling each's
     :c:member:`~PyTypeObject.tp_clear` function.  This repeats as long as the
     cyclic isolate still exists and not all of the objects have been cleared.

@@ -209,7 +209,7 @@ Unlike clearing, finalization is not a phase of destruction.  A finalized
 object must still behave properly by continuing to fulfill its design
 contracts.  An object's finalizer is allowed to execute arbitrary Python code,
 and is even allowed to prevent the impending destruction by adding a reference.
-The finalizer is only contemporaneously related to destruction---it runs just
+The finalizer is only related to destruction by call order---if it runs, it runs
 before destruction, which starts with :c:member:`~PyTypeObject.tp_clear` (if
 called) and concludes with :c:member:`~PyTypeObject.tp_dealloc`.


diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
@@ -695,12 +695,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
     (:c:member:`~PyTypeObject.tp_finalize`) or automatically cleared
     (:c:member:`~PyTypeObject.tp_clear`).

-   .. warning::
-
-      The :c:member:`~PyTypeObject.tp_dealloc` function can be called from any
-      thread, although the :term:`GIL` will be held.
-
-   Python currently destroys an object immediately from :c:func:`Py_DECREF`
+   CPython currently destroys an object immediately from :c:func:`Py_DECREF`
   when the new reference count is zero, but this may change in a future
   version.

@@ -777,13 +772,13 @@ and :c:data:`PyType_Type` effectively act as defaults.)
          PyErr_SetRaisedException(exc);
      }

-   In a garbage collected Python, :c:member:`!tp_dealloc` may be called from
+   :c:member:`!tp_dealloc` may be called from
   any Python thread, not just the thread which created the object (if the
   object becomes part of a refcount cycle, that cycle might be collected by
   a garbage collection on any thread).  This is not a problem for Python
   API calls, since the thread on which :c:member:`!tp_dealloc` is called
   with an :term:`attached thread state`.  However, if the object being
-   destroyed in turn destroys objects from some other C or C++ library, care
+   destroyed in turn destroys objects from some other C library, care
   should be taken to ensure that destroying those objects on the thread
   which called :c:member:`!tp_dealloc` will not violate any assumptions of
   the library.
@@ -1191,9 +1186,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
      must be allocated using :c:macro:`PyObject_GC_New` or
      :c:func:`PyType_GenericAlloc` and deallocated (see
      :c:member:`~PyTypeObject.tp_free`) using :c:func:`PyObject_GC_Del`.  More
-      information in section :ref:`supporting-cycle-detection`.  This bit also
-      implies that the GC-related fields :c:member:`~PyTypeObject.tp_traverse`
-      and :c:member:`~PyTypeObject.tp_clear` are present in the type object.
+      information in section :ref:`supporting-cycle-detection`.

      **Inheritance:**

@@ -1530,10 +1523,10 @@ and :c:data:`PyType_Type` effectively act as defaults.)
   heap-allocated superclass).
   If they do not, the type object may not be garbage-collected.

-   .. warning::
+   .. note::

      The :c:member:`~PyTypeObject.tp_traverse` function can be called from any
-      thread, although the :term:`GIL` will be held.
+      thread.

   .. versionchanged:: 3.9

@@ -1568,29 +1561,29 @@ and :c:data:`PyType_Type` effectively act as defaults.)
   integers.  However, it may be convenient to clear all references, and write
   the type's :c:member:`~PyTypeObject.tp_dealloc` function to invoke
   :c:member:`!tp_clear` to avoid code duplication.  (Beware that
-   :c:member:`!tp_clear` might have already been called, but :c:func:`Py_CLEAR`
-   is idempotent so extra checks are usually unnecessary.)
+   :c:member:`!tp_clear` might have already been called. Prefer calling
+   idempotent functions like :c:func:`Py_CLEAR`.)

   Any non-trivial cleanup should be performed in
   :c:member:`~PyTypeObject.tp_finalize` instead of :c:member:`!tp_clear`.

-   .. warning::
+   .. note::

      If :c:member:`!tp_clear` fails to break a reference cycle then the
      objects in the :term:`cyclic isolate` may remain indefinitely
      uncollectable ("leak").  See :data:`gc.garbage`.

-   .. warning::
+   .. note::

      Referents (direct and indirect) might have already been cleared; they are
      not guaranteed to be in a consistent state.

-   .. warning::
+   .. note::

      The :c:member:`~PyTypeObject.tp_clear` function can be called from any
-      thread, although the :term:`GIL` will be held.
+      thread.

-   .. warning::
+   .. note::

      An object is not guaranteed to be automatically cleared before its
      destructor (:c:member:`~PyTypeObject.tp_dealloc`) is called.
@@ -1635,7 +1628,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
   * Python will not automatically call :c:member:`!tp_clear` multiple times
     concurrently.

-   Python currently only automatically clears objects as needed to break
+   CPython currently only automatically clears objects as needed to break
   reference cycles in a :term:`cyclic isolate`, but future versions might
   clear objects regularly before their destruction.

@@ -2078,11 +2071,11 @@ and :c:data:`PyType_Type` effectively act as defaults.)
   Static subtypes inherit this slot, which will be
   :c:func:`PyType_GenericAlloc` if inherited from :class:`object`.

-   Dynamic subtypes (created by a class statement) do not inherit this slot.
+   :ref:`Heap subtypes <heap-types>` do not inherit this slot.

   **Default:**

-   For dynamic subtypes, this field is always set to
+   For heap subtypes, this field is always set to
   :c:func:`PyType_GenericAlloc`.

   For static subtypes, this slot is inherited (see above).
@@ -2145,11 +2138,11 @@ and :c:data:`PyType_Type` effectively act as defaults.)
   :c:func:`PyObject_Free`, then this slot is not inherited but instead defaults
   to :c:func:`PyObject_GC_Del`.

-   Dynamic subtypes (created by a class statement) do not inherit this slot.
+   :ref:`Heap subtypes <heap-types>` do not inherit this slot.

   **Default:**

-   For dynamic subtypes, this slot defaults to a deallocator suitable to match
+   For :ref:`heap subtypes <heap-types>`, this slot defaults to a deallocator suitable to match
   :c:func:`PyType_GenericAlloc` and the value of the
   :c:macro:`Py_TPFLAGS_HAVE_GC` flag.

@@ -2289,7 +2282,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
   The primary purpose of finalization is to perform any non-trivial cleanup
   that must be performed before the object is destroyed, while the object and
   any other objects it directly or indirectly references are still in a
-   consistent state.  See :pep:`442`.  The finalizer is allowed to execute
+   consistent state.  The finalizer is allowed to execute
   arbitrary Python code.

   Before Python automatically finalizes an object, some of the object's direct
@@ -2301,28 +2294,28 @@ and :c:data:`PyType_Type` effectively act as defaults.)
   finalizer must leave the object in a sane state (e.g., invariants are still
   met).

-   .. warning::
+   .. note::

      After Python automatically finalizes an object, Python might start
      automatically clearing (:c:member:`~PyTypeObject.tp_clear`) the object
      and its referents (direct and indirect).  Cleared objects are not
      guaranteed to be in a consistent state; a finalized object must be able
      to tolerate cleared referents.

-   .. warning::
+   .. note::

      An object is not guaranteed to be automatically finalized before its
      destructor (:c:member:`~PyTypeObject.tp_dealloc`) is called.  It is
      recommended to call :c:func:`PyObject_CallFinalizerFromDealloc` at the
      beginning of :c:member:`!tp_dealloc` to guarantee that the object is
      always finalized before destruction.

-   .. warning::
+   .. note::

      The :c:member:`~PyTypeObject.tp_finalize` function can be called from any
      thread, although the :term:`GIL` will be held.

-   .. warning::
+   .. note::

      The :c:member:`!tp_finalize` function can be called during shutdown,
      after some global variables have been deleted.  See the documentation of