Event taxonomy

Pyccolo emits over a hundred distinct events. Every one is a member of pyccolo.trace_events.TraceEvent and is also re-exported at the top level, so pyc.before_stmt and TraceEvent.before_stmt are the same object. You register a handler for an event with the decorator or registration API, and the handler is invoked with the standard handler signature.

Note

The table below is generated at build time directly from pyccolo/trace_events.py — the list of events, and the thunk / sys / ast flags, come straight from the source, so this page cannot drift from the library. If you are reading a released version, it describes exactly the events that version emits.

How to read the table

• Fires on — the source construct (and moment) that triggers the event.

• Handler return — what the value your handler returns does. The common contracts are:

  • replacement value — the returned value replaces the value flowing out of the instrumented expression (return None to leave it unchanged; return pyccolo.Null to force an actual None). This is what powers behavior-changing tracers.

  • callable (thunk) — the event fires before an expression is evaluated, so the value in flight is a zero-argument callable that produces it. Return a (possibly different) callable to control whether and how it runs. These are exactly the events flagged thunk (they live in BEFORE_EXPR_EVENTS).

  • observe only — the event is a notification; the return value is ignored (aside from the universal pyccolo.Skip / pyccolo.SkipAll controls).

• Flags:

  • thunk — a “before-expression” event; the handler receives/returns a thunk. See Handlers for the calling convention.

  • sys — a native sys.settrace event; no AST rewriting is involved, so it fires without pyc.exec (see Tracing real programs).

  • ast: NodeType — you may register a handler by passing this ast node type instead of the event, via AST_TO_EVENT_MAPPING (e.g. @pyc.register_handler(ast.Assign) is after_assign_rhs).

See also

Handlers for the exact arguments each handler receives, the sentinels (Null, Skip, SkipAll, Pass), and the thunk convention; Registering handlers for the decorator options (when=, guard=, reentrant=, …).

The events

Module & import lifecycle

Event	Fires on	Handler return	Flags
before_import	an import statement is about to run	observe only	—
init_module	a module body begins executing	observe only	ast: Module
exit_module	a module body finishes executing	observe only	—
after_import	an import statement has run	observe only	—

Statements

Event	Fires on	Handler return	Flags
before_stmt	each statement, before it runs	a thunk to run instead, or pyc.Pass to skip the statement	—
after_stmt	each statement, after it runs	observe only	ast: stmt
after_module_stmt	a top-level module statement finishes	replacement value (the displayed result)	—
after_expr_stmt	a bare expression statement finishes	replacement value	—
before_assert	an assert statement, before it runs	observe only	—
after_assert	an assert statement, after it runs	observe only	—

Names & literals

Event	Fires on	Handler return	Flags
load_name	a bare name is loaded (e.g. foo)	replacement value	ast: Name
after_bool	a True / False literal is evaluated	replacement value	—
after_int	an int literal is evaluated	replacement value	—
after_float	a float literal is evaluated	replacement value	—
after_complex	a complex literal is evaluated	replacement value	—
after_string	a str literal is evaluated	replacement value	—
after_bytes	a bytes literal is evaluated	replacement value	—
after_none	a None literal is evaluated	replacement value	—
ellipsis	an ... (Ellipsis) literal is evaluated	replacement value	ast: Ellipsis
before_fstring	an f-string, before it is built	callable (thunk)	thunk
after_fstring	an f-string, after it is built	replacement value	—

Assignment

Event	Fires on	Handler return	Flags
before_assign_rhs	the right-hand side of an assignment, before it runs	callable (thunk)	thunk
after_assign_rhs	the right-hand side of an assignment, after it runs	replacement value	ast: Assign
before_augassign_rhs	the RHS of an augmented assignment (+= etc.), before it runs	callable (thunk)	thunk
after_augassign_rhs	the RHS of an augmented assignment, after it runs	replacement value	—

Attributes & subscripts

Event	Fires on	Handler return	Flags
before_attribute_load	an attribute load obj.attr, before dereference	the receiver object to dereference	—
after_attribute_load	an attribute load, after dereference	replacement value	ast: Attribute
before_attribute_store	an attribute store obj.attr = ...	observe only	—
before_attribute_del	an attribute delete del obj.attr	observe only	—
before_subscript_load	a subscript load obj[key], before dereference	the receiver object to dereference	—
after_subscript_load	a subscript load, after dereference	replacement value	ast: Subscript
before_subscript_store	a subscript store obj[key] = ...	observe only	—
before_subscript_del	a subscript delete del obj[key]	observe only	—
before_subscript_slice	the slice/key of a subscript, before it is evaluated	callable (thunk)	thunk
after_subscript_slice	the slice/key of a subscript, after it is evaluated	replacement value	—
before_load_complex_symbol	a compound load (chained attribute/subscript/call), before it runs	callable (thunk)	thunk
after_load_complex_symbol	a compound load, after it runs	replacement value	—

Calls & arguments

Event	Fires on	Handler return	Flags
decorator	a decorator is applied	replacement value (the decorator)	—
before_call	a call f(...), before invocation	the callable to invoke	—
after_call	a call f(...), after it returns	replacement value	ast: Call
before_argument	a call argument, before it is evaluated	callable (thunk)	thunk
after_argument	a call argument, after it is evaluated	replacement value	ast: arg
before_return	a return value, before it is evaluated	callable (thunk)	thunk
after_return	a return value, after it is evaluated	replacement value	ast: Return

Operators

Event	Fires on	Handler return	Flags
before_binop	a binary op x + y, before it runs	callable (thunk)	thunk
after_binop	a binary op, after it runs	replacement value (result)	ast: BinOp
before_left_binop_arg	the left operand of a binop, before it runs	callable (thunk)	thunk
after_left_binop_arg	the left operand of a binop, after it runs	replacement value	—
before_right_binop_arg	the right operand of a binop, before it runs	callable (thunk)	thunk
after_right_binop_arg	the right operand of a binop, after it runs	replacement value	—
before_unaryop	a unary op -x / not x, before it runs	callable (thunk)	thunk
after_unaryop	a unary op, after it runs	replacement value (result)	ast: UnaryOp
before_unaryop_arg	the operand of a unary op, before it runs	callable (thunk)	thunk
after_unaryop_arg	the operand of a unary op, after it runs	replacement value	—
before_boolop	a boolean op x and y / x or y, before it runs	callable (thunk)	thunk
after_boolop	a boolean op, after it runs	replacement value (result)	—
before_boolop_arg	an operand of a boolean op, before it runs	callable (thunk)	thunk
after_boolop_arg	an operand of a boolean op, after it runs	replacement value	—
before_compare	a comparison x < y, before it runs	callable (thunk)	thunk
after_compare	a comparison, after it runs	replacement value (result)	ast: Compare
left_compare_arg	the left operand of a comparison	replacement value	—
compare_arg	a right-hand operand of a comparison	replacement value	—

Collection literals

Event	Fires on	Handler return	Flags
before_list_literal	a list literal [...], before it is built	callable (thunk)	thunk
after_list_literal	a list literal, after it is built	replacement value	ast: List
before_tuple_literal	a tuple literal (...), before it is built	callable (thunk)	thunk
after_tuple_literal	a tuple literal, after it is built	replacement value	ast: Tuple
before_set_literal	a set literal {...}, before it is built	callable (thunk)	thunk
after_set_literal	a set literal, after it is built	replacement value	ast: Set
before_dict_literal	a dict literal {k: v}, before it is built	callable (thunk)	thunk
after_dict_literal	a dict literal, after it is built	replacement value	ast: Dict
list_elt	an element of a list literal	replacement value	—
tuple_elt	an element of a tuple literal	replacement value	—
set_elt	an element of a set literal	replacement value	—
dict_key	a key of a dict literal	replacement value	—
dict_value	a value of a dict literal	replacement value	—

Comprehensions

Event	Fires on	Handler return	Flags
after_comprehension_if	a comprehension if predicate is evaluated	replacement value	—
after_comprehension_elt	a comprehension element is evaluated	replacement value	—
after_dict_comprehension_key	a dict-comprehension key is evaluated	replacement value	—
after_dict_comprehension_value	a dict-comprehension value is evaluated	replacement value	—

Control flow

Event	Fires on	Handler return	Flags
after_if_test	the test of an if is evaluated	replacement value (test result)	—
after_while_test	the test of a while is evaluated	replacement value (test result)	—
before_for_loop_body	a for loop body, before each iteration	observe only	—
after_for_loop_iter	a for loop body, after each iteration	observe only (guarded)	—
before_while_loop_body	a while loop body, before each iteration	observe only	—
after_while_loop_iter	a while loop body, after each iteration	observe only (guarded)	—
before_for_iter	the iterable of a for loop, before iteration	callable (thunk)	thunk
after_for_iter	the iterable of a for loop, after iteration	replacement value	—

Functions & lambdas

Event	Fires on	Handler return	Flags
before_function_body	a function body, before it executes	observe only	—
after_function_execution	a function body, after it executes	observe only (guarded)	—
before_lambda	a lambda expression, before it is created	callable (thunk)	thunk
after_lambda	a lambda expression, after it is created	replacement value	—
before_lambda_body	a lambda body, before it executes	observe only	—
after_lambda_body	a lambda body, after it executes	replacement value	—

Exceptions

Event	Fires on	Handler return	Flags
exception_handler_type	the type in an except T: clause is evaluated	replacement value (the caught type)	—

sys.settrace events

Event	Fires on	Handler return	Flags
line	sys.settrace fires for a new source line	observe only	sys
call	a stack frame is pushed (sys.settrace)	observe only	sys
return_	a stack frame is popped (sys.settrace)	observe only	sys
exception	an exception is raised (sys.settrace)	observe only	sys
opcode	a bytecode opcode executes (opt-in, sys.settrace)	observe only	sys
c_call	a C function is called (sys.settrace)	observe only (rarely used)	—
c_return	a C function returns (sys.settrace)	observe only (rarely used)	—
c_exception	a C function raises (sys.settrace)	observe only (rarely used)	—

class pyccolo.trace_events.TraceEvent(*values)