pyccolo

What it is and what it does

Pyccolo is a metaprogramming library that instruments Python code by rewriting its abstract syntax tree to emit fine-grained events—over 100 event types covering statements, attribute access, operators, assignments, literals, calls, and returns. Instead of manually patching bytecode or writing ast.NodeTransformer classes, you subclass BaseTracer, decorate handler methods with event decorators like @pyc.before_stmt or @pyc.after_assign_rhs, and register them to observe or modify behavior. Handlers receive the instrumented value, AST node, stack frame, and event object, and can override the value that flows out of an expression by returning a replacement.

The library is designed to be ergonomic, composable, and portable. Multiple independently-written tracers can be nested in context managers and their handlers compose automatically without manual conflict resolution. Because instrumentation is embedded at the source level rather than bytecode, the same code runs across Python 3.6 through 3.14. It powers production tools like ipyflow (a reactive Jupyter kernel), pipescript (pipe operators and macros for IPython), and pycograd (automatic differentiation for plain numpy code), and has been used to build code coverage, syntactic macros, optional chaining, lazy imports, and concolic execution tools.

Use it for

• Build a reactive notebook kernel that tracks dataflow between cells by instrumenting variable assignments and attribute access.
• Implement statement-level code coverage by registering a handler on before_stmt to log which lines execute.
• Add syntax extensions like pipe operators or optional chaining by defining an AugmentationSpec and attaching handlers to the resulting AST nodes.
• Trace computation graphs for automatic differentiation by intercepting operations on ordinary numpy arrays without requiring a special namespace.
• Instrument imports to implement lazy loading or concolic execution by hooking module load events.

Worth the install?

AI-flagged interpretation of the facts on this page. Verify before relying on it.

Install

pyccolo on PyPI

Before you install

Low friction: pure Python wheel with only two lightweight runtime dependencies (traitlets and typing_extensions). Active maintenance with a recent release 34 days ago and ongoing repository activity.

Code to be instrumented must be passed to pyc.exec() or imported inside a tracing context; source code at module level where the tracer class is defined will not be instrumented unless quoted.

License in practice

BSD-3-Clause is permissive; you can use, modify, and distribute Pyccolo with minimal restrictions, provided you include the license notice.

Quickstart

pip install pyccolo

import pyccolo as pyc

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

with HelloTracer:
    pyc.exec("for _ in range(10): pass")

Package facts

Evidence: pyccolo-0.0.94-py2.py3-none-any.whl

Tags

More Software Development packages

See also google-pasta · ipyflow-core · aiocop · pycnite · dncil · diastatic-malt · llama-index-instrumentation · ast-grep-py · Rx · logfury