debug-dojo 0.1.0__py3-none-any.whl

debug_dojo/__init__.py

@@ -0,0 +1,20 @@
+"""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.
+"""
+
+from .installers import install_inspect, use_pudb, use_rich_traceback
+
+ii = install_inspect
+pudb = use_pudb
+rt = use_rich_traceback
+
+__all__ = [
+    "ii",
+    "install_inspect",
+    "pudb",
+    "rt",
+    "use_pudb",
+    "use_rich_traceback",
+]

debug_dojo/all.py

@@ -0,0 +1,22 @@
+"""Install all debugging tools for the debug_dojo package."""
+
+from .installers import (
+    install_breakpoint,
+    install_compare,
+    install_inspect,
+    use_pudb,
+    use_rich_traceback,
+)
+
+
+def install_all() -> None:
+    """Install debugging tools."""
+    use_pudb()
+    use_rich_traceback()
+
+    install_inspect()
+    install_compare()
+    install_breakpoint()
+
+
+install_all()

debug_dojo/compareres.py

@@ -0,0 +1,134 @@
+"""Utilities for side-by-side inspection and comparison of Python objects using Rich.
+
+This module provides functions to display attributes and methods of two objects
+in a visually appealing, side-by-side format in the terminal.
+"""
+
+import contextlib
+
+from rich.columns import Columns
+from rich.console import Console
+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.
+
+    Args:
+        obj: The object to inspect.
+
+    Returns:
+        A list of strings, each representing an attribute in 'name=value' format.
+
+    """
+    attributes: list[str] = []
+    for attr_name in sorted(dir(obj)):
+        # Safely get attribute, returning None if it doesn't exist
+        attr = getattr(obj, attr_name, None)
+        # Exclude dunder methods and callable attributes
+        if not attr_name.startswith("__") and not callable(attr):
+            with contextlib.suppress(AttributeError):
+                # Use !r for robust string representation of the attribute value
+                attributes.append(f"{attr_name}={attr!r}")
+    return attributes
+
+
+def _get_object_methods(obj: object) -> list[str]:
+    """Extract and format public callable methods of an object.
+
+    Args:
+        obj: The object to inspect.
+
+    Returns:
+        A list of strings, each representing a method name.
+
+    """
+    methods: 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
+        if not method_name.startswith("_") and callable(attr):
+            methods.append(method_name)
+    return methods
+
+
+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: The object to generate info for.
+
+    Returns:
+        A list of Rich Text objects, each representing a line of information.
+
+    """
+    info_lines: list[Text] = []
+    obj_type: str = type(obj).__name__
+    info_lines.append(Text(f"<class '{obj_type}'>", style="cyan bold"))
+    info_lines.append(Text(""))
+
+    # Handle basic data types by displaying their value directly
+    if isinstance(obj, (str, int, float, list, dict, tuple, set, bool)) or obj is None:
+        info_lines.append(Text("Value:", style="bold"))
+        info_lines.append(Text(f"  {obj!r}", style="yellow"))
+        info_lines.append(Text(""))
+        info_lines.append(
+            Text("No attributes or methods to display for this type.", style="dim")
+        )
+        return info_lines
+
+    # For other objects, list attributes
+    attributes = _get_object_attributes(obj)
+    if attributes:
+        info_lines.append(Text("Attributes:", style="bold"))
+        info_lines.extend([Text(f"  {attr}") for attr in attributes])
+    else:
+        info_lines.append(Text("No attributes found.", style="dim"))
+    info_lines.append(Text(""))
+
+    # List methods
+    methods = _get_object_methods(obj)
+    if methods:
+        info_lines.append(Text("Methods:", style="bold"))
+        info_lines.extend([Text(f"  {method}()") for method in methods])
+    else:
+        info_lines.append(Text("No public methods found.", style="dim"))
+
+    return info_lines
+
+
+def inspect_objects_side_by_side(
+    obj1: object,
+    obj2: object,
+) -> None:
+    """Display two Python objects side-by-side in the terminal using Rich.
+
+    Showing their attributes and methods in a simplified, aligned format.
+    """
+    main_console: Console = Console()
+
+    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))
+
+    # Pad the shorter list of lines with empty Text objects to match the height
+    if len(lines1) < max_lines:
+        lines1.extend([Text("")] * (max_lines - len(lines1)))
+    if len(lines2) < max_lines:
+        lines2.extend([Text("")] * (max_lines - len(lines2)))
+
+    # Join the padded lines into a single Text object for the Panel content
+    padded_inspect_text1: Text = Text("\n").join(lines1)
+    padded_inspect_text2: Text = Text("\n").join(lines2)
+
+    panel1: Panel = Panel(padded_inspect_text1, border_style="green", expand=True)
+    panel2: Panel = Panel(padded_inspect_text2, border_style="green", expand=True)
+
+    main_console.print(Columns([panel1, panel2]))

debug_dojo/installers.py

@@ -0,0 +1,62 @@
+"""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.
+"""
+
+import builtins
+import os
+import sys
+
+import pudb  # pyright: ignore[reportMissingTypeStubs]
+from rich import (
+    inspect,
+    traceback,
+)
+
+from .compareres import inspect_objects_side_by_side
+
+BREAKPOINT_ENV_VAR = "PYTHONBREAKPOINT"
+PUDB_SET_TRACE = "pudb.set_trace"
+
+
+def use_pudb() -> None:
+    """Check if PuDB is available and set it as the default debugger."""
+    # Set the environment variable. This will primarily affect child processes or later
+    # Python startup if the script is re-run.
+    os.environ[BREAKPOINT_ENV_VAR] = PUDB_SET_TRACE
+
+    # Crucially, to make `breakpoint()` work *immediately* in the current process,
+    # we need to explicitly set `sys.breakpointhook`.
+    sys.breakpointhook = pudb.set_trace
+
+
+def use_rich_traceback() -> None:
+    """Check if Rich Traceback is available and set it as the default."""
+    # Install rich traceback to enhance the debugging experience
+    _ = traceback.install(show_locals=True)
+
+
+def install_inspect() -> None:
+    """Print the object using a custom inspect function."""
+
+    def inspect_with_defaults(obj: object, **kwargs: object) -> None:
+        """Inspect an object using Rich's inspect function."""
+        if not kwargs:
+            kwargs = {"methods": True, "private": True}
+        return inspect(obj, **kwargs)  # pyright: ignore[reportArgumentType]
+
+    # Inject the custom inspect function into builtins
+    builtins.i = inspect_with_defaults  # pyright: ignore[reportAttributeAccessIssue]
+
+
+def install_compare() -> None:
+    """Print the object using a custom inspect function."""
+    # Inject the custom side-by-side comparison function into builtins
+    builtins.c = inspect_objects_side_by_side  # pyright: ignore[reportAttributeAccessIssue]
+
+
+def install_breakpoint() -> None:
+    """Install the breakpoint function."""
+    # Set the breakpoint function to use PuDB's set_trace
+    builtins.b = pudb.set_trace  # pyright: ignore[reportAttributeAccessIssue]

debug_dojo-0.1.0.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.3
+Name: debug-dojo
+Version: 0.1.0
+Summary: Debbugging dojo for Python developers
+Author: bwrob
+Author-email: bwrob <bartosz.marcin.wroblewski@gmail.com>
+Requires-Dist: pudb>=2016.1
+Requires-Dist: rich>=11.0.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# 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 PuDB. All tools can be installed at once or individually, allowing for flexible debugging setups.
+
+## Features
+
+- **Simple API:** Install all tools or only what you need.
+- **PuDB integration:** Quickly enable the PuDB TUI 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
+
+```sh
+pip install debug-dojo
+```
+
+## Usage
+
+### Install all debugging tools
+
+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()
+```
+
+Where`b()` is a builtin-injected function that sets a breakpoint using PuDB's `set_trace()`.
+In the PuDB interface, you can use the following functions:
+
+- `i(object_1)` to inspect an object.
+- `c(object_1, object_2)` to compare two objects side-by-side.
+
+
+### Use individual tools
+
+```python
+from debug_dojo import install_inspect, use_pudb, use_rich_traceback
+
+install_inspect()         # Enable object inspection helpers
+use_pudb()                # Set up PuDB as the debugger
+use_rich_traceback()      # Enable Rich tracebacks
+```
+
+### Compare objects side-by-side
+
+```python
+from debug_dojo.compareres import inspect_objects_side_by_side
+
+a = {"foo": 1, "bar": 2}
+b = [1, 2, 3]
+inspect_objects_side_by_side(a, b)
+```
+
+## Development
+
+### Run tests
+
+```sh
+pytest
+```
+
+### Lint and type check
+
+```sh
+ruff check src/debug_dojo --fix
+basedpyright src/debug_dojo
+```
+
+## License
+
+MIT License
+
+---
+
+*Debugging made delightful!*

debug_dojo-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+debug_dojo/__init__.py,sha256=9d228c661b70e9f6c1859682cccf3ba7d2326dc7e5c944c680fd23408847aaf9,447
+debug_dojo/all.py,sha256=3f29baf80236d01b49bf4aae859e34deb3ac0daee68a1abf81681ebf941c6111,385
+debug_dojo/compareres.py,sha256=717d3e7676be4fbf1918b3e30c0e99544e891f9e0c3f1ebd0dea1bdebdfda6e7,4737
+debug_dojo/installers.py,sha256=eaede2a3642d08a4d5ff2c30e1fef1ee5e1e14a930ed3a8269bea697e28dcd8d,2154
+debug_dojo/py.typed,sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855,0
+debug_dojo-0.1.0.dist-info/WHEEL,sha256=d10358abd5c217094bd40da9e447bd3c8979f6f95a2ce6e2da850cf9abfe7943,78
+debug_dojo-0.1.0.dist-info/entry_points.txt,sha256=0e5c9888d0d9f8636622b36825f2ebe129eaf706916c356787b2930c6efbcf1e,48
+debug_dojo-0.1.0.dist-info/METADATA,sha256=d879fe6d7672ded19a00635e7829237379f2d46b4c44c1940ab8e649ff1023e5,2215
+debug_dojo-0.1.0.dist-info/RECORD,,

debug_dojo-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.0
+Root-Is-Purelib: true
+Tag: py3-none-any

debug_dojo-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+debug-dojo = debug_dojo:main
+