{"id":13501436,"url":"https://github.com/cansarigol/pdbr","last_synced_at":"2026-01-02T10:15:02.474Z","repository":{"id":37949330,"uuid":"274461698","full_name":"cansarigol/pdbr","owner":"cansarigol","description":"pdb + Rich library","archived":false,"fork":false,"pushed_at":"2025-05-12T19:24:31.000Z","size":1971,"stargazers_count":347,"open_issues_count":2,"forks_count":14,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-12T20:43:59.006Z","etag":null,"topics":["celery","debugger","debugger-color","ipython","pdb","python","rich","traceback"],"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/cansarigol.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-06-23T16:56:57.000Z","updated_at":"2025-04-23T19:45:10.000Z","dependencies_parsed_at":"2023-10-03T12:58:20.694Z","dependency_job_id":"a77a81a9-d1ee-4a95-ab1b-2a3eb464c9f2","html_url":"https://github.com/cansarigol/pdbr","commit_stats":{"total_commits":169,"total_committers":7,"mean_commits":"24.142857142857142","dds":"0.40828402366863903","last_synced_commit":"2ff6453fec283b2fa6d58dab2d99f1772a74995b"},"previous_names":[],"tags_count":80,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cansarigol%2Fpdbr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cansarigol%2Fpdbr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cansarigol%2Fpdbr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cansarigol%2Fpdbr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cansarigol","download_url":"https://codeload.github.com/cansarigol/pdbr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254149949,"owners_count":22022851,"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":["celery","debugger","debugger-color","ipython","pdb","python","rich","traceback"],"created_at":"2024-07-31T22:01:37.464Z","updated_at":"2026-01-02T10:15:02.440Z","avatar_url":"https://github.com/cansarigol.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# pdbr\n\n[![PyPI version](https://badge.fury.io/py/pdbr.svg)](https://pypi.org/project/pdbr/) [![Python Version](https://img.shields.io/pypi/pyversions/pdbr.svg)](https://pypi.org/project/pdbr/) [![](https://github.com/cansarigol/pdbr/workflows/Test/badge.svg)](https://github.com/cansarigol/pdbr/actions?query=workflow%3ATest) [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/cansarigol/pdbr/master.svg)](https://results.pre-commit.ci/latest/github/cansarigol/pdbr/master)\n\n\n`pdbr` is intended to make the PDB results more colorful. it uses [Rich](https://github.com/willmcgugan/rich) library to carry out that.\n\n\n## Installing\n\nInstall with `pip` or your favorite PyPi package manager.\n\n```\npip install pdbr\n```\n\n\n## Breakpoint\n\nIn order to use ```breakpoint()```, set **PYTHONBREAKPOINT** with \"pdbr.set_trace\"\n\n```python\nimport os\n\nos.environ[\"PYTHONBREAKPOINT\"] = \"pdbr.set_trace\"\n```\n\nor just import pdbr\n\n```python\nimport pdbr\n```\n\n## New commands\n### (i)nspect / inspectall | ia\n[rich.inspect](https://rich.readthedocs.io/en/latest/introduction.html?s=03#rich-inspector)\n### search | src\nSearch a phrase in the current frame.\nIn order to repeat the last one, type **/** character as arg.\n### sql\nDisplay value in sql format. Don't forget to install [sqlparse](https://github.com/andialbrecht/sqlparse) package.\n![](/images/image13.png)\n\nIt can be used for Django model queries as follows.\n```\n\u003e\u003e\u003e sql str(Users.objects.all().query)\n```\n![](/images/image14.png)\n### (syn)tax\n[ val,lexer ] Display [lexer](https://pygments.org/docs/lexers/).\n### (v)ars\nGet the local variables list as table.\n### varstree | vt\nGet the local variables list as tree.\n\n![](/images/image5.png)\n\n## Config\nConfig is specified in **setup.cfg** and can be local or global. Local config (current working directory) has precedence over global (default) one. Global config must be located at `$XDG_CONFIG_HOME/pdbr/setup.cfg`.\n\n### Style\nIn order to use Rich's traceback, style, and theme:\n\n```\n[pdbr]\nstyle = yellow\nuse_traceback = True\ntheme = friendly\n```\n\nAlso custom `Console` object can be assigned to the `set_trace`.\n```python\nimport pdbr\n\nfrom rich.console import Console\nfrom rich.style import Style\nfrom rich.theme import Theme\n\ncustom_theme = Theme({\n    \"info\": \"dim cyan\",\n    \"warning\": \"magenta\",\n    \"danger\": \"bold red\",\n})\ncustom_style = Style(\n    color=\"magenta\",\n    bgcolor=\"yellow\",\n    italic=True,\n)\nconsole = Console(theme=custom_theme, style=custom_style)\n\npdbr.set_trace(console=console)\n```\n### History\n**store_history** setting is used to keep and reload history, even the prompt is closed and opened again:\n```\n[pdbr]\n...\nstore_history=.pdbr_history\n```\n\nBy default, history is stored globally in `~/.pdbr_history`.\n\n### Context\nThe **context** setting is used to specify the number of lines of source code context to show when displaying stacktrace information.\n```\n[pdbr]\n...\ncontext=10\n```\nThis setting is only available when using `pdbr` with `IPython`.\n\n## Celery\nIn order to use **Celery** remote debugger with pdbr, use ```celery_set_trace``` as below sample. For more information see the [Celery user guide](https://docs.celeryproject.org/en/stable/userguide/debugging.html).\n\n```python\nfrom celery import Celery\n\napp = Celery('tasks', broker='pyamqp://guest@localhost//')\n\n@app.task\ndef add(x, y):\n\n    import pdbr; pdbr.celery_set_trace()\n\n    return x + y\n\n```\n#### Telnet\nInstead of using `telnet` or `nc`, in terms of using pdbr style, `pdbr_telnet` command can be used.\n![](/images/image6.png)\n\nAlso in order to activate history and be able to use arrow keys, install and use [rlwrap](https://github.com/hanslub42/rlwrap) package.\n\n```\nrlwrap -H '~/.pdbr_history' pdbr_telnet localhost 6899\n```\n\n## IPython\n\n`pdbr` integrates with [IPython](https://ipython.readthedocs.io/).\n\nThis makes [`%magics`](https://ipython.readthedocs.io/en/stable/interactive/magics.html) available, for example:\n\n```python\n(Pdbr) %timeit range(100)\n104 ns ± 2.05 ns per loop (mean ± std. dev. of 7 runs, 10,000,000 loops each)\n```\n\nTo enable `IPython` features, install it separately, or like below:\n\n```\npip install pdbr[ipython]\n```\n\n## pytest\nIn order to use `pdbr` with pytest `--pdb` flag, add `addopts` setting in your pytest.ini.\n\n```\n[pytest]\naddopts: --pdbcls=pdbr:RichPdb\n```\n\n## sys.excepthook\nThe `sys.excepthook` is a Python system hook that provides a way to customize the behavior when an unhandled exception occurs. Since `pdbr` use  automatic traceback handler feature of `rich`, formatting exception print is not necessary if `pdbr` module is already imported.\n\nIn order to use post-mortem or perform other debugging features of `pdbr`,  override `sys.excepthook` with a function that will act as your custom excepthook:\n```python\nimport sys\nimport pdbr\n\ndef custom_excepthook(exc_type, exc_value, exc_traceback):\n    pdbr.post_mortem(exc_traceback, exc_value)\n\n    # [Optional] call the original excepthook as well\n    sys.__excepthook__(exc_type, exc_value, exc_traceback)\n\nsys.excepthook = custom_excepthook\n```\nNow, whenever an unhandled exception occurs, `pdbr` will be triggered, allowing you to debug the issue interactively.\n\n## Context Decorator\n`pdbr_context` and `apdbr_context` (`asyncio` corresponding) can be used as **with statement** or **decorator**. It calls `post_mortem` if `traceback` is not none.\n\n```python\nfrom pdbr import apdbr_context, pdbr_context\n\n@pdbr_context()\ndef foo():\n    ...\n\ndef bar():\n    with pdbr_context():\n        ...\n\n\n@apdbr_context()\nasync def foo():\n    ...\n\nasync def bar():\n    async with apdbr_context():\n        ...\n```\n\n![](/images/image12.png)\n## Django DiscoverRunner\nTo being activated the pdb in Django test, change `TEST_RUNNER` like below. Unlike Django (since you are not allowed to use for smaller versions than 3), pdbr runner can be used for version 1.8 and subsequent versions.\n\n```\nTEST_RUNNER = \"pdbr.runner.PdbrDiscoverRunner\"\n```\n![](/images/image10.png)\n## Middlewares\n### Starlette\n```python\nfrom fastapi import FastAPI\nfrom pdbr.middlewares.starlette import PdbrMiddleware\n\napp = FastAPI()\n\napp.add_middleware(PdbrMiddleware, debug=True)\n\n\n@app.get(\"/\")\nasync def main():\n    1 / 0\n    return {\"message\": \"Hello World\"}\n```\n### Django\nIn order to catch the problematic codes with post mortem, place the middleware class.\n\n```\nMIDDLEWARE = (\n    ...\n    \"pdbr.middlewares.django.PdbrMiddleware\",\n)\n```\n![](/images/image11.png)\n## Shell\nRunning `pdbr` command in terminal starts an `IPython` terminal app instance. Unlike default `TerminalInteractiveShell`, the new shell uses pdbr as debugger class instead of `ipdb`.\n#### %debug magic sample\n![](/images/image9.png)\n### As a Script\nIf `pdbr` command is used with an argument, it is invoked as a script and [debugger-commands](https://docs.python.org/3/library/pdb.html#debugger-commands) can be used with it.\n```python\n# equivalent code: `python -m pdbr -c 'b 5' my_test.py`\npdbr -c 'b 5' my_test.py\n\n\u003e\u003e\u003e Breakpoint 1 at /my_test.py:5\n\u003e /my_test.py(3)\u003cmodule\u003e()\n      1\n      2\n----\u003e 3 def test():\n      4         foo = \"foo\"\n1     5         bar = \"bar\"\n\n(Pdbr)\n\n```\n### Terminal\n#### Django shell sample\n![](/images/image7.png)\n\n## Vscode user snippet\n\nTo create or edit your own snippets, select **User Snippets** under **File \u003e Preferences** (**Code \u003e Preferences** on macOS), and then select **python.json**.\n\nPlace the below snippet in json file for **pdbr**.\n\n```\n{\n  ...\n  \"pdbr\": {\n        \"prefix\": \"pdbr\",\n        \"body\": \"import pdbr; pdbr.set_trace()\",\n        \"description\": \"Code snippet for pdbr debug\"\n    },\n}\n```\n\nFor **Celery** debug.\n\n```\n{\n  ...\n  \"rdbr\": {\n        \"prefix\": \"rdbr\",\n        \"body\": \"import pdbr; pdbr.celery_set_trace()\",\n        \"description\": \"Code snippet for Celery pdbr debug\"\n    },\n}\n```\n\n## Samples\n![](/images/image1.png)\n\n![](/images/image3.png)\n\n![](/images/image4.png)\n\n### Traceback\n![](/images/image2.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcansarigol%2Fpdbr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcansarigol%2Fpdbr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcansarigol%2Fpdbr/lists"}