Merge remote-tracking branch 'origin/pr/2470' into mbedtls-2.16

* origin/pr/2470:
  Silence pylint
  check-files.py: readability improvement in permission check
  check-files.py: use class fields for class-wide constants
  check-files.py: clean up class structure
  abi_check.py: Document more methods
  check-files.py: document some classes and methods
  Fix pylint errors going uncaught
  Call pylint3, not pylint
  New, documented pylint configuration

1 files changed, 28 insertions, 3 deletions

diff --git a/scripts/abi_check.py b/scripts/abi_check.py
index 8f9cd0f4..2a90b68f 100755
--- a/scripts/abi_check.py
+++ b/scripts/abi_check.py
@@ -26,8 +26,16 @@ import tempfile
 
 
 class AbiChecker(object):
+    """API and ABI checker."""
 
     def __init__(self, report_dir, old_rev, new_rev, keep_all_reports):
+        """Instantiate the API/ABI checker.
+
+        report_dir: directory for output files
+        old_rev: reference git revision to compare against
+        new_rev: git revision to check
+        keep_all_reports: if false, delete old reports
+        """
         self.repo_path = "."
         self.log = None
         self.setup_logger()
@@ -42,7 +50,8 @@ class AbiChecker(object):
         self.git_command = "git"
         self.make_command = "make"
 
-    def check_repo_path(self):
+    @staticmethod
+    def check_repo_path():
         current_dir = os.path.realpath('.')
         root_dir = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
         if current_dir != root_dir:
@@ -53,12 +62,15 @@ class AbiChecker(object):
         self.log.setLevel(logging.INFO)
         self.log.addHandler(logging.StreamHandler())
 
-    def check_abi_tools_are_installed(self):
+    @staticmethod
+    def check_abi_tools_are_installed():
         for command in ["abi-dumper", "abi-compliance-checker"]:
             if not shutil.which(command):
                 raise Exception("{} not installed, aborting".format(command))
 
     def get_clean_worktree_for_git_revision(self, git_rev):
+        """Make a separate worktree with git_rev checked out.
+        Do not modify the current worktree."""
         self.log.info(
             "Checking out git worktree for revision {}".format(git_rev)
         )
@@ -76,6 +88,7 @@ class AbiChecker(object):
         return git_worktree_path
 
     def build_shared_libraries(self, git_worktree_path):
+        """Build the shared libraries in the specified worktree."""
         my_environment = os.environ.copy()
         my_environment["CFLAGS"] = "-g -Og"
         my_environment["SHARED"] = "1"
@@ -92,6 +105,9 @@ class AbiChecker(object):
             raise Exception("make failed, aborting")
 
     def get_abi_dumps_from_shared_libraries(self, git_ref, git_worktree_path):
+        """Generate the ABI dumps for the specified git revision.
+        It must be checked out in git_worktree_path and the shared libraries
+        must have been built."""
         abi_dumps = {}
         for mbed_module in self.mbedtls_modules:
             output_path = os.path.join(
@@ -117,6 +133,7 @@ class AbiChecker(object):
         return abi_dumps
 
     def cleanup_worktree(self, git_worktree_path):
+        """Remove the specified git worktree."""
         shutil.rmtree(git_worktree_path)
         worktree_process = subprocess.Popen(
             [self.git_command, "worktree", "prune"],
@@ -130,6 +147,7 @@ class AbiChecker(object):
             raise Exception("Worktree cleanup failed, aborting")
 
     def get_abi_dump_for_ref(self, git_rev):
+        """Generate the ABI dumps for the specified git revision."""
         git_worktree_path = self.get_clean_worktree_for_git_revision(git_rev)
         self.build_shared_libraries(git_worktree_path)
         abi_dumps = self.get_abi_dumps_from_shared_libraries(
@@ -139,6 +157,9 @@ class AbiChecker(object):
         return abi_dumps
 
     def get_abi_compatibility_report(self):
+        """Generate a report of the differences between the reference ABI
+        and the new ABI. ABI dumps from self.old_rev and self.new_rev must
+        be available."""
         compatibility_report = ""
         compliance_return_code = 0
         for mbed_module in self.mbedtls_modules:
@@ -188,6 +209,8 @@ class AbiChecker(object):
         return compliance_return_code
 
     def check_for_abi_changes(self):
+        """Generate a report of ABI differences
+        between self.old_rev and self.new_rev."""
         self.check_repo_path()
         self.check_abi_tools_are_installed()
         self.old_dumps = self.get_abi_dump_for_ref(self.old_rev)
@@ -232,7 +255,9 @@ def run_main():
         )
         return_code = abi_check.check_for_abi_changes()
         sys.exit(return_code)
-    except Exception:
+    except Exception: # pylint: disable=broad-except
+        # Print the backtrace and exit explicitly so as to exit with
+        # status 2, not 1.
         traceback.print_exc()
         sys.exit(2)