bpo-46355: What's New: Note that PyFrameObject are private (GH-31032)

This adds a slightly more detailed explanation of the change.
The most important point is that the changed/removed fields
were "subject to change" to begin with.

1 files changed, 20 insertions, 9 deletions

diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index e054008..e7f3dab 100644
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -759,12 +759,19 @@ Porting to Python 3.11
   which are not available in the limited C API.
   (Contributed by Victor Stinner in :issue:`46007`.)
 
-* Changes of the :c:type:`PyFrameObject` structure members:
+* Changes of the private :c:type:`PyFrameObject` structure members.
+
+  While the documentation notes that the fields of ``PyFrameObject`` are
+  subject to change at any time, they have been stable for a long time
+  and were used in several popular extensions.
+  In Python 3.11, the frame struct was reorganized to allow performance
+  optimizations. Rather than reading the fields directly, extensions should
+  use functions:
 
   * ``f_code``: removed, use :c:func:`PyFrame_GetCode` instead.
     Warning: the function returns a :term:`strong reference`, need to call
     :c:func:`Py_DECREF`.
-  * ``f_back``: changed, use :c:func:`PyFrame_GetBack`.
+  * ``f_back``: changed (see below), use :c:func:`PyFrame_GetBack`.
   * ``f_builtins``: removed,
     use ``PyObject_GetAttrString(frame, "f_builtins")``.
   * ``f_globals``: removed,
@@ -773,13 +780,17 @@ Porting to Python 3.11
     use ``PyObject_GetAttrString(frame, "f_locals")``.
   * ``f_lasti``: removed,
     use ``PyObject_GetAttrString(frame, "f_lasti")``.
-  * ``f_valuesstack``: removed.
-  * ``f_stackdepth``: removed.
-  * ``f_gen``: removed.
-  * ``f_iblock``: removed.
-  * ``f_state``: removed.
-  * ``f_blockstack``: removed.
-  * ``f_localsplus``: removed.
+
+  The following fields were removed entirely, as they were details
+  of the old implementation:
+
+  * ``f_valuesstack``
+  * ``f_stackdepth``
+  * ``f_gen``
+  * ``f_iblock``
+  * ``f_state``
+  * ``f_blockstack``
+  * ``f_localsplus``
 
   The Python frame object is now created lazily. A side effect is that the
   ``f_back`` member must not be accessed directly, since its value is now also