Hint

Try the demo for an example of using Command Boards.

jyg#

demo

docs

install

build

binder-badge

docs

install from pypi install from conda-forge reuse from npm

build

run Jupyter browser client commands from a CLI, REST API, or other browser windows

See the full documentation on ReadTheDocs.

Installation#

Note: after installing the browser and server extension, you’ll need to restart your server and/or refresh your Jupyter client browser session.

Prerequisites#

  • python >=3.8

  • jupyterlab >=3

pip#

pip install jyg jupyterlab

mamba#

mamba install -c conda-forge jyg jupyterlab

… or use conda if you must.

Development Install#

See the contributing guide for a development install.

Quick Start#

Before running any of the above, please ensure you have installed the jyg extension for your Jupyter client and server.

Browser#

  • In Advanced Settings: Command Boards

    • Create a new Board with a template like

      <button data-command-id="help:licenses">Show Licenses</button>

    • or more complicated

      <button
  data-command-id="apputils:change-theme"
  data-command-args='{"theme": "JupyterLab Dark"}'
>
  Set theme
</button>

  • Click the Launcher Item for the board

    • Or use the Command Palette

  • Click the elements in the board

CLI#

List commands#

jyg list --json
jyg ls
jyg l

Run commands#

the following are all equivalent

jyg run filebrowser:open '{"path": "Untitled.ipynb"}'
jyg run filebrowser:open --path=Untitled.ipynb
jyg r filebrowser:open --path Untitled.ipynb

REST API#

List commands#

GET http://localhost:8888/jyg/commands

  {
    "apps": [
      {
        "url": "http://localhost:8888"
      }
    ]
  }

Run a command#

POST http://localhost:8888/jyg/command/docmanager:open

  {
    "path": "Untitled.ipynb"
  }

Troubleshooting#

If various pieces do not appear to be working, try some of the steps below.

Verify the installation#

jupyter server extension list
jupyter serverextension list

You should see some output that includes:

jyg enabled
  - Validating jyg...
    jyg x.x.x OK

If not present, you might be able to re-enable it with:

jupyter server extension enable --sys-prefix --py jyg
jupyter serverextension enable --sys-prefix --py jyg.serverextension

jupyter labextension list

You should see something like:

@deathbeds/jyg vx.x.x enabled OK

Verify the server is running#

Make sure the server is running.

jupyter server list
jupyter notebook list

Verify the browser application is running#

To run or list commands, the browser must be running the client. Also look at the Browser Console (usually shown with f12) for any explicit errors or warnings.

Frequently Asked Questions#

Does jyg work with Jupyter notebook<7?#

Sort of. jyg can list and run commands in JupyterLab-derived apps running as an extension to the notebook server… but only when running under jupyter_server<2.

It cannot (and will not) integrate with the Bootstrap/jQuery notebook UI, as there is consistent design pattern for commands.

Does jyg work with Jupyter notebook>=7?#

Not yet. But it will probably work pretty soon after a release.

Does jyg work with another backend than jupyter_server?#

No. Aside from the above about notebook<7. However, the API is extensively typed and tested, and could be implemented in another backend.

Can $MY_APPLICATION use jyg to drive Jupyter clients?#

Probably not. Out of the box. jyg only provides a way to operate its host application in co-deployed <iframe>s as Command Boards, and only runs the postMessage server when a board is actively running.

The in-browser API is available, however, to create custom extensions which would allow a web page that already had access to the Jupyter application to register use postMessage.

If your application already has control over the Jupyter application, you can likely use a handle to the Application instance, get access to the IWindowProxy plugin, and add the host window as a source.

Open Source#

BSD 3-Clause License

Copyright (c) 2022, jyg contributors
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this
  list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.

* Neither the name of the copyright holder nor the names of its
  contributors may be used to endorse or promote products derived from
  this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Learn More#