Synopsis • Installation • Usage • Compatibility • Documentation • Contribute • Credits

Dragonfly is a lightweight CPython debugger designed with speed in mind. Contrary to more traditional debuggers, like pdb, Dragonfly does not rely heavily on tracing, allowing the target application to run at full speed in most cases. Occasionally, tracing might be required, so that the slowdown would be similar to that of pdb in the worst case.

This package can be installed from PyPI with

pip install --user dfly --upgrade

To debug a Python script or application, simply prefix the command with dfly. The built-in breakpoint() is replaced with Dragonfly's own implementation, so that you can set breakpoints in your code by simply adding breakpoint() where needed. Alternatively, if you are not using the dfly command, you can simply import dragonfly.bite before any calls to breakpoint to achieve the same effect.

Dragonfly is still in an early stage of development, so it is not yet feature complete. However, it is already usable for the most common debugging tasks, with some initial support for multi-threading.

If you find this tool useful, please consider starring the repository and/or becoming a Sponsor to support the development.

Dragonfly is tested on Linux and macOS with Python 3.8-3.12.

The typical CPython debugger relies heavily, or even exclusively on tracing in their implementation. This technique is very powerful, but it has a few shortcomings:

• high overhead - tracing is slow, and it can slow down the target application by a factor of 10 or more.

• limited support for multithreading - supporting multithreading in a tracing-based debugger is difficult, especially in older versions of Python.

Some of these problems have been addressed in PEP 669. But whilst the cost of monitoring has been lowered, some impact still remains. Besides, PEP 669 is only available in Python 3.12 and later.

Dragonfly poses itself as a lightweight alternative to the traditional, and the PEP 669-based debuggers. At its core, Dragonfly uses bytecode transformation to implement traps. These can be injected where breakpoints are requested, and control is then passed to the prompt. When the targeted bytecode is already being executed, Dragonfly turns on tracing to ensure that any breakpoints can still be hit. In this case, the performance impact can be similar to that of tracing-based debuggers. However, this should normally be a transient situation, and the ammortised cost of debugging should be essentially negligible.

To make this clearer, let's look at a simple example. Consider the following code:

def fibonacci(n):
    if n < 2:
        return n
    return fibonacci(n - 1) + fibonacc