Update documentation on PyObject opaqueness and module init

Clarified access restrictions on PyObject members and recommended functions for type and reference count manipulation.
python · clin1234 · Apr 12, 2026 · Apr 12, 2026 · Apr 12, 2026 · Apr 12, 2026
commit 0e89d379f61a48570a3b56193dc9cf7b76b15584
diff --git a/Doc/howto/freethreading-stable-abi.rst b/Doc/howto/freethreading-stable-abi.rst
@@ -29,6 +29,12 @@ You can use it to enable code that only runs under the free-threaded build::
    can be used to determine whether the current running interpreter had the
    macro defined.
 
+`PyObject` opaqueness
+=====================
+
+Accessing any member of `PyObject` is now prohibited, like the non-GIL
+stable ABI. For instance, prefer `Py_Type()` and `Py_SET_TYPE()` over manipulating `ob_type` directly,
+`Py_REFCNT`, `Py_INCREF()` and `Py_DecRef().` over `ob_refcnt`, etc.
 
 Module Initialization
 =====================
@@ -412,10 +418,9 @@ Limited C API and Stable ABI
 
 If you use
 `setuptools <https://setuptools.pypa.io/en/latest/setuptools.html>`_ to build
-your extension, a future version of `setuptools` will allow ``py_limited_api=True`` 
+your extension, a future version of `setuptools` will allow ``py_limited_api=True``
 to be set to allow targeting limited API when building with the free-threaded build.
 
-
 Windows
 .......