Expand command lifecycle with optional arg validation, results

[bollwyvl]

references

• Args for commands? #128

changes

• CommandRegistry
  • add describe(id, args, handler)
    • returns configurable command properties
      • icon
      • label
      • caption
      • icon_class
      • described_by
  • change add_command(...
    • add described_by={"args":{}}
  • change execute
    • add validate=True
      • use ajv client-side to validate args
    • add handler=Callable[[Any, List[Any], ...]
      • call with results from validation/execution
• docs
  • use jupyterlite-(core|pyodide-kernel) 0.7.0rc
  • add some config to support all the demo notebooks
  • update notebooks
    • commands (see screenshots)
    • ipytree
    • ???
• package.json
  • use consistent-type-imports linter
  • update some sharedPackages config

user-facing changes

• users will be able to
  • get information about commands
  • better describe custom commands
  • get back (some) results from executed commands
  • return values to the client

note	screen
describing commands
validating args

backwards-incompatible changes

• none, probably (was trying pretty hard to not break anything)

notes

on main, command execution is "fire-and-forget"...

graph TB
subgraph py
    subgraph CommandRegistry
        py-ex[".execute(id, args)"]
    end
end

subgraph js
    subgraph CommandRegistryModel
        js-ex[._execute]
    end
    subgraph AppCommandRegistry [CommandRegistry]
        real-ex[.execute]
    end
end

py-ex --> js-ex --> real-ex 

Loading

...on this PR, with optional validate and handler, results (or errors) come back

graph TB
subgraph py
    subgraph CommandRegistry
        handler["handler(result, error)"]
        py-ex[".execute(..., <br/>handler, validate=True)"]
    end
end

subgraph js
    subgraph CommandRegistryModel
            js-val["._validate"]
            js-ex[._execute]
    end
    subgraph AppCommandRegistry [CommandRegistry]
        real-ex[.execute]
        describe[.describe]
    end
    ajv
end

handler --> py-ex --> js-val
js-val -- await --> describe --> js-val
js-val -- validate(args) -->  ajv --> js-val -.-> js-ex
js-ex -- await --> real-ex
real-ex --> js-ex -- "result<br/>errors" --> handler
js-val -- errors --> handler

Loading

[github-actions]

👈 Try it on Binder (branch bollwyvl/ipylab/gh-128-command-args)

[bollwyvl]

@jtpio this is still fairly WIP (no particular tests) but seems to drive pretty well in lab/notebook and lite.

[bollwyvl]

A down side of adding validation is that no Ajv instance (or sharedPackage) is exported anywhere upstream, so this ships its own copy. Not exactly lightweight, but is, at least, lazily loaded behind the optional validate=True flag.

To fully remove it from being (re-)bundled, it would be theoretically possible to grab an existing one off of:

• the private _validator from a @jupyterlab/settingregistry:DefaultSchemaValidator subclass
• somehow intercept an @jupyterlab/ui-components:FormComponent which has access to the underlying validator through a number of props

[bollwyvl]

Welp, i had a quick look at the panels notebook: looks like there's a fair amount of drift that would need some investigation, and is probably outside the (already sprawling) scope of this PR.

[bollwyvl]

@jtpio finally circled around with the jupyterlite-sphinx thing and all the lite 0.7.0 releases.