{"id":17257820,"url":"https://github.com/p403n1x87/dragonfly","last_synced_at":"2025-07-04T22:34:23.896Z","repository":{"id":220498527,"uuid":"722973624","full_name":"P403n1x87/dragonfly","owner":"P403n1x87","description":"Lightweight CPython Debugger","archived":false,"fork":false,"pushed_at":"2024-03-31T22:33:19.000Z","size":7858,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-23T17:16:15.679Z","etag":null,"topics":["debugger","development","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/P403n1x87.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"p403n1x87","patreon":"P403n1x87","custom":"https://www.buymeacoffee.com/Q9C1Hnm28"}},"created_at":"2023-11-24T11:34:06.000Z","updated_at":"2024-03-04T10:31:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"5074637d-30e1-415d-9553-248307ceca2f","html_url":"https://github.com/P403n1x87/dragonfly","commit_stats":null,"previous_names":["p403n1x87/dragonfly"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/P403n1x87/dragonfly","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P403n1x87%2Fdragonfly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P403n1x87%2Fdragonfly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P403n1x87%2Fdragonfly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P403n1x87%2Fdragonfly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/P403n1x87","download_url":"https://codeload.github.com/P403n1x87/dragonfly/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P403n1x87%2Fdragonfly/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263628141,"owners_count":23490918,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debugger","development","python3"],"created_at":"2024-10-15T07:18:41.374Z","updated_at":"2025-07-04T22:34:23.879Z","avatar_url":"https://github.com/P403n1x87.png","language":"Python","funding_links":["https://github.com/sponsors/p403n1x87","https://patreon.com/P403n1x87","https://www.buymeacoffee.com/Q9C1Hnm28","https://www.patreon.com/bePatron?u=19221563","https://www.paypal.me/gtornetta/1","https://www.github.com/sponsors/P403n1x87"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cbr/\u003e\n  \u003cimg src=\"art/logo.png\"\n       alt=\"Dragonfly logo\"\n       height=\"256px\" /\u003e\n  \u003cbr/\u003e\n\u003c/p\u003e\n\n\u003ch3 align=\"center\"\u003eLightweight CPython Debugger\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/P403n1x87/dragonfly/actions?workflow=Tests\"\u003e\n    \u003cimg src=\"https://github.com/P403n1x87/dragonfly/workflows/Tests/badge.svg\"\n         alt=\"GitHub Actions: Tests\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/P403n1x87/dragonfly/actions?workflow=Checks\"\u003e\n    \u003cimg src=\"https://github.com/P403n1x87/dragonfly/workflows/Checks/badge.svg\"\n         alt=\"GitHub Actions: Checks\"\u003e\n  \u003c/a\u003e  \u003ca href=\"https://codecov.io/gh/P403n1x87/dragonfly\"\u003e\n    \u003cimg src=\"https://codecov.io/gh/P403n1x87/dragonfly/branch/main/graph/badge.svg\"\n         alt=\"Codecov\"\u003e\n  \u003c/a\u003e\n  \u003cbr/\u003e\n  \u003ca href=\"https://pypi.org/project/dfly/\"\u003e\n    \u003cimg src=\"https://img.shields.io/pypi/v/dfly.svg\"\n         alt=\"PyPI\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://pepy.tech/project/dfly\"\u003e\n    \u003cimg src=\"https://static.pepy.tech/personalized-badge/dfly?period=total\u0026units=international_system\u0026left_color=grey\u0026right_color=blue\u0026left_text=downloads\"\n         alt=\"Downloads\" /\u003e\n  \u003ca/\u003e\n  \u003cbr/\u003e\n  \u003ca href=\"https://github.com/P403n1x87/dragonfly/blob/main/LICENSE.md\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-GPLv3-ff69b4.svg\"\n         alt=\"LICENSE\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#synopsis\"\u003e\u003cb\u003eSynopsis\u003c/b\u003e\u003c/a\u003e\u0026nbsp;\u0026bull;\n  \u003ca href=\"#installation\"\u003e\u003cb\u003eInstallation\u003c/b\u003e\u003c/a\u003e\u0026nbsp;\u0026bull;\n  \u003ca href=\"#usage\"\u003e\u003cb\u003eUsage\u003c/b\u003e\u003c/a\u003e\u0026nbsp;\u0026bull;\n  \u003ca href=\"#compatibility\"\u003e\u003cb\u003eCompatibility\u003c/b\u003e\u003c/a\u003e\u0026nbsp;\u0026bull;\n  \u003ca href=\"#documentation\"\u003e\u003cb\u003eDocumentation\u003c/b\u003e\u003c/a\u003e\u0026nbsp;\u0026bull;\n  \u003ca href=\"#contribute\"\u003e\u003cb\u003eContribute\u003c/b\u003e\u003c/a\u003e\u0026nbsp;\u0026bull;\n  \u003ca href=\"#credits\"\u003e\u003cb\u003eCredits\u003c/b\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.buymeacoffee.com/Q9C1Hnm28\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png\" alt=\"Buy Me A Coffee\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\n# Synopsis\n\nDragonfly is a lightweight CPython debugger designed with speed in mind.\nContrary to more traditional debuggers, like pdb, Dragonfly does not rely\nheavily on tracing, allowing the target application to run at full speed in most\ncases. Occasionally, tracing might be required, so that the slowdown would be\nsimilar to that of pdb in the worst case.\n\n\n# Installation\n\nThis package can be installed from PyPI with\n\n~~~ bash\npip install --user dfly --upgrade\n~~~\n\n\n# Usage\n\nTo debug a Python script or application, simply prefix the command with `dfly`.\nThe built-in `breakpoint()` is replaced with Dragonfly's own implementation, so\nthat you can set breakpoints in your code by simply adding `breakpoint()` where\nneeded. Alternatively, if you are not using the `dfly` command, you can simply\nimport `dragonfly.bite` before any calls to `breakpoint` to achieve the same\neffect.\n\nDragonfly is still in an early stage of development, so it is not yet feature\ncomplete. However, it is already usable for the most common debugging tasks,\nwith some initial support for multi-threading.\n\nIf you find this tool useful, please consider starring the repository and/or\nbecoming a [Sponsor][sponsor] to support the development.\n\n\n# Compatibility\n\nDragonfly is tested on Linux and macOS with Python 3.8-3.12.\n\n\n# Why Dragonfly\n\nThe typical CPython debugger relies heavily, or even exclusively on tracing in\ntheir implementation. This technique is very powerful, but it has a few\nshortcomings:\n\n- high overhead - tracing is slow, and it can slow down the target application\n  by a factor of 10 or more.\n\n- limited support for multithreading - supporting multithreading in a\n  tracing-based debugger is difficult, especially in older versions of Python.\n\nSome of these problems have been addressed in [PEP 669][pep-0669]. But whilst\nthe cost of monitoring has been lowered, some impact still remains. Besides,\nPEP 669 is only available in Python 3.12 and later.\n\nDragonfly poses itself as a lightweight alternative to the traditional, and the\nPEP 669-based debuggers. At its core, Dragonfly uses bytecode transformation to\nimplement traps. These can be injected where breakpoints are requested, and\ncontrol is then passed to the prompt. When the targeted bytecode is already\nbeing executed, Dragonfly turns on tracing to ensure that any breakpoints can\nstill be hit. In this case, the performance impact can be similar to that of\ntracing-based debuggers. However, this should normally be a transient situation,\nand the ammortised cost of debugging should be essentially negligible.\n\nTo make this clearer, let's look at a simple example. Consider the following\ncode:\n\n```python\ndef fibonacci(n):\n    if n \u003c 2:\n        return n\n    return fibonacci(n - 1) + fibonacci(n - 2)\n\n\nfrom time import monotonic as time\n\nstart = time()\nfibonacci(30)\nend = time()\nprint(end - start)\n```\n\nWhen we run this without any debuggers, the reported time is of the order of\n0.1 seconds.\n\n```console\n$ python3.12 -m tests.fib\n0.11031840229406953\n```\n\nIf we run this with pdb, without any breakpoints, the reported time is of the\norder of over 3 seconds:\n\n```console\n$ python3.12 -m pdb -m tests.fib\n\u003e /tmp/fib.py(1)\u003cmodule\u003e()\n-\u003e def fibonacci(n):\n(Pdb) r\n3.2781156906858087\n--Return--\n\u003e /tmp/fib.py(12)\u003cmodule\u003e()-\u003eNone\n-\u003e print(end - start)\n(Pdb) \n```\n\nHowever, if we run it through Dragonfly, again without any breakpoints set, the\nreported time is essentially the same as without any debugger:\n\n```console\n$ dfly -r python -m fib         \n0.11001458810642362\n```\n\n## Bytecode debugging\n\nDragonfly can also be used to debug CPython at the bytecode level. When setting\n`trace-opcodes` with `set trace-opcodes 1`, every stepping operation will be\nperformed at the bytecode level. The `disassemble` command can be used to\ndisplay the bytecode currently running, along with the values in the stack for\nthe current frame.\n\n\n# Contribute\n\nIf you want to help with the development, then have a look at the open issues\nand have a look at the [contributing guidelines](CONTRIBUTING.md) before you\nopen a pull request.\n\nYou can also contribute to the development by either [becoming a\nPatron](https://www.patreon.com/bePatron?u=19221563) on Patreon, by [buying me a\ncoffee](https://www.buymeacoffee.com/Q9C1Hnm28) on BMC or by chipping in a few\npennies on [PayPal.Me](https://www.paypal.me/gtornetta/1).\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.buymeacoffee.com/Q9C1Hnm28\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png\"\n         alt=\"Buy Me A Coffee\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\n## Credits\n\nArtwork by [Antea a.k.a. Aisling][aisling].\n\n\n[aisling]: https://linktr.ee/ladyofshalott\n[pep-0669]: https://peps.python.org/pep-0669/\n[sponsor]: https://www.github.com/sponsors/P403n1x87\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp403n1x87%2Fdragonfly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fp403n1x87%2Fdragonfly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp403n1x87%2Fdragonfly/lists"}