A new message type transient_display_data for transient information

[BoPeng]

A proposal for a new transient_display_data message type (#376) with content that is identical to display_data. The messages are supposed to be displayed (or ignored) by the clients but not saved with the notebooks. This post list some applications of this message type.

    content = {
        # The data dict contains key/value pairs, where the keys are MIME types
        # and the values are the raw data of the representation in that format
        'data' : dict,

        # metadata of the message
        'metadata' : dict,
    }

A metadata is allowed but no field is defined for now

    metadata = {
    }

Update Dec 2018: There has been some discussions about this message type in a JupyterLab developer meeting. The conclusion was that it is good enough (at least for now) to display the messages sequentially in a UI separated from the notebook so all the complex title, page stuff are removed from the original version of the PR. A PR is submitted to JLab to display this message in console windows jupyterlab/jupyterlab#5699.

Update March 2019: With the release of JupyterLab 1.0.0 alpha 3, a jupyterlab extension transient-display-data was released to send all transient_display_data to the console panel of notebooks. In addition, a new version of jupyterlab-sos was released to make use of this feature. The easiest way to test this feature is to go to our live server, start a notebook with a SoS kernel, open a console window, then execute the following trivial workflow in the notebook:

%run

import time

[1]
time.sleep(5)

[2]
time.sleep(5)

The idea is that the console window will display progress information while the workflow is running.

[jasongrout]

Can you summarize here some of the usecases for such a message?

[BoPeng]

This message type contains transient information that are for information only. For example,

1. Status/Progress information. For calculations that take a long time to execute, the kernel can send progress information to the frontend. Something like step 1 completed, logging to server.com, retrieving file. These information are not useful at all after the completion of the calculation and should not be saved with the notebook, yet it is very useful to users.

2. Debug information. A kernel might want to output more verbose information under certain debug mode. The information can be long and are not meant to be saved with the notebook. Having a separate message type will allow the separation of debug and real output. Right now, I usually have to re-run my notebook to remove debug information.

3. Side effect of calculation. In addition to regular result, a kernel might want to output some information about the result, either spontaneously or instructed by some magic. For example, the SoS kernel has a %preview magic that users can use to preview the output after the execution of the cell. The "preview" allows users to check if the output is correct but is not meant to be saved with the notebook. Although this might be an invention of SoS, I believe the concept can be widely adopted by other kernels to improve the user experience of interactive data analysis.

4. User-requested status information. The SoS kernel provides some magics that allows users to query the status of the kernel, without saving such information to the notebook. For example, a %taskinfo magic allows users to check the status of remote tasks. Again, the output is for information only and does not need to be saved to the notebook. This is very much like status/progress information above, but is requested by users.

All these usages can be implemented with customized comms and widgets but having a dedicated message type (and dedicated UI) would make it much easier for kernels to send such information to the frontend.

[rgbkrk]

Thanks for opening this PR to kick things off.

[rgbkrk]

I'd word this as:

The transient_display_data message has the same structure as display_data with one addition, title, as well as a different intent. These messages are not to be persisted to notebooks or other formats. Examples of how this could be used is status of a long calculation as well debug information.

[rgbkrk]

Would it make sense if we used update_display_data to target a transient_display_data that was already on the screen? Then you'd able to update an individual output and maintain consistency amongst the other display_data like messages.

I'm assuming you'd want to have a targeted clear_output message too then to clear all of them.

[BoPeng]

It does not seem to be a good idea to multi-purpose update_display_data here, especially because there is no display_id for transient_display_data.

How exactly the messages should be aggregated (appended) and cleared depends on user interaction. I think the use pattern is generally something like this:

1. User does something (e.g. executes a cell)
2. Transient messages appear, and probably aggregate
3. User consumes the message and performs the next action (e.g. modify the code and re-execute).
4. A new batch of transient messages replaces displayed one.

So in my design:

1. title shows the intent of one or more messages.
2. append=true would append message to a previous message with the same title

In practice:

1. If a kernel wants to display some debug or progress information during the execution, it can send multiple transient_display_data with the same title and append=True.
2. If a kernel would like to update previous message (e.g. new CPU/MEM status), it can either send a message with a different title, or the same title with append=False.

[rgbkrk]

If multiple messages come in with different titles, do they each occupy new areas?

Is this regarded as a unique identifier then?

[BoPeng]

See my previous response. title is intended to group consecutive messages with the same title (and append=True), very similar to the aggregation of multiple display_data for the execution of the same input. It is possible to keep (short) history of transient messages (e.g. a navigation button) but it would be easier to start with a single widget and see if there is a strong need from users to keep some sort of history.

[rgbkrk]

Ok, this is definitely getting used as a unique id then. It's both a display name for the user and the way it groups. I want to clarify that here in the doc if this is what you mean.

[BoPeng]

Will do.

[BoPeng]

There is also another possibility for a kernel to send sticky transient information. For example, a category field could be added to the protocol which corresponds to tabs in the frontend. A kernel can then send general information to an Info tab, creates a Help tab for various help messages, and Status for various status updates. Within each tab the title and append rules would still apply.

So in case if there is really a need to keep some sort of log, a kernel can create a Log tab and keep sending messages with the same title there.

[rgbkrk]

Considering the page portion of the payload API has been on the slate for deprecation for quite some time, perhaps this is the protocol we use for that. It even takes a mimebundle so ideally this would be good to position towards.

[BoPeng]

Considering the page portion of the payload API has been on the slate for deprecation for quite some time, perhaps this is the protocol we use for that. It even takes a mimebundle so ideally this would be good to position towards.

I frankly do not know anything about this page and payload stuff. Are you saying the category/tab feature can be used to replaced a deprecating page feature? I do think a category field can make it easy for users to separate transient messages into groups of messages with different lifetime (update frequency) and can accommodate more use cases.

[rgbkrk]

The Payloads API is part of the core protocol, a bit of a carry over to make sure we still support being able to run for example:

df?

to pull up help.

[BoPeng]

Attaching page payload to execute_reply means that only one page could be attached with the return of results. This is similar to transient_display_data although much less useful.

df? is a good use case for transient_display_data, I can imagine a transient_display_data message

content = {
    'page': 'Help',
    'title': 'df',
    'data': 'help message for df'
} 

is sent from the kernel and creates or open a Help tab to display the help information.

[BoPeng]

Proposal updated with a new page field in metadata. I did not put title in metadata because it is mandatary and append and page are optional with their default values.

[BoPeng]

There is a problem on how to handle stream (stdout and stderr) (#376 comment). Because JupyterLab uses application/vnd.jupyter.stdout for stdout and application/vnd.jupyter.stderr for stderr, I would suggest that users pass stream messages such as

{
    'name' : stderr,
    'text' : 'message',
}

as

 {
    'data' :  {
        'text/plain': 'message',
        'application/vnd.jupyter.stderr': 'message'
    }
}

in transient_display_data. Frontends that do not support application/vnd.jupyter.stdout and application/vnd.jupyter.stderr can use text/plain or convert the message to stream.

[BoPeng]

JupyterLab inspector panel has a concept of rank for tabs, which could be incorporated into this message. Basically, a rank indicates the importance of the page. When a background page is updated, it will not be activated if there is any other page with higher rank. This allows the kernel to send a bunch of log or debug messages with low rank to be accumulated in the background, and more important messages with higher rank to be displayed instantly.

[BoPeng]

I merged upstream/master and pushed a change to docs/messaging.rst (add metadata rank), and somehow this PR shows all commits of the merge.

[BoPeng]

BTW, I Don't Like Notebooks - Joel Grus - #JupyterCon 2018 complains about no real time linter information, and this PR tries to solve it.

[BoPeng]

@rgbkrk After some discussions during a JLab developer meeting, it seems easier to make transient_display_data identical to display_data in content. A JLab PR is being created but will not be merged before more consensus on this message type is reached (jupyterlab/jupyterlab#5699). Could you re-review this PR with @jasongrout?