Args for commands?

[fleming79]

Thank you for providing this module. I'd been looking for a way to open the Jupyter console from python.

Looking through your example notebook I can see you are using args for the commands such as:

app.commands.execute('console:create', {
    'insertMode': 'split-right',
    'kernelPreference': {
        'shutdownOnClose': True,
    }
})

Would it be possible to provide some details on what args can be passed to each of the commands?

EDIT: This link now includes args:

https://jupyterlab.readthedocs.io/en/latest/user/commands.html#commands-list

[jtpio]

Thanks @fleming79.

The best ref I found sofar was here: https://jupyterlab.readthedocs.io/en/latest/user/commands.html#commands-list

Indeed that would be the best place for documenting what args can be passed. Which I think is auto-generated.

Unfortunately the args are not all well typed, so not sure it would be easy to add them to the documentation easily.

Likely this would require something like https://github.com/jupyterlab/lumino/issues/58.

[fleming79]

Thank you @jtpio for the link to the issue. It looks like the feature (describedBy) may now exist in Lumino, but not yet in Jupyterlab https://github.com/jupyterlab/jupyterlab/issues/13962?

In the meantime it is worth mentioning (for others who may be looking) that it is relatively straight forward to text search the Jupyterlab source code for the command_id definition with a capable IDE.

As an example; searching in the Jupyterlab source for 'apputils:notify';) gives one definition:

  export const notify = 'apputils:notify';

CTRL + left click on notify to follow the link.

    app.commands.addCommand(CommandIDs.notify, {
      label: trans.__('Emit a notification'),
      caption: trans.__(
        'Notification is described by {message: string, type?: string, options?: {autoClose?: number | false, actions: {label: string, commandId: string, args?: ReadOnlyJSONObject, caption?: string, className?: string}[], data?: ReadOnlyJSONValue}}.'
      ),
      execute: args => {
        const { message, type } = args as any;
        const options = (args.options as any) ?? {};

Here we can see the args are 'message' and 'options'. Fortunately 'caption' also provides some useful details about usage.

[jtpio]

It looks like the feature (describedBy) may now exist in Lumino, but not yet in Jupyterlab jupyterlab/jupyterlab#13962?

Indeed, it would still need to be implemented in JupyterLab.

In the meantime it is worth mentioning (for others who may be looking) that it is relatively straight forward to text search the Jupyterlab source code for the command_id definition with a capable IDE.

Good point. Maybe we should document this in the ipylab repo?

[jtpio]

https://github.com/jupyterlab/jupyterlab/pull/17649 added describedBy information to all JupyterLab core commands.

Which is now available in JupyterLab 4.5.0b0. So we could expose this functionality via ipylab too now.

[bollwyvl]

expose this functionality

Yeah, I might take a crack at this.

Because All The Schema are large, one way to think about it might be fully modeling a Command widget such that the arg only gets fetched if requested (or, i guess, executed, with optional validate=True).

There are also some wrinkles around how they commands interact with the command palette, context menu, etc. which might warrant some deeper exploration, as sometimes these have more human readable stuff.

Even though args are modeled, the return values are not, still. We might further want some ways to model certain well-known things, such as (lumino) widget handles. With that in hand, one could create full, branching pipelines from commands.

[bollwyvl]

#162 is up to explore this (demo mostly working on RTD), and offers a CommandRegistry.describe(id, handler=...) which returns a bunch of useful stuff. It also offers .execute(..., handler=..., validate=True) which, when used together, will actually validate the args on the client side, and return the results.

There are some more places that it could go (e.g. having full Command widgets) but this was the lightest touch I could manage that didn't break the API.