debug-dojo

debug dojo, a place for zen debugging

debug-dojo is a Python package providing utilities for enhanced debugging and inspection in the terminal. It leverages rich for beautiful output and offers helpers for side-by-side object comparison, improved tracebacks from rich, and easy integration with different debuggers -- debugpy, pudb, pdb, and ipdb.

Features

• Convenient CLI Quickly run your code with debugging tools enabled.
• Simple API: Install all tools or only what you need.
• Debugger integration: Quickly enable Debugpy, PuDB, PDB, or IPDB as your default debugger.
• Rich tracebacks: Get readable, colorized tracebacks for easier debugging.
• Side-by-side object inspection: Visually compare Python objects, their attributes, and methods in the terminal.
• Configuration: Easily configure the debugging tools using dojo.toml or pyproject.toml.

Usage

CLI

Run your Python script with debugging tools enabled using the debug-dojo command:

dojo my_script.py

You can optionally set configuration file and verbose mode:

dojo --config dojo.toml --verbose my_script.py

From the code

In the PuDB style, you can install all debugging tools and enter the debugging mode with a single command:

import debug_dojo.install; b()

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

p(object_1)  # Pretty print an object with Rich
i(object_1)  # Inspect an object
c(object_1, object_2)  # Compare two objects side-by-side

Where:

• b() is a builtin-injected function that sets a breakpoint using PuDB's set_trace().
• p(object_1) is pretty printing of an object using Rich.
• i(object_1) to inspect an object using Rich.
• c(object_1, object_2) to compare two objects side-by-side.

Configuration

You can configure the debugging tools using a dojo.toml or pyproject.toml file. The configuration allows you to specify which debugger to use, enable or disable features, and set other options.

Example dojo.toml:

debugger = "ipdb"

[features]
  rich_inspect = true
  rich_print = true
  comparer = false

Installation

The package is available on PyPI and can be installed using standard Python package management tools.

pip install debug-dojo

You can also use poetry or uv to add it to your project:

poetry add debug-dojo

uv add debug-dojo

Note that dojo most likely will not work when installed via pipx or uvx, as it relies on the current Python environment dependencies.

Development

Lint and type check

ruff check src/debug_dojo --fix
basedpyright src/debug_dojo

Changelog

v0.3.0 (2025-07-28)

release tag: [v0.3.2]

What's Changed

• New logo for the project.
• Typer used for CLI implementation.
• Dojo is configured via dojo.toml or pyproject.toml.
• Support for debugpy and ipdb for debugging.

Fixes

• Fixed documentation and history.

v0.2.0 (2025-07-20)

release tag: [v0.2.0]

What's Changed

• Added dojo command for easy debugging setup.
• Added p() function for rich printing.
• Added history file for tracking changes.
• Moved to hatch for building and packaging.

Fixes

• Fixed pyproject.toml to point to GitHub repository as the homepage.

v0.1.0 (2025-07-19)

release tag: [v0.1.0]

What's Changed

• Initial module to install debugging tools.
• Debug mode utilities for PuDB, rich tracebacks, and object inspection.