Updated Test Suite to Include Documentation and More! (#52)

* Added article link

* Automated the saving of the plot

* Added list emptying visualization

* Reorganized file to include main

* Added doc strings

* Created a function which executes all tests

* Executed minor code cleanup

Author: jrg94

testing/__init__.py

@@ -0,0 +1,6 @@
+import glob
+from os.path import dirname, basename, isfile, join
+
+modules = glob.glob(join(dirname(__file__), "*.py"))
+__all__ = [basename(f)[:-3] for f in modules if
+           isfile(f) and not f.endswith('__init__.py') and not f.endswith("test_bench.py")]

testing/how_to_capitalize_a_string.py

@@ -1,42 +1,97 @@
+"""
+Tests the performance of all of the solutions listed in the following article:
+https://therenegadecoder.com/code/how-to-capitalize-a-string-in-python/
+"""
+
 from test_bench import test_bench
 
-def control(string):
+
+def control(_) -> None:
+    """
+    Provides a control scenario for testing. In this case, none of the functions
+    share any overhead, so this function is empty.
+
+    :param _: a placeholder for the string input
+    :return: None
+    """
     pass
 
-def capitalize_by_hand(string):
+
+def capitalize_by_hand(string: str) -> str:
+    """
+    Capitalizes a string by performing a code point shift
+    for the first character.
+
+    :param string: an input string
+    :return: the capitalized string
+    """
     character = string[0]
     if 97 <= ord(character) <= 122:
-        shift = ord(character) - 32 
+        shift = ord(character) - 32
         uppercase = chr(shift)
         return uppercase + string[1:]
     return string
-    
-def capitalize_by_mapping(string):
+
+
+def capitalize_by_mapping(string: str) -> str:
+    """
+    Capitalizes a string by mapping between a set of lowercase
+    characters and a set of uppercase characters.
+
+    :param string: an input string
+    :return: the capitalized string
+    """
     lowercase = "abcdefghijklmnopqrstuvwxyz"
     uppercase = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
     character = string[0]
     i = lowercase.find(character)
     return string if i == -1 else uppercase[i] + string[1:]
 
-def capitalize_with_upper(string):
+
+def capitalize_with_upper(string: str) -> str:
+    """
+    Capitalizes a string by leveraging the upper() method of
+    strings on the first character.
+
+    :param string: an input string
+    :return: the capitalized string
+    """
     character = string[0]
     return character.upper() + string[1:]
 
-def capitalize(string):
+
+def capitalize(string: str) -> str:
+    """
+    Capitalizes a string by leveraging the capitalize() method.
+    The behavior of this function differs from he previous
+    functions because the capitalize() method also converts all
+    other characters int he string to lowercase.
+
+    :param string: an input string
+    :return: the capitalized string
+    """
     return string.capitalize()
 
 
-test_bench(
-    [
-        control,
-        capitalize_by_hand,
-        capitalize_by_mapping,
-        capitalize_with_upper,
-        capitalize
-    ],
-    {
-        "One Letter String": ["a"],
-        "Small String": ["how now brown cow"],
-        "Large String": ["One Punch Man" * 100]
-    }
-)
+def main() -> None:
+    """
+    Tests the performance of all the functions defined in this file.
+    """
+    test_bench(
+        [
+            control,
+            capitalize_by_hand,
+            capitalize_by_mapping,
+            capitalize_with_upper,
+            capitalize
+        ],
+        {
+            "One Letter String": ["a"],
+            "Small String": ["how now brown cow"],
+            "Large String": ["One Punch Man" * 100]
+        }
+    )
+
+
+if __name__ == '__main__':
+    main()

testing/test_bench.py

@@ -1,7 +1,25 @@
+import importlib
+import inspect
+import os
 import timeit
-import seaborn as sns
-import pandas as pd
+
 import matplotlib.pyplot as plt
+import pandas as pd
+import seaborn as sns
+
+import testing
+
+
+def run_suite() -> None:
+    """
+    An experimental function which allows us to run the main function of
+    all of our test files.
+
+    :return: None
+    """
+    for module_name in testing.__all__:
+        module = importlib.import_module(module_name)
+        module.main()
 
 
 def test_bench(funcs: list, test_data: dict):
@@ -70,4 +88,9 @@ def _show_results(results: pd.DataFrame):
     plt.title("How to Python: Function Performance Comparison", fontsize=16)
     plt.legend(bbox_to_anchor=(1.05, 1), loc=2, title="Functions", fontsize='12', title_fontsize='12')
     plt.tight_layout()
-    plt.show()
+    filename = os.path.splitext(os.path.basename(inspect.stack()[2].filename))[0]
+    plt.savefig(f"{os.path.join('visualizations', filename)}.png")
+
+
+if __name__ == '__main__':
+    run_suite()