Clean up docs and typings (#230)

docs/client.rst

@@ -187,7 +187,7 @@ the state of all the widgets can be stored in the notebook's metadata.
 This allows rendering of the live widgets on for instance nbviewer, or when
 converting to html.
 
-We can tell nbclient to not store the state using the `store_widget_state`
+We can tell nbclient to not store the state using the ``store_widget_state``
 argument::
 
     client = NotebookClient(nb, store_widget_state=False)

docs/conf.py

@@ -38,6 +38,7 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.mathjax',
     'sphinx.ext.napoleon',
+    # 'autodoc_traits',  # TODO
     'myst_parser',
 ]
 
@@ -187,4 +188,5 @@ def setup(app):
     os.chdir(HERE)
     with open(autogen_config) as f:
         exec(compile(f.read(), autogen_config, "exec"), {})
+        print('Updated cli docs')
     os.chdir(prev_dir)

docs/requirements-doc.txt

@@ -1,3 +1,4 @@
+autodoc-traits
 mock
 moto
 myst-parser

nbclient/client.py

@@ -114,12 +114,13 @@ class NotebookClient(LoggingConfigurable):
             If a cell execution was interrupted after a timeout, don't wait for
             the execute_reply from the kernel (e.g. KeyboardInterrupt error).
             Instead, return an execute_reply with the given error, which should
-            be of the following form:
-            {
-                'ename': str,  # Exception name, as a string
-                'evalue': str,  # Exception value, as a string
-                'traceback': list(str),  # traceback frames, as strings
-            }
+            be of the following form::
+
+                {
+                    'ename': str,  # Exception name, as a string
+                    'evalue': str,  # Exception value, as a string
+                    'traceback': list(str),  # traceback frames, as strings
+                }
             """
         ),
     ).tag(config=True)
@@ -838,6 +839,7 @@ async def _async_handle_timeout(
                 return execute_reply
             return None
         else:
+            assert cell is not None
             raise CellTimeoutError.error_from_timeout_and_cell(
                 "Cell execution timed out", timeout, cell
             )
@@ -1015,7 +1017,7 @@ async def async_execute_cell(
 
     def process_message(
         self, msg: t.Dict, cell: NotebookNode, cell_index: int
-    ) -> t.Optional[t.List]:
+    ) -> t.Optional[NotebookNode]:
         """
         Processes a kernel message, updates cell state, and returns the
         resulting output object that was appended to cell.outputs.
@@ -1033,7 +1035,7 @@ def process_message(
 
         Returns
         -------
-        output : dict
+        output : NotebookNode
             The execution output payload (or None for no output).
 
         Raises
@@ -1082,6 +1084,7 @@ def output(
     ) -> t.Optional[NotebookNode]:
 
         msg_type = msg['msg_type']
+        out = None
 
         parent_msg_id = msg['parent_header'].get('msg_id')
         if self.output_hook_stack[parent_msg_id]:
@@ -1112,7 +1115,7 @@ def output(
 
         outs.append(out)
 
-        return out
+        return out  # type:ignore[no-any-return]
 
     def clear_output(self, outs: t.List, msg: t.Dict, cell_index: int) -> None:
 

nbclient/tests/test_client.py

@@ -206,8 +206,8 @@ def test_mock_wrapper(self):
             cell_mock = NotebookNode(
                 source='"foo" = "bar"', metadata={}, cell_type='code', outputs=[]
             )
-            executor = NotebookClient({})
-            executor.nb = {'cells': [cell_mock]}
+            executor = NotebookClient({})  # type:ignore
+            executor.nb = {'cells': [cell_mock]}  # type:ignore
 
             # self.kc.iopub_channel.get_msg => message_mock.side_effect[i]
             message_mock = iopub_messages_mock()
@@ -503,7 +503,7 @@ class TestExecute(NBClientTestsBase):
     maxDiff = None
 
     def test_constructor(self):
-        NotebookClient({})
+        NotebookClient({})  # type:ignore
 
     def test_populate_language_info(self):
         nb = nbformat.v4.new_notebook()  # Certainly has no language_info.

nbclient/util.py

@@ -6,7 +6,7 @@
 import asyncio
 import inspect
 import sys
-from typing import Any, Awaitable, Callable, Optional, Union
+from typing import Any, Awaitable, Callable, Optional, TypeVar, Union
 
 
 def check_ipython() -> None:
@@ -62,7 +62,10 @@ def just_run(coro: Awaitable) -> Any:
     return loop.run_until_complete(coro)
 
 
-def run_sync(coro: Callable) -> Callable:
+T = TypeVar("T")
+
+
+def run_sync(coro: Callable[..., Awaitable[T]]) -> Callable[..., T]:
     """Runs a coroutine and blocks until it has executed.
 
     An event loop is created if no one already exists. If an event loop is