24.2 How It Works

Some changes were made to the interpreter:

sys.settrace(func) sets the global trace function
there can also a local trace function (see later)

Trace functions have three arguments: frame, event, and arg. frame is the current stack frame. event is a string: 'call', 'line', 'return', 'exception', 'c_call', 'c_return', or 'c_exception'. arg depends on the event type.

The global trace function is invoked (with event set to 'call') whenever a new local scope is entered; it should return a reference to the local trace function to be used that scope, or None if the scope shouldn't be traced.

The local trace function should return a reference to itself (or to another function for further tracing in that scope), or None to turn off tracing in that scope.

Instance methods are accepted (and very useful!) as trace functions.

The events have the following meaning:

'call': A function is called (or some other code block entered). The global trace function is called; arg is None; the return value specifies the local trace function.
'line': The interpreter is about to execute a new line of code (sometimes multiple line events on one line exist). The local trace function is called; arg is None; the return value specifies the new local trace function.
'return': A function (or other code block) is about to return. The local trace function is called; arg is the value that will be returned. The trace function's return value is ignored.
'exception': An exception has occurred. The local trace function is called; arg is a triple (exception, value, traceback); the return value specifies the new local trace function.
'c_call': A C function is about to be called. This may be an extension function or a builtin. arg is the C function object.
'c_return': A C function has returned. arg is None.
'c_exception': A C function has thrown an exception. arg is None.

Note that as an exception is propagated down the chain of callers, an 'exception' event is generated at each level.

For more information on code and frame objects, refer to the Python Reference Manual.

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