refactor: edit doc strings, names used, type hints

For easier maintenance, the internal documentation was revised.

Signed-off-by: Norwid Behrnd <nbehrnd@yahoo.com>

Author: nbehrnd

.github/workflows/build_wheel.yml

@@ -2,8 +2,8 @@ name: CI_wheel_datawarrior_clustersort
 
 # name:    build_wheel.yml
 # purpose: build a .whl as an artifact without a secret/GitHub token
-# date:    [2025-07-31 Thus]
-# edit:
+# date:    [2025-07-31 Thu]
+# edit:    [2025-08-01 Fri]
 
 on:
   workflow_dispatch:  # launch only by the manual trigger
@@ -33,10 +33,10 @@ jobs:
         pip install build
         python -m build
 
-    - name: delivery within an archive `pubchem_wheel.zip`
+    - name: package archive `datawarrior_clustersort_wheel.zip`
       uses: actions/upload-artifact@v4
       with:
-        name: datawarrior_saturate_Murcko_scaffolds_wheel
+        name: datawarrior_clustersort_wheel
         path: |
           dist/*.whl
           dist/*.tar.gz

Makefile

@@ -1,7 +1,7 @@
 # Local analysis by pytest, coverage run pytest, flake8, and badge generation.
 #
 # This Makefile presumes an activated virtual environment of Python and an
-# internet connection for pytest's checks on pubchempy's interaction with NIH.
+# internet connection to resolve the dependencies (rule `analysis_setup`).
 # In contast to e.g., the coverage badge by coveralls, the setup here does not
 # rely on a separate account, nor a GitHub token to work.  By flag `-l`, the
 # badges are created locally, independent of genbadge's default to reach out
@@ -11,7 +11,6 @@ default:
 	@echo "Tap the tabulator key twice to display the options available."
 
 analysis_setup:
-# For now, the partial overlap with `requirements/dev.txt` is intentional.
 	pip install coverage flake8 genbadge[all] pyclean pytest
 
 coverage_analysis:

coverage-badge.svg

@@ -6,7 +6,7 @@
 # author:  nbehrnd@yahoo.com
 # license: GPL v2, 2022, 2023
 # date:    [2022-04-22 Fri]
-# edit:    [2025-07-31 Thu]
+# edit:    [2025-08-01 Fri]
 """Provide a sort on DataWarrior clusters by popularity of the cluster.
 
 DataWarrior can recognize structure similarity in a set of molecules.  The
@@ -269,5 +269,5 @@ def main(arg_list=None) -> None:
     read_dw_list(report_list, old_cluster_label)
 
 
-if __name__ == "__main__":
+if __name__ == "__main__":  # pragma: no cover
     main()

src/datawarrior_clustersort/datawarrior_clustersort.py

@@ -6,7 +6,7 @@
 # author:  nbehrnd@yahoo.com
 # license: GPL v2, 2025
 # date:    [2025-03-19 Wed]
-# edit:    [2025-07-31 Thu]
+# edit:    [2025-08-01 Fri]
 
 """External pytest checks by pytest on datawarrior_clustersort.py.
 
@@ -29,17 +29,14 @@
 REFERENCE_REVERSE_SORT = "tests/100Random_Molecules_rev_sort_ref.txt"
 
 
-def test_script_exists():
-    """check for the script's presence"""
+def test_script_exists() -> None:
+    """Check for the script's presence."""
     assert os.path.isfile(PRG), f"script {PRG} was not found"
 
 
-# section of black-box tests (the inner working doesn't matter):
-
-
 @pytest.mark.blackbox
-def test_get_test_data():
-    """get a copy of the test's input data"""
+def test_get_test_data() -> None:
+    """Check copy/paste of test input data to the script."""
     source = os.path.join("tests", INPUT_FILE)
     target = os.path.join(os.getcwd(), INPUT_FILE)
 
@@ -54,10 +51,16 @@ def test_get_test_data():
     except OSError as e:
         print(f"failed to copy '{INPUT_FILE}' for the test; {e}")
 
+    assert os.path.isfile(INPUT_FILE)
+
 
 @pytest.mark.blackbox
-def test_default_sort():
-    """check the results of the normal sort"""
+def test_default_sort() -> None:
+    """Check the results of the normal sort.
+
+    By this logic, label `1` is assigned to the cluster containing the
+    most structures.  Any cluster label higher than `1` is about a subsequent
+    cluster with equal or less structures."""
     if os.path.exists(OUTPUT_FILE):
         try:
             os.remove(OUTPUT_FILE)
@@ -77,8 +80,12 @@ def test_default_sort():
 
 
 @pytest.mark.blackbox
-def test_reverse_sort():
-    """check the results of the normal sort"""
+def test_reverse_sort() -> None:
+    """Check the results of the reversed sort.
+
+    By this logic, label `1` is for the cluster with the lowest number of
+    structures.  The higher the label (`2`, `3`, etc.), either the same, or
+    a higher number of structures are in this particular cluster."""
     if os.path.exists(OUTPUT_FILE):
         try:
             os.remove(OUTPUT_FILE)
@@ -98,8 +105,8 @@ def test_reverse_sort():
 
 
 @pytest.mark.blackbox
-def test_space_cleaning():
-    """remove copy of the input file"""
+def test_space_cleaning() -> None:
+    """Check the removal of the local copy of the input file."""
     if os.path.exists(INPUT_FILE):
         try:
             os.remove(INPUT_FILE)

tests/test_blackbox.py

@@ -6,7 +6,7 @@
 # author:  nbehrnd@yahoo.com
 # license: GPL v2, 2025
 # date:    [2025-03-19 Wed]
-# edit:    [2025-04-17 Thu]
+# edit:    [2025-08-01 Fri]
 
 """pytest script of datawarrior_clustersort.py
 
@@ -29,7 +29,8 @@
 
 
 @pytest.mark.imported
-def test_file_reader():
+def test_file_reader() -> None:
+    """Check recognizing headline, table body, DW's lowest cluster label."""
     probe_data = r"""Structure [idcode]	Cluster No	Is Representative	record_number
 edR\FD@KFncOLbji`HbHHrJIJYKJYSQRJiSIQITLRJ@pp@@DtuKMMP@@PARBj@	1	No	1
 elRRF@@DLCH`FMLfilbbRbrTVtTTRbtqbRRJzAQZijfhHbbZBA@@@@	2	No	2
@@ -50,16 +51,21 @@ def test_file_reader():
 
 
 @pytest.mark.imported
-def test_identify_cluster_column():
-    """identification of the cluster column"""
+def test_identify_cluster_column() -> None:
+    """Check identification of the cluster column."""
     input_string = "Structure [idcode]	Cluster No	Is Representative	record_number"
     expected_column = 1
     test_column = identify_cluster_column(input_string)
     assert test_column == expected_column, "wrong column index"
 
 
 @pytest.mark.imported
-def test_read_dw_list():
+def test_read_dw_list() -> None:
+    """Perform a frequency analysis on DW assigned cluster labels.
+
+    This checks if DW assigned cluster labels are used to build a
+    dictionary where DW labels indicate (as key) to the number of
+    times they are assigned by DW (as value)."""
     # some records of DW cluster 1, 5, and 8 of `100Random_Molecules.txt`
     mock_table_body = [
         r"fko`H@D@yHsQ{OdTRbbbtRLLRTvRfoEjuTuUTAAUSPSBiAKL@@	1	No	6",
@@ -83,7 +89,11 @@ def test_read_dw_list():
 
 
 @pytest.mark.imported
-def test_label_sorter_default_sort():
+def test_label_sorter_default_sort() -> None:
+    """Check the normal sort of a new frequency dictionary.
+
+    By default, the lowest key (label) describes the cluster with the
+    most structures (value)."""
     mock_dictionary = {"1": 4, "5": 3, "8": 2}
     reversed_order = False
     expected_dictionary = {"1": 1, "5": 2, "8": 3}
@@ -92,7 +102,11 @@ def test_label_sorter_default_sort():
 
 
 @pytest.mark.imported
-def test_label_sorter_reverse_sort():
+def test_label_sorter_reverse_sort() -> None:
+    """Check the reverse sort of a new frequency dictionary.
+
+    By default, the lowest key (label) describes the cluster with the
+    least number of structures (value)."""
     mock_dictionary = {"1": 4, "5": 3, "8": 2}
     reversed_order = True
     expected_dictionary = {"1": 3, "5": 2, "8": 1}
@@ -101,7 +115,8 @@ def test_label_sorter_reverse_sort():
 
 
 @pytest.mark.imported
-def test_update_cluster_labels():
+def test_update_cluster_labels() -> None:
+    """Check the reassignment of cluster labels."""
     # some of DW clusters 1, 5, and 8
     mock_table_body = [
         r"fko`H@D@yHsQ{OdTRbbbtRLLRTvRfoEjuTuUTAAUSPSBiAKL@@	1	No	6",
@@ -134,7 +149,8 @@ def test_update_cluster_labels():
 
 
 @pytest.mark.imported
-def test_permanent_report(tmp_path):
+def test_permanent_report(tmp_path) -> None:
+    """Probe the generation of a permanent record."""
     # prepare data to write
     input_file = "test_input.txt"
     headline = "Structure [idcode]	Cluster No	Is Representative	record_number"