Kalong

A new take on python debugging

Kalong is a modern, web-based Python debugger that provides a rich, interactive interface for inspecting and controlling your Python programs. It combines a powerful Python backend with a reactive frontend to offer a seamless debugging experience.

Features

• Web-Based Interface: A clean, modern UI built with React and CodeMirror.
• Interactive Debugging: Step through code, inspect variables, and evaluate expressions in real-time.
• Process Injection: Attach to running Python processes using GDB (requires gdb and ptrace support).
• Flexible Deployment: Run locally or remotely, with configurable host/port settings.
• Shell Mode: Launch an interactive shell with debugging capabilities.

Installation

pip install kalong

To include optional dependencies for code disassembly or recursive debugging:

pip install "kalong[disassembly,recursive]"

Usage

Basic Usage

Run a Python script with Kalong:

kalong my_script.py

This will start the debugger server and open the web interface.

By setting the PYTHONBREAKPOINT environment variable, you can also use Kalong with the built-in breakpoint() function in your code:

PYTHONBREAKPOINT=kalong.breakpoint

Interactive Shell

Launch an interactive shell:

kalong

Attaching to a Process

Inject Kalong into a running Python process (requires sudo or appropriate permissions):

kalong --inject <PID>

Command Line Options

Frontend Interface

Kalong provides a responsive, split-pane interface designed for efficient debugging.

Top Bar (Debugger Controls)

Control the execution flow using the top bar buttons or keyboard shortcuts:

Code Editor (Source View)

• Syntax Highlighting: Full Python syntax highlighting powered by CodeMirror.
• Breakpoints: Click on the gutter (line numbers) to toggle breakpoints.

Interactive Terminal (REPL)

The terminal allows you to interact with the running process in real-time.

• Execute Code: Type any valid Python expression to evaluate it in the current context.
• Command History: Navigate through your command history using Up and Down arrows.
• Autocomplete: Press Tab for intelligent code completion.
• Search History: Use Ctrl+r (reverse) and Ctrl+s (forward) to search through your command history.

Prompt Commands

Special commands can be entered in the terminal, prefixed with ?. Shortcuts are available for convenience.

Side Panel

• Stack Frames: View the call stack and click on any frame to inspect its local variables and code context.
• Settings: Toggle Light/Dark mode and adjust UI density.

Keyboard Shortcuts

Configuration

You can also configure Kalong using environment variables. The variable names are prefixed with KALONG_ and correspond to the CLI options (e.g., KALONG_PORT, KALONG_HOST, KALONG_LOG).

Development

To set up the development environment:

1. Install Python dependencies:

   pip install -e ".[dev]"
   

2. Install JavaScript dependencies:

   yarn install
   

3. Run the development server:

   yarn start
   

   This command runs the Vite dev server and the Python backend concurrently.

License

This project is licensed under the GPL-3.0-or-later license. See the LICENSE file for details.

Author

Florian Mounier