Jupyter UI Poll

1.1.0 · active · verified Thu Apr 16

jupyter-ui-poll is a Python library that enables blocking Jupyter cell execution while interacting with ipywidgets or similar interactive elements. It addresses the challenge of creating 'blocking GUI' within notebooks, allowing for sequential workflows where user input via widgets is required before subsequent cells execute. The current version, 1.1.0, includes critical fixes for compatibility with newer `ipykernel` versions and improved handling of asynchronous operations. The library maintains an active release cadence, primarily driven by `ipykernel` compatibility updates.

Common errors

```
The polling mechanism no longer works under the latest release of ipykernel from pip. ... The most immediate problem is that do_one_iteration is now an async method.
```
cause Incompatibility between `jupyter-ui-poll` and a newer `ipykernel` version, specifically when `ipykernel`'s internal event loop methods become asynchronous.

fix Upgrade `jupyter-ui-poll` to the latest version. For `ipykernel` 6+, you may need to adopt `async` patterns in your `jupyter-ui-poll` usage (e.g., `async with ui_events() as poll: await poll()`) or ensure your `jupyter-ui-poll` version explicitly supports your `ipykernel` version.
```
Jupyter kernel died / Jupyter Notebook connection error
```
cause While not directly a `jupyter-ui-poll` error, an incompatible `jupyter-ui-poll` or `ipykernel` setup can destabilize the kernel. If `jupyter-ui-poll` fails to correctly hook into the kernel's event handling, it can lead to dead kernels or connection issues. This can also be caused by general `ipykernel` installation issues, or conflicting `pyzmq` versions.

fix First, ensure `jupyter-ui-poll` is the latest version. If the issue persists, try reinstalling `ipykernel` and `jupyter-ui-poll` in a fresh environment. Check for `pyzmq` compatibility issues by uninstalling and reinstalling it (e.g., `pip uninstall pyzmq; pip install pyzmq==19.0.2` if an older version is needed, or the latest otherwise).
```
Callbacks you have registered with the widget library won't get a chance to run and so state of app.have_all_the_data() won't ever change.
```
cause This is the fundamental problem `jupyter-ui-poll` solves. Without `jupyter-ui-poll`, Jupyter's kernel is busy executing the current cell and does not process UI events or callbacks from widgets, leading to unresponsive UIs and blocking logic.

fix Wrap your polling logic within `with ui_events() as poll:` and call `poll()` periodically inside your loop to explicitly process UI events. Alternatively, use `async for` with `with_ui_events()` for asynchronous iterables.

Warnings

breaking Version `0.2.0a0` introduced breaking changes by making the library async-only. Synchronous usage patterns for `with_ui_events` and `run_ui_poll_loop` were removed, requiring `async with` and `async for` instead. While `v0.2.0` later re-introduced synchronous support for `ui_events`, if you are on an `ipykernel` >= 6, the async patterns might be required for certain operations.
Fix: Migrate blocking code to `async with ui_events() as poll: await poll()` or `async for x in with_ui_events(iterable):`. For `ipykernel<6`, the synchronous `with ui_events() as poll: poll()` is generally safe. For `ipykernel>=6`, be mindful of async requirements, especially when integrating with other async code.
breaking Version `1.1.0` includes crucial fixes for `ipykernel` series 7+. Newer `ipykernel` versions introduce internal locks that stop message processing during cell execution. `jupyter-ui-poll` v1.1.0 dynamically patches the running kernel instance to bypass this lock and allow UI event processing. Older versions of `jupyter-ui-poll` will likely cease to function correctly with `ipykernel` 7+.
Fix: Upgrade to `jupyter-ui-poll==1.1.0` or newer to ensure compatibility with `ipykernel` 7 series. `pip install --upgrade jupyter-ui-poll`.
gotcha `jupyter-ui-poll` has historically had to adapt to significant changes in `ipykernel`'s internal architecture across major versions (e.g., v5, v6, v7). This means that a `jupyter-ui-poll` version compatible with `ipykernel` v5 might not work with v6 or v7, and vice-versa. Always check the release notes for specific `ipykernel` compatibility details.
Fix: Always install the latest `jupyter-ui-poll` version. If encountering issues, ensure your `ipykernel` version is compatible with your `jupyter-ui-poll` version. Consider using a pinned version of `ipykernel` if stability is critical.

Install

pip install jupyter-ui-poll PyPI
conda install -c conda-forge jupyter-ui-poll Conda-Forge

Imports

ui_events
```
from jupyter_ui_poll import ui_events
```
Used for synchronous-like polling with a 'with' statement.
with_ui_events
```
from jupyter_ui_poll import with_ui_events
```
Used for asynchronous iteration over events with an 'async for' statement (available since v0.2.0).
run_ui_poll_loop
```
from jupyter_ui_poll import run_ui_poll_loop
```
Lower-level function for custom poll loops, often used in async contexts (available since v0.2.0).

Quickstart

This quickstart demonstrates how to use `jupyter-ui-poll` to block cell execution until a user interacts with an `ipywidget`. A button is displayed, and the `ui_events` context manager is used to create a polling loop. The `poll(10)` call allows Jupyter to process UI events (like button clicks) while the `while` loop is active, ensuring the notebook doesn't hang. Once the button is clicked, the `ui_done` flag is set, and the cell execution proceeds.

import time
from ipywidgets import Button, display
from jupyter_ui_poll import ui_events

# Global flag to control the loop
ui_done = False

def on_click(btn):
    global ui_done
    ui_done = True
    btn.description = 'Done!'

# Create a button
button = Button(description='Click Me to Continue')
button.on_click(on_click)

display(button)

print('Waiting for button click...')

# Wait for user to press the button, processing UI events
with ui_events() as poll:
    while not ui_done:
        poll(10) # Process up to 10 UI events per call
        print('.', end='', flush=True)
        time.sleep(0.1) # Prevent busy-waiting

print('\nButton clicked! Execution continues.')

view raw JSON →