[IMPROVEMENT] Add new docstrings (#527)

Author: dukkee

.pydocstylerc

@@ -1,4 +1,5 @@
 [pydocstyle]
 convention = numpy
-match_dir = mod_.*|.
+add-ignore=D100
+match_dir = ^(?!(venv|.venv|migrations|static|logs|install)).*
 

mod_test/nicediff/__init__.py

@@ -0,0 +1 @@
+"""Maintains logic for diffs."""

mod_test/nicediff/diff.py

@@ -9,17 +9,18 @@
 
 
 def zip_(ls: List[str]) -> str:
+    """Add an alias for strings joining."""
     return ''.join(ls)
 
 
-# compress words and digits to one list
 def compress(s: str) -> List[str]:
+    """Compress words and digits to one list."""
     return re.split(r'(\W)', s)
 
 
-# equality factor
 def eq(a: List[str], b: List[str], same_regions: Optional[List[List[int]]] = None,
        delta_a: int = 0, delta_b: int = 0) -> Union[List[int], List[Union[int, List[str]]]]:
+    """Implement equality factor."""
     if index.get(zip_(a), dict()).get(zip_(b), None) is None:
         e = 0
         rez = []    # type: Union[int, Any, List[str]]
@@ -74,8 +75,8 @@ def eq(a: List[str], b: List[str], same_regions: Optional[List[List[int]]] = Non
     return index[zip_(a)][zip_(b)]
 
 
-# processing one line
 def _process(test_result: str, correct: str, suffix_id: str) -> Tuple[str, str]:
+    """Process one line."""
     test_result = html.escape(test_result)
     correct = html.escape(correct)
     tr_compr = compress(test_result)
@@ -104,9 +105,7 @@ def _process(test_result: str, correct: str, suffix_id: str) -> Tuple[str, str]:
 
 
 def create_diff_entries(suffix_id: str, id_name: str, events: List[List[object]], compressed_data: List[str]) -> str:
-    """
-    Create the diff entries for the correct or wrong side.
-    """
+    """Create the diff entries for the correct or wrong side."""
     result = ''
     idx = 0
     for event in events:
@@ -122,9 +121,8 @@ def create_diff_entries(suffix_id: str, id_name: str, events: List[List[object]]
     return result
 
 
-# return generated difference in HTML formatted table
 def get_html_diff(test_correct_lines: List[str], test_res_lines: List[str], to_view: bool = True) -> str:
-
+    """Return generated difference in HTML formatted table."""
     # variable to keep count of diff lines noted
     number_of_noted_diff_lines = 0
 

tests/TestConfigParser.py

@@ -1,3 +1,5 @@
+"""Contains tests related to the config handling."""
+
 import json
 from unittest import mock
 
@@ -6,7 +8,10 @@
 
 
 class TestConfigParser(BaseTestCase):
+    """Test config parsing."""
+
     def test_parse_config(self):
+        """Test parse_config function."""
         file_config = "TEST = 'run'"
         expected_config = {'TEST': 'run'}
 

tests/TestLogConfiguration.py

@@ -9,7 +9,10 @@
 
 
 class TestLogConfiguration(unittest.TestCase):
+    """Test log setup."""
+
     def _test_init_with_log_value(self, debug, result_level):
+        """Test logger initialization with specific debug and level."""
         joined_path = 'baz'
         folder = 'foo'
         filename = 'bar'
@@ -48,12 +51,15 @@ def _test_init_with_log_value(self, debug, result_level):
                         return log_config
 
     def test_init_correctly_initializes_the_instance_when_debug(self):
+        """Test log initialization with debug mode and level."""
         self._test_init_with_log_value(True, logging.DEBUG)
 
     def test_init_correctly_initializes_the_instance_when_no_debug(self):
+        """Test log initialization with info level."""
         self._test_init_with_log_value(False, logging.INFO)
 
     def test_create_logger(self):
+        """Test logger creation."""
         with mock.patch.object(LogConfiguration, '__init__',
                                return_value=None):
             with mock.patch('logging.getLogger') as mock_get:

tests/TestMailer.py

@@ -5,7 +5,10 @@
 
 
 class TestMailer(unittest.TestCase):
+    """Test Mailer features."""
+
     def test_that_init_works_correctly(self):
+        """Test Mailer initialization."""
         domain = 'domain'
         api_key = 'APIKEY'
         sender_name = 'foo'
@@ -20,6 +23,7 @@ def test_that_init_works_correctly(self):
         self.assertEqual(actual.sender, sender)
 
     def test_that_send_simple_message_creates_the_appropriate_request(self):
+        """Test simple message sending."""
         domain = 'domain'
         api_key = 'APIKEY'
         sender_name = 'foo'

tests/TestRun.py

@@ -6,15 +6,18 @@
 
 
 class mock_application:
+    """Mock object for application."""
 
     def __init__(self):
         self.config = {}
         self.root_path = ''
 
 
 class TestRun(BaseTestCase):
+    """Test application running."""
 
     def test_load_secret_keys_files_present(self):
+        """Test csrf session and secret keys loading when they are presented."""
         secrets = tempfile.NamedTemporaryFile()
         csrf = tempfile.NamedTemporaryFile()
         application = mock_application()
@@ -35,6 +38,7 @@ def test_load_secret_keys_files_present(self):
         self.assertEqual(application.config['CSRF_SESSION_KEY'], b'csrf', 'csrf session key not loaded properly')
 
     def test_load_secret_keys_secrets_not_present(self):
+        """Test csrf session and secret keys loading when csrf session key is not presented."""
         secrets = tempfile.NamedTemporaryFile()
         csrf = "notAvailable"
         application = mock_application()
@@ -53,6 +57,7 @@ def test_load_secret_keys_secrets_not_present(self):
         self.assertEquals(cmd.exception.code, 1, 'function exited with a wrong code')
 
     def test_load_secret_keys_csrf_not_present(self):
+        """Test csrf session and secret keys loading when secret key is not presented."""
         secrets = "notAvailable"
         csrf = tempfile.NamedTemporaryFile()
         application = mock_application()

tests/TestUtility.py

@@ -1,15 +1,16 @@
+"""Contains tests related to the utility helpers."""
+
 from unittest import mock
 
 from tests.base import BaseTestCase
 
 
 class TestUtility(BaseTestCase):
+    """Test utility helpers."""
 
     @mock.patch('utility.path')
     def test_serve_file_download(self, mock_path):
-        """
-        Test function serve_file_download.
-        """
+        """Test function serve_file_download."""
         from utility import serve_file_download
 
         response = serve_file_download('to_download', 'folder', 'accl_folder')

tests/__init__.py

@@ -0,0 +1 @@
+"""Contains all project tests."""

tests/base.py

@@ -1,3 +1,5 @@
+"""Contains base test case with needed setup and helpers."""
+
 import os
 from collections import namedtuple
 from contextlib import contextmanager
@@ -22,9 +24,7 @@
 
 @contextmanager
 def provide_file_at_root(file_name, to_write=None):
-    """
-    Provide file with name file_name at application root.
-    """
+    """Provide file with name file_name at application root."""
     if to_write is None:
         to_write = "DATABASE_URI = 'sqlite:///:memory:'"
 
@@ -48,9 +48,7 @@ def load_file_lines(filepath):
 
 
 def mock_decorator(f):
-    """
-    Mock login_required decorator.
-    """
+    """Mock login_required decorator."""
     @wraps(f)
     def decorated_function(*args, **kwargs):
         return f(*args, **kwargs)
@@ -59,6 +57,7 @@ def decorated_function(*args, **kwargs):
 
 
 def generate_keys():
+    """Generate CSRF session and secret keys."""
     from utility import ROOT_DIR
     secret_csrf_path = f"{os.path.join(ROOT_DIR, '')}secret_csrf"
     secret_key_path = f"{os.path.join(ROOT_DIR, '')}secret_key"
@@ -73,6 +72,7 @@ def generate_keys():
 
 
 def load_config(file):
+    """Load start config."""
     key_paths = generate_keys()
     with open(key_paths['secret_key_path'], 'rb') as secret_key_file:
         secret_key = secret_key_file.read()
@@ -102,6 +102,7 @@ def load_config(file):
 
 
 def mock_api_request_github(url, data=None, timeout=None):
+    """Mock all responses to the Github API."""
     if url == "https://api.github.com/repos/test/test_repo/commits/abcdef":
         return MockResponse({}, 200)
     elif url == "https://api.github.com/user":
@@ -139,7 +140,7 @@ def mock_api_request_github(url, data=None, timeout=None):
 
 def generate_signature(data, private_key):
     """
-    Generate signature token of hook request
+    Generate signature token of hook request.
 
     :param data: Signature's data
     :param private_key: Signature's token
@@ -171,19 +172,19 @@ def generate_git_api_header(event, sig):
 
 
 class BaseTestCase(TestCase):
+    """Base setup for all test cases."""
+
     @mock.patch('config_parser.parse_config', side_effect=load_config)
     def create_app(self, mock_config):
-        """
-        Create an instance of the app with the testing configuration
-        :return:
-        """
+        """Create an instance of the app with the testing configuration."""
         user = namedtuple('user', "name password email github_token")
         self.user = user(name="test", password="test123",
                          email="[email protected]", github_token="abcdefgh")
         from run import app
         return app
 
     def setUp(self):
+        """Set up all entities."""
         self.app.preprocess_request()
         g.db = create_session(
             self.app.config['DATABASE_URI'], drop_tables=True)
@@ -304,13 +305,15 @@ def setUp(self):
     @staticmethod
     def create_login_form_data(email, password) -> dict:
         """
-        Creates the form data for a login event.
+        Create the form data for a login event.
+
         :return: A dictionary containing the name, password and submit fields.
         """
         return {'email': email, 'password': password, 'submit': True}
 
     @staticmethod
     def create_customize_form(commit_hash, platform, commit_select=None, regression_test=None):
+        """Create the request form part."""
         if regression_test is None:
             regression_test = [1, 2]
         if commit_select is None:
@@ -324,9 +327,7 @@ def create_customize_form(commit_hash, platform, commit_select=None, regression_
         }
 
     def create_forktest(self, commit_hash, platform, regression_tests=None):
-        """
-        Create a test on fork based on commit and platform
-        """
+        """Create a test on fork based on commit and platform."""
         from flask import g
         fork_url = f"https://github.com/{self.user.name}/{g.github['repository']}.git"
         fork = Fork(fork_url)
@@ -346,9 +347,7 @@ def create_forktest(self, commit_hash, platform, regression_tests=None):
                 g.db.commit()
 
     def create_user_with_role(self, user, email, password, role, github_token=None):
-        """
-        Create a user with specified user details and role.
-        """
+        """Create a user with specified user details and role."""
         from flask import g
         user = User(self.user.name, email=self.user.email,
                     password=User.generate_hash(self.user.password), role=role, github_token=github_token)
@@ -357,16 +356,20 @@ def create_user_with_role(self, user, email, password, role, github_token=None):
 
     @staticmethod
     def create_random_string(length=32):
+        """Generate random string of ASCII symbols."""
         import random
         import string
         random_string = ''.join([random.choice(string.ascii_letters + string.digits) for n in range(length)])
         return random_string
 
 
 class MockResponse:
+    """A class to mock HTTP response."""
+
     def __init__(self, json_data, status_code):
         self.json_data = json_data
         self.status_code = status_code
 
     def json(self):
+        """Mock response json method."""
         return self.json_data