Update Pathlib usage and docstrings (#68)

* Update pathlib references in IO submodule

* Update pathlib references in the general module

* Apply suggestions from code review

Co-authored-by: Kimberly Meechan <[email protected]>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* TYPE_CHECKING is confusing codecov

* Apply suggestions from code review

All the "Path"s

Co-authored-by: Kimberly Meechan <[email protected]>

---------

Co-authored-by: Kimberly Meechan <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

brainglobe_utils/IO/cells.py

@@ -7,7 +7,7 @@
 
 import logging
 import os
-import pathlib
+from pathlib import Path
 from typing import List, Optional, Union
 from xml.dom import minidom
 from xml.etree import ElementTree
@@ -88,7 +88,9 @@ def raise_cell_read_error(cells_file_path):
     )
 
 
-def get_cells_xml(xml_file_path, cells_only=False):
+def get_cells_xml(
+    xml_file_path: Union[str, Path], cells_only: Optional[bool] = False
+):
     """
     Read cells from an xml file.
 
@@ -121,7 +123,11 @@ def get_cells_xml(xml_file_path, cells_only=False):
     return cells
 
 
-def get_cells_yml(cells_file_path, ignore_type=False, marker="markers"):
+def get_cells_yml(
+    cells_file_path: Union[str, Path],
+    ignore_type: Optional[bool] = False,
+    marker: Optional[str] = "markers",
+):
     """
     Read cells from a yml file.
 
@@ -158,7 +164,9 @@ def get_cells_yml(cells_file_path, ignore_type=False, marker="markers"):
     return cells
 
 
-def get_cells_dir(cells_file_path, cell_type=None):
+def get_cells_dir(
+    cells_file_path: Union[str, Path], cell_type: Optional[bool] = None
+):
     """
     Read cells from a directory. Cells will be created based on the filenames
     of files in the directory, one cell per file.
@@ -230,7 +238,10 @@ def save_cells(
 
 
 def cells_to_xml(
-    cells, xml_file_path, indentation_str="  ", artifact_keep=True
+    cells: List[Cell],
+    xml_file_path: Union[str, Path],
+    indentation_str: Optional[str] = "  ",
+    artifact_keep: Optional[bool] = True,
 ):
     """
     Save cells to an xml file.
@@ -263,7 +274,7 @@ def cells_to_dataframe(cells: List[Cell]) -> pd.DataFrame:
     return pd.DataFrame([c.to_dict() for c in cells])
 
 
-def cells_to_csv(cells: List[Cell], csv_file_path: Union[str, pathlib.Path]):
+def cells_to_csv(cells: List[Cell], csv_file_path: Union[str, Path]):
     """Save cells to csv file"""
     df = cells_to_dataframe(cells)
     df.to_csv(csv_file_path)

brainglobe_utils/IO/surfaces.py

@@ -1,4 +1,12 @@
-def marching_cubes_to_obj(marching_cubes_out, output_file):
+from pathlib import Path
+from typing import Tuple, Union
+
+from numpy.typing import NDArray
+
+
+def marching_cubes_to_obj(
+    marching_cubes_out: Tuple[NDArray], output_file: Union[str, Path]
+):
     """
     Saves the output of skimage.measure.marching_cubes as an .obj file
 

brainglobe_utils/IO/yaml.py

@@ -1,7 +1,10 @@
+from pathlib import Path
+from typing import Any, Dict, Optional, Union
+
 import yaml
 
 
-def read_yaml_section(yaml_file, section):
+def read_yaml_section(yaml_file: Union[str, Path], section: str) -> Any:
     """
     Read section from yaml file.
 
@@ -21,7 +24,7 @@ def read_yaml_section(yaml_file, section):
     return contents
 
 
-def open_yaml(yaml_file):
+def open_yaml(yaml_file: Union[str, Path]) -> Dict[str, Any]:
     """
     Read the contents of a yaml file.
 
@@ -40,7 +43,11 @@ def open_yaml(yaml_file):
     return yaml_contents
 
 
-def save_yaml(yaml_contents, output_file, default_flow_style=False):
+def save_yaml(
+    yaml_contents: Dict[str, Any],
+    output_file: Union[str, Path],
+    default_flow_style: Optional[bool] = False,
+):
     """
     Save contents to a yaml file.
 

brainglobe_utils/general/pathlib.py

@@ -1,4 +1,7 @@
-def append_to_pathlib_stem(path, string_to_append):
+from pathlib import Path
+
+
+def append_to_pathlib_stem(path: Path, string_to_append: str):
     """
     Appends a string to the stem of a pathlib object.
 

brainglobe_utils/general/string.py

@@ -1,15 +1,18 @@
+from pathlib import Path
+from typing import Optional
+
 from natsort import natsorted
 
 from brainglobe_utils.general import list
 
 
 def get_text_lines(
-    file,
-    return_lines=None,
-    rstrip=True,
-    sort=False,
-    remove_empty_lines=True,
-    encoding="utf8",
+    file: Path,
+    return_lines: Optional[int] = None,
+    rstrip: Optional[bool] = True,
+    sort: Optional[bool] = False,
+    remove_empty_lines: Optional[bool] = True,
+    encoding: Optional[str] = "utf8",
 ):
     """
     Return only the nth line of a text file.