.. _debugging:

Debugging
#########

Debugging in modern GUI IDEs such as PyCharm and Visual Studio Code offers a visual and interactive way to identify and fix errors in code. Instead of using print statements or command-line tools, these IDEs provide intuitive features like breakpoints, step execution, variable inspection, and call stack navigation—all within a user-friendly interface.

This debugging flow is especially useful because it allows developers to pause code execution at any line, examine the current state of variables, and step through the program line by line. This makes it much easier to understand logic errors, track down bugs, and test edge cases without repeatedly modifying code. The convenience of integrated tools and visual feedback significantly improves development efficiency and accuracy.

Remote Debugging in Embedded Python Environments
================================================

In many modern applications, the Python interpreter is embedded within a larger host process. This is a common pattern in domains like game development, data processing, scientific computing, and enterprise software, where Python is used to provide scripting, automation, or extensibility inside a compiled application.
The same applies to PyStim where Python is embedded in SystemVerilog simulation environments to provide scripting capabilities.

In such cases, the Python code is not executed as a standalone script—it runs within the context of the host application, often triggered by internal events, plugin hooks, or system logic. Because of this, **traditional or direct debugging methods (such as launching a script directly from your IDE) are not applicable**. The Python interpreter is controlled by the host process, not your development environment, which means you can’t simply start a debug session by pressing “Run with Debugger.”

This is where *remote debugging* becomes essential. Remote debugging enables your IDE to attach to the running Python interpreter inside the host application, allowing you to:

- Set breakpoints in your local codebase.
- Step through Python code executed by the host.
- Inspect variables, call stacks, and program state in real time.
- Debug without changing the host application’s launch behavior.

This workflow is especially useful when working with complex systems where Python is embedded for runtime control or scripting capabilities.

Python remote debugging withing PyStim
================================================

In bellow tutorials, demonstrate how to use remote debugging with two popular tools:

- **PyCharm Remote Debugger** – `Remote Debugging with PyCharm <https://www.jetbrains.com/help/pycharm/remote-debugging-with-product.html>`_
- **Visual Studio Code and ``debugpy``** – `Debugging in VS Code <https://code.visualstudio.com/docs/python/debugging>`_

You’ll learn how to instrument your embedded Python environment to support remote debugging, initiate debug sessions from within the process, and connect your IDE to those sessions for interactive inspection and control.

Whether you're integrating Python into a desktop application or embedding it in a PyStim workflow,  remote debugging offers a powerful and flexible approach to understanding and developing your embedded Python code.