Added documentation to relevant functions

Author: cedricrupb

code_diff/__init__.py

@@ -10,6 +10,46 @@
 # Main method --------------------------------------------------------
 
 def difference(source, target, lang = "guess", **kwargs):
+    """
+    Computes the smallest difference between source and target
+
+    Computes the smallest code difference between the given 
+    code snippets. Difference is computed by a simulteanous
+    walk over the ASTs of the given code snippets. Returned
+    will be the smallest code snippet that represent
+    the first AST node found to be different.
+
+    Parameters
+    ----------
+    source : str
+        Source code which should be compared
+    
+    target : str
+        Comparison target as a code string
+
+    lang : [python, java, javascript, ...]
+        Programming language which should be used
+        to parse the code snippets.
+        Default: guess (Currently not supported, will throw error)
+    
+    syntax_error : [raise, warn, ignore]
+        Strategy to handle syntax errors in code.
+        To parse incomplete code snippets, 'ignore' should
+        be selected to silent any warning.
+        Default: raise (Raises an exception)
+
+    **kwargs : dict
+        Further config option that are specific to
+        the underlying AST parser. See code_tokenize
+        for more infos.
+
+    Returns
+    -------
+    ASTDiff
+        The smallest code change necessary
+        to convert the source code into the target code.
+    
+    """
 
     config     = load_from_lang_config(lang, **kwargs)
     source_ast = parse_ast(source, lang = lang, **kwargs)
@@ -56,6 +96,56 @@ def diff_search(source_ast, target_ast):
 # AST Difference --------------------------------------------------------
 
 class ASTDiff:
+    """
+    Difference between two code snippets
+
+    This object represents the smallest code change
+    necessary to transform a source code snippet
+    into a target code.
+
+    Attributes
+    ----------
+    is_single_statement : bool
+        Whether the code difference only affect a single program statement
+
+    source_ast : ASTNode
+        AST node related to the code change
+    
+    source_text : str
+        Source code which have to be changed
+
+    target_ast : ASTNode
+        AST node which is different to the source AST
+
+    target_text : str
+        Target text for converting source to target
+    
+    Methods
+    -------
+    edit_script : list[EditOp]
+        Computes a sequence of AST operations which need
+        to be performed to translate source code in target code
+        
+        Note: We balance performance and precision by computing
+        the AST edit script at the current diff level. The
+        algorithm runs the fastest on the smallest diff level
+        but is also most imprecise. To achieve the highest precision,
+        the root_diff should be used.
+
+    sstub_pattern : SStuBPattern
+        Categorizes the current diff into one of 20 SStuB categories.
+        Note: Currently, this operation is only supported for
+        Python code. Running the function on code in another language
+        will cause an exception.
+
+    statement_diff : ASTDiff
+        raises the AST difference to the statement level
+    
+    root_diff : ASTDiff
+        raises the AST difference to the root level (of each code snippet)
+
+    
+    """
 
     def __init__(self, config, source_ast, target_ast):
         self.config     = config
@@ -88,6 +178,8 @@ def root_diff(self):
         return ASTDiff(self.config, ast_root(self.source_ast), ast_root(self.target_ast))
 
     def sstub_pattern(self):
+        if self.config.lang != "python":
+            raise ValueError("SStuB can currently only be computed for Python code.")
 
         if (parent_statement(self.config.statement_types, self.source_ast) is None
                 or parent_statement(self.config.statement_types, self.target_ast) is None):

code_diff/ast.py

@@ -6,6 +6,40 @@
 
 
 class ASTNode(object):
+    """
+    A representation of an AST node together with its children
+
+    Node Attributes
+    ---------------
+    type : str
+        Syntactic type of the AST node
+
+    text : str
+        If this node belongs to a program token, then
+        it contains the text of the program token. Otherwise, None.
+    
+    children : list[ASTNode]
+        Potenially empty list of child nodes
+    
+    position : int
+        If supported, the code position that is referenced by the AST node
+
+    parent : ASTNode
+        If not root node, the AST parent of this node.
+    
+    Subtree Attributes
+    ------------------
+    subtree_hash : str
+        A hash string representing the subtree of the AST node
+        Two subtrees are isomorph if they have the same subtree hash.
+    
+    subtree_height : int
+        Longest path from this node to a leaf node
+
+    subtree_weight : int
+        Count of all nodes in this subtree
+    
+    """
 
     def __init__(self, type, text = None, position = None, parent = None, children = None):
 
@@ -264,6 +298,30 @@ def __call__(self, tokens):
 
 
 def parse_ast(source_code, lang = "guess", **kwargs):
+    """
+    Parses a given source code string into its AST
+
+    Function to parse source code in the given language
+    into its AST. As a backend, we employ
+    code_tokenize (tree-sitter). The final
+    AST is additionally analyzed to compute
+    additional annotations
+
+    Parameters
+    ----------
+    source_code : str
+        Source code snippet as a string
+    
+    lang : [python, java, javascript, ...]
+        Language to parse the given source code
+        Default: guess (Currently not supported; will raise error)
+
+    Returns
+    -------
+    ASTNode
+        the root node of the computed AST
+    
+    """
 
     # Parse AST 
     kwargs["lang"] = lang

code_diff/sstubs.py

@@ -1,5 +1,4 @@
 from enum import Enum
-import re
 
 class SStubPattern(Enum):
 
@@ -62,7 +61,9 @@ def classify_sstub(source_ast, target_ast):
         if source_name == target_name:
             classifier_fns.append(same_function_mod)
 
-    if _query_path(source_ast, "if_statement", "condition") or _query_path(source_ast, "elif_clause", "condition"):
+    if (_query_path(source_ast, "if_statement", "condition")
+         or _query_path(source_ast, "elif_clause", "condition")
+         or _query_path(source_ast, "while_statement", "condition")):
         classifier_fns.append(change_if_statement)
 
     if source_ast.type in ["tuple", "list", "dictionary", "set"]:
@@ -119,15 +120,15 @@ def pisomorph(A, B):
 
 # Binary operand ----------------------------------------------------------------
 
-def _is_binary_operand(source_ast, target_ast):
-    return _query_path(source_ast, "binary_operator", "left") or _query_path(source_ast, "binary_operator", "right")
-
-def is_boolean_operand(source_ast, target_ast):
-    return _query_path(source_ast, "boolean_operator", "left") or _query_path(source_ast, "boolean_operator", "right")
-
 
 def is_binary_operand(source_ast, target_ast):
-    return _is_binary_operand(source_ast, target_ast) or is_boolean_operand(source_ast, target_ast)
+
+    for bin_op_type in ["binary_operator", "comparison_operator", "boolean_operator"]:
+        for direction in ["left", "right"]:
+            if (_query_path(source_ast, bin_op_type, direction, depth = 1)):
+                return True
+    
+    return False
 
 
 
@@ -218,16 +219,19 @@ def change_attribute_used(source_ast, target_ast):
 
 
 def change_identifier_used(source_ast, target_ast):
-    return source_ast.type == "identifier"
+
+    # Following ManySStuBs we ignore the following Method declaration, Class Declaration, Variable Declaration
+    if any(x in source_ast.parent.type for x in ["definition", "declaration"]):
+        return False
+
+    return source_ast.type == "identifier" and target_ast.type == "identifier"
 
 
 def change_binary_operator(source_ast, target_ast):
 
-    for operator in ["binary_operator", "boolean_operator", "comparison_operator"]:
-        if _query_path(source_ast, operator, "*", depth = 1):
-            if (not _query_path(source_ast, operator, "left", depth = 1) 
-                    and not _query_path(source_ast, operator, "right", depth = 1)):
-                return True
+    if source_ast.parent.type in ["binary_operator", "boolean_operator", "comparison_operator"]:
+        bin_op = source_ast.parent
+        return bin_op.children[1] == source_ast
 
     return False
 
@@ -332,12 +336,16 @@ def same_function_swap_args(source_ast, target_ast):
     if len(source_ast.children) != len(target_ast.children):
         return False
 
-    arguments = source_ast.children
-    for arg in arguments:
-        if not any(pisomorph(t, arg) for t in target_ast.children):
-            return False
+    src_arguments    = source_ast.children
+    target_arguments = target_ast.children
 
-    return True
+    diff_args = [i for i, src_arg in enumerate(src_arguments) if not pisomorph(src_arg, target_arguments[i])]
+
+    if len(diff_args) != 2: return False
+
+    swap_0, swap_1 = diff_args
+    return (pisomorph(src_arguments[swap_0], target_arguments[swap_1])
+             and pisomorph(src_arguments[swap_1], target_arguments[swap_0]))
 
 
 same_function_edits = {
@@ -364,11 +372,18 @@ def same_function_mod(source_ast, target_ast):
 
 
 def more_specific_if(source_ast, target_ast):
+    
+    if not target_ast.type == "boolean_operator": return False
+    if target_ast.children[1].type != "and"     : return False
+
     return any(pisomorph(c, source_ast) for c in target_ast.children)
 
 
 def less_specific_if(source_ast, target_ast):
-    return any(pisomorph(c, target_ast) for c in source_ast.children)
+    if not target_ast.type == "boolean_operator": return False
+    if target_ast.children[1].type != "or"      : return False
+
+    return any(pisomorph(c, source_ast) for c in target_ast.children)
 
 
 def change_if_statement(source_ast, target_ast):
@@ -413,7 +428,8 @@ def add_function_around_expression(source_ast, target_ast):
     if argument_list.type != "argument_list":
         return False
 
-    if len(argument_list.children) != 3: return False
+    # It seems that adding arguments together with a function seems to be okay (see PySStuBs dataset)
+    #if len(argument_list.children) != 3: return False 
 
     for arg in argument_list.children:
         if pisomorph(arg, source_ast):