Debugging Embedded Python Code
Python is designed so it can be embedded into larger applications as a scripting language, as a way to write high-level code that controls the functionality of that application. This is common, for example, in applications designed for 2D and 3D animation, compositing, and rendering, and some game development software. Examples include Blender, Autodesk Maya, NUKE, and Source Filmmaker.
When Python code is run by an embedded interpreter, you may need some extra configuration to make debugging work properly. What is needed depends on how the host application embeds and invokes Python.
Single Python Instance
If the host application is simply creating a single Python instance and reusing it for all script invocations, setting kEmbedded=1 in wingdbstub.py will usually be all that is needed, in addition to adding import wingdbstub to your code.
This tells the debugger that complete exit of the debug code does not indicate that Python has exited as well, so that the debug connection can remain intact between script invocations.
Custom Python Thread States
Some host applications manually create or alter the Python thread states that is used for each script invocation. This may disable the debugger and/or disconnect the debug process from the IDE.
To solve this, invoke Ensure() in the debugger API, to reset the debugger for each script invocation:
import wingdbstub
wingdbstub.Ensure()
This tells the debugger to ensure that the debug tracer is properly installed and that the debug process is connected to the IDE, as needed in this particular application.
Multiple Python Instances
In other cases where the host application uses an entirely different Python instance for each invocation, you will need to arrange that the Debugger API function ProgramQuit() is called before each instance of Python is destroyed.
In this case, you should leave kEmbedded=0 in wingdbstub.py. The debugger will disconnect and reconnect for each script invocation, as if they were separate debug processes.
You may also need to unset the environment variable WINGDB_ACTIVE before importing wingdbstub, if this is left in place by the host application. When this is present it will prevent wingdbstub from initiating debug in the second or later Python instance because the debugger will think that debugging is already active.
