Metadata-Version: 2.4
Name: debug-dojo
Version: 0.3.2
Summary: Debbugging dojo for Python developers
Project-URL: Homepage, https://github.com/bwrob/debug-dojo
Project-URL: Documentation, https://github.com/bwrob/debug-dojo/blob/main/README.md
Project-URL: Source, https://github.com/bwrob/debug-dojo/tree/main/src/debug_dojo
Project-URL: Changelog, https://github.com/bwrob/debug-dojo/blob/main/HISTORY.md
Author-email: bwrob <bartosz.marcin.wroblewski@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: debugging,inspection,pudb,rich,tools,traceback
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: debugpy>=1.8.0
Requires-Dist: ipdb>=0.13.0
Requires-Dist: pudb>=2020.1
Requires-Dist: pydantic>=2.11.7
Requires-Dist: rich>=12.0.0
Requires-Dist: tomlkit>=0.13.3
Requires-Dist: typer>=0.15.0
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://github.com/bwrob/debug-dojo/blob/main/logo/logo_python.png?raw=true" alt="debug dojo" style="width:50%; max-width:300px;"/>
</p>

<p align="center">
    <em>debug dojo, a place for zen debugging</em>
</p>

[![PyPi Version](https://img.shields.io/pypi/v/debug-dojo.svg?style=flat-square)](https://pypi.org/project/debug-dojo)
[![PyPI pyversions](https://img.shields.io/pypi/pyversions/debug-dojo.svg?style=flat-square)](https://pypi.org/pypi/debug-dojo/)

**debug-dojo** is a Python package providing utilities for enhanced debugging and inspection in the terminal. 
It leverages [`rich`](https://github.com/Textualize/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:

```console
dojo my_script.py
```

You can optionally set configuration file and verbose mode:

```console
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:

```python
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`:**

```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.

```console
pip install debug-dojo
```

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

```console
poetry add debug-dojo
```

```console
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

```console
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.
