{"library":"pyccolo","title":"Pyccolo: Declarative Instrumentation for Python","description":"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).","language":"python","status":"active","last_verified":"Thu Apr 16","install":{"commands":["pip install pyccolo"],"cli":null},"imports":["from pyccolo import BaseTracer","from pyccolo import before_stmt","from pyccolo import Null"],"auth":{"required":false,"env_vars":[]},"quickstart":{"code":"import pyccolo as pyc\n\nclass MyTracer(pyc.BaseTracer):\n    def should_instrument_file(self, filename: str) -> bool:\n        # Only instrument files ending with 'my_script.py'\n        # For broader instrumentation, adjust this logic.\n        return 'my_script.py' in filename\n\n    @pyc.before_stmt\n    def on_before_statement(self, ret, node, frame, event):\n        print(f\"Executing statement: {node.lineno}: {node.__class__.__name__}\")\n\n# Example usage with a dummy script content\nscript_content = \"\"\"\nprint(\"Hello from my_script.py\")\nx = 1 + 2\nif x == 3:\n    print(\"x is 3\")\n\"\"\"\n\n# To simulate a file, we can use exec with a custom globals dict\n# and then trace its execution within a temporary module scope.\nimport types\nimport sys\n\n# Create a dummy module to hold our script content, so should_instrument_file can identify it\nmy_script_module = types.ModuleType('my_script')\nmy_script_module.__file__ = '<string>my_script.py'\nsys.modules['my_script'] = my_script_module\n\n# Execute the script content within the dummy module's namespace\nwith MyTracer():\n    exec(script_content, my_script_module.__dict__)\n\n# Clean up the dummy module\ndel sys.modules['my_script']","lang":"python","description":"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.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":null}