[Feat] [pydeck] Propagate Javascript errors to notebook cells when using pydeck in Colab

[bijanvakili]

Target Use Case

A common experience with using pydeck are silent failures. This occurs when running code in a python notebook but seeing no output (a blank output cell). What is actually occurring is that the IPython.display.HTML object has encountered a Javascript error during its render (display) operation. This error is not propagated from the client browser to the python notebook runtime.

The only way to discover this error is to review the browser’s Javascript console output (for example, manually opening the Console panel from Chrome’s Dev Tools). This creates friction for python notebooks as it takes the user outside their normal workflow.

Examples of this friction can be seen from issues filed for pydeck:

• [Bug] console says deck: Picked non-existent layer. Is picking buffer corrupt? #9134 "not able to get output back"
• [Bug] TypeError: Cannot read properties of undefined (reading 'extend') in pydeck Jupyter Widget #8596 "error in question ... is present int he browser console"
• Private Mapbox basemap not showing in pydeck=0.7 and 0.6.1 #6249 collaborators need to explicitly remind/ask about "any relevant error messages in browser's developer console"

Proposal

A better user experience would be to display the Javascript error and fail the notebook cell operation. Notebook users would get feedback immediately so as to fix their code or, more typically, their deck.gl layer parameters.

pydeck already has logic here to detect the google.colab package. This can be extended to use Colab's Javascript to Python communication.

More specifically:

1. pydeck.deck.Deck.show can be extended to register callbacks with google.colab.output.register_callback
2. The HTML rendered index.j2 Jinja template can be extended to set up event handlers to listen to both the Deck.onAfterRender and Deck.onError events.
3. Console errors can then be propagated from the client browser back to the python notebook runtime.
4. The receiver callback registered in step 1n can raise a python exception to propagate the error back to the user and fail the notebook’s cell operation.

If synchronization is required, a python condition object can be used to ensure safe waiting on these messages.

Optional If google.colab is unavailable, the Jinja template can still be modified to at least display the Javascript error in a <div/> or <code/> HTML element. Although the error is still displayed to the user immediately, the only drawback of this approach is that the notebook’s cell operation will not be marked as an error (a false positive). Still, showing output is still a major UX improvement over the current behavior of no output.