Added docstrings samples in google docstyle.

Author: Patryk Szulczewski

netcompare/check_type.py

@@ -1,5 +1,5 @@
 """CheckType Implementation."""
-from typing import Mapping, Iterable, Tuple, Union, List
+from typing import Mapping, Iterable, Tuple, Union, List, Dict, Any
 from .evaluator import diff_generator
 from .runner import extract_values_from_output
 
@@ -12,7 +12,11 @@ def __init__(self, *args):
 
     @staticmethod
     def init(*args):
-        """Factory pattern to get the appropiate CheckType implementation."""
+        """Factory pattern to get the appropriate CheckType implementation.
+
+        Args:
+            *args: Variable length argument list.
+        """
         check_type = args[0]
         if check_type == "exact_match":
             return ExactMatchType(*args)
@@ -21,18 +25,23 @@ def init(*args):
         raise NotImplementedError
 
     @staticmethod
-    def extract_value_from_json_path(
-        output: Union[Mapping, Iterable], path: str, exclude: List = None
-    ) -> Union[Mapping, List, int, str, bool]:
+    def extract_value_from_json_path(output: Union[Mapping, Iterable], path: str, exclude: List = None) -> Any:
         """Return the value contained into a Mapping for a defined path."""
         return extract_values_from_output(output, path, exclude)
 
     def evaluate(
         self, reference_value: Union[Mapping, Iterable], value_to_compare: Union[Mapping, Iterable]
-    ) -> Tuple[Mapping, bool]:
+    ) -> Tuple[Dict, bool]:
         """Return the result of the evaluation and a boolean True if it passes it or False otherwise.
 
         This method is the one that each CheckType has to implement.
+
+        Args:
+            reference_value: dataset to compare
+            value_to_compare: dataset to compare
+
+        Returns:
+            tuple: Dictionary representing differences between datasets, bool indicating if differences are found.
         """
         raise NotImplementedError
 
@@ -52,12 +61,12 @@ class ToleranceType(CheckType):
     """Tolerance class docstring."""
 
     def __init__(self, *args):
-        """Tollerance init method."""
+        """Tolerance init method."""
         self.tolerance_factor = float(args[1]) / 100
         super().__init__()
 
     def evaluate(self, reference_value: Mapping, value_to_compare: Mapping) -> Tuple[Mapping, bool]:
-        """Returns the difference between values and the boolean."""
+        """Returns the difference between values and the boolean. Overwrites method in base class."""
         diff = diff_generator(reference_value, value_to_compare)
         diff = self._get_outliers(diff)
         return diff, not diff

netcompare/evaluator.py

@@ -11,7 +11,15 @@
 
 
 def diff_generator(pre_result: Union[Mapping, Iterable], post_result: Union[Mapping, Iterable]) -> Dict:
-    """Generates diff between pre and post data based on check definition."""
+    """Generates diff between pre and post data based on check definition.
+
+    Args:
+        pre_result: dataset to compare
+        post_result: dataset to compare
+
+    Returns:
+        differences between two datasets
+    """
     diff_result = DeepDiff(pre_result, post_result)
 
     result = diff_result.get("values_changed", {})
@@ -28,13 +36,18 @@ def diff_generator(pre_result: Union[Mapping, Iterable], post_result: Union[Mapp
 
 
 def get_diff_iterables_items(diff_result: Mapping) -> Dict:
-    """Return a dict with new and missing values where the values are in a list.
+    """Helper function for diff_generator to postprocess changes reported by DeepDiff for iterables.
 
     DeepDiff iterable_items are returned when the source data is a list
     and provided in the format: "root['Ethernet3'][1]"
     or more generically: root['KEY']['KEY']['KEY']...[numeric_index]
     where the KEYs are dict keys within the original object
     and the "[index]" is appended to indicate the position within the list.
+
+    Args:
+        diff_result: iterable comparison result from DeepDiff
+    Returns:
+        Return a dict with new and missing values where the values are in a list.
     """
     get_dict_keys = re.compile(r"^root((\['\w.*'\])+)\[\d+\]$")
 
@@ -59,7 +72,13 @@ def get_diff_iterables_items(diff_result: Mapping) -> Dict:
 def fix_deepdiff_key_names(obj: Mapping) -> Dict:
     """Return a dict based on the provided dict object where the brackets and quotes are removed from the string.
 
-    obj sample: root[2]['10.64.207.255']['accepted_prefixes']
+    Args:
+        obj: Example: {"root[3]['7.7.7.7']['is_enabled']": {'new_value': False, 'old_value': True},
+                       "root[3]['7.7.7.7']['is_up']": {'new_value': False, 'old_value': True}}
+
+    Returns:
+        normalized output Example: {'7.7.7.7': {'is_enabled': {'new_value': False, 'old_value': True},
+                                                'is_up': {'new_value': False, 'old_value': True}}}
     """
     pattern = r"'([A-Za-z0-9_\./\\-]*)'"
 

netcompare/runner.py

@@ -1,20 +1,29 @@
 """Library wrapper for output parsing."""
 import re
-from typing import Mapping, List, Union
+from typing import Mapping, List, Union, Any
 import jmespath
 from .utils.jmspath_parsers import jmspath_value_parser, jmspath_refkey_parser
 from .utils.filter_parsers import exclude_filter
 from .utils.refkey import keys_cleaner, keys_values_zipper, associate_key_of_my_value
 from .utils.flatten import flatten_list
 
 
-def extract_values_from_output(
-    output: Union[Mapping, List], path: str, exclude: List = None
-) -> Union[Mapping, List, int, str, bool]:
+def extract_values_from_output(output: Union[Mapping, List], path: str, exclude: List = None) -> Any:
     """Return data from output depending on the check path. See unit test for complete example.
 
-    Get the wanted values to be evaluated if jmspath expression is defined,
+    Get the wanted values to be evaluated if JMESPath expression is defined,
     otherwise use the entire output if jmespath is not defined in check. This covers the "raw" diff type.
+    Exclude data not desired to compare.
+
+    Notes:
+        https://jmespath.org/ shows how JMESPath works.
+
+    Args:
+        output: json data structure
+        path: JMESPath to extract specific values
+        exclude: list of keys to exclude
+    Returns:
+        Evaluated data, may be anything depending on JMESPath used.
     """
     if exclude:
         exclude_filter(output, exclude)  # exclude unwanted elements