Add a CI pipeline and fix static code issues (#1)

This adds a CI pipeline to run the unittests and perform some static code
analysis on the project. We also fix the issues the static code analysis
detected.

Author: s-heppner

.github/workflows/ci.yaml

@@ -0,0 +1,52 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+env:
+  X_PYTHON_MIN_VERSION: "3.11"
+
+jobs:
+  test:
+    # This job runs the unittests on the python versions specified down at the matrix
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ env.X_PYTHON_MIN_VERSION }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{env.X_PYTHON_MIN_VERSION }}
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]
+      - name: Test with coverage + unittest
+        run: |
+          coverage run --source=bibtex_linter -m unittest
+      - name: Report test coverage
+        if: ${{ always() }}
+        run: |
+          coverage report -m
+
+  static-analysis:
+    # This job runs static code analysis, namely pycodestyle and mypy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ env.X_PYTHON_MIN_VERSION }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.X_PYTHON_MIN_VERSION }}
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]
+      - name: Check typing with MyPy
+        run: |
+          mypy --strict bibtex_linter test
+      - name: Check code style with PyCodestyle
+        run: |
+          pycodestyle --count --max-line-length 120 bibtex_linter test

bibtex_linter/default_rules.py

@@ -87,7 +87,7 @@ def check_online(entry: BibTeXEntry) -> List[str]:
         "address",
         "url",
     }
-    if not "note" in entry.fields.keys():
+    if "note" not in entry.fields.keys():
         invariant_violations.append(f"Entry '{entry.name}' is of type 'online' and needs a field 'note' with the URL.")
         # Todo: In the future, we could actually check that it contains an URL
     invariant_violations.extend(check_required_fields(entry, required_fields))
@@ -145,7 +145,7 @@ def check_in_book(entry: BibTeXEntry) -> List[str]:
         "number",
         "url",
     }
-    if not "chapter" in entry.fields.keys() or not "pages" in entry.fields.keys():
+    if "chapter" not in entry.fields.keys() or "pages" not in entry.fields.keys():
         invariant_violations.append(f"Entry {entry.name} needs to contain one of the "
                                     f"following fields: [chapter, pages].")
     invariant_violations.extend(check_required_fields(entry, required_fields))

bibtex_linter/main.py

@@ -7,7 +7,7 @@
 from bibtex_linter.parser import BibTeXEntry, parse_bibtex_file
 
 
-def import_from_path(file_path: str):
+def import_from_path(file_path: str) -> None:
     """
     Import a given module using its path.
     """
@@ -17,13 +17,14 @@ def import_from_path(file_path: str):
     # It seems a bit cursed, but I guess as long as it works and really only used on known and safe `rules.py`...
     module_name: str = "ruleset"
     spec = importlib.util.spec_from_file_location(module_name, file_path)
+    if not spec or not spec.loader:
+        raise ImportError(f"Could not import ruleset from '{file_path}'.")
     module = importlib.util.module_from_spec(spec)
     sys.modules[module_name] = module
     spec.loader.exec_module(module)
-    return module
 
 
-def main():
+def main() -> None:
     parser = argparse.ArgumentParser(description="Verify a .bib file using a set of defined rules.")
     parser.add_argument("filepath", type=str, help="Path to the .bib file to verify")
     parser.add_argument("ruleset",
@@ -65,5 +66,6 @@ def main():
 
     sys.exit(1)  # Exit as failure
 
+
 if __name__ == "__main__":
     main()

bibtex_linter/parser.py

@@ -129,7 +129,6 @@ def _split_fields(entry_string: str) -> List[str]:
 
         return raw_fields
 
-
     @staticmethod
     def _parse_field_value(raw_value: str) -> str:
         """
@@ -199,9 +198,3 @@ def parse_bibtex_file(filename: str) -> List[BibTeXEntry]:
         for raw_entry_string in raw_entries:
             entries.append(BibTeXEntry.from_string(raw_entry_string))
     return entries
-
-
-if __name__ == '__main__':
-    e = parse_bibtex_file("../test/test_refs.bib")
-    for i in e:
-        print(i)

bibtex_linter/py.typed

@@ -4,21 +4,26 @@
 When using the decorators, they automatically load the method below them into the `_rules` list at time
 of import.
 """
-from typing import Callable, Tuple, List, Optional, Set
+from typing import Callable, TypeVar, List, Optional, Set
 
 from bibtex_linter.parser import BibTeXEntry, EntryType
 
 # The dynamic list of known rules.
 # This list gets updated when a method with the `@linter_rule` decorator gets imported.
-_rules: List[Callable] = []
+_rules: List[Callable[[BibTeXEntry], List[str]]] = []
 
-def linter_rule(entry_type: Optional[EntryType] = None) -> Callable:
+# For the type annotations, we define a `LINTER_RULE_TYPE` variable, which describes the type of the methods that
+# define the linter rules.
+LINTER_RULE_TYPE = TypeVar("LINTER_RULE_TYPE", bound=Callable[[BibTeXEntry], List[str]])
+
+
+def linter_rule(entry_type: Optional[EntryType] = None) -> Callable[[LINTER_RULE_TYPE], LINTER_RULE_TYPE]:
     """
     Decorator to mark a method defines rules to be checked by the linter for a specific entry type.
 
     If `entry_type` is `None`, we assume it is valid for all types.
     """
-    def wrapper(func: Callable[[BibTeXEntry], List[Tuple[bool, str]]]) -> Callable:
+    def wrapper(func: LINTER_RULE_TYPE) -> LINTER_RULE_TYPE:
         setattr(func, "_is_invariant", True)
         setattr(func, "_entry_type", entry_type)
         _rules.append(func)

bibtex_linter/verification.py

@@ -30,9 +30,10 @@ readme = "README.md"
 requires-python = ">=3.11"
 
 [project.optional-dependencies]
-testing = [
-    "pytest",
-    "pytest-cov"
+dev = [
+    "mypy",
+    "pycodestyle",
+    "coverage",
 ]
 
 [tool.pytest.ini_options]

pyproject.toml

@@ -1,8 +1,12 @@
 import unittest
+import os
+from typing import Dict, List
+
 from bibtex_linter.parser import EntryType, BibTeXEntry, split_entries, parse_bibtex_file
 
+
 class TestBibTeXEntry(unittest.TestCase):
-    def test_parse_field_value(self):
+    def test_parse_field_value(self) -> None:
         test_cases = [
             ("{John Doe}", "John Doe"),
             ("{{John Doe}}", "John Doe"),
@@ -31,7 +35,7 @@ def test_parse_field_value(self):
                 result = BibTeXEntry._parse_field_value(raw_value)
                 self.assertEqual(expected, result)
 
-    def test_split_fields_basic(self):
+    def test_split_fields_basic(self) -> None:
         entry = """@article{doe2020,
   author = {John Doe},
   title = {A Study},
@@ -45,7 +49,7 @@ def test_split_fields_basic(self):
         result = BibTeXEntry._split_fields(entry)
         self.assertEqual(expected, result)
 
-    def test_split_fields_with_trailing_comma_and_newline(self):
+    def test_split_fields_with_trailing_comma_and_newline(self) -> None:
         entry = """@book{smith2021,
   author = {Jane Smith},
   title = {The Book of Testing},
@@ -59,7 +63,7 @@ def test_split_fields_with_trailing_comma_and_newline(self):
         result = BibTeXEntry._split_fields(entry)
         self.assertEqual(expected, result)
 
-    def test_split_fields_multiline_values(self):
+    def test_split_fields_multiline_values(self) -> None:
         entry = """@misc{nested2022,
   author = {{Industrial Digital Twin Association e. V.}},
   url = {https://example.com},
@@ -74,12 +78,11 @@ def test_split_fields_multiline_values(self):
         result = BibTeXEntry._split_fields(entry)
         self.assertEqual(expected, result)
 
-    def test_split_fields_with_extra_whitespace(self):
-        entry = """@misc{id123,  
-    author    =    {Someone}  , 
-    title=   {  Extra Spaces   }   , 
-    year= {2023}    
-}"""
+    def test_split_fields_with_extra_whitespace(self) -> None:
+        entry = ("@misc{id123,  \n    "
+                 "author    =    {Someone}  , \n    "
+                 "title=   {  Extra Spaces   }   , \n    "
+                 "year= {2023}    }")
         expected = [
             "    author    =    {Someone}  ",
             "    title=   {  Extra Spaces   }   ",
@@ -88,7 +91,7 @@ def test_split_fields_with_extra_whitespace(self):
         result = BibTeXEntry._split_fields(entry)
         self.assertEqual(expected, result)
 
-    def test_split_fields_with_linebreak_after_entry_type(self):
+    def test_split_fields_with_linebreak_after_entry_type(self) -> None:
         entry = """@misc
 {
 id456,
@@ -102,14 +105,14 @@ def test_split_fields_with_linebreak_after_entry_type(self):
         result = BibTeXEntry._split_fields(entry)
         self.assertEqual(expected, result)
 
-    def test_split_fields_missing_open_brace(self):
+    def test_split_fields_missing_open_brace(self) -> None:
         entry = "article, author = {John Doe}, title = {Oops}"
         with self.assertRaises(KeyError):
             BibTeXEntry._split_fields(entry)
 
 
 class TestSplitEntries(unittest.TestCase):
-    def test_single_entry(self):
+    def test_single_entry(self) -> None:
         raw = """@article{key1,
   author = {John Doe},
   title = {Example},
@@ -119,7 +122,7 @@ def test_single_entry(self):
         self.assertEqual(1, len(entries))
         self.assertIn("key1", entries[0])
 
-    def test_multiple_entries(self):
+    def test_multiple_entries(self) -> None:
         raw = """@article{key1,
   author = {John Doe},
   title = {Example 1},
@@ -136,15 +139,15 @@ def test_multiple_entries(self):
         self.assertIn("key1", entries[0])
         self.assertIn("key2", entries[1])
 
-    def test_entry_with_nested_braces(self):
+    def test_entry_with_nested_braces(self) -> None:
         raw = """@misc{key3,
   note = {Something with {nested} braces}
 }"""
         entries = split_entries(raw)
         self.assertEqual(1, len(entries))
         self.assertIn("nested", entries[0])
 
-    def test_entry_with_line_breaks(self):
+    def test_entry_with_line_breaks(self) -> None:
         raw = """@online{key4,
   author = {Someone},
   title = {Line
@@ -155,7 +158,7 @@ def test_entry_with_line_breaks(self):
         self.assertEqual(1, len(entries))
         self.assertIn("Line\nBreak", entries[0])
 
-    def test_incomplete_entry(self):
+    def test_incomplete_entry(self) -> None:
         raw = """@article{key5,
   title = {Missing closing brace}
 """
@@ -164,8 +167,9 @@ def test_incomplete_entry(self):
 
 
 class TestParseBibtexFile(unittest.TestCase):
-    def test_parse_all_entries(self):
-        entries = parse_bibtex_file("./test_refs.bib")
+    def test_parse_all_entries(self) -> None:
+        bib_path = os.path.join(os.path.dirname(__file__), "test_refs.bib")
+        entries = parse_bibtex_file(bib_path)
         self.assertEqual(17, len(entries))
 
         expected_types = {
@@ -185,8 +189,8 @@ def test_parse_all_entries(self):
                 actual_count = sum(1 for e in entries if e.entry_type == entry_type)
                 self.assertEqual(expected_count, actual_count)
 
-    def test_entry_fields_and_values(self):
-        expected_entries = [
+    def test_entry_fields_and_values(self) -> None:
+        expected_entries: List[Dict[str, EntryType | Dict[str, str]]] = [
             {
                 "type": EntryType.ARTICLE,
                 "fields": {
@@ -309,12 +313,16 @@ def test_entry_fields_and_values(self):
             },
         ]
 
-        parsed_entries = parse_bibtex_file("./test_refs.bib")
+        bib_path = os.path.join(os.path.dirname(__file__), "test_refs.bib")
+        parsed_entries = parse_bibtex_file(bib_path)
 
         for expected in expected_entries:
             with self.subTest(expected=expected["fields"]):
+                # (2025-04-24, s-heppner)
+                # We can safely ignore the mypy warning here, since we wrote the `expected_entries` this way just above.
+                expected_fields: Dict[str, str] = expected["fields"]  # type: ignore
                 match = next(
-                    (e for e in parsed_entries if all(e.fields.get(k) == v for k, v in expected["fields"].items())),
+                    (e for e in parsed_entries if all(e.fields.get(k) == v for k, v in expected_fields.items())),
                     None
                 )
                 all_field_sets = [e.fields for e in parsed_entries]
@@ -323,7 +331,10 @@ def test_entry_fields_and_values(self):
                     f"Missing or incorrect entry for:\nExpected Fields: {expected['fields']}\n"
                     f"Parsed Entries:\n{all_field_sets}"
                 )
-                self.assertEqual(expected["type"], match.entry_type)
+                # (2025-04-24, s-heppner)
+                # We can safely ignore the mypy warning here, since we already asserted that `match` is not `None` in
+                # the line above.
+                self.assertEqual(expected["type"], match.entry_type)  # type: ignore
 
 
 if __name__ == "__main__":