{"id":13501510,"url":"https://github.com/CCExtractor/vardbg","last_synced_at":"2025-03-29T09:30:35.051Z","repository":{"id":40618949,"uuid":"233500493","full_name":"CCExtractor/vardbg","owner":"CCExtractor","description":"A simple Python debugger and profiler that generates animated visualizations of program flow, useful for algorithm learning.","archived":false,"fork":false,"pushed_at":"2021-06-10T20:44:27.000Z","size":1537,"stargazers_count":1102,"open_issues_count":5,"forks_count":90,"subscribers_count":21,"default_branch":"master","last_synced_at":"2024-10-29T17:54:12.886Z","etag":null,"topics":["debugger","flow","gci","gci2019","hacktoberfest","profiler","python","video","visualization"],"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/CCExtractor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-13T03:07:46.000Z","updated_at":"2024-10-26T06:17:48.000Z","dependencies_parsed_at":"2022-07-14T04:10:29.240Z","dependency_job_id":null,"html_url":"https://github.com/CCExtractor/vardbg","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CCExtractor%2Fvardbg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CCExtractor%2Fvardbg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CCExtractor%2Fvardbg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CCExtractor%2Fvardbg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CCExtractor","download_url":"https://codeload.github.com/CCExtractor/vardbg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246166975,"owners_count":20734376,"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","flow","gci","gci2019","hacktoberfest","profiler","python","video","visualization"],"created_at":"2024-07-31T22:01:39.946Z","updated_at":"2025-03-29T09:30:35.019Z","avatar_url":"https://github.com/CCExtractor.png","language":"Python","readme":"# vardbg\n\n[![Available on PyPI](https://img.shields.io/pypi/v/vardbg)](https://pypi.org/project/vardbg/)\n\nA simple Python debugger and profiler that generates animated visualizations of program flow. It is meant to help with learning algorithms by allowing you to visualize what the algorithms are doing.\n\n**Python 3.6** or newer is required due to the use of f-strings.\n\nThis project was created during [Google Code-in](https://codein.withgoogle.com/) 2019 for [CCExtractor Development](https://ccextractor.org/).\n\n## Demo\n\n![Insertion Sort Demo](https://user-images.githubusercontent.com/7930239/73394845-3aa8fb00-4293-11ea-8477-6590cdeab5eb.gif)\n\n## Features\n\n- Tracking the history of each variable and its contents\n- Tracking elements within containers (lists, sets, dicts, etc.)\n- Ignoring specific variables\n- Profiling the execution of each line\n- Summarizing all variables and execution times after execution\n- Passing arguments to debugged programs\n- Exporting execution history in JSON format and replaying (including program output)\n- Creating videos that show program flow, execution times, variables (with relationships), and output\n- Writing videos in MP4, GIF, and WebP formats\n\n## Installation\n\nThe latest tagged version can be obtained from PyPI:\n\n```bash\npip install vardbg\n```\n\nAlternatively, one can clone this repository and run it directly after installing dependencies:\n\n```bash\ngit clone https://github.com/CCExtractor/vardbg\ncd vardbg\npython3 -m venv venv\nsource venv/bin/activate\npip install poetry\npoetry install .\n./debug.py\n```\n\nIt can also be installed from the repository:\n\n```bash\npip install .\n```\n\nThe above instructions assume the use of a virtual environment to avoid interfering with the system install of Python.\n\n## Usage\n\nAll of the debugger's subcommands and options are documented in the usage help, which is readily available on the command line.\n\nFor example, this command will debug the function `quick_sort` from the file `sort.py` with the arguments `9 3 5 1` and record the session to a JSON file named `sort1.json`:\n\n```bash\nvardbg run sort.py quick_sort -o qsort.json -a 9 -a 3 -a 5 -a 1\n```\n\nA video can then be generated from the above recording:\n\n```bash\nvardbg replay qsort.json -v sort_vis.mp4\n```\n\nIt is possible to generate videos live while running the debugged program, but this is discouraged because the overhead of video creation inflates execution times greatly and thus ruins profiler results. However, if profiling is not important to you, it is a valid use case.\n\n## Configuration\n\nThe video generator has many options: resolution, speed, fonts, and sizes. These options can be modified using a [TOML](https://learnxinyminutes.com/docs/toml/) config file. The [default config](https://github.com/CCExtractor/vardbg/blob/master/vardbg/output/video_writer/default_config.toml) documents the available options, which can be customized in an minimal overlay config without having to duplicate the entire config. The config can then be used by passing the `-c` argument on the command line.\n\nAn example of a simple overlay is the [config](https://github.com/CCExtractor/vardbg/blob/master/demo_config.toml) used to generate official demo videos for embedding in READMEs. This simple config increases the speed (FPS) slightly and adds an intro screen at the beginning of the video.\n\n## Behavior Control\n\nSpecial comments can be added to lines of code that define variables to control how vardbg handles said variable:\n\n- `# vardbg: ignore` — do not display this variable or track its values\n- `# vardbg: ref lst[i]` — treat variable `i` as the index/key of an element in container `lst` (only shown in videos)\n\nSpecifying the name of the variable may appear to be redundant, but there are two reasons behind this: reliably parsing all code that defines variables is very hard (there are more possible methods than one might think — loops, unpacking, direct assignments, `exec` calls, etc.), and more than one variable can be declared on a line. For example, tuple unpacking and function arguments are common occurrences of multiple variables being added on a single line. Thus, specifying the variable name in references is mandatory to prevent ambiguity.\n\n## Contributing\n\nFeel free to contribute to this project! You can add features, fix bugs, or make any other improvements you see fit. We just ask that you follow the [code style guidelines](https://github.com/CCExtractor/vardbg/blob/master/CODE_STYLE.md) to keep the code consistent and coherent. These guidelines can easily be enforced before pushing with the [pre-commit](https://pre-commit.com/) framework, which can install Git pre-commit hooks with the `pre-commit install` command.\n\nOnce your contribution meets the guidelines, [open a pull request](https://github.com/CCExtractor/vardbg/compare) to make things official.\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCCExtractor%2Fvardbg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCCExtractor%2Fvardbg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCCExtractor%2Fvardbg/lists"}