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

debug_dojo-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+# 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.6.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: debug-dojo
+Version: 0.6.0
+Summary: 🏣 debug dojo, a place for zen debugging
+Author-email: bwrob <bartosz.marcin.wroblewski@gmail.com>
+License-Expression: MIT
+Project-URL: Changelog, https://bwrob.github.io/debug-dojo/changelog/
+Project-URL: Documentation, https://bwrob.github.io/debug-dojo/
+Project-URL: Homepage, https://bwrob.github.io/debug-dojo/
+Project-URL: Source, https://github.com/bwrob/debug-dojo/
+Keywords: debugging,inspection,tools,development
+Classifier: Intended Audience :: Developers
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dacite>=1.0.0
+Requires-Dist: debugpy>=1.0.0
+Requires-Dist: ipdb>=0.12.0
+Requires-Dist: pudb>=2019.1
+Requires-Dist: rich>=10.0.0
+Requires-Dist: tomlkit>=0.7.0
+Requires-Dist: typer>=0.3.0
+Dynamic: license-file
+
+# 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:350px;"/>
+</p>
+
+<p align="center">
+<em>🏣 debug dojo, a place for zen debugging</em>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/debug-dojo">
+    <img src="https://img.shields.io/pypi/v/debug-dojo.svg?style=flat-square" alt="PyPi Version">
+  </a>
+  <a href="https://pypi.org/pypi/debug-dojo/">
+    <img src="https://img.shields.io/pypi/pyversions/debug-dojo.svg?style=flat-square" alt="PyPI pyversions">
+  </a>
+  <a href="https://pepy.tech/project/debug-dojo">
+    <img src="https://static.pepy.tech/badge/debug-dojo/month" alt="downloads">
+  </a>
+  <a href="https://github.com/bwrob/debug-dojo/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/bwrob/debug-dojo.svg" alt="license">
+  </a>
+  <a href="https://results.pre-commit.ci/latest/github/bwrob/debug-dojo/main">
+    <img src="https://results.pre-commit.ci/badge/github/bwrob/debug-dojo/main.svg" alt="pre-commit.ci status">
+  </a>
+</p>
+
+[**debug-dojo**](https://bwrob.github.io/debug-dojo/) is a powerful Python package designed to streamline your debugging workflow directly from the terminal. It integrates seamlessly with popular debuggers and enhances your inspection capabilities with beautiful, readable output.
+
+## ✨ Features
+
+*   **Unified Debugging Interface:** Easily launch your scripts or modules with your preferred debugger (`debugpy`, `pudb`, `pdb`, `ipdb`).
+*   **Enhanced Output with Rich:** Leverages [`rich`](https://github.com/Textualize/rich) for stunning, syntax-highlighted code, pretty-printed objects, and improved tracebacks.
+*   **Side-by-Side Object Comparison:** Quickly identify differences between two Python objects.
+*   **Interactive Object Inspection:** Dive deep into object structures with a powerful `inspect` utility.
+*   **Simplified Breakpoints:** Set breakpoints effortlessly with a concise helper function.
+
+## 🚀 Installation
+
+Install `debug-dojo` using `pip`:
+
+```bash
+pip install debug-dojo
+```
+
+For full debugger support, you might want to install optional dependencies:
+
+```bash
+pip install "debug-dojo[all]"
+```
+
+## 💻 CLI Usage
+
+Run your Python script or module with `debug-dojo`:
+
+```console
+dojo my_script.py
+```
+
+Specify a debugger, configuration file, or enable verbose output:
+
+```console
+dojo --debugger ipdb --config dojo.toml --verbose --module my_module
+```
+
+Run an executable command with debugging tools:
+
+```console
+dojo --exec pytest
+```
+
+## 🐍 Usage in Code
+
+Integrate `debug-dojo` directly into your Python code for on-demand debugging and inspection utilities:
+
+```python
+import debug_dojo.install
+
+# Set a breakpoint and enter the debugger
+# debug_dojo.install.b() # Equivalent to breakpoint()
+
+object_1 = {"foo": 1, "bar": 2}
+object_2 = [1, 2, 3]
+
+# Pretty print an object with Rich
+debug_dojo.install.p(object_1)
+
+# Inspect an object using Rich
+debug_dojo.install.i(object_1)
+
+# Compare two objects side-by-side
+debug_dojo.install.c(object_1, object_2)
+
+# Enter the debugger (e.g., ipdb, pudb, pdb, debugpy based on config)
+# debug_dojo.install.b()
+```
+
+## 📚 Documentation
+
+For comprehensive instructions on installation, configuration, advanced usage, and API reference, please visit the [official documentation](https://bwrob.github.io/debug-dojo/).
+
+## 🤝 Contributing
+
+Contributions are welcome! Please refer to the [development guidelines](https://bwrob.github.io/debug-dojo/development/) for details on how to set up your development environment and submit changes.

debug_dojo-0.6.0/README.md

@@ -0,0 +1,105 @@
+# 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:350px;"/>
+</p>
+
+<p align="center">
+<em>🏣 debug dojo, a place for zen debugging</em>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/debug-dojo">
+    <img src="https://img.shields.io/pypi/v/debug-dojo.svg?style=flat-square" alt="PyPi Version">
+  </a>
+  <a href="https://pypi.org/pypi/debug-dojo/">
+    <img src="https://img.shields.io/pypi/pyversions/debug-dojo.svg?style=flat-square" alt="PyPI pyversions">
+  </a>
+  <a href="https://pepy.tech/project/debug-dojo">
+    <img src="https://static.pepy.tech/badge/debug-dojo/month" alt="downloads">
+  </a>
+  <a href="https://github.com/bwrob/debug-dojo/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/bwrob/debug-dojo.svg" alt="license">
+  </a>
+  <a href="https://results.pre-commit.ci/latest/github/bwrob/debug-dojo/main">
+    <img src="https://results.pre-commit.ci/badge/github/bwrob/debug-dojo/main.svg" alt="pre-commit.ci status">
+  </a>
+</p>
+
+[**debug-dojo**](https://bwrob.github.io/debug-dojo/) is a powerful Python package designed to streamline your debugging workflow directly from the terminal. It integrates seamlessly with popular debuggers and enhances your inspection capabilities with beautiful, readable output.
+
+## ✨ Features
+
+*   **Unified Debugging Interface:** Easily launch your scripts or modules with your preferred debugger (`debugpy`, `pudb`, `pdb`, `ipdb`).
+*   **Enhanced Output with Rich:** Leverages [`rich`](https://github.com/Textualize/rich) for stunning, syntax-highlighted code, pretty-printed objects, and improved tracebacks.
+*   **Side-by-Side Object Comparison:** Quickly identify differences between two Python objects.
+*   **Interactive Object Inspection:** Dive deep into object structures with a powerful `inspect` utility.
+*   **Simplified Breakpoints:** Set breakpoints effortlessly with a concise helper function.
+
+## 🚀 Installation
+
+Install `debug-dojo` using `pip`:
+
+```bash
+pip install debug-dojo
+```
+
+For full debugger support, you might want to install optional dependencies:
+
+```bash
+pip install "debug-dojo[all]"
+```
+
+## 💻 CLI Usage
+
+Run your Python script or module with `debug-dojo`:
+
+```console
+dojo my_script.py
+```
+
+Specify a debugger, configuration file, or enable verbose output:
+
+```console
+dojo --debugger ipdb --config dojo.toml --verbose --module my_module
+```
+
+Run an executable command with debugging tools:
+
+```console
+dojo --exec pytest
+```
+
+## 🐍 Usage in Code
+
+Integrate `debug-dojo` directly into your Python code for on-demand debugging and inspection utilities:
+
+```python
+import debug_dojo.install
+
+# Set a breakpoint and enter the debugger
+# debug_dojo.install.b() # Equivalent to breakpoint()
+
+object_1 = {"foo": 1, "bar": 2}
+object_2 = [1, 2, 3]
+
+# Pretty print an object with Rich
+debug_dojo.install.p(object_1)
+
+# Inspect an object using Rich
+debug_dojo.install.i(object_1)
+
+# Compare two objects side-by-side
+debug_dojo.install.c(object_1, object_2)
+
+# Enter the debugger (e.g., ipdb, pudb, pdb, debugpy based on config)
+# debug_dojo.install.b()
+```
+
+## 📚 Documentation
+
+For comprehensive instructions on installation, configuration, advanced usage, and API reference, please visit the [official documentation](https://bwrob.github.io/debug-dojo/).
+
+## 🤝 Contributing
+
+Contributions are welcome! Please refer to the [development guidelines](https://bwrob.github.io/debug-dojo/development/) for details on how to set up your development environment and submit changes.

debug_dojo-0.6.0/pyproject.toml

@@ -0,0 +1,142 @@
+[project]
+    authors = [ { name = "bwrob", email = "bartosz.marcin.wroblewski@gmail.com" } ]
+    classifiers = [
+        "Intended Audience :: Developers",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
+        "Programming Language :: Python :: 3.14",
+        "Topic :: Software Development :: Debuggers",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+    ]
+    dependencies = [
+        "dacite>=1.0.0",
+        "debugpy>=1.0.0",
+        "ipdb>=0.12.0",
+        "pudb>=2019.1",
+        "rich>=10.0.0",
+        "tomlkit>=0.7.0",
+        "typer>=0.3.0",
+    ]
+    description = "🏣 debug dojo, a place for zen debugging"
+    keywords = [ "debugging", "inspection", "tools", "development" ]
+    license = 'MIT'
+    license-files = [ 'LICENSE' ]
+    name = "debug-dojo"
+    readme = "README.md"
+    requires-python = ">=3.10,<3.15"
+version = "0.6.0"
+
+    [project.urls]
+        Changelog     = "https://bwrob.github.io/debug-dojo/changelog/"
+        Documentation = "https://bwrob.github.io/debug-dojo/"
+        Homepage      = "https://bwrob.github.io/debug-dojo/"
+        Source        = "https://github.com/bwrob/debug-dojo/"
+
+    [project.scripts]
+        "dojo" = "debug_dojo._cli:main"
+
+
+[dependency-groups]
+
+    dev = [
+        "basedpyright>=1.31.2",
+        "coverage>=7.10.4",
+        "diff-cover>=9.6.0",
+        "poethepoet>=0.37.0",
+        "pytest>=8.4.1",
+        "pytest-cov>=6.2.1",
+        "ruff>=0.12.9",
+        "tach>=0.29.0",
+    ]
+    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",
+        "pymdown-extensions>=10.16.1",
+    ]
+
+
+[tool.uv]
+    package          = true
+    required-version = ">=0.8.0"
+
+
+[tool.basedpyright]
+    ignore           = [ "examples", "tests/assets" ]
+    pythonVersion    = "3.10"
+    strict           = [ "src/debug_dojo/*" ]
+    typeCheckingMode = "all"
+
+
+[tool.ruff]
+    line-length    = 88
+    target-version = "py310"
+
+    [tool.ruff.lint]
+        exclude = [ "examples" ]
+        ignore  = [ "COM", "D203", "D211", "D213" ]
+        select  = [ "ALL" ]
+
+        [tool.ruff.lint.per-file-ignores]
+            "examples/*"                    = [ "INP001" ]
+            "examples/test_target.py"       = [ "F821" ]
+            "src/debug_dojo/_installers.py" = [ "PLC0415", "T100" ]
+            "tests/*"                       = [ "S101", "T201" ]
+            "tests/assets/*"                = [ "T201", "INP001", "F821" ]
+
+    [tool.ruff.format]
+        docstring-code-format = true
+
+
+[tool.poe.tasks]
+
+    coverage         = { cmd = "pytest --doctest-modules --verbose --cov --cov-report=xml", help = "Create test coverage report." }
+    dependencies     = { cmd = "tach check", help = "Check dependency layers using tach." }
+    dependency-graph = { cmd = "tach show --mermaid -o docs/dependency_graph.mmd", help = "Generate the dependency graph." }
+    docs             = { cmd = "hap run mkdocs serve", help = "Spawn docs server." }
+    format           = { cmd = "ruff format --diff --config=pyproject.toml", help = "Check code formatting using ruff." }
+    lint             = { cmd = "uv run ruff check --config=pyproject.toml", help = "Check code rules using ruff." }
+    precommit        = { cmd = "pre-commit run --all-files", help = "Run all code quality checks." }
+    publish-docs     = { cmd = "mkdocs gh-deploy --force", help = "Publish the docs to GitHub Pages." }
+    test             = { cmd = "pytest", help = "Run tests using pytest." }
+    type-check       = { cmd = "basedpyright src tests", help = "Check static typing using basedpyright." }
+
+    [tool.poe.tasks.code-quality]
+        help        = "Run all code quality checks."
+        ignore_fail = "return_non_zero"
+        sequence    = [ "fix", "precommit", "format", "lint", "type-check" ]
+
+    [tool.poe.tasks.fix]
+        default_item_type = "cmd"
+        help = "Code quality fixes using ruff."
+        ignore_fail = "return_non_zero"
+        sequence = [
+            "ruff check --fix --unsafe-fixes --config=pyproject.toml",
+            "ruff format --config=pyproject.toml",
+        ]
+
+    [tool.poe.tasks.publish]
+        sequence = [
+            "code-quality",
+            { cmd = "rm -rf dist" },
+            { cmd = "uv build" },
+            { cmd = "uv publish" },
+            "publish-docs",
+        ]
+
+[tool.docformatter]
+    black   = true
+    non-cap = [ "dojo" ]
+
+[tool.pytest.ini_options]
+    addopts                = "--verbose --doctest-modules"
+    collect_imported_tests = false
+    console_output_style   = "classic"
+    minversion             = "8.0"

debug_dojo-0.6.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

debug_dojo-0.6.0/src/debug_dojo/_cli.py

@@ -0,0 +1,192 @@
+"""Command-line interface for running Python scripts or modules with debugging tools."""
+
+from __future__ import annotations
+
+import runpy
+import sys
+import traceback
+from bdb import BdbQuit
+from enum import Enum
+from pathlib import Path
+from shutil import which
+from typing import Annotated
+
+import typer
+from rich import print as rich_print
+
+from ._config import load_config
+from ._config_models import DebugDojoConfig, DebuggerType  # noqa: TC001
+from ._installers import install_by_config
+
+
+class ExecMode(Enum):
+    """Execution mode for the target."""
+
+    FILE = "file"
+    MODULE = "module"
+    EXECUTABLE = "executable"
+
+
+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(  # noqa: C901
+    target_name: str,
+    target_args: list[str],
+    *,
+    target_mode: ExecMode,
+    verbose: bool,
+    config: DebugDojoConfig,
+) -> None:
+    """Execute a target script or module with installed debugging tools.
+
+    Args:
+        target_name (str): The name of the script, module, or executable to run.
+        target_args (list[str]): Arguments to pass to the target.
+        target_mode (ExecMode): The execution mode (FILE, MODULE, or EXECUTABLE).
+        verbose (bool): If True, print verbose output.
+        config (DebugDojoConfig): The debug-dojo configuration.
+
+    Raises:
+        typer.Exit: If the target file is not found, or if an import error occurs,
+                    or if the script exits with a non-zero code.
+
+    """
+    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]")
+
+    install_by_config(config)
+
+    if target_mode is ExecMode.MODULE:
+        runner = runpy.run_module
+    else:
+        if target_mode is ExecMode.EXECUTABLE:
+            target_name = which(target_name) or target_name
+
+        if not Path(target_name).exists():
+            raise typer.Exit(1)
+
+        runner = runpy.run_path
+
+    try:
+        _ = runner(target_name, run_name="__main__")
+    except ImportError as e:
+        rich_print(f"[red]Error importing {target_name}:[/red]\n{e}")
+        raise typer.Exit(1) from e
+    except BdbQuit:
+        rich_print("[red]Debugging session terminated by user.[/red]")
+        raise typer.Exit(0) from None
+    except KeyboardInterrupt:
+        rich_print("[red]Execution interrupted by user.[/red]")
+        raise typer.Exit(0) from None
+    except SystemExit as e:
+        if e.code:
+            rich_print(f"[red]Script exited with code {e.code}.[/red]")
+    except Exception as e:
+        rich_print(f"[red]Error while running {target_name}:[/red]\n{e}")
+        rich_print(traceback.format_exc())
+        if config.exceptions.post_mortem:
+            import ipdb  # pyright: ignore[reportMissingTypeStubs]  # noqa: PLC0415, T100
+
+            rich_print("[blue]Entering post-mortem debugging session...[/blue]")
+            ipdb.post_mortem(e.__traceback__)  # pyright: ignore[reportUnknownMemberType]
+        raise typer.Exit(1) from e
+
+
+@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(  # 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", help="Enable verbose output"),
+    ] = False,
+    module: Annotated[
+        bool,
+        typer.Option("--module", "-m", help="Run a module"),
+    ] = False,
+    executable: Annotated[
+        bool,
+        typer.Option("--exec", "-e", help="Run a command"),
+    ] = False,
+) -> None:
+    """Run a Python script, module, or executable with debug-dojo tools.
+
+    This command acts as the main entry point for `debug-dojo`, allowing users to
+    execute their code while automatically installing and configuring debugging tools
+    based on the provided options or configuration file.
+
+    Args:
+        ctx (typer.Context): The Typer context object.
+        target_name (str | None): The path to the script, name of the module, or
+                                  name of the executable to run. If not provided,
+                                  the command will exit.
+        config_path (Path | None): Path to a custom configuration file
+                                   (e.g., `dojo.toml`).
+        debugger (DebuggerType | None): Override the default debugger specified
+                                        in the config.
+        verbose (bool): Enable verbose output, showing loaded configuration
+                        and installation steps.
+        module (bool): Treat `target_name` as a Python module to run
+                       (e.g., `dojo -m my_package.my_module`).
+        executable (bool): Treat `target_name` as an executable command to run
+                           (e.g., `dojo -e pytest`).
+
+    Raises:
+        typer.Exit: If `--module` and `--exec` are used together, or if the target
+                    cannot be executed, or if an error occurs during execution.
+
+    """
+    if module and executable:
+        rich_print(
+            "[red]Error: --module and --command options are mutually exclusive.[/red]"
+        )
+        raise typer.Exit(1)
+
+    mode = (
+        ExecMode.EXECUTABLE
+        if executable
+        else ExecMode.MODULE
+        if module
+        else ExecMode.FILE
+    )
+
+    config = load_config(config_path, verbose=verbose, debugger=debugger)
+
+    if verbose:
+        rich_print(f"[blue]Using debug-dojo configuration: {config} [/blue]")
+
+    if target_name:
+        __execute_with_debug(
+            target_name=target_name,
+            target_mode=mode,
+            target_args=ctx.args,
+            verbose=verbose,
+            config=config,
+        )
+
+
+def main() -> None:
+    """Run the command-line interface."""
+    cli()