The call stack — Introspection documentation

# The call stack

class `introspection.` `CallStack`(frames)

  Represents the call stack - a series of `CallFrame` instances.

  This class can be used like a read-only list. It supports iteration, indexing, membership testing, etc. The root frame is first in the list, at index 0.

  Because holding references to call frames can result in reference cycles, it’s recommended to use CallStack objects as context managers. Upon exit, the frame objects are released and the CallStack becomes empty:

      with CallStack.current() as stack:
          ...  # do something with the stack
      # at this point, len(stack) is 0

  `__init__`(frames)

    Creates a new `CallStack` from the given frame objects.

    Parameters

      frames (Iterable[Union[CallFrame, frame]]) – An iterable of frame objects, starting with the root frame

  classmethod `current`()

    Get the current call stack.

    Return type

      CallStack

  classmethod `from_frame`(frame)

    Creates a `CallStack` containing `frame` and all its parents.

    Parameters

      frame – The last frame in the call stack

    Returns

      A new `CallStack` instance

    Return type

      CallStack

class `introspection.` `CallFrame`(frame)

  Represents a call frame - an element of the call stack. It keeps track of local and closure variables.

  Although `CallFrame` does not inherit from `types.FrameType`, they can be used just like regular frame objects.

  Note that storing CallFrames in variables can create reference cycles where a frame contains a reference to itself. To avoid this, CallFrames can be used as context managers - upon exit, the reference to the underlying frame object is released:

      with CallFrame.current() as frame:
          ...  # do stuff with the frame
      # at this point, the frame has become unusable

  `__init__`(frame)

    Creates a new `CallFrame` from a `CallFrame` or `types.FrameType` object.

    Parameters

      frame – An existing frame object

  classmethod `current`()

    Retrieves the current call frame.

    Return type

      CallFrame

  classmethod `from_frame`(frame)

    Creates a new `CallFrame` from a `CallFrame` or `types.FrameType` object.

    This is equivalent to calling `CallFrame(frame)`.

  property `parent`

    Returns the next frame one level higher on the call stack.

  property `builtins`

    Returns the builtins seen by this frame

  property `globals`

    Returns the global scope seen by this frame

  property `locals`

    Returns the frame’s local variable scope

  property `code_object`

    Returns the code object being executed in this frame

  property `file_name`

    Returns the name of the file in which this frame’s code was defined

  property `scope_name`

    Returns the name of the scope in which this frame’s code was defined. In case of a function, the function’s name. In case of a class, the class’s name. In any other case, whichever name the interpreter assigned to that scope.

  `resolve_name`(name)

    Resolves a variable name, returning the variable’s value.

    Note

    Closure variables don’t have a named associated with them, which means they cannot be looked up with this function.

    This includes variables marked as `nonlocal`.

    Parameters

      name (str) – The name of the variable you want to look up

    Returns

      The value mapped to the given name

    Raises

      NameError – If no matching variable is found

  `get_surrounding_function`()

    Finds and returns the function in which the code of this frame was defined.

    If the function can’t be found, `None` is returned.

    Returns

      The calling function object or `None` if it can’t be found