Inconsistencies in error propagation after calling `_PyFrame_GetFrameObject`

[taegyunkim]

Bug report

Bug description:

There are 3 callers of _PyFrame_GetFrameObject which explicitly clear error when it returns NULL.

1. take_ownership

   cpython/Python/frame.c

   Lines 74 to 79 in b67a64d

   	PyFrameObject *back = _PyFrame_GetFrameObject(prev);
   	if (back == NULL) {
   	/* Memory error here. */
   	assert(PyErr_ExceptionMatches(PyExc_MemoryError));
   	/* Nothing we can do about it */
   	PyErr_Clear();

2. PyEval_GetFrame

   cpython/Python/ceval.c

   Lines 2562 to 2564 in b67a64d

   	PyFrameObject *f = _PyFrame_GetFrameObject(frame);
   	if (f == NULL) {
   	PyErr_Clear();

3. PyThreadState_GetFrame

   cpython/Python/pystate.c

   Lines 2101 to 2103 in b67a64d

   	PyFrameObject *frame = _PyFrame_GetFrameObject(f);
   	if (frame == NULL) {
   	PyErr_Clear();

PyEval_GetFrame and PyThreadState_GetFrame docs say that NULL is returned when "no frame is currently executing", and doesn't say anything about any error (probably as they explicitly clear it?).

I wonder whether PyFrame_GetBack also would want to clear error

cpython/Objects/frameobject.c

Lines 2407 to 2409 in b67a64d

	if (prev) {
	back = _PyFrame_GetFrameObject(prev);
	}

PyFrame_GetBack's documentation doesn't say anything about MemoryError which can be set by its internal API calls https://docs.python.org/3.15/c-api/frame.html#c.PyFrame_GetBack

The rest of the _PyFrame_GetFrameObject callers that don't clear error including PyFrame_GetBack are

• _PyEval_ExceptionGroupMatch
• _PyEval_EvalFrameDefault (error label)
• _gen_getframe
• sys__getframe_impl
• _PyThread_CurrentFrames
• _Py_call_instrumentation_line
• _PyFrame_GetLocals
• PyEval_GetLocals — Public C API (deprecated), no NULL check
• PyFrame_GetBack — Public C API, no NULL check

And PyEval_GetLocals and PyFrame_GetBack are public C APIs that don't check for NULL and don't clear the error. I guess the internals are ok to propagate the errors?

Can someone explain whether PyFrame_GetBack not clearing error on null is ok/intended or it's a discrepancy/bug?

I would prefer PyFrame_GetBack to not propagate an error given that its documentation doesn't say anything about MemoryError.

CPython versions tested on:

CPython main branch

Operating systems tested on:

No response

[sergey-miryanov]

_PyFrame_GetFrameObject is not setting an exception (but preserves it if it exists). PyFrame_GetBack can return NULL and this is handled by frame_back_get_impl, for example. In this case frame.f_back will have None value.

From Python point of view, frame.f_back and PyFrame_GetBack can't be called with exception set.
From C-API point of view, it is responsibility of the user to handle exceptions that can exist before calling a PyFrame_GetBack.

Maybe it is worth to update a documentation that API preserves existing exceptions.

[sergey-miryanov]

It seems that _PyFrame_GetLocals potentially can be called with frame == NULL, maybe it is worth to add checks there.

Would you like open PRs? If so please open two separate PRs, one for documentation update, one for _PyFrame_GetLocals.

[sergey-miryanov]

I believe _gen_getframe, PyEval_GetLocals should have NULL checks or at least asserts.

sys__getframe_impl, _PyThread_CurrentFrames, _Py_call_instrumentation_line should set an exception if _PyFrame_GetFrameObject returns NULL.

_PyEval_ExceptionGroupMatch seems OK.

[sergey-miryanov]

cc @markshannon as an owner
cc @colesbury as an expert

[taegyunkim]

Would you like open PRs? If so please open two separate PRs, one for documentation update, one for _PyFrame_GetLocals.

Sure will do shortly