Pyccolo (pronounced like "piccolo") is a library for declarative instrumentation in Python, allowing users to specify *what* instrumentation to perform rather than *how* to implement it. It aims for ergonomics, composability, and portability across various Python versions. It achieves this by embedding instrumentation at the source code level. The library is actively maintained, with the current version being 0.0.85, and supports Python versions from 3.6 up to 3.14 (since v0.0.73).
pip install pyccoloVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to create a custom tracer that logs statements before execution. It highlights the use of `BaseTracer` and the `should_instrument_file` method to control which files are instrumented, as well as a `before_stmt` event handler.
Subclass `pyccolo.BaseTracer` and override the `should_instrument_file(self, filename: str) -> bool` method to return `True` for the desired module filenames.
Use `return pyccolo.Null` if you want to set the overridden value to `None`. Otherwise, `return None` will cause the original expression's value to be used.
Ensure your project is running on Python 3.8 or newer when using syntax augmentation. Also, activate the correct tracer (e.g., `pyccolo.examples.OptionalChainer`) that implements the desired syntax transformation.
Pyccolo aims to execute both its handlers and any active `sys.settrace` functions. If conflicts arise, simplify your tracing setup to isolate the issue, and consult Pyccolo's documentation or examples (e.g., how it co-exists with `coverage.py`).
Run `pip install pyccolo` in your terminal to install the library.
Ensure your custom `BaseTracer` implementation's `should_instrument_file` method correctly identifies and allows the target file(s) to be instrumented. Remember that instrumentation is opt-in for imports.
Verify that your Python interpreter is version 3.8 or higher. If the syntax is a `pyccolo` augmentation, ensure the corresponding tracer (e.g., `pyccolo.examples.OptionalChainer`) is activated.
If the intention is to explicitly set the expression's value to `None` from a handler, return `pyccolo.Null` instead of `None`.
No dependency data recorded yet.