Add subshell docstrings (#1405)

Author: ianthomas23

ipykernel/kernelbase.py

@@ -300,7 +300,7 @@ def __init__(self, **kwargs):
         )
 
     async def dispatch_control(self, msg):
-        # Ensure only one control message is processed at a time
+        """Dispatch a control request, ensuring only one message is processed at a time."""
         async with asyncio.Lock():
             await self.process_control(msg)
 
@@ -1225,6 +1225,10 @@ async def do_debug_request(self, msg):
         raise NotImplementedError
 
     async def create_subshell_request(self, socket, ident, parent) -> None:
+        """Handle a create subshell request.
+
+        .. versionadded:: 7
+        """
         if not self.session:
             return
         if not self._supports_kernel_subshells:
@@ -1241,6 +1245,10 @@ async def create_subshell_request(self, socket, ident, parent) -> None:
         self.session.send(socket, "create_subshell_reply", reply, parent, ident)
 
     async def delete_subshell_request(self, socket, ident, parent) -> None:
+        """Handle a delete subshell request.
+
+        .. versionadded:: 7
+        """
         if not self.session:
             return
         if not self._supports_kernel_subshells:
@@ -1265,6 +1273,10 @@ async def delete_subshell_request(self, socket, ident, parent) -> None:
         self.session.send(socket, "delete_subshell_reply", reply, parent, ident)
 
     async def list_subshell_request(self, socket, ident, parent) -> None:
+        """Handle a list subshell request.
+
+        .. versionadded:: 7
+        """
         if not self.session:
             return
         if not self._supports_kernel_subshells:

ipykernel/socket_pair.py

@@ -1,3 +1,5 @@
+"""Pair of ZMQ inproc sockets used for communication between threads."""
+
 from __future__ import annotations
 
 from typing import Any
@@ -12,6 +14,8 @@ class SocketPair:
 
     One of the threads is always the shell_channel_thread, the other may be the control
     thread, main thread or a subshell thread.
+
+    .. versionadded:: 7
     """
 
     from_socket: zmq.Socket[Any]
@@ -21,20 +25,23 @@ class SocketPair:
     on_recv_copy: bool
 
     def __init__(self, context: zmq.Context[Any], name: str):
+        """Initialize the inproc socker pair."""
         self.from_socket = context.socket(zmq.PAIR)
         self.to_socket = context.socket(zmq.PAIR)
         address = self._address(name)
         self.from_socket.bind(address)
         self.to_socket.connect(address)  # Or do I need to do this in another thread?
 
     def close(self):
+        """Close the inproc socker pair."""
         self.from_socket.close()
 
         if self.to_stream is not None:
             self.to_stream.close()
         self.to_socket.close()
 
     def on_recv(self, io_loop: IOLoop, on_recv_callback, copy: bool = False):
+        """Set the callback used when a message is received on the to stream."""
         # io_loop is that of the 'to' thread.
         self.on_recv_callback = on_recv_callback
         self.on_recv_copy = copy
@@ -43,12 +50,15 @@ def on_recv(self, io_loop: IOLoop, on_recv_callback, copy: bool = False):
         self.resume_on_recv()
 
     def pause_on_recv(self):
+        """Pause receiving on the to stream."""
         if self.to_stream is not None:
             self.to_stream.stop_on_recv()
 
     def resume_on_recv(self):
+        """Resume receiving on the to stream."""
         if self.to_stream is not None and not self.to_stream.closed():
             self.to_stream.on_recv(self.on_recv_callback, copy=self.on_recv_copy)
 
     def _address(self, name) -> str:
+        """Return the address used for this inproc socket pair."""
         return f"inproc://subshell{name}"

ipykernel/subshell.py

@@ -9,7 +9,10 @@
 
 
 class SubshellThread(BaseThread):
-    """A thread for a subshell."""
+    """A thread for a subshell.
+
+    .. versionadded:: 7
+    """
 
     def __init__(
         self,
@@ -27,6 +30,7 @@ def __init__(
         self.aborting = False
 
     def run(self) -> None:
+        """Run the thread."""
         try:
             super().run()
         finally:

ipykernel/subshell_manager.py

@@ -29,6 +29,8 @@ class SubshellManager:
 
     Sending reply messages via the shell_socket is wrapped by another lock to protect
     against multiple subshells attempting to send at the same time.
+
+    .. versionadded:: 7
     """
 
     def __init__(
@@ -37,6 +39,7 @@ def __init__(
         shell_channel_io_loop: IOLoop,
         shell_socket: zmq.Socket[t.Any],
     ):
+        """Initialize the subshell manager."""
         assert current_thread() == main_thread()
 
         self._context: zmq.Context[t.Any] = context
@@ -80,22 +83,30 @@ def close(self) -> None:
         self._shell_channel_to_main.close()
 
     def get_shell_channel_to_subshell_pair(self, subshell_id: str | None) -> SocketPair:
+        """Return the inproc socket pair used to send messages from the shell channel
+        to a particular subshell or main shell."""
         if subshell_id is None:
             return self._shell_channel_to_main
         with self._lock_cache:
             return self._cache[subshell_id].shell_channel_to_subshell
 
     def get_subshell_to_shell_channel_socket(self, subshell_id: str | None) -> zmq.Socket[t.Any]:
+        """Return the socket used by a particular subshell or main shell to send
+        messages to the shell channel.
+        """
         if subshell_id is None:
             return self._main_to_shell_channel.from_socket
         with self._lock_cache:
             return self._cache[subshell_id].subshell_to_shell_channel.from_socket
 
     def get_shell_channel_to_subshell_socket(self, subshell_id: str | None) -> zmq.Socket[t.Any]:
+        """Return the socket used by the shell channel to send messages to a particular
+        subshell or main shell.
+        """
         return self.get_shell_channel_to_subshell_pair(subshell_id).from_socket
 
     def get_subshell_aborting(self, subshell_id: str) -> bool:
-        """Get the aborting flag of the specified subshell."""
+        """Get the boolean aborting flag of the specified subshell."""
         return self._cache[subshell_id].aborting
 
     def list_subshell(self) -> list[str]:
@@ -107,6 +118,9 @@ def list_subshell(self) -> list[str]:
             return list(self._cache)
 
     def set_on_recv_callback(self, on_recv_callback):
+        """Set the callback used by the main shell and all subshells to receive
+        messages sent from the shell channel thread.
+        """
         assert current_thread() == main_thread()
         self._on_recv_callback = on_recv_callback
         self._shell_channel_to_main.on_recv(IOLoop.current(), partial(self._on_recv_callback, None))