---
id: pyccolo
version: "0.0.94"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# pyccolo — Declarative instrumentation for Python

License: permissive · Maintenance: active · Downloads: 223.0K/mo

## 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 above — verify before relying.

Pyccolo is a library for declarative instrumentation in Python that rewrites source code with event-emitting AST transformations, letting you specify what instrumentation to perform and handling the implementation details automatically.

Yes, with conditions. Pyccolo is actively maintained, has no known vulnerabilities, and installs with minimal friction. It is genuinely useful for building observability and syntax-augmentation tools that would otherwise require manual bytecode patching or complex AST visitor logic. However, it is classified as Alpha, so production use should account for potential API changes. Start with it if you need composable, source-level instrumentation; avoid it if you need guaranteed stability or are looking for a simple logging library.

## Install

pip install pyccolo
uv add pyccolo
poetry add pyccolo

## Installing pyccolo

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.

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")

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.

Verify before relying:

- Performance overhead of AST transformation and event emission at runtime compared to uninstrumented code.
- Compatibility edge cases or limitations across the stated Python 3.6–3.14 range beyond the general claim of portability.
- Maturity and stability guarantees given the Alpha development status classification.

## Package facts

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 223.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

python ast instrumentation, declarative code tracing, dynamic analysis framework, python metaprogramming, event-driven code transformation, source code rewriting, python bytecode-free instrumentation, metaprogramming, ast-transformation, dynamic-analysis

[View on SkillFed](https://skillfed.io/packages/pyccolo) · [View on PyPI](https://pypi.org/project/pyccolo/)