refactor: address code review findings

decorator_processor.py:
- Add FormattedEntry, RequirementAnnotations, FormattedData TypedDicts for
  format_results return type (replaces bare dict)
- Add str | os.PathLike to all path/file parameters for consistency
- Tighten format_results body to use typed local variables

test_processors.py:
- Standardise all tests on tmp_path (drop legacy tmpdir fixture)
- Remove stray inline `import os` from test body; use pathlib Path.exists()
- Remove unused tmpdir parameter from test_format_results_implementations

Author: jimisola

src/reqstool_python_decorators/processors/decorator_processor.py

@@ -32,6 +32,20 @@ class ElementResult(TypedDict):
     decorators: ReadOnly[list[DecoratorInfo]]
 
 
+class FormattedEntry(TypedDict):
+    elementKind: str
+    fullyQualifiedName: str
+
+
+class RequirementAnnotations(TypedDict):
+    implementations: dict[str, list[FormattedEntry]]
+    tests: dict[str, list[FormattedEntry]]
+
+
+class FormattedData(TypedDict):
+    requirement_annotations: RequirementAnnotations
+
+
 type Results = list[ElementResult]
 
 
@@ -65,12 +79,12 @@ def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self.req_svc_results: Results = []
 
-    def find_python_files(self, directory) -> list[str]:
+    def find_python_files(self, directory: str | os.PathLike) -> list[str]:
         """
         Find Python files in the given directory.
 
         Parameters:
-        - `directory` (str): The directory to search for Python files.
+        - `directory` (str | PathLike): The directory to search for Python files.
 
         Returns:
         - `python_files` (list): List of Python files found in the directory.
@@ -82,17 +96,16 @@ def find_python_files(self, directory) -> list[str]:
                     python_files.append(os.path.join(root, file))
         return python_files
 
-    def get_functions_and_classes(self, file_path, decorator_names) -> None:
+    def get_functions_and_classes(
+        self, file_path: str | os.PathLike, decorator_names: list[str]
+    ) -> None:
         """
         Get information about functions and classes, if annotated with "Requirements" or "SVCs":
         decorator filepath, elementKind, name and decorators is saved to list that is returned.
 
         Parameters:
-        - `file_path` (str): The path to the Python file.
-        - `decorator_names` (list): List of decorator names to search for.
-
-        Returns:
-        - `results` (list): List of dictionaries containing information about functions and classes.
+        - `file_path` (str | PathLike): The path to the Python file.
+        - `decorator_names` (list[str]): List of decorator names to search for.
 
         Each dictionary includes:
             - `fullyQualifiedName` (str): The fully qualified name of the file.
@@ -101,7 +114,7 @@ def get_functions_and_classes(self, file_path, decorator_names) -> None:
             - `decorators` (list): List of dictionaries with decorator info including name and arguments e.g. "REQ_001".
         """
         with open(file_path, "r") as file:
-            tree = ast.parse(file.read(), filename=file_path)
+            tree = ast.parse(file.read(), filename=str(file_path))
 
         for node in ast.walk(tree):
             if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
@@ -122,12 +135,12 @@ def get_functions_and_classes(self, file_path, decorator_names) -> None:
                         }
                     )
 
-    def write_to_yaml(self, output_file, formatted_data) -> None:
+    def write_to_yaml(self, output_file: str | os.PathLike, formatted_data) -> None:
         """
         Write formatted data to a YAML file.
 
         Parameters:
-        - `output_file` (str): The path to the output YAML file.
+        - `output_file` (str | PathLike): The path to the output YAML file.
         - `formatted_data` (dict): The formatted data to be written to the YAML file.
 
         Writes the formatted data to the specified YAML file.
@@ -151,25 +164,25 @@ def map_type(self, input_str) -> str:
         mapping = {item.from_value: item.to_value for item in DECORATOR_TYPES}
         return mapping.get(input_str, input_str)
 
-    def format_results(self, results: Results) -> dict:
+    def format_results(self, results: Results) -> FormattedData:
         """
         Format the collected results into a structured data format for YAML.
 
         Parameters:
         - `results` (list): List of dictionaries containing information about functions and classes.
 
         Returns:
-        - `formatted_data` (dict): Formatted data in a structured `yaml_language_server` compatible format.
+        - `formatted_data` (FormattedData): Formatted data in a structured `yaml_language_server` compatible format.
 
         This function formats a list of decorated data into the structure required by the `yaml_language_server`.
         It includes version information, requirement annotations, and relevant element information.
         """
 
-        formatted_data = {}
-        implementations = {}
-        tests = {}
-        requirement_annotations = {"implementations": implementations, "tests": tests}
-        formatted_data["requirement_annotations"] = requirement_annotations
+        implementations: dict[str, list[FormattedEntry]] = {}
+        tests: dict[str, list[FormattedEntry]] = {}
+        formatted_data: FormattedData = {
+            "requirement_annotations": {"implementations": implementations, "tests": tests}
+        }
 
         for result in results:
             for decorator_info in result["decorators"]:
@@ -190,26 +203,28 @@ def format_results(self, results: Results) -> dict:
 
         return formatted_data
 
-    def create_dir_from_path(self, filepath: str) -> None:
+    def create_dir_from_path(self, filepath: str | os.PathLike) -> None:
         """
         Creates directory of provided filepath if it does not exists
 
         Parameters:
-        - `filepath` (str): Filepath to check and create directory from.
+        - `filepath` (str | PathLike): Filepath to check and create directory from.
         """
         directory = os.path.dirname(filepath)
         if not os.path.exists(directory):
             os.makedirs(directory)
 
     def process_decorated_data(
-        self, path_to_python_files: str, output_file: str = "build/reqstool/annotations.yml"
+        self,
+        path_to_python_files: list[str | os.PathLike],
+        output_file: str | os.PathLike = "build/reqstool/annotations.yml",
     ) -> None:
         """
         "Main" function, runs all functions resulting in  a yaml file containing decorated data.
 
         Parameters:
         - `path_to_python_files` (list): List of directories containing Python files.
-        - `output_file` (str): Set path for output file, defaults to build/annotations.yml
+        - `output_file` (str | PathLike): Set path for output file, defaults to build/annotations.yml
 
         This method takes a list of directories containing Python files, collects decorated data from these files,
         formats the collected data, and writes the formatted results to YAML file for Requirements and SVCs annotations.

tests/unit/reqstool_decorators/processors/test_processors.py

@@ -13,27 +13,28 @@ def process_decorator_instance():
 # ---------------------------------------------------------------------------
 
 
-def test_find_python_files(process_decorator_instance: DecoratorProcessor, tmpdir):
-    tmpdir.join("pythonfile.py").write("content")
-    result = process_decorator_instance.find_python_files(tmpdir)
-    assert result == [str(tmpdir.join("pythonfile.py"))]
+def test_find_python_files(process_decorator_instance: DecoratorProcessor, tmp_path):
+    (tmp_path / "pythonfile.py").write_text("content")
+    result = process_decorator_instance.find_python_files(tmp_path)
+    assert result == [str(tmp_path / "pythonfile.py")]
 
 
-def test_find_python_files_empty_dir(process_decorator_instance: DecoratorProcessor, tmpdir):
-    result = process_decorator_instance.find_python_files(tmpdir)
+def test_find_python_files_empty_dir(process_decorator_instance: DecoratorProcessor, tmp_path):
+    result = process_decorator_instance.find_python_files(tmp_path)
     assert result == []
 
 
-def test_find_python_files_nested(process_decorator_instance: DecoratorProcessor, tmpdir):
-    sub = tmpdir.mkdir("sub")
-    sub.join("nested.py").write("content")
-    result = process_decorator_instance.find_python_files(tmpdir)
-    assert str(sub.join("nested.py")) in result
+def test_find_python_files_nested(process_decorator_instance: DecoratorProcessor, tmp_path):
+    sub = tmp_path / "sub"
+    sub.mkdir()
+    (sub / "nested.py").write_text("content")
+    result = process_decorator_instance.find_python_files(tmp_path)
+    assert str(sub / "nested.py") in result
 
 
-def test_find_python_files_ignores_non_py(process_decorator_instance: DecoratorProcessor, tmpdir):
-    tmpdir.join("readme.txt").write("content")
-    result = process_decorator_instance.find_python_files(tmpdir)
+def test_find_python_files_ignores_non_py(process_decorator_instance: DecoratorProcessor, tmp_path):
+    (tmp_path / "readme.txt").write_text("content")
+    result = process_decorator_instance.find_python_files(tmp_path)
     assert result == []
 
 
@@ -42,39 +43,39 @@ def test_find_python_files_ignores_non_py(process_decorator_instance: DecoratorP
 # ---------------------------------------------------------------------------
 
 
-def test_get_functions_and_classes(process_decorator_instance: DecoratorProcessor, tmpdir):
-    file_path = str(tmpdir.join("test_file.py"))
-    tmpdir.join("test_file.py").write('@SVCs("SVC_001")\nclass Test:\n  pass')
+def test_get_functions_and_classes(process_decorator_instance: DecoratorProcessor, tmp_path):
+    file_path = tmp_path / "test_file.py"
+    file_path.write_text('@SVCs("SVC_001")\nclass Test:\n  pass')
     process_decorator_instance.get_functions_and_classes(file_path, ["SVCs"])
     assert process_decorator_instance.req_svc_results[0]["name"] == "Test"
     assert process_decorator_instance.req_svc_results[0]["decorators"][0]["args"][0] == "SVC_001"
     assert process_decorator_instance.req_svc_results[0]["decorators"][0]["name"] == "SVCs"
     assert process_decorator_instance.req_svc_results[0]["elementKind"] == "CLASS"
 
 
-def test_get_functions_and_classes_function_def(process_decorator_instance: DecoratorProcessor, tmpdir):
-    file_path = str(tmpdir.join("f.py"))
-    tmpdir.join("f.py").write('@Requirements("REQ_001")\ndef my_func():\n    pass')
+def test_get_functions_and_classes_function_def(process_decorator_instance: DecoratorProcessor, tmp_path):
+    file_path = tmp_path / "f.py"
+    file_path.write_text('@Requirements("REQ_001")\ndef my_func():\n    pass')
     process_decorator_instance.get_functions_and_classes(file_path, ["Requirements"])
     assert len(process_decorator_instance.req_svc_results) == 1
     result = process_decorator_instance.req_svc_results[0]
     assert result["name"] == "my_func"
     assert result["elementKind"] == "FUNCTION"
 
 
-def test_get_functions_and_classes_async_function_def(process_decorator_instance: DecoratorProcessor, tmpdir):
-    file_path = str(tmpdir.join("af.py"))
-    tmpdir.join("af.py").write('@Requirements("REQ_001")\nasync def my_async():\n    pass')
+def test_get_functions_and_classes_async_function_def(process_decorator_instance: DecoratorProcessor, tmp_path):
+    file_path = tmp_path / "af.py"
+    file_path.write_text('@Requirements("REQ_001")\nasync def my_async():\n    pass')
     process_decorator_instance.get_functions_and_classes(file_path, ["Requirements"])
     assert len(process_decorator_instance.req_svc_results) == 1
     result = process_decorator_instance.req_svc_results[0]
     assert result["name"] == "my_async"
     assert result["elementKind"] == "ASYNCFUNCTION"
 
 
-def test_get_functions_and_classes_multiple_args(process_decorator_instance: DecoratorProcessor, tmpdir):
-    file_path = str(tmpdir.join("m.py"))
-    tmpdir.join("m.py").write('@Requirements("A", "B")\ndef func():\n    pass')
+def test_get_functions_and_classes_multiple_args(process_decorator_instance: DecoratorProcessor, tmp_path):
+    file_path = tmp_path / "m.py"
+    file_path.write_text('@Requirements("A", "B")\ndef func():\n    pass')
     process_decorator_instance.get_functions_and_classes(file_path, ["Requirements"])
     args = process_decorator_instance.req_svc_results[0]["decorators"][0]["args"]
     assert args == ["A", "B"]
@@ -89,28 +90,28 @@ def test_get_functions_and_classes_multiple_args(process_decorator_instance: Dec
     ],
 )
 def test_get_functions_and_classes_element_kind(
-    process_decorator_instance: DecoratorProcessor, tmpdir, code, expected_kind
+    process_decorator_instance: DecoratorProcessor, tmp_path, code, expected_kind
 ):
     """Fix 4: elementKind must be derived from __class__.__name__, not CPython repr."""
-    f = tmpdir.join("f.py")
-    f.write(code)
-    process_decorator_instance.get_functions_and_classes(str(f), ["Requirements"])
+    f = tmp_path / "f.py"
+    f.write_text(code)
+    process_decorator_instance.get_functions_and_classes(f, ["Requirements"])
     assert process_decorator_instance.req_svc_results[0]["elementKind"] == expected_kind
 
 
-def test_get_functions_and_classes_no_match(process_decorator_instance: DecoratorProcessor, tmpdir):
-    file_path = str(tmpdir.join("n.py"))
-    tmpdir.join("n.py").write('@OtherDecorator("X")\ndef func():\n    pass')
+def test_get_functions_and_classes_no_match(process_decorator_instance: DecoratorProcessor, tmp_path):
+    file_path = tmp_path / "n.py"
+    file_path.write_text('@OtherDecorator("X")\ndef func():\n    pass')
     process_decorator_instance.get_functions_and_classes(file_path, ["Requirements"])
     assert process_decorator_instance.req_svc_results == []
 
 
 def test_get_functions_and_classes_multiple_decorators_on_func(
-    process_decorator_instance: DecoratorProcessor, tmpdir
+    process_decorator_instance: DecoratorProcessor, tmp_path
 ):
-    file_path = str(tmpdir.join("md.py"))
+    file_path = tmp_path / "md.py"
     code = '@Requirements("REQ_001")\n@SVCs("SVC_001")\ndef func():\n    pass'
-    tmpdir.join("md.py").write(code)
+    file_path.write_text(code)
     process_decorator_instance.get_functions_and_classes(file_path, ["Requirements", "SVCs"])
     assert len(process_decorator_instance.req_svc_results) == 1
     names = [d["name"] for d in process_decorator_instance.req_svc_results[0]["decorators"]]
@@ -140,7 +141,7 @@ def test_map_type_unknown_type(process_decorator_instance: DecoratorProcessor):
 # ---------------------------------------------------------------------------
 
 
-def test_format_results_implementations(process_decorator_instance: DecoratorProcessor, tmpdir):
+def test_format_results_implementations(process_decorator_instance: DecoratorProcessor):
     results = [
         {
             "fullyQualifiedName": "my.module.py",
@@ -252,22 +253,20 @@ def test_process_decorated_data_produces_yaml(process_decorator_instance: Decora
     src_file.parent.mkdir()
     src_file.write_text('@Requirements("REQ_001")\ndef my_func():\n    pass\n')
 
-    output_file = str(tmp_path / "out" / "annotations.yml")
+    output_file = tmp_path / "out" / "annotations.yml"
     process_decorator_instance.process_decorated_data(
         path_to_python_files=[str(src_file.parent)], output_file=output_file
     )
 
-    import os
-
-    assert os.path.exists(output_file)
+    assert output_file.exists()
 
 
 def test_process_decorated_data_correct_structure(process_decorator_instance: DecoratorProcessor, tmp_path):
     src_file = tmp_path / "src" / "app.py"
     src_file.parent.mkdir()
     src_file.write_text('@Requirements("REQ_001")\ndef my_func():\n    pass\n')
 
-    output_file = str(tmp_path / "out" / "annotations.yml")
+    output_file = tmp_path / "out" / "annotations.yml"
     process_decorator_instance.process_decorated_data(
         path_to_python_files=[str(src_file.parent)], output_file=output_file
     )
@@ -285,7 +284,7 @@ def test_process_decorated_data_no_state_accumulation(process_decorator_instance
     src_file.parent.mkdir()
     src_file.write_text('@Requirements("REQ_001")\ndef my_func():\n    pass\n')
 
-    output_file = str(tmp_path / "out" / "annotations.yml")
+    output_file = tmp_path / "out" / "annotations.yml"
 
     # Call twice
     process_decorator_instance.process_decorated_data(