py-script and py-worker boundary: preserving Python exception fidelity and event-loop responsiveness

Question

PyScript exposes two distinct execution surfaces: the main-thread <py-script> tag and the isolated <py-worker> context. When a Python application relies on both, the boundary between them becomes critical for both error diagnosis and user-perceived responsiveness. A documented behavior is that Pyodide exceptions are translated into JavaScript exceptions at the WebAssembly boundary, yet the fidelity of tracebacks and custom exception types can be lossy, leaving the browser console as the only diagnostic surface. Because PyScript's API and defaults have shifted across major releases, the exact rendering of these errors may depend on the deployed version.

The unresolved design tension is whether long-running Python should remain on the main thread—where it blocks rendering and event handling—or be offloaded to a worker, where explicit message passing is required and shared memory assumptions break down. Additionally, the documentation does not fully specify ownership semantics when a Python object holds a reference to a DOM node or when a JavaScript callback retains a Python object across the proxy boundary.

Given these constraints, which boundary ownership rules apply when Python objects reference DOM nodes or JavaScript callbacks retain Python state? How should developers interpret truncated or rewrapped tracebacks when a custom exception crosses from Pyodide into the browser console? What architectural signals indicate that a blocking main-thread script should be migrated to a worker before page responsiveness degrades?

Tasadduq Burney · Answer

The PyScript py-script and py-worker contexts create distinct execution surfaces. The following separates confirmed behavior from version-dependent interop details: Pyodide translates Python exceptions into JavaScript Error objects. Custom exception types and full tracebacks are typically lost; the traceback appears as a string attribute rather than a native JavaScript stack. Inspect error.pythonTraceback for the original traceback string, but note that the property name and availability vary between Pyodide releases.When a Python object holds a reference to a DOM node, the node's lifecycle is managed by JavaScript. Python garbage collection does not free the node, and cross-boundary mutations require explicit cleanup if the API provides a release() or destroy() method.A JavaScript callback that retains a Python object creates a rooted reference in the Pyodide heap. The object remains rooted and is not subject to Pyodide's garbage collector unless the callback explicitly clears the reference. Large held state can degrade worker responsiveness.A blocking main-thread PyScript script signals itself when the UI thread's frame budget exceeds ~50 ms, the page becomes unresponsive, or the Pyodide loading spinner persists. These are architectural indicators to migrate the script to a py-worker context. Migration steps (scoped to this case): Move the Pyodide instance into a web worker (py-worker context).Replace direct DOM references with postMessage-serialized data; do not pass DOM nodes across the boundary.Ensure no JavaScript callback retains a Python object reference after the call completes; explicitly clear rooted references.Use postMessage for data exchange; assume shared-memory assumptions are broken. To confirm the exact shape of the translated exception and whether pythonTraceback is available under the current runtime, what Pyodide version are you running? The property location and exception rendering behavior are version-sensitive, and the migration recommendation may change based on the answer.

py-script and py-worker boundary: preserving Python exception fidelity and event-loop responsiveness

1 answer

Your perspective belongs here.

1 question comment

Clarifying Exception Serialization in PyScript Workers