debug-dojo 0.2.0__tar.gz → 0.3.1__tar.gz

{debug_dojo-0.2.0 → debug_dojo-0.3.1}/HISTORY.md

@@ -1,6 +1,20 @@
+## v0.3.0 (2025-07-20)
+
+*release tag*: [v0.3.0]
+
+### What's Changed
+
+- New logo for the project.
+- Typer used for CLI implementation.
+- Dojo is configured via `dojo.toml` or `pyproject.toml`.
+
+#### Fixes
+
+- Fixed documentation and history.
+
 ## v0.2.0 (2025-07-20)
 
-*release tag*: [v0.2.0](https://github.com/pydantic/pydantic/releases/tag/v2.11.6)
+*release tag*: [v0.2.0]
 
 ### What's Changed
 
@@ -13,13 +27,11 @@
 
 - Fixed `pyproject.toml` to point to GitHub repository as the homepage.
 
-## v0.1.0 (2025-07-20)
+## v0.1.0 (2025-07-19)
 
-*release tag*: [v0.1.0](https://github.com/pydantic/pydantic/releases/tag/v2.11.6)
+*release tag*: [v0.1.0]
 
 ### What's Changed
 
 - Initial module to install debugging tools.
 - Debug mode utilities for PuDB, rich tracebacks, and object inspection.
-
-#### Fixes

{debug_dojo-0.2.0 → debug_dojo-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: debug-dojo
-Version: 0.2.0
+Version: 0.3.1
 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
@@ -20,36 +20,63 @@ 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: rich>=11.0.0
+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
 
-# debug-dojo
+<p align="center">
+  <img src="https://github.com/bwrob/debug-dojo/blob/main/logo/logo_white.png?raw=true" alt="debug dojo" style="width:50%; max-width:400px;"/>
+</p>
 
-**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 PuDB. All tools can be installed at once or individually, allowing for flexible debugging setups.
+<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. All tools can be installed at once or individually, allowing for flexible debugging setups.
 
 ## Features
 
+- **Convenient CLI** Quickly run your code with debugging tools enabled.
 - **Simple API:** Install all tools or only what you need.
-- **PuDB integration:** Quickly enable the PuDB TUI debugger.
+- **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.
 
-## Installation
+## Usage
 
-```sh
-pip install debug-dojo
+### CLI
+
+Run your Python script with debugging tools enabled using the `debug-dojo` command:
+
+```console
+dojo my_script.py
 ```
 
-## Usage
+You can optionally set configuration file and verbose mode:
 
-### Install all debugging tools
+```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.all; b()
+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
 ```
@@ -57,40 +84,50 @@ 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()`.
-- `i(object_1)` to inspect an object.
+- `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.
 
-### Use individual tools
+## Configuration
 
-```python
-from debug_dojo import install_inspect, use_pudb, use_rich_traceback
+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.
 
-install_inspect()         # Enable object inspection helpers
-use_pudb()                # Set up PuDB as the debugger
-use_rich_traceback()      # Enable Rich tracebacks
+**Example `dojo.toml`:**
+
+```toml
+debugger = "ipdb"
+
+[features]
+  rich_inspect = true
+  rich_print = true
+  comparer = false
 ```
 
-### Compare objects side-by-side
+## Installation
 
-```python
-from debug_dojo.compareres import inspect_objects_side_by_side
+The package is available on PyPI and can be installed using standard Python package management tools.
 
-a = {"foo": 1, "bar": 2}
-b = [1, 2, 3]
-inspect_objects_side_by_side(a, b)
+```console
+pip install debug-dojo
 ```
 
-## Development
+You can also use `poetry` or `uv` to add it to your project:
 
-### Run tests
+```console
+poetry add debug-dojo
+```
 
-```sh
-pytest
+```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
 
-```sh
+```console
 ruff check src/debug_dojo --fix
 basedpyright src/debug_dojo
 ```
@@ -98,9 +135,23 @@ basedpyright src/debug_dojo
 
 ## Changelog
 
+## v0.3.0 (2025-07-20)
+
+*release tag*: [v0.3.0]
+
+### What's Changed
+
+- New logo for the project.
+- Typer used for CLI implementation.
+- Dojo is configured via `dojo.toml` or `pyproject.toml`.
+
+#### Fixes
+
+- Fixed documentation and history.
+
 ## v0.2.0 (2025-07-20)
 
-*release tag*: [v0.2.0](https://github.com/pydantic/pydantic/releases/tag/v2.11.6)
+*release tag*: [v0.2.0]
 
 ### What's Changed
 
@@ -113,13 +164,11 @@ basedpyright src/debug_dojo
 
 - Fixed `pyproject.toml` to point to GitHub repository as the homepage.
 
-## v0.1.0 (2025-07-20)
+## v0.1.0 (2025-07-19)
 
-*release tag*: [v0.1.0](https://github.com/pydantic/pydantic/releases/tag/v2.11.6)
+*release tag*: [v0.1.0]
 
 ### What's Changed
 
 - Initial module to install debugging tools.
 - Debug mode utilities for PuDB, rich tracebacks, and object inspection.
-
-#### Fixes

debug_dojo-0.3.1/README.md

@@ -0,0 +1,102 @@
+<p align="center">
+  <img src="https://github.com/bwrob/debug-dojo/blob/main/logo/logo_white.png?raw=true" alt="debug dojo" style="width:50%; max-width:400px;"/>
+</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. All tools can be installed at once or individually, allowing for flexible debugging setups.
+
+## 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.
+
+## 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
+```

debug_dojo-0.3.1/dojo.toml

@@ -0,0 +1,7 @@
+debugger = "ipdb"
+
+[features]
+    rich_inspect = true
+    rich_print   = true
+    comparer     = false
+    breakpoint   = true

{debug_dojo-0.2.0 → debug_dojo-0.3.1}/pyproject.toml

@@ -5,7 +5,15 @@
         { name = "bwrob", email = "bartosz.marcin.wroblewski@gmail.com" },
     ]
     requires-python = ">=3.10"
-    dependencies = ["pudb>=2020.1", "rich>=11.0.0"]
+    dependencies = [
+        "debugpy>=1.8.0",
+        "ipdb>=0.13.0",
+        "pudb>=2020.1",
+        "pydantic>=2.11.7",
+        "rich>=12.0.0",
+        "tomlkit>=0.13.3",
+        "typer>=0.15.0",
+]
     license = 'MIT'
     license-files = ['LICENSE']
     keywords = [
@@ -28,7 +36,8 @@
         "Topic :: Software Development :: Debuggers",
         "Topic :: Software Development :: Libraries :: Python Modules",
     ]
-    dynamic = ['readme', 'version']
+version = "0.3.1"
+    dynamic = ['readme']
 
     [project.urls]
         Homepage      = "https://github.com/bwrob/debug-dojo"
@@ -39,10 +48,15 @@
     [project.scripts]
         # This defines your command-line script!
         # It points to the 'main' function in your 'cli' module.
-        "dojo" = "debug_dojo.cli:main"
+        "dojo" = "debug_dojo._cli:main"
 
 [dependency-groups]
-    dev = ["basedpyright>=1.31.0", "ruff>=0.12.4"]
+    dev = [
+        "basedpyright>=1.31.0",
+        "jupyter>=1.1.1",
+        "poethepoet>=0.36.0",
+        "ruff>=0.12.4",
+]
 
 [build-system]
     requires = [
@@ -72,3 +86,10 @@
     pythonVersion    = "3.10"
     strict           = ["src/debug_dojo/*"]
     ignore           = ["examples"]
+
+[tool.poe.tasks]
+    # Define your tasks here
+    lint = "ruff check --fix src"
+    format = "ruff format src"
+    type-check = "basedpyright"
+    code-quality = ["format", "lint", "type-check"]

debug_dojo-0.3.1/ruff.toml

@@ -0,0 +1,19 @@
+line-length    = 88
+target-version = "py310"
+
+
+[lint]
+    select  = ["ALL"]
+    ignore  = ["COM", "D203", "D211", "D213"]
+    exclude = ["examples"]
+
+    [lint.per-file-ignores]
+        "src/debug_dojo/_installers.py" = [
+            "PLC0415",
+            "T100",
+        ]
+        "examples/test_target.py" = ["F821"]
+        "examples/*" = ["INP001"]
+
+[format]
+    docstring-code-format = true

debug_dojo-0.3.1/src/debug_dojo/__init__.py

@@ -0,0 +1,23 @@
+"""Debugging tools for Python.
+
+This module provides functions to set up debugging tools like PuDB and Rich Traceback.
+It checks for the availability of these tools and configures them accordingly.
+
+Importing this module will install the debugging tools based on the configuration.
+Example usage:
+
+```python
+import debug_dojo.install
+
+b()
+```
+
+This will install the debugging tools and put debug breakpoint at this line.
+
+Another way to use this module is to run the desired script or module with the
+`dojo` command-line interface.
+
+```console
+$ dojo --verbose --config dojo.toml target_script.py --arg_1_for_script value1
+```
+"""

{debug_dojo-0.2.0 → debug_dojo-0.3.1}/src/debug_dojo/__main__.py

@@ -1,6 +1,6 @@
 """Entry point for the debug_dojo package."""
 
-from .cli import main
-
 if __name__ == "__main__":
+    from ._cli import main
+
     main()

debug_dojo-0.3.1/src/debug_dojo/_cli.py

@@ -0,0 +1,101 @@
+"""Command-line interface for running Python scripts or modules with debugging tools."""
+
+from __future__ import annotations
+
+import os
+import runpy
+import sys
+from bdb import BdbQuit
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from pydantic import ValidationError
+from rich import print as rich_print
+
+from ._config import DebugDojoConfig, load_config
+from ._installers import install_by_config
+
+cli = typer.Typer(
+    name="debug_dojo",
+    help="Run a Python script or module with debugging tools installed.",
+    no_args_is_help=True,
+)
+
+
+def execute_with_debug(
+    target_name: str,
+    target_args: list[str],
+    *,
+    verbose: bool,
+) -> None:
+    """Execute a target script or module with installation of debugging tools."""
+    sys.argv = [target_name, *target_args]
+
+    if verbose:
+        rich_print(f"[blue]Installing debugging tools for {target_name}.[/blue]")
+        rich_print(f"[blue]Arguments for target: {target_args}[/blue]")
+
+    config = load_config()
+    install_by_config(config)
+
+    if (
+        Path(target_name).exists()
+        or target_name.endswith(".py")
+        or os.sep in target_name
+    ):
+        if not Path(target_name).exists():
+            sys.exit(1)
+        runner = runpy.run_path
+    else:
+        runner = runpy.run_module
+
+    _ = runner(target_name, run_name="__main__")
+
+
+def display_config(config: DebugDojoConfig) -> None:
+    """Display the configuration for the debug dojo."""
+    rich_print("[blue]Using debug-dojo configuration:[/blue]")
+    rich_print(config.model_dump_json(indent=4))
+
+
+@cli.command(
+    help="Run a Python script or module with debugging tools installed.",
+    no_args_is_help=True,
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)
+def run_debug(
+    ctx: typer.Context,
+    target_name: Annotated[
+        str | None, typer.Argument(help="The target script or module to debug.")
+    ] = None,
+    config_path: Annotated[
+        Path | None, typer.Option("--config", "-c", help="Show configuration")
+    ] = None,
+    *,
+    verbose: Annotated[
+        bool,
+        typer.Option("--verbose", "-v", is_flag=True, help="Enable verbose output"),
+    ] = False,
+) -> None:
+    """Run the command-line interface."""
+    try:
+        config = load_config(config_path, verbose=verbose)
+    except ValidationError as e:
+        rich_print(f"[red]Configuration error:\n{e}[/red]")
+        sys.exit(1)
+
+    if verbose:
+        display_config(config)
+
+    if target_name:
+        try:
+            execute_with_debug(target_name, ctx.args, verbose=verbose)
+        except BdbQuit:
+            rich_print("[red]Debugging session terminated by user.[/red]")
+            sys.exit(0)
+
+
+def main() -> None:
+    """Run the command-line interface."""
+    cli()

debug_dojo-0.2.0/src/debug_dojo/compareres.py → debug_dojo-0.3.1/src/debug_dojo/_compareres.py

@@ -4,6 +4,8 @@ This module provides functions to display attributes and methods of two objects
 in a visually appealing, side-by-side format in the terminal.
 """
 
+from __future__ import annotations
+
 import contextlib
 
 from rich.columns import Columns
@@ -48,7 +50,7 @@ def _get_object_methods(obj: object) -> list[str]:
     for method_name in sorted(dir(obj)):
         # Safely get attribute, returning None if it doesn't exist
         attr = getattr(obj, method_name, None)
-        # Exclude private/protected methods (starting with '_') and non-callable attributes
+        # Exclude private/protected methods (starting with '_') and non-callables.
         if not method_name.startswith("_") and callable(attr):
             methods.append(method_name)
     return methods

debug_dojo-0.3.1/src/debug_dojo/_config.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from enum import Enum
+from pathlib import Path
+from typing import Any, cast
+
+import tomlkit
+from pydantic import BaseModel, ConfigDict
+from rich import print as rich_print
+
+
+class DebuggerType(Enum):
+    """Enum for different types of debuggers."""
+
+    PDB = "pdb"
+    PUDB = "pudb"
+    IPDB = "ipdb"
+    DEBUGPY = "debugpy"
+
+
+class Features(BaseModel):
+    """Configuration for installing debug features."""
+
+    model_config = ConfigDict(extra="forbid")  # pyright: ignore[reportUnannotatedClassAttribute]
+
+    rich_inspect: bool = True
+    """Install rich inspect as 'i' for enhanced object inspection."""
+    rich_print: bool = True
+    """Install rich print as 'p' for enhanced printing."""
+    rich_traceback: bool = True
+    """Install rich traceback for better error reporting."""
+    comparer: bool = True
+    """Install comparer as 'c' for side-by-side object comparison."""
+    breakpoint: bool = True
+    """Install breakpoint as 'b' for setting breakpoints in code."""
+
+
+class DebugDojoConfig(BaseModel):
+    """Configuration for Debug Dojo."""
+
+    model_config = ConfigDict(extra="forbid")  # pyright: ignore[reportUnannotatedClassAttribute]
+
+    debugger: DebuggerType = DebuggerType.PUDB
+    """The type of debugger to use."""
+    features: Features = Features()
+    """Features to install for debugging."""
+
+
+def resolve_config_path(config_path: Path | None) -> Path | None:
+    """Resolve the configuration path, returning a default if none is provided."""
+    if config_path:
+        if not config_path.exists():
+            msg = f"Configuration file not found:\n{config_path.resolve()}"
+            raise FileNotFoundError(msg)
+        return config_path
+
+    # Default configuration path
+    for path in (Path("dojo.toml"), Path("pyproject.toml")):
+        if path.exists():
+            return path
+    return None
+
+
+def load_raw_config(
+    config_path: Path,
+) -> dict[str, Any]:  # pyright: ignore[reportExplicitAny]
+    """Load the Debug Dojo configuration from a file.
+
+    Currently supports 'dojo.toml' or 'pyproject.toml'.
+    If no path is provided, it checks the current directory for these files.
+    """
+    with config_path.open("rb") as f:
+        config_data = tomlkit.load(f).unwrap()
+
+    # If config is in [tool.debug_dojo] (pyproject.toml), extract it.
+    if config_path.name == "dojo.toml":
+        return config_data
+
+    if config_path.name == "pyproject.toml":
+        try:
+            dojo_config = cast(
+                "dict[str, Any]",  # pyright: ignore[reportExplicitAny]
+                config_data["tool"]["debug_dojo"],
+            )
+        except KeyError:
+            return {}
+        else:
+            return dojo_config
+
+    # If the file is not recognized, raise an error.
+    msg = (
+        f"Unsupported configuration file: \n{config_path.resolve()}\n"
+        "Expected 'dojo.toml' or 'pyproject.toml'."
+    )
+    raise ValueError(msg)
+
+
+def load_config(
+    config_path: Path | None = None,
+    *,
+    verbose: bool = False,
+) -> DebugDojoConfig:
+    """Load the Debug Dojo configuration and return a DebugDojoConfig instance."""
+    resolved_path = resolve_config_path(config_path)
+
+    if verbose:
+        if resolved_path:
+            msg = f"Using configuration file: {resolved_path.resolve()}."
+        else:
+            msg = "No configuration file found, using default settings."
+        rich_print(f"[blue]{msg}[/blue]")
+
+    if not resolved_path:
+        return DebugDojoConfig()
+
+    raw_config = load_raw_config(resolved_path)
+    return DebugDojoConfig.model_validate(raw_config)