stratified_packager.toolbelt.debugging

Optional debugpy bootstrap for attaching an IDE to the (possibly embedded) Python.

start_debug_server() opens a debugpy listen socket when the QGIS_DEBUGPY environment variable is truthy, so an IDE can attach to the running interpreter; it is a no-op otherwise, which keeps it dormant in normal use while costing nothing to leave wired in.

When Python is embedded in a host application — QGIS runs the interpreter inside its qgis / qgis_process executable — sys.executable points at that host binary rather than at Python. Since debugpy needs the real interpreter to spawn its adapter subprocess, the bootstrap resolves it with python_executable() and passes it to debugpy.configure before listening.

Recognised environment variables (explicit host / port arguments take precedence), read through the typed EnvironmentVariables subclass _DebugEnv:

QGIS_DEBUGPY

Truthy (1 / true / yes / on) to enable the listen server.

QGIS_DEBUGPY_HOST

Host/address to listen on (default "localhost").

QGIS_DEBUGPY_PORT

TCP port to listen on (default 5678).

QGIS_DEBUGPY_WAIT

Truthy to block startup until an IDE attaches — needed to break on early load (e.g. classFactory / initGui) or on a short-lived qgis_process run.

debugpy is an optional dependency imported lazily inside start_debug_server(); when it is not installed the resulting ImportError is contained like any other failure, so the bootstrap never breaks loading.

Functions

start_debug_server([host, port])

Start a debugpy listen server when QGIS_DEBUGPY is truthy, else do nothing.
class stratified_packager.toolbelt.debugging._DebugEnv(environ=None)[source]

Typed view of the QGIS_DEBUGPY* environment toggles (see the module docstring).

Parameters:

environ (MutableMapping[str, str] | None)

QGIS_DEBUGPY

A bool environment variable, parsed via the converter registry.

QGIS_DEBUGPY_HOST

A str environment variable.

QGIS_DEBUGPY_PORT

An int environment variable.

QGIS_DEBUGPY_WAIT

A bool environment variable, parsed via the converter registry.

_abc_impl = <_abc._abc_data object>
stratified_packager.toolbelt.debugging.start_debug_server(host=None, port=None)[source]

Start a debugpy listen server when QGIS_DEBUGPY is truthy, else do nothing.

Resolve the listen address from the arguments, then the QGIS_DEBUGPY* environment variables, then the module defaults. Safe to call on every plugin load: a repeat call, a missing debugpy or a busy port is logged and swallowed so that loading never fails because of the debugger.

Parameters:
Return type:

bool

Returns:

True when the server is (already) listening, False otherwise.

stratified_packager.toolbelt.debugging._LISTEN_LATCH: Final[dict[str, bool]] = {'started': False}

Process-global latch (mutated in place, never rebound): debugpy.listen may be called only once per process, so re-entry (e.g. on plugin reload) stays a quiet no-op.