From 378b9a75e75dc441efafbba590c0806fad62e216 Mon Sep 17 00:00:00 2001 From: Ian Thomas Date: Mon, 18 Nov 2024 10:22:11 +0000 Subject: [PATCH 1/3] Add messaging docs for optional features and kernel subshells --- docs/messaging.rst | 107 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 106 insertions(+), 1 deletion(-) 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 --- From 346f44911a3c8ded2ed8003d859c23c6c1a5f524 Mon Sep 17 00:00:00 2001 From: Ian Thomas Date: Wed, 20 Nov 2024 09:12:57 +0000 Subject: [PATCH 2/3] Use ID rather than id in text --- docs/messaging.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/messaging.rst b/docs/messaging.rst index 61ff2847..45d864a9 100644 --- a/docs/messaging.rst +++ b/docs/messaging.rst @@ -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 @@ -124,27 +124,27 @@ so that frontends can label the various messages in a meaningful way. .. 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. + subshell ID then it is handled by the subshell with that ID. .. versionchanged:: 5.0 @@ -924,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, @@ -1349,7 +1349,7 @@ 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 +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``:: @@ -1363,7 +1363,7 @@ Message type: ``create_subshell_reply``:: # '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. + # The ID of the subshell, unique within the kernel. 'subshell_id': str, } @@ -1372,13 +1372,13 @@ Message type: ``create_subshell_reply``:: Delete subshell ~~~~~~~~~~~~~~~ -In a kernel that supports subshells, this deletes a subshell identified by its unique id. +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. + # The ID of the subshell. 'subshell_id': str } @@ -1394,7 +1394,7 @@ Message type: ``delete_subshell_reply``:: List subshell ~~~~~~~~~~~~~ -In a kernel that supports subshells, this returns a list of the ids of all subshells that exist +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``:: @@ -1408,7 +1408,7 @@ Message type: ``list_subshell_reply``:: # 'ok' if the request succeeded or 'error', with error information as in all other replies. 'status': 'ok', - # A list of subshell ids. + # A list of subshell IDs. 'subshell_id': [str] } From 150b33f16e84805b2eec16d226e88ab86170edc5 Mon Sep 17 00:00:00 2001 From: Ian Thomas Date: Mon, 16 Dec 2024 11:10:17 +0000 Subject: [PATCH 3/3] Review comment --- docs/messaging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/messaging.rst b/docs/messaging.rst index 45d864a9..292156f7 100644 --- a/docs/messaging.rst +++ b/docs/messaging.rst @@ -1342,7 +1342,7 @@ 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']`` +Kernels supporting subshells must include ``'kernel subshells'`` in ``'supported_features'`` in :ref:`kernel info ` reply messages. Create subshell