Skip to content

Latest commit

 

History

History
executable file
·
178 lines (127 loc) · 5.04 KB

README.md

File metadata and controls

executable file
·
178 lines (127 loc) · 5.04 KB

Ghostly Debugger

Welcome to Ghostly Debugger – a modern, extensible Python debugger for educational and professional use. Ghostly Debugger offers advanced features such as conditional breakpoints, variable watchpoints, variable history, interactive variable modification, call stack inspection, and more, all from a powerful command-line interface.

Table of Contents

Features

1. Breakpoints (Conditional, Hit Count, Temporary)

Set breakpoints at any file and line, with optional conditions, hit counts, and temporary status.

# Example: Set a conditional breakpoint
ghost_debugger.set_breakpoint('myfile.py', 15, condition='result > 20')

2. Watch Expressions

Monitor the value of any Python expression during execution.

# Example: Add a watch expression
ghost_debugger.add_watch_expression('result')

3. Variable Watchpoints (Break on Change)

Pause execution automatically when a variable's value changes.

# Example: Set a watchpoint on a variable
ghost_debugger.set_watchpoint('result')

4. Variable History Tracking

Track and inspect the history of variable values during debugging.

# Variable history is tracked automatically for watched variables

5. Interactive Variable Modification

Modify variables on-the-fly during a paused debugging session.

# Interactive variable modification is prompted during inspection

6. Call Stack Inspection

View the call stack and navigate between frames.

# Inspect the call stack
ghost_debugger.inspect_call_stack()

7. Exception Handling

Break on all or uncaught exceptions, and inspect tracebacks.

# Set exception break mode
# In the debugger command loop: except all | except uncaught

8. Thread Awareness

List and inspect running threads (switching is informational only).

# In the debugger command loop: threads

9. Command-Line Debugging

A rich CLI for stepping, continuing, setting/clearing breakpoints, watchpoints, evaluating expressions, and more.

# Example commands in the debugger prompt:
continue, step, next, out, bt, frame <idx>, break <file> <line> [cond=EXPR] [hit=N] [temp],
enable <file> <line>, disable <file> <line>, clear <file> <line>,
watch <expr>, watch remove <expr>, watchpoint <var>, watchpoint clear <var>,
threads, thread <ident>, eval <expr>, loglevel <level>, except all|uncaught, help

How to Use

  1. Installation:

    • Install Ghostly Debugger using pip (if published) or clone the repository.
    pip install ghostly_debugger
    # or clone and use directly
  2. Importing Ghostly Debugger:

    from ghostly_debugger import GhostlyDebugger
    ghost_debugger = GhostlyDebugger()
  3. Setting Up Your Code:

    • Create an instance and configure breakpoints, watchpoints, or expressions as needed.
    ghost_debugger.set_breakpoint('<string>', 15, condition='result > 20')
    ghost_debugger.add_watch_expression('result')
    ghost_debugger.set_watchpoint('result')
  4. Executing Your Code:

    • Run your code with the debugger:
    code_to_debug = """
    def calculate():
        x = 5
        y = 3
        result = x * y
        return result
    def main():
        z = 2
        result = calculate() + z
        return result
    result = main()
    print('Result:', result)
    """
    ghost_debugger.run_with_debugger(code_to_debug)
  5. Using the Debugger CLI:

    • When execution pauses, use the interactive prompt to step, inspect, modify, and control execution.

Release Notes

v1.1.0

  • Added variable watchpoints (break on change)
  • Improved command-line interface and help
  • Enhanced variable inspection and modification
  • Thread awareness and exception break modes

v1.0.0

  • Initial release: breakpoints, watch expressions, variable tracking, interactive modification, call stack inspection, and more.

Contribution

Contributions are welcome! Fork the repository, make improvements, and submit pull requests.

License

This project is licensed under the GNU AGPL v3 License.


Back to Top