Skip to content

Commit

Permalink
Merge pull request #2130 from allison-casey/refactor/clean-up-docstrings
Browse files Browse the repository at this point in the history 
Clean up/Normalize docstrings
  • Loading branch information
@allison-casey
allison-casey committed Jul 27, 2021
2 parents ca5069f + f0c981a commit 781dc35
Show file tree
Hide file tree
Showing 4 changed files with 119 additions and 144 deletions.
145 changes: 66 additions & 79 deletions hy/compiler.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand All @@ -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)
Expand Down Expand 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
Expand Down Expand Up @@ -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
Expand All @@ -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)
Expand Down Expand Up @@ -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)

Expand Down
40 changes: 20 additions & 20 deletions hy/errors.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
13 changes: 8 additions & 5 deletions hy/lex/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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")] +
Expand All @@ -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
Expand Down
65 changes: 25 additions & 40 deletions hy/macros.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down Expand Up @@ -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)
Expand Down

0 comments on commit 781dc35

Please sign in to comment.