Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add messaging docs for optional features and kernel subshells #1045

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add messaging docs for optional features and kernel subshells #1045

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
378b9a7
Add messaging docs for optional features and kernel subshells
ianthomas23 Nov 18, 2024
346f449
Use ID rather than id in text
ianthomas23 Nov 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 116 additions & 11 deletions docs/messaging.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ Message Header
--------------

The message ``header`` contains information about the message,
such as unique identifiers for the originating session and the actual message id,
such as unique identifiers for the originating session and the actual message ID,
the type of message, the version of the Jupyter protocol,
and the date the message was created.
In addition, there is a username field, e.g. for the process that generated the
Expand All @@ -118,27 +118,34 @@ so that frontends can label the various messages in a meaningful way.
"msg_type": str,
# the message protocol version
"version": "5.0",
# Optional subshell_id
"subshell_id": str | None,
}

.. note::

The ``session`` id in a message header identifies a unique entity with state,
The ``session`` ID in a message header identifies a unique entity with state,
such as a kernel process or client process.

A client session id, in message headers from a client, should be unique among
A client session ID, in message headers from a client, should be unique among
all clients connected to a kernel. When a client reconnects to a kernel, it
should use the same client session id in its message headers. When a client
restarts, it should generate a new client session id.
should use the same client session ID in its message headers. When a client
restarts, it should generate a new client session ID.

A kernel session id, in message headers from a kernel, should identify a
particular kernel process. If a kernel is restarted, the kernel session id
A kernel session ID, in message headers from a kernel, should identify a
particular kernel process. If a kernel is restarted, the kernel session ID
should be regenerated.

The session id in a message header can be used to identify the sending entity.
The session ID in a message header can be used to identify the sending entity.
For example, if a client disconnects and reconnects to a kernel, and messages
from the kernel have a different kernel session id than prior to the disconnect,
from the kernel have a different kernel session ID than prior to the disconnect,
the client should assume that the kernel was restarted.

The ``subshell_id`` is only used in shell messages of kernels that support
subshells (:ref:`kernel_subshells`). If it is not included or is ``None`` then the
shell message is handled by the parent subshell (main shell), if it is a string
subshell ID then it is handled by the subshell with that ID.

.. versionchanged:: 5.0

``version`` key added to the header.
Expand All @@ -150,6 +157,10 @@ so that frontends can label the various messages in a meaningful way.
so implementers are strongly encouraged to include it.
It will be mandatory in 5.1.

.. versionchanged:: 5.5

``subshell_id`` added to the header.

Parent header
-------------

Expand Down Expand Up @@ -913,7 +924,7 @@ Message type: ``comm_info_reply``::
# 'ok' if the request succeeded or 'error', with error information as in all other replies.
'status' : 'ok',

# A dictionary of the comms, indexed by uuids.
# A dictionary of the comms, indexed by UUIDs.
'comms': {
comm_id: {
'target_name': str,
Expand Down Expand Up @@ -997,14 +1008,20 @@ Message type: ``kernel_info_reply``::
'banner': str,

# A boolean flag which tells if the kernel supports debugging in the notebook.
# Default is False
# Default is False.
# Deprecated as replaced by 'supported_features'=['debugger'] (see below).
'debugger': bool,

# Optional: A list of dictionaries, each with keys 'text' and 'url'.
# These will be displayed in the help menu in the notebook UI.
'help_links': [
{'text': str, 'url': str}
],

# Optional: A list of optional features such as 'debugger' and
# 'kernel subshells'. Introduced by Jupyter Enhancement Proposal 92
# https://github.com/jupyter/enhancement-proposals/pull/92
'supported_features': [str]
}

Refer to the lists of available `Pygments lexers <http://pygments.org/docs/lexers/>`_
Expand All @@ -1031,6 +1048,10 @@ and `codemirror modes <http://codemirror.net/mode/index.html>`_ for those fields

``language`` moved to ``language_info.name``

.. versionchanged:: 5.5

``supported_features`` added and ``debugger`` deprecated.

Messages on the Control (ROUTER/DEALER) channel
===============================================

Expand Down Expand Up @@ -1313,6 +1334,86 @@ of the debugger to the ``global`` scope to inspect it after debug session.

.. versionadded:: 5.5

.. _kernel_subshells:

Kernel subshells
----------------

Kernel subshells are separate threads of execution within the same kernel process that
were introduced by
`Jupyter Enhancement Proposal 91 <https://github.com/jupyter/enhancement-proposals/pull/91>`_.
Kernels supporting subshells must return ``'supported_features'=['kernel subshells']``
in :ref:`kernel info <msging_kernel_info>` reply messages.

Create subshell
~~~~~~~~~~~~~~~

In a kernel that supports subshells, this creates a new subshell (running in a separate thread)
and returns its unique ID. In a kernel that does not support subshells an error is logged and
no reply is sent.

Message type: ``create_subshell_request``::

content = {
}

Message type: ``create_subshell_reply``::

content = {
# 'ok' if the request succeeded or 'error', with error information as in all other replies.
'status' : 'ok',

# The ID of the subshell, unique within the kernel.
'subshell_id': str,
}

.. versionadded:: 5.5

Delete subshell
~~~~~~~~~~~~~~~

In a kernel that supports subshells, this deletes a subshell identified by its unique ID.
In a kernel that does not support subshells an error is logged and no reply is sent.

Message type: ``delete_subshell_request``::

content = {
# The ID of the subshell.
'subshell_id': str
}

Message type: ``delete_subshell_reply``::

content = {
# 'ok' if the request succeeded or 'error', with error information as in all other replies.
'status': 'ok',
}

.. versionadded:: 5.5

List subshell
~~~~~~~~~~~~~

In a kernel that supports subshells, this returns a list of the IDs of all subshells that exist
in that kernel. In a kernel that does not support subshells an error is logged and no reply is sent.

Message type: ``list_subshell_request``::

content = {
}

Message type: ``list_subshell_reply``::

content = {
# 'ok' if the request succeeded or 'error', with error information as in all other replies.
'status': 'ok',

# A list of subshell IDs.
'subshell_id': [str]
}

.. versionadded:: 5.5

Messages on the IOPub (PUB/SUB) channel
=======================================

Expand Down Expand Up @@ -1755,6 +1856,10 @@ Changelog

- Added ``debug_request/reply`` messages
- Added ``debug_event`` message
- Added ``supported_features`` in :ref:`kernel info <msging_kernel_info>` reply messages.
- Deprecated ``debugger`` in :ref:`kernel info <msging_kernel_info>` reply messages as
replaced with ``supported_features``.
- Added ``create_subshell``, ``delete_subshell`` and ``list_subshell`` messages.

5.4
---
Expand Down
Loading