DOC: Autoreformat docstrings.

Carreau · mwakaba2 · commit 4f4eab2a5527 · 2021-04-30T20:43:21.000-06:00
This uses an autoreformatter to reformat and fix some of the common
mistakes in numpydoc.

Some of this is purely visual, but other like space before colon in
parameters actually have semantic values. In the case of space before
colon this is to make sure that nupmydoc properly distinguish the
parameter name from its type.
diff --git a/jupyter_server/_sysinfo.py b/jupyter_server/_sysinfo.py
@@ -26,15 +26,15 @@ def pkg_commit_hash(pkg_path):
     Parameters
     ----------
     pkg_path : str
-       directory containing package
-       only used for getting commit from active repo
+        directory containing package
+        only used for getting commit from active repo
 
     Returns
     -------
     hash_from : str
-       Where we got the hash from - description
+        Where we got the hash from - description
     hash_str : str
-       short form of hash
+        short form of hash
     """
 
     # maybe we are in a repository, check for a .git folder
@@ -68,12 +68,12 @@ def pkg_info(pkg_path):
     Parameters
     ----------
     pkg_path : str
-       path containing __init__.py for package
+        path containing __init__.py for package
 
     Returns
     -------
     context : dict
-       with named parameters of interest
+        with named parameters of interest
     """
     src, hsh = pkg_commit_hash(pkg_path)
     return dict(
diff --git a/jupyter_server/_tz.py b/jupyter_server/_tz.py
@@ -36,7 +36,7 @@ def utc_method(*args, **kwargs):
 
 def isoformat(dt):
     """Return iso-formatted timestamp
-    
+
     Like .isoformat(), but uses Z for UTC instead of +00:00
     """
     return dt.isoformat().replace('+00:00', 'Z')
diff --git a/jupyter_server/auth/login.py b/jupyter_server/auth/login.py
@@ -196,7 +196,7 @@ def get_user(cls, handler):
     @classmethod
     def get_user_token(cls, handler):
         """Identify the user based on a token in the URL or Authorization header
-        
+
         Returns:
         - uuid if authenticated
         - None if not
diff --git a/jupyter_server/base/zmqhandlers.py b/jupyter_server/base/zmqhandlers.py
@@ -32,7 +32,6 @@ def serialize_binary_message(msg):
 
     Returns
     -------
-
     The message serialized to bytes.
 
     """
@@ -64,7 +63,6 @@ def deserialize_binary_message(bmsg):
 
     Returns
     -------
-
     message dictionary
     """
     nbufs = struct.unpack('!i', bmsg[:4])[0]
diff --git a/jupyter_server/extension/serverextension.py b/jupyter_server/extension/serverextension.py
@@ -27,7 +27,6 @@ def _get_config_dir(user=False, sys_prefix=False):
 
     Parameters
     ----------
-
     user : bool [default: False]
         Get the user's .jupyter config directory
     sys_prefix : bool [default: False]
diff --git a/jupyter_server/gateway/managers.py b/jupyter_server/gateway/managers.py
@@ -293,7 +293,7 @@ def init_static_args(self):
 
     def load_connection_args(self, **kwargs):
         """Merges the static args relative to the connection, with the given keyword arguments.  If statics
-         have yet to be initialized, we'll do that here.
+        have yet to be initialized, we'll do that here.
 
         """
         if len(self._static_args) == 0:
@@ -360,7 +360,7 @@ def _get_kernel_endpoint_url(self, kernel_id=None):
 
         Parameters
         ----------
-        kernel_id: kernel UUID (optional)
+        kernel_id : kernel UUID (optional)
         """
         if kernel_id:
             return url_path_join(self.base_endpoint, url_escape(str(kernel_id)))
@@ -562,7 +562,7 @@ def _get_kernelspecs_endpoint_url(self, kernel_name=None):
 
         Parameters
         ----------
-        kernel_name: kernel name (optional)
+        kernel_name : kernel name (optional)
         """
         if kernel_name:
             return url_path_join(self.base_endpoint, url_escape(kernel_name))
diff --git a/jupyter_server/serverapp.py b/jupyter_server/serverapp.py
@@ -1823,19 +1823,16 @@ def initialize(self, argv=None, find_extensions=True, new_httpserver=True, start
 
         Parameters
         ----------
-        argv: list or None
+        argv : list or None
             CLI arguments to parse.
-
-        find_extensions: bool
+        find_extensions : bool
             If True, find and load extensions listed in Jupyter config paths. If False,
             only load extensions that are passed to ServerApp directy through
             the `argv`, `config`, or `jpserver_extensions` arguments.
-
-        new_httpserver: bool
+        new_httpserver : bool
             If True, a tornado HTTPServer instance will be created and configured for the Server Web
             Application. This will set the http_server attribute of this class.
-
-        starter_extension: str
+        starter_extension : str
             If given, it references the name of an extension point that started the Server.
             We will try to load configuration from extension point
         """
diff --git a/jupyter_server/services/contents/checkpoints.py b/jupyter_server/services/contents/checkpoints.py
@@ -121,12 +121,12 @@ def create_notebook_checkpoint(self, nb, path):
     def get_file_checkpoint(self, checkpoint_id, path):
         """Get the content of a checkpoint for a non-notebook file.
 
-         Returns a dict of the form:
-         {
-             'type': 'file',
-             'content': <str>,
-             'format': {'text','base64'},
-         }
+        Returns a dict of the form:
+        {
+            'type': 'file',
+            'content': <str>,
+            'format': {'text','base64'},
+        }
         """
         raise NotImplementedError("must be implemented in a subclass")
 
@@ -229,12 +229,12 @@ async def create_notebook_checkpoint(self, nb, path):
     async def get_file_checkpoint(self, checkpoint_id, path):
         """Get the content of a checkpoint for a non-notebook file.
 
-         Returns a dict of the form:
-         {
-             'type': 'file',
-             'content': <str>,
-             'format': {'text','base64'},
-         }
+        Returns a dict of the form:
+        {
+            'type': 'file',
+            'content': <str>,
+            'format': {'text','base64'},
+        }
         """
         raise NotImplementedError("must be implemented in a subclass")
 
diff --git a/jupyter_server/services/contents/fileio.py b/jupyter_server/services/contents/fileio.py
@@ -86,17 +86,14 @@ def atomic_writing(path, text=True, encoding='utf-8', log=None, **kwargs):
     Parameters
     ----------
     path : str
-      The target file to write to.
-
+        The target file to write to.
     text : bool, optional
-      Whether to open the file in text mode (i.e. to write unicode). Default is
-      True.
-
+        Whether to open the file in text mode (i.e. to write unicode). Default is
+        True.
     encoding : str, optional
-      The encoding to use for files opened in text mode. Default is UTF-8.
-
+        The encoding to use for files opened in text mode. Default is UTF-8.
     **kwargs
-      Passed to :func:`io.open`.
+        Passed to :func:`io.open`.
     """
     # realpath doesn't work on Windows: https://bugs.python.org/issue9949
     # Luckily, we only need to resolve the file itself being a symlink, not
@@ -142,17 +139,14 @@ def _simple_writing(path, text=True, encoding='utf-8', log=None, **kwargs):
     Parameters
     ----------
     path : str
-      The target file to write to.
-
+        The target file to write to.
     text : bool, optional
-      Whether to open the file in text mode (i.e. to write unicode). Default is
-      True.
-
+        Whether to open the file in text mode (i.e. to write unicode). Default is
+        True.
     encoding : str, optional
-      The encoding to use for files opened in text mode. Default is UTF-8.
-
+        The encoding to use for files opened in text mode. Default is UTF-8.
     **kwargs
-      Passed to :func:`io.open`.
+        Passed to :func:`io.open`.
     """
     # realpath doesn't work on Windows: https://bugs.python.org/issue9949
     # Luckily, we only need to resolve the file itself being a symlink, not
diff --git a/jupyter_server/services/contents/manager.py b/jupyter_server/services/contents/manager.py
@@ -326,7 +326,7 @@ def increment_filename(self, filename, path='', insert=''):
             The name of a file, including extension
         path : unicode
             The API path of the target's directory
-        insert: unicode
+        insert : unicode
             The characters to insert after the base filename
 
         Returns
@@ -691,7 +691,7 @@ async def increment_filename(self, filename, path='', insert=''):
             The name of a file, including extension
         path : unicode
             The API path of the target's directory
-        insert: unicode
+        insert : unicode
             The characters to insert after the base filename
 
         Returns
diff --git a/jupyter_server/services/kernels/kernelmanager.py b/jupyter_server/services/kernels/kernelmanager.py
@@ -251,11 +251,11 @@ def start_buffering(self, kernel_id, session_key, channels):
         ----------
         kernel_id : str
             The id of the kernel to stop buffering.
-        session_key: str
+        session_key : str
             The session_key, if any, that should get the buffer.
             If the session_key matches the current buffered session_key,
             the buffer will be returned.
-        channels: dict({'channel': ZMQStream})
+        channels : dict({'channel': ZMQStream})
             The zmq channels whose messages should be buffered.
         """
 
@@ -290,7 +290,7 @@ def get_buffer(self, kernel_id, session_key):
         ----------
         kernel_id : str
             The id of the kernel to stop buffering.
-        session_key: str, optional
+        session_key : str, optional
             The session_key, if any, that should get the buffer.
             If the session_key matches the current buffered session_key,
             the buffer will be returned.
diff --git a/jupyter_server/tests/services/sessions/test_api.py b/jupyter_server/tests/services/sessions/test_api.py
@@ -150,9 +150,9 @@ def session_client(jp_root_dir, jp_fetch):
 
 def assert_kernel_equality(actual, expected):
     """ Compares kernel models after taking into account that execution_states
-        may differ from 'starting' to 'idle'.  The 'actual' argument is the
-        current state (which may have an 'idle' status) while the 'expected'
-        argument is the previous state (which may have a 'starting' status).
+    may differ from 'starting' to 'idle'.  The 'actual' argument is the
+    current state (which may have an 'idle' status) while the 'expected'
+    argument is the previous state (which may have a 'starting' status).
     """
     actual.pop('execution_state', None)
     actual.pop('last_activity', None)
@@ -163,8 +163,8 @@ def assert_kernel_equality(actual, expected):
 
 def assert_session_equality(actual, expected):
     """ Compares session models.  `actual` is the most current session,
-        while `expected` is the target of the comparison.  This order
-        matters when comparing the kernel sub-models.
+    while `expected` is the target of the comparison.  This order
+    matters when comparing the kernel sub-models.
     """
     assert actual['id'] == expected['id']
     assert actual['path'] == expected['path']
diff --git a/jupyter_server/utils.py b/jupyter_server/utils.py
@@ -82,12 +82,12 @@ def samefile_simple(path, other_path):
     Only to be used if os.path.samefile is not available.
 
     Parameters
-    -----------
-    path:       String representing a path to a file
-    other_path: String representing a path to another file
+    ----------
+    path : String representing a path to a file
+    other_path : String representing a path to another file
 
     Returns
-    -----------
+    -------
     same:   Boolean that is True if both path and other path are the same
     """
     path_stat = os.stat(path)
@@ -193,7 +193,7 @@ def run_sync(maybe_async):
 
     Returns
     -------
-    result :
+    result
         Whatever the async object returns, or the object itself.
     """
     if not inspect.isawaitable(maybe_async):
