===============
jupyter-ui-poll
===============
|Documentation Status| |Binder|
Block Jupyter cell execution while interacting with widgets.
This library is for people familiar with ``ipywidgets`` who want to solve the
following problem:
1. Display User Interface in Jupyter [#]_ using ``ipywidgets`` [#]_ or similar
2. Wait for data to be entered (this step is surprisingly non-trivial to implement)
3. Use entered data in cells below
You want to implement a notebook like the one below
.. code-block:: python
# cell 1
ui = make_ui()
display(ui)
data = ui.wait_for_data()
# cell 2
do_things_with(data)
# cell 3.
do_more_tings()
And you want to be able to execute ``Cells -> Run All`` menu option and still get correct output.
This library assists in implementing your custom ``ui.wait_for_data()`` poll loop.
If you have tried implementing such workflow in the past you'll know that it is
not that simple. If you haven't, see `Technical Details`_ section below for an
explanation on why it's hard and how ``jupyter-ui-poll`` solves it.
Quick, self contained example:
.. code-block:: python
import time
from ipywidgets import Button
from jupyter_ui_poll import ui_events
# Set up simple GUI, button with on_click callback
# that sets ui_done=True and changes button text
ui_done = False
def on_click(btn):
global ui_done
ui_done = True
btn.description = '👍'
btn = Button(description='Click Me')
btn.on_click(on_click)
display(btn)
# Wait for user to press the button
with ui_events() as poll:
while ui_done is False:
poll(10) # React to UI events (up to 10 at a time)
print('.', end='')
time.sleep(0.1)
print('done')
For a more detailed tutorial see `Example notebook`_, you can also `run it`_ right now using awesome `Binder`_ service.
Installation
============
This library requires Python 3.6 or greater.
.. code-block::
pip install jupyter-ui-poll
# or with conda/mamba
conda install -c conda-forge jupyter-ui-poll
Technical Details
=================
Jupyter widgets (``ipywidgets``) provide an excellent foundation to develop
interactive data investigation apps directly inside Jupyter notebook or Jupyter
lab environment. Jupyter is great at displaying data and ``ipywidgets`` provide
a mechanism to get input from the user in a more convenient way than entering or
changing Python code inside a Jupyter cell. Developer can construct an
interactive user interface often used to parameterize information display or
other kinds of computation.
Interactivity is handled with callbacks, ``ipywidget`` GUI is HTML based, user
actions, like clicking a button, trigger JavaScript events that are then
translated in to calls to Python code developer registered with the library. It
is a significantly different, asynchronous, paradigm than your basic Jupyter
notebook which operates in a straightforward blocking, linear fashion. It is not
possible to display a Modal UI that would block execution of other Jupyter cells
until needed information is supplied by the user.
``jupyter-ui-poll`` allows one to implement a "blocking GUI" inside a Jupyter
environment. It is a common requirement to query user for some non-trivial input
parameters that are easier to enter via GUI rather than code. User input happens
at the top of the notebook, then that data is used in cells below. While this is
possible to achieve directly with ``ipywidgets`` it requires teaching the user
to enter all the needed data before moving on to execute the cells below. This
is bound to cause some confusion and also breaks ``Cells -> Run All`` functionality.
An obvious solution is to keep running in a loop until all the needed data was
entered by the user.
.. code-block:: python
display(app.make_ui())
while not app.have_all_the_data():
time.sleep(0.1)
A naive version of the code above does not work. This is because no widget
events are being processed while executing code inside a Jupyter cell. 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. "Execute code inside
Jupyter cell" is just another event being processed by the IPython kernel, and
only one event is executed at a time. One could ask IPython kernel to process
more events by calling ``kernel.do_one_iteration()`` in the poll loop. This
kinda works, callbacks will be called as input is entered, but IPython will also
process "execute cell" events, so ``Cells -> Run All`` scenario will still be
broken, as code in lower cells will be executed before the data it operates on
becomes available.
This library hooks into IPython internal machinery to selectively execute events
in a polling fashion, delaying code cell execution events until after
interactive part is over.
Basic idea was copied from ``ipython_blocking`` [#]_ project:
1. Overwrite ``execute_request`` handler in IPython kernel temporarily
2. Call ``kernel.do_one_iteration()`` in a polling fashion until exit conditions are met
3. Reinstate default handler for ``execute_request``
4. Replay code cell execution events cached by custom handler taking care of
where output goes, and being careful about exception handling
.. [#] https://jupyter.org/
.. [#] https://github.com/jupyter-widgets/ipywidgets
.. [#] https://github.com/kafonek/ipython_blocking
.. _Example notebook: notebooks/Examples.ipynb
.. _run it: https://mybinder.org/v2/gh/kirill888/jupyter-ui-poll/develop?filepath=notebooks%2FExamples.ipynb
.. _Binder: https://mybinder.org/
.. |Documentation Status| image:: https://readthedocs.org/projects/jupyter-ui-poll/badge/?version=latest
:target: https://jupyter-ui-poll.readthedocs.io/en/latest/?badge=latest
.. |Binder| image:: https://mybinder.org/badge_logo.svg
:target: https://mybinder.org/v2/gh/kirill888/jupyter-ui-poll/develop?filepath=notebooks%2FExamples.ipynb
:alt: Run Examples in Binder
Raw data
{
"_id": null,
"home_page": "https://github.com/kirill888/jupyter-ui-poll",
"name": "jupyter-ui-poll",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "jupyter, ipywidgets",
"author": "Kirill Kouzoubov",
"author_email": "kirill888@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e0/3e/2a544e76d0729cc7c8003e6737b44ad2e7164c66caefa442f0dc290ab181/jupyter-ui-poll-1.0.0.tar.gz",
"platform": "any",
"description": "===============\njupyter-ui-poll\n===============\n\n|Documentation Status| |Binder|\n\nBlock Jupyter cell execution while interacting with widgets.\n\nThis library is for people familiar with ``ipywidgets`` who want to solve the\nfollowing problem:\n\n1. Display User Interface in Jupyter [#]_ using ``ipywidgets`` [#]_ or similar\n2. Wait for data to be entered (this step is surprisingly non-trivial to implement)\n3. Use entered data in cells below\n\nYou want to implement a notebook like the one below\n\n.. code-block:: python\n\n # cell 1\n ui = make_ui()\n display(ui)\n data = ui.wait_for_data()\n\n # cell 2\n do_things_with(data)\n\n # cell 3.\n do_more_tings()\n\nAnd you want to be able to execute ``Cells -> Run All`` menu option and still get correct output.\n\nThis library assists in implementing your custom ``ui.wait_for_data()`` poll loop.\nIf you have tried implementing such workflow in the past you'll know that it is\nnot that simple. If you haven't, see `Technical Details`_ section below for an\nexplanation on why it's hard and how ``jupyter-ui-poll`` solves it.\n\nQuick, self contained example:\n\n.. code-block:: python\n\n import time\n from ipywidgets import Button\n from jupyter_ui_poll import ui_events\n\n # Set up simple GUI, button with on_click callback\n # that sets ui_done=True and changes button text\n ui_done = False\n def on_click(btn):\n global ui_done\n ui_done = True\n btn.description = '\ud83d\udc4d'\n\n btn = Button(description='Click Me')\n btn.on_click(on_click)\n display(btn)\n\n # Wait for user to press the button\n with ui_events() as poll:\n while ui_done is False:\n poll(10) # React to UI events (up to 10 at a time)\n print('.', end='')\n time.sleep(0.1)\n print('done')\n\nFor a more detailed tutorial see `Example notebook`_, you can also `run it`_ right now using awesome `Binder`_ service.\n\nInstallation\n============\n\nThis library requires Python 3.6 or greater.\n\n\n.. code-block::\n\n pip install jupyter-ui-poll\n # or with conda/mamba\n conda install -c conda-forge jupyter-ui-poll\n\n\nTechnical Details\n=================\n\nJupyter widgets (``ipywidgets``) provide an excellent foundation to develop\ninteractive data investigation apps directly inside Jupyter notebook or Jupyter\nlab environment. Jupyter is great at displaying data and ``ipywidgets`` provide\na mechanism to get input from the user in a more convenient way than entering or\nchanging Python code inside a Jupyter cell. Developer can construct an\ninteractive user interface often used to parameterize information display or\nother kinds of computation.\n\nInteractivity is handled with callbacks, ``ipywidget`` GUI is HTML based, user\nactions, like clicking a button, trigger JavaScript events that are then\ntranslated in to calls to Python code developer registered with the library. It\nis a significantly different, asynchronous, paradigm than your basic Jupyter\nnotebook which operates in a straightforward blocking, linear fashion. It is not\npossible to display a Modal UI that would block execution of other Jupyter cells\nuntil needed information is supplied by the user.\n\n``jupyter-ui-poll`` allows one to implement a \"blocking GUI\" inside a Jupyter\nenvironment. It is a common requirement to query user for some non-trivial input\nparameters that are easier to enter via GUI rather than code. User input happens\nat the top of the notebook, then that data is used in cells below. While this is\npossible to achieve directly with ``ipywidgets`` it requires teaching the user\nto enter all the needed data before moving on to execute the cells below. This\nis bound to cause some confusion and also breaks ``Cells -> Run All`` functionality.\n\nAn obvious solution is to keep running in a loop until all the needed data was\nentered by the user.\n\n.. code-block:: python\n\n display(app.make_ui())\n while not app.have_all_the_data():\n time.sleep(0.1)\n\nA naive version of the code above does not work. This is because no widget\nevents are being processed while executing code inside a Jupyter cell. Callbacks\nyou have registered with the widget library won't get a chance to run and so\nstate of ``app.have_all_the_data()`` won't ever change. \"Execute code inside\nJupyter cell\" is just another event being processed by the IPython kernel, and\nonly one event is executed at a time. One could ask IPython kernel to process\nmore events by calling ``kernel.do_one_iteration()`` in the poll loop. This\nkinda works, callbacks will be called as input is entered, but IPython will also\nprocess \"execute cell\" events, so ``Cells -> Run All`` scenario will still be\nbroken, as code in lower cells will be executed before the data it operates on\nbecomes available.\n\nThis library hooks into IPython internal machinery to selectively execute events\nin a polling fashion, delaying code cell execution events until after\ninteractive part is over.\n\nBasic idea was copied from ``ipython_blocking`` [#]_ project:\n\n1. Overwrite ``execute_request`` handler in IPython kernel temporarily\n2. Call ``kernel.do_one_iteration()`` in a polling fashion until exit conditions are met\n3. Reinstate default handler for ``execute_request``\n4. Replay code cell execution events cached by custom handler taking care of\n where output goes, and being careful about exception handling\n\n\n.. [#] https://jupyter.org/\n.. [#] https://github.com/jupyter-widgets/ipywidgets\n.. [#] https://github.com/kafonek/ipython_blocking\n\n.. _Example notebook: notebooks/Examples.ipynb\n.. _run it: https://mybinder.org/v2/gh/kirill888/jupyter-ui-poll/develop?filepath=notebooks%2FExamples.ipynb\n.. _Binder: https://mybinder.org/\n\n.. |Documentation Status| image:: https://readthedocs.org/projects/jupyter-ui-poll/badge/?version=latest\n :target: https://jupyter-ui-poll.readthedocs.io/en/latest/?badge=latest\n\n.. |Binder| image:: https://mybinder.org/badge_logo.svg\n :target: https://mybinder.org/v2/gh/kirill888/jupyter-ui-poll/develop?filepath=notebooks%2FExamples.ipynb\n :alt: Run Examples in Binder\n\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Block jupyter cell execution while interacting with widgets",
"version": "1.0.0",
"project_urls": {
"Bug Reporting": "https://github.com/kirill888/jupyter-ui-poll/issues",
"Documentation": "https://jupyter-ui-poll.readthedocs.io/en/latest/",
"Homepage": "https://github.com/kirill888/jupyter-ui-poll"
},
"split_keywords": [
"jupyter",
" ipywidgets"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7a9bcbf48a399c78e749c23aa33d51ac97c8f35154846b470907db8d2a40e437",
"md5": "c746bdef4440108e320a749565d5a095",
"sha256": "c43182aac11d5419f86c4de19581e82d712cae7186f04a5681deb0727ef8079c"
},
"downloads": -1,
"filename": "jupyter_ui_poll-1.0.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "c746bdef4440108e320a749565d5a095",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 9089,
"upload_time": "2024-06-10T09:31:40",
"upload_time_iso_8601": "2024-06-10T09:31:40.839618Z",
"url": "https://files.pythonhosted.org/packages/7a/9b/cbf48a399c78e749c23aa33d51ac97c8f35154846b470907db8d2a40e437/jupyter_ui_poll-1.0.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e03e2a544e76d0729cc7c8003e6737b44ad2e7164c66caefa442f0dc290ab181",
"md5": "da4951b3012e170e7767cc55bd3757c7",
"sha256": "439fa936a37e09c0d3eaa9b835eeb0da2edaec3db06eade43a01d614a528424c"
},
"downloads": -1,
"filename": "jupyter-ui-poll-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "da4951b3012e170e7767cc55bd3757c7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 9752,
"upload_time": "2024-06-10T09:31:42",
"upload_time_iso_8601": "2024-06-10T09:31:42.148539Z",
"url": "https://files.pythonhosted.org/packages/e0/3e/2a544e76d0729cc7c8003e6737b44ad2e7164c66caefa442f0dc290ab181/jupyter-ui-poll-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-10 09:31:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kirill888",
"github_project": "jupyter-ui-poll",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jupyter-ui-poll"
}
JSON
