Topics

#jupyter #jupyterlab #jupyterlab-extension

Language breakdown

Python 60.1%

TypeScript 30.0%

RobotFramework 6.1%

JavaScript 3.0%

HTML 0.3%

CSS 0.3%

▸ Files click to expand

README

`jyg`

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

[binder-badge]: https://mybinder.org/badge_logo.svg [binder]: https://mybinder.org/v2/gh/deathbeds/jyg/HEAD?urlpath=lab [docs-badge]: https://readthedocs.org/projects/jyg/badge/?version=latest [docs]: https://jyg.rtfd.io [conda-badge]: https://img.shields.io/conda/vn/conda-forge/jyg [conda]: https://anaconda.org/conda-forge/jyg [pypi-badge]: https://img.shields.io/pypi/v/jyg [pypi]: https://pypi.org/project/jyg [npm]: https://npmjs.com/package/@deathbeds/jyg [npm-badge]: https://img.shields.io/npm/v/@deathbeds/jyg [workflow-badge]: https://github.com/deathbeds/jyg/actions/workflows/ci.yml/badge.svg?branch=main [workflow]: https://github.com/deathbeds/jyg/actions/workflows/ci.yml?query=branch%3Amain

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.

[contributing guide]: https://github.com/deathbeds/jyg/tree/main/README.md

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.

🔗 More in this category