Merge pull request #12893 from Carreau/doc-reformat

reformat docstring in IPython utils

IPython/utils/_process_common.py

@@ -49,18 +49,16 b' def process_handler(cmd, callback, stderr=subprocess.PIPE):'
     Parameters
     ----------
     cmd : str or list
-      A command to be executed by the system, using :class:`subprocess.Popen`.
-      If a string is passed, it will be run in the system shell. If a list is
-      passed, it will be used directly as arguments.
-
+        A command to be executed by the system, using :class:`subprocess.Popen`.
+        If a string is passed, it will be run in the system shell. If a list is
+        passed, it will be used directly as arguments.
     callback : callable
-      A one-argument function that will be called with the Popen object.
-
+        A one-argument function that will be called with the Popen object.
     stderr : file descriptor number, optional
-      By default this is set to ``subprocess.PIPE``, but you can also pass the
-      value ``subprocess.STDOUT`` to force the subprocess' stderr to go into
-      the same file descriptor as its stdout.  This is useful to read stdout
-      and stderr combined in the order they are generated.
+        By default this is set to ``subprocess.PIPE``, but you can also pass the
+        value ``subprocess.STDOUT`` to force the subprocess' stderr to go into
+        the same file descriptor as its stdout.  This is useful to read stdout
+        and stderr combined in the order they are generated.
 
     Returns
     -------
@@ -117,12 +115,12 b' def getoutput(cmd):'
     Parameters
     ----------
     cmd : str or list
-      A command to be executed in the system shell.
+        A command to be executed in the system shell.
 
     Returns
     -------
     output : str
-      A string containing the combination of stdout and stderr from the
+        A string containing the combination of stdout and stderr from the
     subprocess, in whatever order the subprocess originally wrote to its
     file descriptors (so the order of the information in this string is the
     correct order as would be seen if running the command in a terminal).
@@ -141,7 +139,7 b' def getoutputerror(cmd):'
     Parameters
     ----------
     cmd : str or list
-      A command to be executed in the system shell.
+        A command to be executed in the system shell.
 
     Returns
     -------
@@ -159,7 +157,7 b' def get_output_error_code(cmd):'
     Parameters
     ----------
     cmd : str or list
-      A command to be executed in the system shell.
+        A command to be executed in the system shell.
 
     Returns
     -------

IPython/utils/_process_posix.py

@@ -82,12 +82,12 b' class ProcessHandler(object):'
         Parameters
         ----------
         cmd : str
-          A command to be executed in the system shell.
+            A command to be executed in the system shell.
 
         Returns
         -------
         output : str
-          A string containing the combination of stdout and stderr from the
+            A string containing the combination of stdout and stderr from the
         subprocess, in whatever order the subprocess originally wrote to its
         file descriptors (so the order of the information in this string is the
         correct order as would be seen if running the command in a terminal).
@@ -103,12 +103,12 b' class ProcessHandler(object):'
         Parameters
         ----------
         cmd : str
-          A command to be executed in the system shell.
+            A command to be executed in the system shell.
 
         Returns
         -------
         output : str
-          A string containing the combination of stdout and stderr from the
+            A string containing the combination of stdout and stderr from the
         subprocess, in whatever order the subprocess originally wrote to its
         file descriptors (so the order of the information in this string is the
         correct order as would be seen if running the command in a terminal).
@@ -124,7 +124,7 b' class ProcessHandler(object):'
         Parameters
         ----------
         cmd : str
-          A command to be executed in the system shell.
+            A command to be executed in the system shell.
 
         Returns
         -------

IPython/utils/_process_win32.py

@@ -128,7 +128,7 b' def system(cmd):'
     Parameters
     ----------
     cmd : str or list
-      A command to be executed in the system shell.
+        A command to be executed in the system shell.
 
     Returns
     -------
@@ -152,7 +152,7 b' def getoutput(cmd):'
     Parameters
     ----------
     cmd : str or list
-      A command to be executed in the system shell.
+        A command to be executed in the system shell.
 
     Returns
     -------
@@ -181,7 +181,7 b' try:'
 
         This is a special version for windows that use a ctypes call to CommandLineToArgvW
         to do the argv splitting. The posix parameter is ignored.
-        
+
         If strict=False, process_common.arg_split(...strict=False) is used instead.
         """
         #CommandLineToArgvW returns path to executable if called with empty string.

IPython/utils/_process_win32_controller.py

@@ -551,13 +551,13 b' def system(cmd):'
     Parameters
     ----------
     cmd : str
-      A command to be executed in the system shell.
+        A command to be executed in the system shell.
 
     Returns
     -------
     None : we explicitly do NOT return the subprocess status code, as this
     utility is meant to be used extensively in IPython, where any return value
-    would trigger :func:`sys.displayhook` calls.
+    would trigger : func:`sys.displayhook` calls.
     """
     with AvoidUNCPath() as path:
         if path is not None:

IPython/utils/decorators.py

@@ -50,7 +50,7 b' def flag_calls(func):'
 
 def undoc(func):
     """Mark a function or class as undocumented.
-    
+
     This is found by inspecting the AST, so for now it must be used directly
     as @undoc, not as e.g. @decorators.undoc
     """

IPython/utils/encoding.py

@@ -37,10 +37,10 b' def get_stream_enc(stream, default=None):'
 # won't need to make changes all over IPython.
 def getdefaultencoding(prefer_stream=True):
     """Return IPython's guess for the default encoding for bytes as text.
-    
+
     If prefer_stream is True (default), asks for stdin.encoding first,
     to match the calling Terminal, but that is often None for subprocesses.
-    
+
     Then fall back on locale.getpreferredencoding(),
     which should be a sensible platform default (that respects LANG environment),
     and finally to sys.getdefaultencoding() which is the most conservative option,

IPython/utils/frame.py

@@ -28,12 +28,10 b' def extract_vars(*names,**kw):'
     *names : str
         One or more variable names which will be extracted from the caller's
         frame.
-
-    depth : integer, optional
+    **kw : integer, optional
         How many frames in the stack to walk when looking for your variables.
         The default is 0, which will use the frame where the call was made.
 
-
     Examples
     --------
     ::

IPython/utils/generics.py

@@ -22,7 +22,6 b' def complete_object(obj, prev_completions):'
         The object to complete.
     prev_completions : list
         List of attributes discovered so far.
-
     This should return the list of attributes in obj. If you only wish to
     add to the attributes already discovered normally, return
     own_attrs + prev_completions.

IPython/utils/importstring.py

@@ -16,12 +16,12 b' def import_item(name):'
     Parameters
     ----------
     name : string
-      The fully qualified name of the module/package being imported.
+        The fully qualified name of the module/package being imported.
 
     Returns
     -------
     mod : module object
-       The module that was imported.
+        The module that was imported.
     """
     
     parts = name.rsplit('.', 1)

IPython/utils/io.py

@@ -113,11 +113,9 b' class Tee(object):'
         Parameters
         ----------
         file_or_name : filename or open filehandle (writable)
-          File that will be duplicated
-
+            File that will be duplicated
         mode : optional, valid mode for open().
-          If a filename was give, open with this mode.
-
+            If a filename was give, open with this mode.
         channel : str, one of ['stdout', 'stderr']
         """
         if channel not in ['stdout', 'stderr']:
@@ -195,15 +193,14 b" def temp_pyfile(src, ext='.py'):"
     Parameters
     ----------
     src : string or list of strings (no need for ending newlines if list)
-      Source code to be written to the file.
-
+        Source code to be written to the file.
     ext : optional, string
-      Extension for the generated file.
+        Extension for the generated file.
 
     Returns
     -------
     (filename, open filehandle)
-      It is the caller's responsibility to close the open file and unlink it.
+        It is the caller's responsibility to close the open file and unlink it.
     """
     fname = tempfile.mkstemp(ext)[1]
     with open(Path(fname), "w") as f:

IPython/utils/ipstruct.py

@@ -43,14 +43,13 b' class Struct(dict):'
 
         Parameters
         ----------
-        args : dict, Struct
+        *args : dict, Struct
             Initialize with one dict or Struct
-        kw : dict
+        **kw : dict
             Initialize with key, value pairs.
 
         Examples
         --------
-
         >>> s = Struct(a=10,b=30)
         >>> s.a
         10
@@ -68,7 +67,6 b' class Struct(dict):'
 
         Examples
         --------
-
         >>> s = Struct()
         >>> s['a'] = 10
         >>> s.allow_new_attr(False)
@@ -95,7 +93,6 b' class Struct(dict):'
 
         Examples
         --------
-
         >>> s = Struct()
         >>> s.a = 10
         >>> s.a
@@ -130,7 +127,6 b' class Struct(dict):'
 
         Examples
         --------
-
         >>> s = Struct(a=10)
         >>> s.a
         10
@@ -155,7 +151,6 b' class Struct(dict):'
 
         Examples
         --------
-
         >>> s = Struct(a=10,b=30)
         >>> s2 = Struct(a=20,c=40)
         >>> s += s2
@@ -170,7 +165,6 b' class Struct(dict):'
 
         Examples
         --------
-
         >>> s1 = Struct(a=10,b=30)
         >>> s2 = Struct(a=20,c=40)
         >>> s = s1 + s2
@@ -186,7 +180,6 b' class Struct(dict):'
 
         Examples
         --------
-
         >>> s1 = Struct(a=10,b=30)
         >>> s2 = Struct(a=40)
         >>> s = s1 - s2
@@ -202,7 +195,6 b' class Struct(dict):'
 
         Examples
         --------
-
         >>> s1 = Struct(a=10,b=30)
         >>> s2 = Struct(a=40)
         >>> s1 -= s2
@@ -236,7 +228,6 b' class Struct(dict):'
 
         Examples
         --------
-
         >>> s = Struct(a=10,b=30)
         >>> s2 = s.copy()
         >>> type(s2) is Struct
@@ -251,7 +242,6 b' class Struct(dict):'
 
         Examples
         --------
-
         >>> s = Struct(a=10)
         >>> s.hasattr('a')
         True
@@ -284,7 +274,7 b' class Struct(dict):'
 
         Parameters
         ----------
-        __loc_data : dict, Struct
+        __loc_data__ : dict, Struct
             The data to merge into self
         __conflict_solve : dict
             The conflict policy dict.  The keys are binary functions used to
@@ -292,12 +282,11 b' class Struct(dict):'
             the keys the conflict resolution function applies to.  Instead of
             a list of strings a space separated string can be used, like
             'a b c'.
-        kw : dict
+        **kw : dict
             Additional key, value pairs to merge in
 
         Notes
         -----
-
         The `__conflict_solve` dict is a dictionary of binary functions which will be used to
         solve key conflicts.  Here is an example::
 
@@ -338,7 +327,6 b' class Struct(dict):'
 
         Examples
         --------
-
         This show the default policy:
 
         >>> s = Struct(a=10,b=30)

IPython/utils/module_paths.py

@@ -43,7 +43,7 b' def find_mod(module_name):'
     """
     Find module `module_name` on sys.path, and return the path to module `module_name`.
 
-      - If `module_name` refers to a module directory, then return path to __init__ file. 
+      - If `module_name` refers to a module directory, then return path to __init__ file.
         - If `module_name` is a directory without an __init__file, return None.
       - If module is missing or does not have a `.py` or `.pyw` extension, return None.
         - Note that we are not interested in running bytecode.
@@ -52,7 +52,7 b' def find_mod(module_name):'
     Parameters
     ----------
     module_name : str
-    
+
     Returns
     -------
     module_path : str

IPython/utils/openpy.py

@@ -60,15 +60,15 b' def strip_encoding_cookie(filelike):'
 
 def read_py_file(filename, skip_encoding_cookie=True):
     """Read a Python file, using the encoding declared inside the file.
-    
+
     Parameters
     ----------
     filename : str
-      The path to the file to read.
+        The path to the file to read.
     skip_encoding_cookie : bool
-      If True (the default), and the encoding declaration is found in the first
-      two lines, that line will be excluded from the output.
-    
+        If True (the default), and the encoding declaration is found in the first
+        two lines, that line will be excluded from the output.
+
     Returns
     -------
     A unicode string containing the contents of the file.
@@ -82,18 +82,18 b' def read_py_file(filename, skip_encoding_cookie=True):'
 
 def read_py_url(url, errors='replace', skip_encoding_cookie=True):
     """Read a Python file from a URL, using the encoding declared inside the file.
-    
+
     Parameters
     ----------
     url : str
-      The URL from which to fetch the file.
+        The URL from which to fetch the file.
     errors : str
-      How to handle decoding errors in the file. Options are the same as for
-      bytes.decode(), but here 'replace' is the default.
+        How to handle decoding errors in the file. Options are the same as for
+        bytes.decode(), but here 'replace' is the default.
     skip_encoding_cookie : bool
-      If True (the default), and the encoding declaration is found in the first
-      two lines, that line will be excluded from the output.
-    
+        If True (the default), and the encoding declaration is found in the first
+        two lines, that line will be excluded from the output.
+
     Returns
     -------
     A unicode string containing the contents of the file.

IPython/utils/path.py

@@ -109,7 +109,7 b' def get_py_filename(name, force_win32=None):'
         raise IOError('File `%r` not found.' % name)
 
 
-def filefind(filename, path_dirs=None):
+def filefind(filename: str, path_dirs=None) -> str:
     """Find a file by looking through a sequence of paths.
 
     This iterates through a sequence of paths looking for a file and returns
@@ -139,7 +139,12 b' def filefind(filename, path_dirs=None):'
 
     Returns
     -------
-    Raises :exc:`IOError` or returns absolute path to file.
+    path : str
+        returns absolute path to file.
+
+    Raises
+    ------
+    IOError
     """
 
     # If paths are quoted, abspath gets confused, strip them...
@@ -178,7 +183,6 b' def get_home_dir(require_writable=False) -> str:'
 
     Parameters
     ----------
-
     require_writable : bool [default: False]
         if True:
             guarantees the return value is a writable directory, otherwise

IPython/utils/sysinfo.py

@@ -40,15 +40,15 b' 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
     """
     # Try and get commit from written commit text file
     if _sysinfo.commit:
@@ -71,12 +71,12 b' 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(

IPython/utils/terminal.py

@@ -45,7 +45,7 b' def toggle_set_term_title(val):'
 
     Parameters
     ----------
-      val : bool
+    val : bool
         If True, set_term_title() actually writes to the terminal (using the
         appropriate platform-specific module).  If False, it is a no-op.
     """

IPython/utils/tests/test_capture.py

@@ -111,7 +111,7 b' def test_rich_output_metadata(method_mime):'
 
 def test_rich_output_display():
     """test RichOutput.display
-    
+
     This is a bit circular, because we are actually using the capture code we are testing
     to test itself.
     """

IPython/utils/tests/test_module_paths.py

@@ -54,8 +54,8 b' def setup_module():'
 def teardown_module():
     """Teardown testenvironment for the module:
 
-            - Remove tempdir
-            - restore sys.path
+    - Remove tempdir
+    - restore sys.path
     """
     # Note: we remove the parent test dir, which is the root of all test
     # subdirs we may have created.  Use shutil instead of os.removedirs, so

IPython/utils/tests/test_path.py

@@ -56,7 +56,7 b' HOME_TEST_DIR = join(TMP_TEST_DIR, "home_test_dir")'
 def setup_module():
     """Setup testenvironment for the module:
 
-            - Adds dummy home dir tree
+    - Adds dummy home dir tree
     """
     # Do not mask exceptions here.  In particular, catching WindowsError is a
     # problem because that exception is only defined on Windows...
@@ -66,7 +66,7 b' def setup_module():'
 def teardown_module():
     """Teardown testenvironment for the module:
 
-            - Remove dummy home dir tree
+    - Remove dummy home dir tree
     """
     # Note: we remove the parent test dir, which is the root of all test
     # subdirs we may have created.  Use shutil instead of os.removedirs, so

IPython/utils/tests/test_sysinfo.py

@@ -12,6 +12,6 b' from IPython.utils import sysinfo'
 
 def test_json_getsysinfo():
     """
-    test that it is easily jsonable and don't return bytes somewhere. 
+    test that it is easily jsonable and don't return bytes somewhere.
     """
     json.dumps(sysinfo.get_sys_info())

IPython/utils/text.py

@@ -252,7 +252,6 b' def indent(instr,nspaces=4, ntabs=0, flatten=False):'
 
     Parameters
     ----------
-
     instr : basestring
         The string to be indented.
     nspaces : int (default: 4)
@@ -266,7 +265,6 b' def indent(instr,nspaces=4, ntabs=0, flatten=False):'
 
     Returns
     -------
-
     str|unicode : string indented by ntabs and nspaces.
 
     """
@@ -390,7 +388,6 b' def wrap_paragraphs(text, ncols=80):'
 
     Returns
     -------
-
     list of complete paragraphs, wrapped to fill `ncols` columns.
     """
     paragraph_re = re.compile(r'\n(\s*\n)+', re.MULTILINE)
@@ -410,7 +407,7 b' def wrap_paragraphs(text, ncols=80):'
 
 def long_substr(data):
     """Return the longest common substring in a list of strings.
-    
+
     Credit: http://stackoverflow.com/questions/2892931/longest-common-substring-from-more-than-two-strings-python
     """
     substr = ''
@@ -474,7 +471,7 b' def strip_email_quotes(text):'
 def strip_ansi(source):
     """
     Remove ansi escape codes from text.
-    
+
     Parameters
     ----------
     source : str
@@ -651,7 +648,6 b' def compute_item_matrix(items, row_first=False, empty=None, *args, **kwargs) :'
 
     Parameters
     ----------
-
     items
         list of strings to columize
     row_first : (default False)
@@ -666,14 +662,11 b' def compute_item_matrix(items, row_first=False, empty=None, *args, **kwargs) :'
 
     Returns
     -------
-
     strings_matrix
-
         nested list of string, the outer most list contains as many list as
         rows, the innermost lists have each as many element as columns. If the
         total number of elements in `items` does not equal the product of
         rows*columns, the last element of some lists are filled with `None`.
-
     dict_info
         some info to make columnize easier:
 
@@ -713,14 +706,11 b" def columnize(items, row_first=False, separator=' ', displaywidth=80, spread=Fa"
     ----------
     items : sequence of strings
         The strings to process.
-
     row_first : (default False)
         Whether to compute columns for a row-first matrix instead of
         column-first (default).
-
     separator : str, optional [default is two spaces]
         The string that separates columns.
-
     displaywidth : int, optional [default is 80]
         Width of the display in number of characters.
 

IPython/utils/tokenutil.py

@@ -23,20 +23,18 b' def generate_tokens(readline):'
 
 def line_at_cursor(cell, cursor_pos=0):
     """Return the line in a cell at a given cursor position
-    
+
     Used for calling line-based APIs that don't support multi-line input, yet.
-    
+
     Parameters
     ----------
-    
-    cell: str
+    cell : str
         multiline block of text
-    cursor_pos: integer
+    cursor_pos : integer
         the cursor position
-    
+
     Returns
     -------
-    
     (line, offset): (string, integer)
         The line with the current cursor, and the character offset of the start of the line.
     """
@@ -58,15 +56,14 b' def line_at_cursor(cell, cursor_pos=0):'
 
 def token_at_cursor(cell, cursor_pos=0):
     """Get the token at a given cursor
-    
+
     Used for introspection.
-    
+
     Function calls are prioritized, so the token for the callable will be returned
     if the cursor is anywhere inside the call.
-    
+
     Parameters
     ----------
-    
     cell : unicode
         A block of Python code
     cursor_pos : int