`jupyter.widget.control` `update_states` schema

[AntoinePrv]

Problem

According to the Control Widget messaging protocol, kernels should reply to request_states request with a message like

{
  'comm_id' : 'u-u-i-d',
  'data' : {
    'method': 'update_states',
    'states': {
      <widget1 u-u-i-d>: <widget1 state>,
      <widget2 u-u-i-d>: <widget2 state>,
      [...]
    },
    'buffer_paths': [ <list with paths corresponding to the binary buffers> ]
  }

But it is unclear what <widget1 state> is. Intuitively, it looks like this would be some dictionary like

{
    "some_property": "some_value",
    [...]
}

However, from the IPyWidgets implementation, and from trying to implement this protocol for XWidget, it looks like the <widget1 state> should rather be:

{
    "model_name": "...",
    "model_module": "...",
    "model_module_version": "...",
    "state": {
        "some_property": "some_value",
        [...]
    }
}

Suggested Improvement

It looks like the actual implementation has redundant information that exists in the state's _model_name.
But the point here is rather to clarify what is the expected schema, and possibly adapt the documentation,

[martinRenou]

Thanks for opening an issue!

the actual implementation has redundant information that exists in the state's _model_name

What do you mean by this?

and possibly adapt the documentation

Improving the documentation there could be good indeed 👍🏽

[AntoinePrv]

What do you mean by this?

From ipywidget implementation

'model_name': widget._model_name,
'model_module': widget._model_module,
'model_module_version': widget._model_module_version,

And also from the desciption of the protocol

Several fields are assumed to be in every state object:

• _model_module: the model module
• _model_module_version: the semver range of the model
• _model_name: the name of the model
• ...

So isn't the current state something like:

{
   "model_name": "SomeModel",
   "model_module": "@jupyter-widgets/controls",
   "model_module_version": "...",
   "state": {
       "_model_name": "SomeModel",
       "_model_module": "@jupyter-widgets/controls",
       "_model_module_version": "...",
       "some_property": "some_value",
       [...]
   }
}

[martinRenou]

Indeed! We should probably update this then, and remove this duplication.

The code here would need to be updated https://github.com/jupyter-widgets/ipywidgets/blob/main/packages/base-manager/src/manager-base.ts#L479. We should also update Voila.

[jasongrout]

Indeed! We should probably update this then, and remove this duplication.

That would be a breaking change to the control comm protocol, so we'd need to consider when to do the change.

On the other hand, fixing the documentation is always a good thing to do! I'd suggest updating the documentation for now, and keeping this issue to correct the duplication for when we have a major release of the base-manager package.

[AntoinePrv]

That would be a breaking change to the control comm protocol.

I had a feeling that would be the case.

I'd suggest updating the documentation for now

I'll send a PR.

keeping this issue to correct the duplication for when we have a major release of the base-manager package.

I leave it to you to manage this issue how you see fit.

[martinRenou]

Updating the code here https://github.com/jupyter-widgets/ipywidgets/blob/main/packages/base-manager/src/manager-base.ts#L479 would be non-breaking though. Same for updating Voila which uses the same logic.

[martinRenou]

@jasongrout I feel like we could come up with a plan to implement a new version for the control comm target protocol without making breaking changes in both ipywidgets (python) and the base-manager package.

On the Python side we are checking the protocol version here: https://github.com/jupyter-widgets/ipywidgets/blob/main/python/ipywidgets/ipywidgets/widgets/widget.py#L372. We could update this code to be:

    @classmethod
    def handle_control_comm_opened(cls, comm, msg):
        version = msg.get('metadata', {}).get('version', '')
        if version.split('.')[0] == '1':
            cls._control_comm = comm
            cls._control_comm.on_msg(cls._handle_control_comm_msg_v1)
            return
        if version.split('.')[0] == '2':
            cls._control_comm = comm
            cls._control_comm.on_msg(cls._handle_control_comm_msg_v2)
            return
        raise ValueError(f"control protocol version {version} not supported")

That way the back-end supports both v1 and v2 and that would not be a breaking change in ipywidgets.

In the base-manager package, I understand that changing the control protocol version it uses would not be breaking? If the back-end does not support the same protocol version, it is supposed to fallback to the old way of fetching widgets states -> not breaking change, but the implementation would suffer from performance issues.