Welcome to Pyccolo’s documentation!

Pyccolo (pronounced like the instrument “piccolo”) is a library for declarative instrumentation in Python: you specify the what of the instrumentation you wish to perform, and Pyccolo takes care of the how. It brings metaprogramming to everybody through general, event-emitting AST transformations, and aims to be:

  • ergonomic — you subclass pyccolo.BaseTracer and decorate a handler; there’s no bytecode to patch and no ast.NodeTransformer to hand-write;

  • composable — layering multiple, independently-written instrumentations usually Just Works (see Composing tracers);

  • portable — the same code runs across Python 3.6 through 3.14, with few exceptions, because instrumentation is embedded at the level of source code rather than bytecode.

Here is the smallest interesting program: a tracer that prints "Hello, world!" before every statement that executes.

import pyccolo as pyc


class HelloTracer(pyc.BaseTracer):
    @pyc.before_stmt
    def handle_stmt(self, *_, **__):
        print("Hello, world!")


with HelloTracer:
    # prints "Hello, world!" 11 times
    pyc.exec("for _ in range(10): pass")

New here? Start with Installation, then walk through Quickstart. From there, The model: events and handlers is the conceptual heart of the library. Looking for a specific class or function? Jump to the API reference, or the Command line interface for the pyc command-line tool.

Getting started

Concepts

Reference

Indices and tables