{"id":8252,"library":"jupyter-ui-poll","title":"Jupyter UI Poll","description":"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.","status":"active","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/kirill888/jupyter-ui-poll","tags":["jupyter","ipywidgets","interactive","notebook","ui","blocking"],"install":[{"cmd":"pip install jupyter-ui-poll","lang":"bash","label":"PyPI"},{"cmd":"conda install -c conda-forge jupyter-ui-poll","lang":"bash","label":"Conda-Forge"}],"dependencies":[{"reason":"Core dependency for Jupyter environment, critical for operation. Version compatibility is a frequent concern across jupyter-ui-poll releases.","package":"ipykernel","optional":false},{"reason":"Commonly used for building the interactive UI that jupyter-ui-poll manages.","package":"ipywidgets","optional":true}],"imports":[{"note":"Used for synchronous-like polling with a 'with' statement.","symbol":"ui_events","correct":"from jupyter_ui_poll import ui_events"},{"note":"Used for asynchronous iteration over events with an 'async for' statement (available since v0.2.0).","symbol":"with_ui_events","correct":"from jupyter_ui_poll import with_ui_events"},{"note":"Lower-level function for custom poll loops, often used in async contexts (available since v0.2.0).","symbol":"run_ui_poll_loop","correct":"from jupyter_ui_poll import run_ui_poll_loop"}],"quickstart":{"code":"import time\nfrom ipywidgets import Button, display\nfrom jupyter_ui_poll import ui_events\n\n# Global flag to control the loop\nui_done = False\n\ndef on_click(btn):\n    global ui_done\n    ui_done = True\n    btn.description = 'Done!'\n\n# Create a button\nbutton = Button(description='Click Me to Continue')\nbutton.on_click(on_click)\n\ndisplay(button)\n\nprint('Waiting for button click...')\n\n# Wait for user to press the button, processing UI events\nwith ui_events() as poll:\n    while not ui_done:\n        poll(10) # Process up to 10 UI events per call\n        print('.', end='', flush=True)\n        time.sleep(0.1) # Prevent busy-waiting\n\nprint('\\nButton clicked! Execution continues.')","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"0.2.0a0 - <0.2.0"},{"fix":"Upgrade to `jupyter-ui-poll==1.1.0` or newer to ensure compatibility with `ipykernel` 7 series. `pip install --upgrade jupyter-ui-poll`.","message":"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+.","severity":"breaking","affected_versions":"<1.1.0 with ipykernel 7+"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"Incompatibility between `jupyter-ui-poll` and a newer `ipykernel` version, specifically when `ipykernel`'s internal event loop methods become asynchronous.","error":"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."},{"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).","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.","error":"Jupyter kernel died / Jupyter Notebook connection error"},{"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.","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.","error":"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."}]}