3.11.4 The interpreter stack

When the following functions return ``frame records,'' each record is a tuple of six items: the frame object, the filename, the line number of the current line, the function name, a list of lines of context from the source code, and the index of the current line within that list. The optional context argument specifies the number of lines of context to return, which are centered around the current line.

Warning: Keeping references to frame objects, as found in the first element of the frame records these functions return, can cause your program to create reference cycles. Once a reference cycle has been created, the lifespan of all objects which can be accessed from the objects which form the cycle can become much longer even if Python's optional cycle detector is enabled. If such cycles must be created, it is important to ensure they are explicitly broken to avoid the delayed destruction of objects and increased memory consumption which occurs.

getframeinfo( frame[, context]): Get information about a frame or traceback object. A 5-tuple is returned, the last five elements of the frame's frame record. The optional second argument specifies the number of lines of context to return, which are centered around the current line.

getouterframes( frame[, context]): Get a list of frame records for a frame and all higher (calling) frames.

getinnerframes( traceback[, context]): Get a list of frame records for a traceback's frame and all lower frames.

currentframe( ): Return the frame object for the caller's stack frame.

stack( [context]): Return a list of frame records for the stack above the caller's frame.

trace( [context]): Return a list of frame records for the stack below the current exception.

Stackframes stored directly or indirectly in local variables can easily cause reference cycles. Though the cycle detector will catch these, destruction of the frames (and local variables) can be made deterministic by removing the cycle in a finally clause. This is also important if the cycle detector was disabled when Python was compiled or using gc.disable(). For example:

def handle_stackframe_without_leak():
    frame = inspect.currentframe()
    try:
        # do something with the frame
    finally:
        del frame

See About this document... for information on suggesting changes.