Clean up/Normalize docstrings

hy/compiler.py

@@ -18,19 +18,13 @@
 def ast_compile(a, filename, mode):
     """Compile AST.
 
-    Parameters
-    ----------
-    a : instance of `ast.AST`
-
-    filename : str
-        Filename used for run-time error messages
-
-    mode: str
-        `compile` mode parameter
+    Args:
+        a (ast.AST): instance of `ast.AST`
+        filename (str): Filename used for run-time error messages
+        mode (str): `compile` mode parameter
 
-    Returns
-    -------
-    out : instance of `types.CodeType`
+    Returns:
+        types.CodeType: instance of `types.CodeType`
     """
     return compile(a, filename, mode, hy_ast_compile_flags)
 
@@ -41,16 +35,12 @@ def calling_module(n=1):
     As a fallback, this will import a module using the calling frame's
     globals value of `__name__`.
 
-    Parameters
-    ----------
-    n: int, optional
-        The number of levels up the stack from this function call.
-        The default is one level up.
+    Args:
+        n (int): The number of levels up the stack from this function call.
+            The default is `1` (level up).
 
-    Returns
-    -------
-    out: types.ModuleType
-        The module at stack level `n + 1` or `None`.
+    Returns:
+        types.ModuleType: The module at stack level `n + 1` or `None`.
     """
     frame_up = inspect.stack(0)[n + 1][0]
     module = inspect.getmodule(frame_up)
@@ -284,17 +274,13 @@ class HyASTCompiler(object):
 
     def __init__(self, module, filename=None, source=None):
         """
-        Parameters
-        ----------
-        module: str or types.ModuleType
-            Module name or object in which the Hy tree is evaluated.
-        filename: str, optional
-            The name of the file for the source to be compiled.
-            This is optional information for informative error messages and
-            debugging.
-        source: str, optional
-            The source for the file, if any, being compiled.  This is optional
-            information for informative error messages and debugging.
+        Args:
+            module (Union[str, types.ModuleType]): Module name or object in which the Hy tree is evaluated.
+            filename (Optional[str]): The name of the file for the source to be compiled.
+                This is optional information for informative error messages and
+                debugging.
+            source (Optional[str]): The source for the file, if any, being compiled.  This is optional
+                information for informative error messages and debugging.
         """
         self.anon_var_count = 0
         self.temp_if = None
@@ -642,8 +628,16 @@ def get_compiler_module(module=None, compiler=None, calling_frame=False):
     return module
 
 
-def hy_eval(hytree, locals=None, module=None, ast_callback=None,
-            compiler=None, filename=None, source=None, import_stdlib=True):
+def hy_eval(
+    hytree,
+    locals=None,
+    module=None,
+    ast_callback=None,
+    compiler=None,
+    filename=None,
+    source=None,
+    import_stdlib=True,
+):
     """Evaluates a quoted expression and returns the value.
 
     If you're evaluating hand-crafted AST trees, make sure the line numbers
@@ -663,44 +657,44 @@ def hy_eval(hytree, locals=None, module=None, ast_callback=None,
          2
 
     Args:
-      hytree (hy.models.Object):
+      hytree (Object):
           The Hy AST object to evaluate.
 
-      locals (dict, optional):
+      locals (Optional[dict]):
           Local environment in which to evaluate the Hy tree.  Defaults to the
           calling frame.
 
-      module (str or types.ModuleType, optional):
+      module (Optional[Union[str, types.ModuleType]]):
           Module, or name of the module, to which the Hy tree is assigned and
           the global values are taken.
           The module associated with `compiler` takes priority over this value.
           When neither `module` nor `compiler` is specified, the calling frame's
           module is used.
 
-      ast_callback (callable, optional):
+      ast_callback (Optional[Callable]):
           A callback that is passed the Hy compiled tree and resulting
           expression object, in that order, after compilation but before
           evaluation.
 
-      compiler (HyASTCompiler, optional):
+      compiler (Optional[HyASTCompiler]):
           An existing Hy compiler to use for compilation.  Also serves as
           the `module` value when given.
 
-      filename (str, optional):
+      filename (Optional[str]):
           The filename corresponding to the source for `tree`.  This will be
           overridden by the `filename` field of `tree`, if any; otherwise, it
           defaults to "<string>".  When `compiler` is given, its `filename` field
           value is always used.
 
-      source (str, optional):
+      source (Optional[str]):
           A string containing the source code for `tree`.  This will be
           overridden by the `source` field of `tree`, if any; otherwise,
           if `None`, an attempt will be made to obtain it from the module given by
           `module`.  When `compiler` is given, its `source` field value is always
           used.
 
     Returns:
-      Result of evaluating the Hy compiled tree.
+      Any: Result of evaluating the Hy compiled tree.
     """
 
     module = get_compiler_module(module, compiler, True)
@@ -732,45 +726,38 @@ def hy_eval(hytree, locals=None, module=None, ast_callback=None,
                 module.__dict__, locals)
 
 
-def hy_compile(tree, module, root=ast.Module, get_expr=False,
-               compiler=None, filename=None, source=None, import_stdlib=True):
+def hy_compile(
+    tree,
+    module,
+    root=ast.Module,
+    get_expr=False,
+    compiler=None,
+    filename=None,
+    source=None,
+    import_stdlib=True,
+):
     """Compile a hy.models.Object tree into a Python AST Module.
 
-    Parameters
-    ----------
-    tree: hy.models.Object
-        The Hy AST object to compile.
-
-    module: str or types.ModuleType, optional
-        Module, or name of the module, in which the Hy tree is evaluated.
-        The module associated with `compiler` takes priority over this value.
-
-    root: ast object, optional (ast.Module)
-        Root object for the Python AST tree.
-
-    get_expr: bool, optional (False)
-        If true, return a tuple with `(root_obj, last_expression)`.
-
-    compiler: HyASTCompiler, optional
-        An existing Hy compiler to use for compilation.  Also serves as
-        the `module` value when given.
-
-    filename: str, optional
-        The filename corresponding to the source for `tree`.  This will be
-        overridden by the `filename` field of `tree`, if any; otherwise, it
-        defaults to "<string>".  When `compiler` is given, its `filename` field
-        value is always used.
-
-    source: str, optional
-        A string containing the source code for `tree`.  This will be
-        overridden by the `source` field of `tree`, if any; otherwise,
-        if `None`, an attempt will be made to obtain it from the module given by
-        `module`.  When `compiler` is given, its `source` field value is always
-        used.
-
-    Returns
-    -------
-    out : A Python AST tree
+    Args:
+        tree (Object): The Hy AST object to compile.
+        module (Union[str, types.ModuleType]): Module, or name of the module, in which the Hy tree is evaluated.
+            The module associated with `compiler` takes priority over this value.
+        root (Type[ast.AST]): Root object for the Python AST tree.
+        get_expr (bool): If true, return a tuple with `(root_obj, last_expression)`.
+        compiler (Optional[HyASTCompiler]): An existing Hy compiler to use for compilation.  Also serves as
+            the `module` value when given.
+        filename (Optional[str]): The filename corresponding to the source for `tree`.  This will be
+            overridden by the `filename` field of `tree`, if any; otherwise, it
+            defaults to "<string>".  When `compiler` is given, its `filename` field
+            value is always used.
+        source (Optional[str]): A string containing the source code for `tree`.  This will be
+            overridden by the `source` field of `tree`, if any; otherwise,
+            if `None`, an attempt will be made to obtain it from the module given by
+            `module`.  When `compiler` is given, its `source` field value is always
+            used.
+
+    Returns:
+        ast.AST: A Python AST tree
     """
     module = get_compiler_module(module, compiler, False)
 

hy/errors.py

@@ -33,27 +33,27 @@ class HyLanguageError(HyError):
     This, and any errors inheriting from this, are user-facing.
     """
 
-    def __init__(self, message, expression=None, filename=None, source=None,
-                 lineno=1, colno=1):
+    def __init__(
+        self,
+        message,
+        expression=None,
+        filename=None,
+        source=None,
+        lineno=1,
+        colno=1,
+    ):
         """
-        Parameters
-        ----------
-        message: str
-            The message to display for this error.
-        expression: HyObject, optional
-            The Hy expression generating this error.
-        filename: str, optional
-            The filename for the source code generating this error.
-            Expression-provided information will take precedence of this value.
-        source: str, optional
-            The actual source code generating this error.  Expression-provided
-            information will take precedence of this value.
-        lineno: int, optional
-            The line number of the error.  Expression-provided information will
-            take precedence of this value.
-        colno: int, optional
-            The column number of the error.  Expression-provided information
-            will take precedence of this value.
+        Args:
+            message (str): The message to display for this error.
+            expression (Optional[Object]): The Hy expression generating this error.
+            filename (Optional[str]): The filename for the source code generating this error.
+                Expression-provided information will take precedence of this value. Defaults to `None`.
+            source (Optional[str]): The actual source code generating this error.  Expression-provided
+                information will take precedence of this value. Defaults to `None`.
+            lineno (int): The line number of the error.  Expression-provided information will
+                take precedence of this value. Defaults to `1`.
+            colno (int): The column number of the error.  Expression-provided information
+                will take precedence of this value. Defaults to `1`.
         """
         self.msg = message
         self.compute_lineinfo(expression, filename, source, lineno, colno)

hy/lex/__init__.py

@@ -16,11 +16,11 @@ def hy_parse(source, filename='<string>'):
     """Parse a Hy source string.
 
     Args:
-      source (string): Source code to parse.
-      filename (string, optional): File name corresponding to source.  Defaults to "<string>".
+      source (str): Source code to parse.
+      filename (str): File name corresponding to source.  Defaults to "<string>".
 
     Returns:
-      out : hy.models.Expression
+      Expression: the parsed models wrapped in an hy.models.Expression
     """
     _source = re.sub(r'\A#!.*', '', source)
     res = Expression([Symbol("do")] +
@@ -41,8 +41,11 @@ def tokenize(source, filename=None):
     """ Tokenize a Lisp file or string buffer into internal Hy objects.
 
     Args:
-    source (str): The source to tokenize.
-    filename (str, optional): The filename corresponding to `source`.
+       source (str): The source to tokenize.
+       filename (Optional[str]): The filename corresponding to `source`.
+
+    Returns:
+       typing.List[Object]: list of hy object models
     """
     from hy.lex.lexer import lexer
     from hy.lex.parser import parser

hy/macros.py

@@ -115,28 +115,19 @@ def require(source_module, target_module, assignments, prefix=""):
 
     This function is called from the macro also named `require`.
 
-    Parameters
-    ----------
-    source_module: str or types.ModuleType
-        The module from which macros are to be imported.
-
-    target_module: str, types.ModuleType or None
-        The module into which the macros will be loaded.  If `None`, then
-        the caller's namespace.
-        The latter is useful during evaluation of generated AST/bytecode.
-
-    assignments: str or list of tuples of strs
-        The string "ALL" or a list of macro name and alias pairs.
-
-    prefix: str, optional ("")
-        If nonempty, its value is prepended to the name of each imported macro.
-        This allows one to emulate namespaced macros, like
-        "mymacromodule.mymacro", which looks like an attribute of a module.
-
-    Returns
-    -------
-    out: boolean
-        Whether or not macros were actually transferred.
+    Args:
+        source_module (Union[str, ModuleType]): The module from which macros are
+            to be imported.
+        target_module (Optional[Union[str, ModuleType]]): The module into which the
+            macros will be loaded.  If `None`, then the caller's namespace.
+            The latter is useful during evaluation of generated AST/bytecode.
+        assignments (Union[str, typing.Sequence[str]]): The string "ALL" or a list of macro name and alias pairs.
+        prefix (str): If nonempty, its value is prepended to the name of each imported macro.
+            This allows one to emulate namespaced macros, like "mymacromodule.mymacro",
+            which looks like an attribute of a module. Defaults to ""
+
+    Returns:
+        bool: Whether or not macros were actually transferred.
     """
     if target_module is None:
         parent_frame = inspect.stack()[1][0]
@@ -287,24 +278,18 @@ def macroexpand(tree, module, compiler=None, once=False, result_ok=True):
     outer-most namespace--e.g.  the one given by the `module` parameter--is used
     as a fallback.
 
-    Parameters
-    ----------
-    tree: hy.models.Object or list
-        Hy AST tree.
-
-    module: str or types.ModuleType
-        Module used to determine the local namespace for macros.
-
-    compiler: HyASTCompiler, optional
-        The compiler object passed to expanded macros.
-
-    once: boolean, optional
-        Only expand the first macro in `tree`.
-
-    Returns
-    ------
-    out: hy.models.Object
-        Returns a mutated tree with macros expanded.
+    Args:
+        tree (Union[Object, list]): Hy AST tree.
+        module (Union[str, ModuleType]): Module used to determine the local
+            namespace for macros.
+        compiler (Optional[HyASTCompiler] ): The compiler object passed to
+            expanded macros. Defaults to None
+        once (bool): Only expand the first macro in `tree`. Defaults to False
+        result_ok (bool): Whether or not it's okay to return a compiler `Result` instance.
+            Defaults to True.
+
+    Returns:
+        Union[Object, Result]: A mutated tree with macros expanded.
     """
     if not inspect.ismodule(module):
         module = importlib.import_module(module)