document public api #63

qastle/__init__.py

@@ -1,6 +1,3 @@
-from .ast_util import *
-from .columns_util import *
-from .linq_util import *
-from .parse import *
-from .transform import *
-from .translate import *
+from .ast_util import unwrap_ast, wrap_ast
+from .linq_util import insert_linq_nodes, remove_linq_nodes
+from .translate import python_ast_to_text_ast, text_ast_to_python_ast

qastle/ast_util.py

@@ -3,6 +3,19 @@
 
 
 def unwrap_ast(module_node):
+    """
+    Extract a Python AST from an ast.Module node
+
+    Parameters
+    ----------
+    python_ast : ast.AST
+        Python AST wrapped in an ast.Module
+
+    Returns
+    -------
+    ast.AST
+        Bare Python AST without an ast.Module
+    """
     if len(module_node.body) == 0:
         return None
     else:
@@ -11,6 +24,19 @@ def unwrap_ast(module_node):
 
 
 def wrap_ast(node=None):
+    """
+    Insert a Python AST into an ast.Module node
+
+    Parameters
+    ----------
+    python_ast : ast.AST
+        Python AST to be wrapped
+
+    Returns
+    -------
+    ast.AST
+        Python AST wrapped in an ast.Module
+    """
     if node is None:
         body_list = []
     else:

qastle/linq_util.py

@@ -242,6 +242,19 @@ def visit_Call(self, node):
 
 
 def insert_linq_nodes(python_ast):
+    """
+    Insert LINQ nodes into a Python AST
+
+    Parameters
+    ----------
+    python_ast : ast.AST
+        Python AST without LINQ nodes
+
+    Returns
+    -------
+    ast.AST
+        Python AST with LINQ nodes inserted
+    """
     return InsertLINQNodesTransformer().visit(python_ast)
 
 
@@ -250,4 +263,17 @@ class RemoveLINQNodesTransformer(ast.NodeTransformer):
 
 
 def remove_linq_nodes(python_ast):
+    """
+    Remove LINQ nodes from a Python AST
+
+    Parameters
+    ----------
+    python_ast : ast.AST
+        Python AST with LINQ nodes
+
+    Returns
+    -------
+    ast.AST
+        Python AST without LINQ nodes
+    """
     return RemoveLINQNodesTransformer().visit(python_ast)

qastle/translate.py

@@ -14,9 +14,35 @@ def python_source_to_text_ast(python_source):
 
 
 def python_ast_to_text_ast(python_ast):
+    """
+    Create a qastle text AST from a native Python AST
+
+    Parameters
+    ----------
+    python_ast : ast.AST
+        Python AST to translate
+
+    Returns
+    -------
+    str
+        Translated qastle AST as a text string
+    """
     return PythonASTToTextASTTransformer().visit(python_ast)
 
 
 def text_ast_to_python_ast(text_ast):
+    """
+    Create a native Python AST from a qastle text AST
+
+    Parameters
+    ----------
+    test_ast : str
+        qastle AST to translate
+
+    Returns
+    -------
+    ast.AST
+        Translated Python AST
+    """
     tree = parse(text_ast)
     return TextASTToPythonASTTransformer().transform(tree)

tests/test_ast_language.py

@@ -1,6 +1,8 @@
 from .testing_util import *
 
 from qastle import *
+from qastle.linq_util import *
+from qastle.translate import *
 
 import ast
 

tests/test_columns_util.py

@@ -1,6 +1,8 @@
 from .testing_util import *
 
 from qastle import *
+from qastle.columns_util import *
+from qastle.linq_util import *
 
 import ast
 

tests/test_linq_util.py

@@ -1,6 +1,7 @@
 from .testing_util import *
 
 from qastle import *
+from qastle.linq_util import *
 
 import ast
 import copy