diff --git a/docs/messaging.rst b/docs/messaging.rst
index 12ae051f..61ff2847 100644
--- a/docs/messaging.rst
+++ b/docs/messaging.rst
@@ -118,6 +118,8 @@ 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::
@@ -139,6 +141,11 @@ so that frontends can label the various messages in a meaningful way.
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.
@@ -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
-------------
@@ -997,7 +1008,8 @@ 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'.
@@ -1005,6 +1017,11 @@ Message type: ``kernel_info_reply``::
'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 `_
@@ -1031,6 +1048,10 @@ and `codemirror modes `_ 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
===============================================
@@ -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 `_.
+Kernels supporting subshells must return ``'supported_features'=['kernel subshells']``
+in :ref:`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
=======================================
@@ -1755,6 +1856,10 @@ Changelog
- Added ``debug_request/reply`` messages
- Added ``debug_event`` message
+- Added ``supported_features`` in :ref:`kernel info ` reply messages.
+- Deprecated ``debugger`` in :ref:`kernel info ` reply messages as
+ replaced with ``supported_features``.
+- Added ``create_subshell``, ``delete_subshell`` and ``list_subshell`` messages.
5.4
---