🏣 debug dojo, a place for zen debugging

debug-dojo is a standalone, zero-configuration Python debugger and runner built around dpdb—an IPython-powered interactive debugger with rich terminal panels, inline variable diffs, and built-in object inspection.

✨ Features

• Zero-Install & Zero-Config: Run any script directly with uvx debug-dojo script.py. Automatically discovers your project's .venv and leaves no configuration, cache, or history files behind.
• Opinionated dpdb Debugger: Combines IPython tab completion and syntax highlighting with Rich tables (w, a, b, display, h), panels (whatis, psource, pinfo), adaptive source context, and an inline frame context banner (Δ Changed, ↳ Line, ↩ Return, 👁 Watch).
• Automatic Post-Mortem: Unhandled exceptions render a Rich traceback and drop directly into a dpdb post-mortem session at the failing frame.
• Built-in Inspection Shortcuts: Injects b() (breakpoint), p(obj) (Rich print), i(obj) (Rich inspect), and c(obj1, obj2) (side-by-side comparison) into builtins.

🚀 Quick Start

Run any Python script directly with uvx:

uvx debug-dojo my_script.py

Or install debug-dojo into an environment with uv:

uv pip install debug-dojo

💻 CLI Usage

Run a Python script, executable command, or module directly with debug-dojo (or the dojo alias), optionally seeding breakpoints from the command line without editing the file:

debug-dojo my_script.py arg1 arg2
debug-dojo -b 42 -b process_data my_script.py
debug-dojo pytest -k test_feature
debug-dojo my_package.my_module

🐍 Usage in Code

Import debug_dojo.install in your Python code to configure dpdb and inject helpers (b, p, i, c) into builtins:

import debug_dojo.install

object_1 = {"foo": 1, "bar": 2}
object_2 = [1, 2, 3]

# Pretty print an object with Rich
p(object_1)

# Inspect an object using Rich
i(object_1)

# Compare two objects side-by-side
c(object_1, object_2)

# Enter the dpdb debugger
# b()

Or use the standard pdb / ipdb-compatible top-level functions and PYTHONBREAKPOINT hook directly:

import debug_dojo

debug_dojo.set_trace()
# debug_dojo.post_mortem()
# debug_dojo.pm()

📚 Documentation

For CLI flags, dpdb interactive commands, and API reference, visit the official documentation.

🤝 Contributing

Contributions are welcome! Refer to the development guidelines for instructions on setting up the development environment and running verification checks.