debug-dojo 0.3.2__tar.gz → 0.4.1__tar.gz

{debug_dojo-0.3.2 → debug_dojo-0.4.1}/.gitignore

@@ -205,3 +205,5 @@ __marimo__/
 # IDE specific files
 .idea/
 .vscode/
+.DS_Store
+junit/test-results.xml

debug_dojo-0.4.1/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: debug-dojo
+Version: 0.4.1
+Summary: 🏣 Debugging dojo for Python developers
+Project-URL: Homepage, https://bwrob.github.io/debug-dojo/
+Project-URL: Documentation, https://bwrob.github.io/debug-dojo/
+Project-URL: Source, https://github.com/bwrob/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
+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.14,>=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
+
+# debug dojo
+
+<p align="center">
+  <img src="https://github.com/bwrob/debug-dojo/blob/main/docs/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**](https://bwrob.github.io/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`.
+
+## CLI usage
+
+Run your Python script with debugging tools enabled using the `debug-dojo` command:
+
+```console
+dojo my_script.py
+```
+
+You can optionally set configuration, verbose mode, and specify the debugger type. Both script files and modules are supported:
+
+```console
+dojo --debugger ipdb --config dojo.toml --verbose --module my_module
+```
+
+## From the code
+
+In the `PuDB` style, you can install all debugging tools and enter the debugging mode with a single command:
+
+```python
+object_1 = {"foo": 1, "bar": 2}
+object_2 = [1, 2, 3]
+
+import debug_dojo.install; b()
+
+p(object_1)             # Pretty print an object with Rich.
+i(object_1)             # Inspect an object using Rich.
+c(object_1, object_2)   # Compare two objects side-by-side.
+
+```
+
+## Documentation
+
+For instructions regarding installation, configuration and usage please visit [documentation](https://bwrob.github.io/debug-dojo/).
+# Changelog
+
+## v0.4.1 (2025-08-10)
+
+*release tag*: [v0.4.1](https://github.com/bwrob/debug-dojo/releases/tag/v0.4.1)
+
+- Mkdocs documentation at [debug dojo](https://bwrob.github.io/debug-dojo).
+
+## v0.4.0 (2025-08-10)
+
+*release tag*: [v0.4.0](https://github.com/bwrob/debug-dojo/releases/tag/v0.4.0)
+
+- New configuration model `DebugDojoConfig` for better structure.
+- Added support for `debugger` configuration in `dojo.toml`.
+- Updated `dojo` command to include debugger type in command call.
+- Configuration versioning allows for in-flight migration of old configurations.
+- Improved error handling in configuration loading.
+- Improved catching errors from target execution.
+
+## v0.3.2 (2025-07-28)
+
+*release tag*: [v0.3.2](https://github.com/bwrob/debug-dojo/releases/tag/v0.3.2)
+
+- 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.
+- Fixed documentation and history.
+
+## v0.2.0 (2025-07-20)
+
+*release tag*: [v0.2.0](https://github.com/bwrob/debug-dojo/releases/tag/v0.2.0)
+
+- 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.
+- Fixed `pyproject.toml` to point to GitHub repository as the homepage.
+
+## v0.1.0 (2025-07-19)
+
+*release tag*: [v0.1.0](https://github.com/bwrob/debug-dojo/releases/tag/v0.1.0)
+
+- Initial module to install debugging tools.
+- Debug mode utilities for PuDB, rich tracebacks, and object inspection.

debug_dojo-0.4.1/README.md

@@ -0,0 +1,49 @@
+# debug dojo
+
+<p align="center">
+  <img src="https://github.com/bwrob/debug-dojo/blob/main/docs/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**](https://bwrob.github.io/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`.
+
+## CLI usage
+
+Run your Python script with debugging tools enabled using the `debug-dojo` command:
+
+```console
+dojo my_script.py
+```
+
+You can optionally set configuration, verbose mode, and specify the debugger type. Both script files and modules are supported:
+
+```console
+dojo --debugger ipdb --config dojo.toml --verbose --module my_module
+```
+
+## From the code
+
+In the `PuDB` style, you can install all debugging tools and enter the debugging mode with a single command:
+
+```python
+object_1 = {"foo": 1, "bar": 2}
+object_2 = [1, 2, 3]
+
+import debug_dojo.install; b()
+
+p(object_1)             # Pretty print an object with Rich.
+i(object_1)             # Inspect an object using Rich.
+c(object_1, object_2)   # Compare two objects side-by-side.
+
+```
+
+## Documentation
+
+For instructions regarding installation, configuration and usage please visit [documentation](https://bwrob.github.io/debug-dojo/).

{debug_dojo-0.3.2 → debug_dojo-0.4.1}/pyproject.toml

@@ -1,10 +1,10 @@
 [project]
     name = "debug-dojo"
-    description = "Debbugging dojo for Python developers"
+    description = "🏣 Debugging dojo for Python developers"
     authors = [
         { name = "bwrob", email = "bartosz.marcin.wroblewski@gmail.com" },
     ]
-    requires-python = ">=3.10"
+    requires-python = ">=3.10,<3.14"
     dependencies = [
         "debugpy>=1.8.0",
         "ipdb>=0.13.0",
@@ -13,7 +13,7 @@
         "rich>=12.0.0",
         "tomlkit>=0.13.3",
         "typer>=0.15.0",
-]
+    ]
     license = 'MIT'
     license-files = ['LICENSE']
     keywords = [
@@ -36,26 +36,33 @@
         "Topic :: Software Development :: Debuggers",
         "Topic :: Software Development :: Libraries :: Python Modules",
     ]
-version = "0.3.2"
+    version = "0.4.1"
     dynamic = ['readme']
 
     [project.urls]
-        Homepage      = "https://github.com/bwrob/debug-dojo"
-        Documentation = "https://github.com/bwrob/debug-dojo/blob/main/README.md"
-        Source        = "https://github.com/bwrob/debug-dojo/tree/main/src/debug_dojo"
+        Homepage      = "https://bwrob.github.io/debug-dojo/"
+        Documentation = "https://bwrob.github.io/debug-dojo/"
+        Source        = "https://github.com/bwrob/debug-dojo/"
         Changelog     = "https://github.com/bwrob/debug-dojo/blob/main/HISTORY.md"
 
     [project.scripts]
-        # This defines your command-line script!
-        # It points to the 'main' function in your 'cli' module.
         "dojo" = "debug_dojo._cli:main"
 
 [dependency-groups]
     dev = [
-        "basedpyright>=1.31.0",
-        "jupyter>=1.1.1",
-        "poethepoet>=0.36.0",
-        "ruff>=0.12.4",
+        "basedpyright>=1.31.2",
+        "poethepoet>=0.37.0",
+        "pytest>=8.4.1",
+        "ruff>=0.12.9",
+    ]
+    docs = [
+        "mkdocs>=1.6.1",
+        "mkdocs-git-authors-plugin>=0.10.0",
+        "mkdocs-git-committers-plugin-2>=2.5.0",
+        "mkdocs-git-revision-date-localized-plugin>=1.4.7",
+        "mkdocs-material>=9.6.17",
+        "mkdocs-typer2>=0.1.5",
+        "mkdocstrings-python>=1.17.0",
 ]
 
 [build-system]
@@ -65,6 +72,9 @@ version = "0.3.2"
     ]
     build-backend = "hatchling.build"
 
+[tool.uv]
+    required-version = ">=0.8.0"
+
 [tool.hatch.metadata]
     allow-direct-references = true
 
@@ -73,8 +83,7 @@ version = "0.3.2"
         # construct the PyPI readme from README.md and HISTORY.md
         fragments = [
             { path = 'README.md' },
-            { text = "\n\n## Changelog\n\n" },
-            { path = 'HISTORY.md' },
+            { path = './docs/changelog.md' },
         ]
 
 
@@ -86,22 +95,7 @@ version = "0.3.2"
     ]
 
 [tool.basedpyright]
-    typeCheckingMode = "all"
+    typeCheckingMode = "basic"
     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"]
-    publish = [
-        "format",
-        "lint",
-        "type-check",
-        {cmd="rm -rf dist"},
-        {cmd="uv build"},
-        {cmd="uv publish"},
-    ]

{debug_dojo-0.3.2 → debug_dojo-0.4.1}/src/debug_dojo/_cli.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import os
 import runpy
 import sys
 from bdb import BdbQuit
@@ -10,10 +9,9 @@ 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 ._config import DebugDojoConfig, DebuggerType, load_config
 from ._installers import install_by_config
 
 cli = typer.Typer(
@@ -23,11 +21,13 @@ cli = typer.Typer(
 )
 
 
-def execute_with_debug(
+def execute_with_debug(  # noqa: C901
     target_name: str,
     target_args: list[str],
     *,
+    target_is_module: bool,
     verbose: bool,
+    config: DebugDojoConfig,
 ) -> None:
     """Execute a target script or module with installation of debugging tools."""
     sys.argv = [target_name, *target_args]
@@ -36,21 +36,37 @@ def execute_with_debug(
         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 target_is_module:
+        runner = runpy.run_module
+    else:
         if not Path(target_name).exists():
             sys.exit(1)
         runner = runpy.run_path
-    else:
-        runner = runpy.run_module
 
-    _ = runner(target_name, run_name="__main__")
+    try:
+        _ = runner(target_name, run_name="__main__")
+    except ImportError as e:
+        rich_print(f"[red]Error importing {target_name}:[/red]\n{e}")
+        sys.exit(1)
+    except BdbQuit:
+        rich_print("[red]Debugging session terminated by user.[/red]")
+        sys.exit(0)
+    except KeyboardInterrupt:
+        rich_print("[red]Execution interrupted by user.[/red]")
+        sys.exit(0)
+    except SystemExit as e:
+        if e.code:
+            rich_print(f"[red]Script exited with code {e.code}.[/red]")
+    except Exception as e:  # noqa: BLE001
+        rich_print(f"[red]Error while running {target_name}:[/red]\n{e}")
+        if config.exceptions.post_mortem:
+            import pdb  # noqa: PLC0415, T100
+
+            rich_print("[blue]Entering post-mortem debugging session...[/blue]")
+            pdb.post_mortem(e.__traceback__)
+        sys.exit(1)
 
 
 def display_config(config: DebugDojoConfig) -> None:
@@ -64,36 +80,42 @@ def display_config(config: DebugDojoConfig) -> None:
     no_args_is_help=True,
     context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
 )
-def run_debug(
+def run_debug(  # noqa: PLR0913
     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,
-    *,
+    debugger: Annotated[
+        DebuggerType | None,
+        typer.Option("--debugger", "-d", help="Specify the debugger to use"),
+    ] = None,
     verbose: Annotated[
         bool,
         typer.Option("--verbose", "-v", is_flag=True, help="Enable verbose output"),
     ] = False,
+    module: Annotated[
+        bool,
+        typer.Option("--module", "-m", is_flag=True, help="Run as a module"),
+    ] = 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)
+    config = load_config(config_path, verbose=verbose, debugger=debugger)
 
     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)
+        execute_with_debug(
+            target_name=target_name,
+            target_is_module=module,
+            target_args=ctx.args,
+            verbose=verbose,
+            config=config,
+        )
 
 
 def main() -> None:

debug_dojo-0.4.1/src/debug_dojo/_config.py

@@ -0,0 +1,136 @@
+"""Debug Dojo configuration module.
+
+It includes configurations for different debuggers, exception handling,
+and features that can be enabled or disabled.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any, cast
+
+from pydantic import ValidationError
+from rich import print as rich_print
+from tomlkit import parse
+from tomlkit.exceptions import TOMLKitError
+
+from ._config_models import (
+    DebugDojoConfig,
+    DebugDojoConfigV1,
+    DebugDojoConfigV2,
+    DebuggerType,
+)
+
+
+def __filter_pydantic_error_msg(error: ValidationError) -> str:
+    """Filter out specific lines from a Pydantic validation error."""
+    return "\n".join(
+        line
+        for line in str(error).splitlines()
+        if not line.startswith("For further information visit")
+    )
+
+
+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.resolve()
+
+    # Default configuration path
+    for path in (Path("dojo.toml"), Path("pyproject.toml")):
+        if path.exists():
+            return path.resolve()
+    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.
+    """
+    config_str = config_path.read_text(encoding="utf-8")
+
+    try:
+        config_data = parse(config_str).unwrap()
+    except TOMLKitError as e:
+        msg = f"Error parsing configuration file {config_path.resolve()}."
+        raise ValueError(msg) from e
+
+    # If config is in [tool.debug_dojo] (pyproject.toml), extract it.
+    if config_path.name == "pyproject.toml":
+        try:
+            dojo_config = cast("dict[str, Any]", config_data["tool"]["debug_dojo"])
+        except KeyError:
+            return {}
+        else:
+            return dojo_config
+
+    return config_data
+
+
+def load_config(  # noqa: C901
+    config_path: Path | None = None,
+    *,
+    verbose: bool = False,
+    debugger: DebuggerType | None = None,
+) -> 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}."
+        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)
+
+    config = None
+    for model in (DebugDojoConfigV2, DebugDojoConfigV1):
+        model_name = model.__name__
+        try:
+            config = model.model_validate(raw_config)
+        except ValidationError as e:
+            if verbose:
+                msg = (
+                    f"[yellow]Configuration validation error for {model_name}:\n"
+                    f"{__filter_pydantic_error_msg(e)}\n\n"
+                    f"Please check your configuration file {resolved_path}.[/yellow]"
+                )
+                rich_print(msg)
+        else:
+            if verbose or model_name != DebugDojoConfig.__name__:
+                msg = (
+                    f"[blue]Using configuration model: {model_name}.\n"
+                    f"Current configuration model {DebugDojoConfig.__name__}. [/blue]"
+                )
+                rich_print(msg)
+            break
+
+    if not config:
+        msg = (
+            f"[red]Unsupported configuration version in {resolved_path.resolve()}.\n"
+            "Please update your configuration file.[/red]"
+        )
+        rich_print(msg)
+        sys.exit(1)
+
+    while not isinstance(config, DebugDojoConfig):
+        config = config.update()
+
+    # If a debugger is specified, update the config.
+    if debugger:
+        config.debuggers.default = debugger
+
+    return config

debug_dojo-0.4.1/src/debug_dojo/_config_models.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict
+
+
+class BaseConfig(BaseModel):
+    """Base configuration class with extra fields forbidden."""
+
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+
+
+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 DebugpyConfig(BaseConfig):
+    """Configuration for debugpy debugger."""
+
+    port: int = 1992
+    """Port for debugpy debugger."""
+    host: str = "localhost"
+    """Host for debugpy debugger."""
+    wait_for_client: bool = True
+    """Whether to wait for the client to connect before starting debugging."""
+    log_to_file: bool = False
+    """Whether to log debugpy output to a file."""
+
+
+class IpdbConfig(BaseConfig):
+    """Configuration for ipdb debugger."""
+
+    context_lines: int = 20
+    """Number of context lines to show in ipdb."""
+
+
+class DebuggersConfig(BaseConfig):
+    """Configuration for debuggers."""
+
+    default: DebuggerType = DebuggerType.IPDB
+    """Default debugger to use."""
+    prompt_name: str = "debug-dojo> "
+    """Prompt name for the debugger, used in the REPL."""
+    debugpy: DebugpyConfig = DebugpyConfig()
+    """Configuration for debugpy debugger."""
+    ipdb: IpdbConfig = IpdbConfig()
+    """Configuration for ipdb debugger."""
+
+
+class ExceptionsConfig(BaseConfig):
+    """Configuration for exceptions handling."""
+
+    rich_traceback: bool = True
+    """Enable rich traceback for better error reporting."""
+    locals_in_traceback: bool = False
+    """Include local variables in traceback."""
+    post_mortem: bool = True
+    """Enable post-mortem debugging after an exception."""
+
+
+class FeaturesConfig(BaseConfig):
+    """Configuration for installing debug features."""
+
+    rich_inspect: str = "i"
+    """Install rich inspect as 'i' for enhanced object inspection."""
+    rich_print: str = "p"
+    """Install rich print as 'p' for enhanced printing."""
+    comparer: str = "c"
+    """Install comparer as 'c' for side-by-side object comparison."""
+    breakpoint: str = "b"
+    """Install breakpoint as 'b' for setting breakpoints in code."""
+
+
+class DebugDojoConfigV1(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 update(self) -> DebugDojoConfigV2:
+        """Update the configuration to the latest version."""
+        v2_exceptions = ExceptionsConfig(
+            rich_traceback=self.features.rich_traceback,
+        )
+        v2_debuggers = DebuggersConfig(default=self.debugger)
+        v2_features = FeaturesConfig(
+            rich_inspect="i" if self.features.rich_inspect else "",
+            rich_print="p" if self.features.rich_print else "",
+            comparer="c" if self.features.comparer else "",
+            breakpoint="b" if self.features.breakpoint else "",
+        )
+        return DebugDojoConfigV2(
+            exceptions=v2_exceptions,
+            debuggers=v2_debuggers,
+            features=v2_features,
+        )
+
+
+class DebugDojoConfigV2(BaseModel):
+    """Configuration for Debug Dojo."""
+
+    model_config = ConfigDict(extra="forbid")  # pyright: ignore[reportUnannotatedClassAttribute]
+
+    exceptions: ExceptionsConfig = ExceptionsConfig()
+    debuggers: DebuggersConfig = DebuggersConfig()
+    """Default debugger and configs."""
+    features: FeaturesConfig = FeaturesConfig()
+    """Features mnemonics ."""
+
+
+DebugDojoConfig = DebugDojoConfigV2

{debug_dojo-0.3.2 → debug_dojo-0.4.1}/src/debug_dojo/_installers.py

@@ -14,7 +14,13 @@ import sys
 from rich import print as rich_print
 
 from ._compareres import inspect_objects_side_by_side
-from ._config import DebugDojoConfig, DebuggerType, Features
+from ._config_models import (
+    DebugDojoConfig,
+    DebuggersConfig,
+    DebuggerType,
+    ExceptionsConfig,
+    FeaturesConfig,
+)
 
 BREAKPOINT_ENV_VAR = "PYTHONBREAKPOINT"
 
@@ -69,11 +75,11 @@ def _use_debugpy() -> None:
     debugpy.wait_for_client()
 
 
-def _rich_traceback() -> None:
+def _rich_traceback(*, locals_in_traceback: bool) -> None:
     """Check if Rich Traceback is available and set it as the default."""
     from rich import traceback
 
-    _ = traceback.install(show_locals=True)
+    _ = traceback.install(show_locals=locals_in_traceback)
 
 
 def _inspect() -> None:
@@ -90,49 +96,81 @@ def _inspect() -> None:
 
 
 def _compare() -> None:
-    """Print the object using a custom inspect function."""
+    """Print the object using a custom inspect function.
+
+    >>> _compare()
+    >>> import builtins
+    >>> callable(builtins.c)
+    True
+
+    """
     builtins.c = inspect_objects_side_by_side  # pyright: ignore[reportAttributeAccessIssue]
 
 
 def _breakpoint() -> None:
-    """Install the breakpoint function."""
+    """Install the breakpoint function.
+
+    >>> _breakpoint()
+    >>> import builtins
+    >>> callable(builtins.b)
+    True
+
+    """
     builtins.b = breakpoint  # pyright: ignore[reportAttributeAccessIssue]
 
 
 def _rich_print() -> None:
-    """Install the print from rich."""
+    """Install the print from rich.
+
+    >>> _rich_print()
+    >>> import builtins
+    >>> callable(builtins.p)
+    True
+    >>> p("test")
+    test
+
+    """
     from rich import print as rich_print
 
     builtins.p = rich_print  # pyright: ignore[reportAttributeAccessIssue]
 
 
-def _install_features(features: Features) -> None:
+def _install_features(features: FeaturesConfig) -> None:
     """Install the specified debugging features."""
     if features.rich_inspect:
         _inspect()
     if features.rich_print:
         _rich_print()
-    if features.rich_traceback:
-        _rich_traceback()
     if features.comparer:
         _compare()
     if features.breakpoint:
         _breakpoint()
 
 
-def _set_debugger(debugger: DebuggerType) -> None:  # noqa: RET503
+def _set_debugger(debugger_config: DebuggersConfig) -> None:
     """Set the debugger based on the configuration."""
+    debugger = debugger_config.default
+
     if debugger == DebuggerType.PDB:
-        return _use_pdb()
+        _use_pdb()
     if debugger == DebuggerType.PUDB:
-        return _use_pudb()
+        _use_pudb()
     if debugger == DebuggerType.IPDB:
-        return _use_ipdb()
+        _use_ipdb()
     if debugger == DebuggerType.DEBUGPY:
-        return _use_debugpy()
+        _use_debugpy()
+
+    sys.ps1 = debugger_config.prompt_name
+
+
+def _set_exceptions(exceptions: ExceptionsConfig) -> None:
+    """Set the exception handling based on the configuration."""
+    if exceptions.rich_traceback:
+        _rich_traceback(locals_in_traceback=exceptions.locals_in_traceback)
 
 
 def install_by_config(config: DebugDojoConfig) -> None:
     """Install debugging tools."""
-    _set_debugger(config.debugger)
+    _set_debugger(config.debuggers)
+    _set_exceptions(config.exceptions)
     _install_features(config.features)

debug_dojo-0.3.2/HISTORY.md

@@ -1,38 +0,0 @@
-## 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.

debug_dojo-0.3.2/LICENSE

@@ -1,21 +0,0 @@
-The MIT License (MIT)
-
-Copyright (c) 2025 to bwrob.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

debug_dojo-0.3.2/PKG-INFO

@@ -1,178 +0,0 @@
-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.

debug_dojo-0.3.2/README.md

@@ -1,104 +0,0 @@
-<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
-```

debug_dojo-0.3.2/src/debug_dojo/_config.py

@@ -1,117 +0,0 @@
-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)