From aaee444c68e5545ed2522cc330100ecbcef3eca7 Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Tue, 24 Mar 2020 16:49:21 +0100
Subject: [PATCH] Document more methods in Python scripts
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
---
tests/scripts/check-files.py | 19 +++++++++++++++++++
tests/scripts/check-test-cases.py | 2 ++
2 files changed, 21 insertions(+)
diff --git a/tests/scripts/check-files.py b/tests/scripts/check-files.py
index 6e35f5224..16aebb59a 100755
--- a/tests/scripts/check-files.py
+++ b/tests/scripts/check-files.py
@@ -37,20 +37,31 @@ class FileIssueTracker(object):
self.files_with_issues = {}
def should_check_file(self, filepath):
+ """Whether the given file name should be checked.
+
+ Files whose name ends with a string listed in ``self.files_exemptions``
+ will not be checked.
+ """
for files_exemption in self.files_exemptions:
if filepath.endswith(files_exemption):
return False
return True
def check_file_for_issue(self, filepath):
+ """Check the specified file for the issue that this class is for.
+
+ Subclasses must implement this method.
+ """
raise NotImplementedError
def record_issue(self, filepath, line_number):
+ """Record that an issue was found at the specified location."""
if filepath not in self.files_with_issues.keys():
self.files_with_issues[filepath] = []
self.files_with_issues[filepath].append(line_number)
def output_file_issues(self, logger):
+ """Log all the locations where the issue was found."""
if self.files_with_issues.values():
logger.info(self.heading)
for filename, lines in sorted(self.files_with_issues.items()):
@@ -70,6 +81,10 @@ class LineIssueTracker(FileIssueTracker):
"""
def issue_with_line(self, line, filepath):
+ """Check the specified line for the issue that this class is for.
+
+ Subclasses must implement this method.
+ """
raise NotImplementedError
def check_file_line(self, filepath, line, line_number):
@@ -77,6 +92,10 @@ class LineIssueTracker(FileIssueTracker):
self.record_issue(filepath, line_number)
def check_file_for_issue(self, filepath):
+ """Check the lines of the specified file.
+
+ Subclasses must implement the ``issue_with_line`` method.
+ """
with open(filepath, "rb") as f:
for i, line in enumerate(iter(f.readline, b"")):
self.check_file_line(filepath, line, i + 1)
diff --git a/tests/scripts/check-test-cases.py b/tests/scripts/check-test-cases.py
index 4abaa6882..35a998749 100755
--- a/tests/scripts/check-test-cases.py
+++ b/tests/scripts/check-test-cases.py
@@ -77,6 +77,7 @@ def check_description(results, seen, file_name, line_number, description):
seen[description] = line_number
def check_test_suite(results, data_file_name):
+ """Check the test cases in the given unit test data file."""
in_paragraph = False
descriptions = {}
with open(data_file_name, 'rb') as data_file:
@@ -94,6 +95,7 @@ def check_test_suite(results, data_file_name):
in_paragraph = True
def check_ssl_opt_sh(results, file_name):
+ """Check the test cases in ssl-opt.sh or a file with a similar format."""
descriptions = {}
with open(file_name, 'rb') as file_contents:
for line_number, line in enumerate(file_contents, 1):