MyDebugger

MyDebugger is an interactive CLI debugger for Python scripts, built on top of sys.settrace. It is designed for learning and experimentation with stepping controls, breakpoints, watchpoints, safe expression evaluation, and lightweight mutation history.

Features

• Line-by-line stepping for your own Python scripts
• Conditional and temporary breakpoints with hit targeting
• Watchpoints that pause execution when values change
• Call stack inspection and delta-based mutation history
• Sandboxed expression evaluation (unsafe calls are blocked)

Requirements

• Python 3.9+
• No third-party dependencies

Project Layout

.
├── mydebugger.py
├── README.md
├── LICENSE
├── .gitignore
└── test_scripts/
    ├── test1_basic.py
    ├── test2_intermediate.py
    └── test3_advanced.py

Quick Start

Run the debugger with a target script:

python mydebugger.py test_scripts/test1_basic.py

When execution pauses, the prompt appears as:

(MyDebugger)>

Built-In Help Menu

The debugger's -h / -help output is:

NAME
       mydebugger - Advanced interactive micro-debugger for Python scripts.

SYNOPSIS
       (MyDebugger)> [COMMAND] [OPTIONS]

DESCRIPTION
       A frame-aware, highly secure debugger featuring AST-evaluated watchpoints,
       delta-based state history, and instruction-level precise step-overs.

COMMANDS
   Execution & Stepping
       -si                 Step INTO function calls.
       -so                 Step OVER the current line (Instruction-aware).
       -su                 Step OUT of the current function frame.
       -c                  CONTINUE execution until the next breakpoint.
       -q, -quit           QUIT the debugger and terminate the script.

   Breakpoints
       -b [L] [COND]       Set a breakpoint at line L with optional condition.
                         Flags:
                         --temp  (Delete after first hit)
                         --hit N (Trigger only on Nth hit)
                         Ex: -b 42 x > 5 --temp
       -lb                 LIST all active breakpoints.
       -db [L]             DELETE breakpoint at line L.
       -cb                 CLEAR all breakpoints.

   Inspection & Data
       -p [EXPR]           PRINT expression safely (No function calls allowed).
       -w [EXPR]           WATCH variable. Pauses when value mutates.
       -hist              HISTORY of the last 15 variable mutations.
       -bt                 BACKTRACE (Call stack).
       -l                  TOGGLE the local variable dashboard.

   General
       -h, -help           Display this manual.

Common Examples

Set breakpoints:

-b 12                          # Sets an unconditional breakpoint at line 12
-b 24 x > 5                    # Stops only when x > 5
-b 40 total > 100 --temp       # Auto-removes after the first hit
-b 18 i == 3 --hit 2           # Stops on the 2nd hit even if condition matches earlier

Quick summary:

• -b [L] [COND]: Sets a breakpoint at a specific line, with an optional condition.
• --temp: Removes the breakpoint automatically after its first hit.
• --hit N: Stops only on the Nth time the breakpoint is reached.
• -lb: Lists all active breakpoints.
• -db [L]: Deletes the breakpoint at the given line.
• -cb: Clears all breakpoints at once.

Inspect values and flow:

-p i
-w total
-bt
-hist

Included Demo Scripts

• test_scripts/test1_basic.py: simple loop and arithmetic flow
• test_scripts/test2_intermediate.py: branching and helper calls (add_tax)
• test_scripts/test3_advanced.py: recursion plus intentional out-of-range error path

These scripts are ideal for trying stepping, breakpoints, watchpoints, and exception behavior.

Notes and Limitations

• Intended for educational/debugging experiments, not production debugging
• Expression evaluation intentionally blocks unsafe syntax such as calls and attribute access

License

This project is licensed. For detailed information, see the License section in project documentation and the LICENSE file.