Currentframe

Currentframe is a function in Python’s standard library (the inspect module) that returns the frame object for the caller’s stack frame. It is a debugging and introspection aid, used to inspect the local and global context of the code that is currently executing. The function returns a frame object of type types.FrameType or None if no frame is accessible.

A frame object exposes several attributes that describe the execution context. Key attributes include f_globals (the global namespace), f_locals (the local namespace), f_code (the compiled code object), and f_lineno (the current line number). Frames are linked via f_back, which points to the previous frame in the call stack, enabling stack traversal from the current point outward. This makes currentframe useful for constructing lightweight debuggers, tracers, or custom logging that includes runtime state.

Usage considerations are important. While powerful, using currentframe can keep references to large local variables alive, potentially creating reference cycles and hindering garbage collection. It also introduces overhead and may behave differently across Python implementations or optimized builds. Therefore, it is generally recommended to use currentframe only when necessary, and to promptly release references to the frame object after use (for example, by deleting variables that hold the frame).

In CPython, inspect.currentframe is typically implemented as a safe wrapper around sys._getframe(1), returning the caller’s frame. For alternatives or deeper stack access, sys._getframe(depth) can be used directly. If a frame is not available, these calls may return None. See also the traceback module and the FrameType API for related tooling.