gh-139924: Add PyFunction_PYFUNC_EVENT_MODIFY_QUALNAME event for function watchers

Doc/c-api/function.rst

@@ -175,6 +175,9 @@ There are a few functions specific to Python functions.
 
    .. versionadded:: 3.12
 
+    - ``PyFunction_PYFUNC_EVENT_MODIFY_QUALNAME``
+
+   .. versionadded:: 3.15
 
 .. c:type:: int (*PyFunction_WatchCallback)(PyFunction_WatchEvent event, PyFunctionObject *func, PyObject *new_value)
 

Include/cpython/funcobject.h

@@ -134,7 +134,8 @@ PyAPI_FUNC(PyObject *) PyStaticMethod_New(PyObject *);
     V(DESTROY)                   \
     V(MODIFY_CODE)               \
     V(MODIFY_DEFAULTS)           \
-    V(MODIFY_KWDEFAULTS)
+    V(MODIFY_KWDEFAULTS)         \
+    V(MODIFY_QUALNAME)
 
 typedef enum {
     #define PY_DEF_EVENT(EVENT) PyFunction_EVENT_##EVENT,

Lib/test/test_capi/test_watchers.py

@@ -514,6 +514,10 @@ def myfunc():
             _testcapi.set_func_kwdefaults_via_capi(myfunc, new_kwdefaults)
             self.assertIn((_testcapi.PYFUNC_EVENT_MODIFY_KWDEFAULTS, myfunc, new_kwdefaults), events)
 
+            new_qualname = "foo.bar"
+            myfunc.__qualname__ = new_qualname
+            self.assertIn((_testcapi.PYFUNC_EVENT_MODIFY_QUALNAME, myfunc, new_qualname), events)
+
             # Clear events reference to func
             events = []
             del myfunc

Misc/NEWS.d/next/C_API/2025-10-10-20-59-07.gh-issue-139924.ALByCb.rst

@@ -0,0 +1 @@
+Function watchers can now receive a PyFunction_PYFUNC_EVENT_MODIFY_QUALNAME event when a watched functions qualname is changed.

Objects/funcobject.c

@@ -62,6 +62,7 @@ handle_func_event(PyFunction_WatchEvent event, PyFunctionObject *func,
         case PyFunction_EVENT_MODIFY_CODE:
         case PyFunction_EVENT_MODIFY_DEFAULTS:
         case PyFunction_EVENT_MODIFY_KWDEFAULTS:
+        case PyFunction_EVENT_MODIFY_QUALNAME:
             RARE_EVENT_INTERP_INC(interp, func_modification);
             break;
         default:
@@ -747,6 +748,7 @@ func_set_qualname(PyObject *self, PyObject *value, void *Py_UNUSED(ignored))
                         "__qualname__ must be set to a string object");
         return -1;
     }
+    handle_func_event(PyFunction_EVENT_MODIFY_QUALNAME, (PyFunctionObject *) op, value);
     Py_XSETREF(op->func_qualname, Py_NewRef(value));
     return 0;
 }