Repository navigation
Inconsistencies in error propagation after calling _PyFrame_GetFrameObject #144693
Description
Activity
_PyFrame_GetFrameObjectis not setting an exception (but preserves it if it exists).PyFrame_GetBackcan return NULL and this is handled byframe_back_get_impl, for example. In this caseframe.f_backwill haveNonevalue.From
Pythonpoint of view,frame.f_backandPyFrame_GetBackcan'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 aPyFrame_GetBack.Maybe it is worth to update a documentation that API preserves existing exceptions.
Reacted by Petr ViktorinIt seems that
_PyFrame_GetLocalspotentially can be called withframe == 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.Reacted by Taegyun KimI believe
_gen_getframe,PyEval_GetLocalsshould have NULL checks or at least asserts.sys__getframe_impl,_PyThread_CurrentFrames,_Py_call_instrumentation_lineshould set an exception if_PyFrame_GetFrameObjectreturns NULL._PyEval_ExceptionGroupMatchseems OK.cc @markshannon as an owner
cc @colesbury as an expertWould you like open PRs? If so please open two separate PRs, one for documentation update, one for _PyFrame_GetLocals.
Sure will do shortly
From C-API point of view, it is responsibility of the user to handle exceptions that can exist before calling a
PyFrame_GetBack.Yes, that's the general expectation for public C API functions. The behaviour is undefined if called with an active exception. If preserving the exception isn't documented, it's an implementation detail that can change in future versions.
I'm not sure if the frame experts want to turn it into a documented guarantee.
- added a commit that references this issue
on Feb 27, 2026
Bug report
Bug description:
There are 3 callers of
_PyFrame_GetFrameObjectwhich explicitly clear error when it returns NULL.take_ownershipcpython/Python/frame.c
Lines 74 to 79 in b67a64d
PyEval_GetFramecpython/Python/ceval.c
Lines 2562 to 2564 in b67a64d
PyThreadState_GetFramecpython/Python/pystate.c
Lines 2101 to 2103 in b67a64d
PyEval_GetFrameandPyThreadState_GetFramedocs 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_GetBackalso would want to clear errorcpython/Objects/frameobject.c
Lines 2407 to 2409 in b67a64d
PyFrame_GetBack's documentation doesn't say anything aboutMemoryErrorwhich can be set by its internal API calls https://docs.python.org/3.15/c-api/frame.html#c.PyFrame_GetBackThe rest of the
_PyFrame_GetFrameObjectcallers that don't clear error includingPyFrame_GetBackare_PyEval_ExceptionGroupMatch_PyEval_EvalFrameDefault(error label)_gen_getframesys__getframe_impl_PyThread_CurrentFrames_Py_call_instrumentation_line_PyFrame_GetLocalsPyEval_GetLocals— Public C API (deprecated), no NULL checkPyFrame_GetBack— Public C API, no NULL checkAnd
PyEval_GetLocalsandPyFrame_GetBackare 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_GetBacknot clearing error on null is ok/intended or it's a discrepancy/bug?I would prefer
PyFrame_GetBackto 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
Linked PRs
PyFrame_GetBackdoes not raise exceptions (GH-144824) #145318PyFrame_GetBackdoes not raise exceptions (GH-144824) #145319