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

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.5.0 → debug_dojo-0.6.0}/pyproject.toml

@@ -7,17 +7,18 @@
         "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 = [
-        "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",
+        "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" ]
@@ -25,8 +26,8 @@
     license-files = [ 'LICENSE' ]
     name = "debug-dojo"
     readme = "README.md"
-    requires-python = ">=3.10,<3.14"
-version = "0.5.0"
+    requires-python = ">=3.10,<3.15"
+version = "0.6.0"
 
     [project.urls]
         Changelog     = "https://bwrob.github.io/debug-dojo/changelog/"
@@ -43,10 +44,13 @@ version = "0.5.0"
     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",
@@ -55,11 +59,11 @@ version = "0.5.0"
         "mkdocs-material>=9.6.17",
         "mkdocs-typer2>=0.1.5",
         "mkdocstrings-python>=1.17.0",
+        "pymdown-extensions>=10.16.1",
     ]
 
 
 [tool.uv]
-    default-groups   = "all"
     package          = true
     required-version = ">=0.8.0"
 
@@ -93,11 +97,16 @@ version = "0.5.0"
 
 [tool.poe.tasks]
 
-    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." }
-    test       = { cmd = "pytest --verbose --doctest-modules", help = "Run tests using pytest." }
-    type-check = { cmd = "basedpyright", help = "Check static typing using basedpyright." }
+    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."
@@ -119,8 +128,15 @@ version = "0.5.0"
             { 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.5.0 → debug_dojo-0.6.0}/src/debug_dojo/_cli.py

@@ -42,7 +42,20 @@ def __execute_with_debug(  # noqa: C901
     verbose: bool,
     config: DebugDojoConfig,
 ) -> None:
-    """Execute a target script or module with installed debugging tools."""
+    """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:
@@ -87,12 +100,6 @@ def __execute_with_debug(  # noqa: C901
         raise typer.Exit(1) from e
 
 
-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,
@@ -124,7 +131,33 @@ def run_debug(  # noqa: PLR0913
         typer.Option("--exec", "-e", help="Run a command"),
     ] = False,
 ) -> None:
-    """Run the command-line interface."""
+    """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]"
@@ -142,7 +175,7 @@ def run_debug(  # noqa: PLR0913
     config = load_config(config_path, verbose=verbose, debugger=debugger)
 
     if verbose:
-        display_config(config)
+        rich_print(f"[blue]Using debug-dojo configuration: {config} [/blue]")
 
     if target_name:
         __execute_with_debug(

{debug_dojo-0.5.0 → debug_dojo-0.6.0}/src/debug_dojo/_compare.py

@@ -14,8 +14,16 @@ from rich.panel import Panel
 from rich.text import Text
 
 
-def _get_object_attributes(obj: object) -> list[str]:
-    """Extract and format non-callable attributes of an object."""
+def get_object_attributes(obj: object) -> list[str]:
+    """Extract and format non-callable attributes of an object.
+
+    Args:
+        obj (object): The object to extract attributes from.
+
+    Returns:
+        list[str]: A list of formatted strings, each representing an attribute.
+
+    """
     attributes: list[str] = []
     for attr_name in sorted(dir(obj)):
         # Safely get attribute, returning None if it doesn't exist
@@ -28,8 +36,16 @@ def _get_object_attributes(obj: object) -> list[str]:
     return attributes
 
 
-def _get_object_methods(obj: object) -> list[str]:
-    """Extract and format public callable methods of an object."""
+def get_object_methods(obj: object) -> list[str]:
+    """Extract and format public callable methods of an object.
+
+    Args:
+        obj (object): The object to extract methods from.
+
+    Returns:
+        list[str]: A list of method names.
+
+    """
     methods: list[str] = []
     for method_name in sorted(dir(obj)):
         # Safely get attribute, returning None if it doesn't exist
@@ -40,11 +56,18 @@ def _get_object_methods(obj: object) -> list[str]:
     return methods
 
 
-def _get_simplified_object_info(obj: object) -> list[Text]:
+def get_simplified_object_info(obj: object) -> list[Text]:
     """Generate a simplified, Rich-formatted inspection output for an object.
 
     Handles basic Python types by displaying their value directly. For other objects, it
     lists their attributes and public methods.
+
+    Args:
+        obj (object): The object to generate info for.
+
+    Returns:
+        list[Text]: A list of Rich Text objects representing the object's information.
+
     """
     info_lines: list[Text] = []
     obj_type: str = type(obj).__name__
@@ -62,7 +85,7 @@ def _get_simplified_object_info(obj: object) -> list[Text]:
         return info_lines
 
     # For other objects, list attributes
-    attributes = _get_object_attributes(obj)
+    attributes = get_object_attributes(obj)
     if attributes:
         info_lines.append(Text("Attributes:", style="bold"))
         info_lines.extend([Text(f"  {attr}") for attr in attributes])
@@ -71,7 +94,7 @@ def _get_simplified_object_info(obj: object) -> list[Text]:
     info_lines.append(Text(""))
 
     # List methods
-    methods = _get_object_methods(obj)
+    methods = get_object_methods(obj)
     if methods:
         info_lines.append(Text("Methods:", style="bold"))
         info_lines.extend([Text(f"  {method}()") for method in methods])
@@ -88,11 +111,16 @@ def inspect_objects_side_by_side(
     """Display two Python objects side-by-side in the terminal using Rich.
 
     Showing their attributes and methods in a simplified, aligned format.
+
+    Args:
+        obj1 (object): The first object to display.
+        obj2 (object): The second object to display.
+
     """
     main_console: Console = Console()
 
-    lines1: list[Text] = _get_simplified_object_info(obj1)
-    lines2: list[Text] = _get_simplified_object_info(obj2)
+    lines1: list[Text] = get_simplified_object_info(obj1)
+    lines2: list[Text] = get_simplified_object_info(obj2)
 
     # Determine the maximum number of lines to ensure consistent height
     max_lines: int = max(len(lines1), len(lines2))