Update Pathlib usage and docstrings

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,7 @@ 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: Path, cells_only: Optional[bool] = False):
     """
     Read cells from an xml file.
 
@@ -121,7 +121,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: Path,
+    ignore_type: Optional[bool] = False,
+    marker: Optional[str] = "markers",
+):
     """
     Read cells from a yml file.
 
@@ -158,7 +162,7 @@ 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: 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 +234,10 @@ def save_cells(
 
 
 def cells_to_xml(
-    cells, xml_file_path, indentation_str="  ", artifact_keep=True
+    cells: Cell,
+    xml_file_path: Path,
+    indentation_str: Optional[str] = "  ",
+    artifact_keep: Optional[bool] = True,
 ):
     """
     Save cells to an xml file.
@@ -263,7 +270,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,14 @@
-def marching_cubes_to_obj(marching_cubes_out, output_file):
+from typing import TYPE_CHECKING, Tuple, Union
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    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,14 @@
+from typing import TYPE_CHECKING, Any, Dict, Optional, Union
+
 import yaml
 
+if TYPE_CHECKING:
+    from pathlib import Path
+
 
-def read_yaml_section(yaml_file, section):
+def read_yaml_section(
+    yaml_file: Union[str, "Path"], section: str
+) -> Dict[str, Any]:
     """
     Read section from yaml file.
 
@@ -21,7 +28,7 @@
     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 +47,11 @@
     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,10 @@
-def append_to_pathlib_stem(path, string_to_append):
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def append_to_pathlib_stem(path: "Path", string_to_append):
     """
     Appends a string to the stem of a pathlib object.
 

brainglobe_utils/general/string.py

@@ -1,15 +1,20 @@
+from typing import TYPE_CHECKING, Optional
+
 from natsort import natsorted
 
 from brainglobe_utils.general import list
 
+if TYPE_CHECKING:
+    from pathlib import Path
+
 
 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.