chore: format code

Author: DiogoRibeiro7

src/ssspx/io.py

@@ -15,14 +15,40 @@
 
 
 def _iter_edges(G: Graph) -> Iterable[Tuple[int, int, float]]:
-    """Yield all edges ``(u, v, w)`` from ``G``."""
+    """
+    Iterates over all edges in the given graph.
+
+    Args:
+        G (Graph): The graph object containing adjacency information.
+
+    Yields:
+        Tuple[int, int, float]: A tuple representing an edge in the graph,
+            where the first element is the source node index (u),
+            the second element is the destination node index (v),
+            and the third element is the edge weight (w).
+    """
     for u in range(G.n):
         for v, w in G.adj[u]:
             yield u, v, w
 
 
 def _read_csv(path: Path) -> Tuple[int, EdgeList]:
-    """Parse a CSV/TSV edges file."""
+    """
+    Reads a CSV file containing edge data and returns the number of nodes and the edge list.
+
+    Each line in the file should contain at least three columns: source node, target node, and edge weight.
+    Lines starting with '#' or empty lines are ignored. Columns can be separated by commas or tabs.
+
+    Args:
+        path (Path): The path to the CSV file.
+
+    Returns:
+        Tuple[int, EdgeList]: A tuple containing the number of nodes (max node id + 1) and a list of edges,
+        where each edge is represented as a tuple (u, v, w).
+
+    Raises:
+        GraphFormatError: If no edges are parsed from the file.
+    """
     edges: EdgeList = []
     max_id = -1
     with path.open("r", encoding="utf-8") as fh:
@@ -47,14 +73,41 @@ def _read_csv(path: Path) -> Tuple[int, EdgeList]:
 
 
 def _write_csv(path: Path, G: Graph) -> None:
-    """Write ``G`` as a CSV edges file."""
+    """
+    Writes the edges of a graph to a CSV file.
+
+    Each row in the CSV file represents an edge in the graph, with columns for the source node, target node, and edge weight.
+
+    Args:
+        path (Path): The file path where the CSV will be written.
+        G (Graph): The graph whose edges will be written to the CSV file.
+
+    Returns:
+        None
+    """
     with path.open("w", encoding="utf-8") as fh:
         for u, v, w in _iter_edges(G):
             fh.write(f"{u},{v},{w}\n")
 
 
 def _read_jsonl(path: Path) -> Tuple[int, EdgeList]:
-    """Parse a JSON Lines edges file."""
+    """
+    Reads a JSON Lines (JSONL) file containing graph edges and returns the 
+    number of nodes and the edge list.
+
+    Each line in the file should be a JSON object with keys "u", "v", and "w",
+    representing the source node, target node, and edge weight, respectively.
+
+    Args:
+        path (Path): Path to the JSONL file.
+
+    Returns:
+        Tuple[int, EdgeList]: A tuple containing the number of nodes 
+        (max node id + 1) and a list of edges as (u, v, w) tuples.
+
+    Raises:
+        GraphFormatError: If no edges are parsed from the file.
+    """
     edges: EdgeList = []
     max_id = -1
     with path.open("r", encoding="utf-8") as fh:
@@ -74,14 +127,42 @@ def _read_jsonl(path: Path) -> Tuple[int, EdgeList]:
 
 
 def _write_jsonl(path: Path, G: Graph) -> None:
-    """Write ``G`` as a JSON Lines edges file."""
+    """
+    Writes the edges of a graph to a file in JSON Lines (JSONL) format.
+
+    Each line in the output file represents an edge as a JSON object 
+    with keys 'u', 'v', and 'w', corresponding to the source node, target node,
+    and edge weight, respectively.
+
+    Args:
+        path (Path): The file path where the JSONL data will be written.
+        G (Graph): The graph object containing the edges to be serialized.
+
+    Returns:
+        None
+    """
     with path.open("w", encoding="utf-8") as fh:
         for u, v, w in _iter_edges(G):
             fh.write(json.dumps({"u": u, "v": v, "w": w}) + "\n")
 
 
 def _read_mtx(path: Path) -> Tuple[int, EdgeList]:
-    """Parse a MatrixMarket edges file."""
+    """
+    Reads a Matrix Market (.mtx) file and extracts the edge list.
+
+    Args:
+        path (Path): Path to the Matrix Market file.
+
+    Returns:
+        Tuple[int, EdgeList]: A tuple containing the number of nodes (n) and the edge list.
+            The edge list is a list of tuples (u, v, w), where u and v are zero-based node indices,
+            and w is the edge weight.
+
+    Notes:
+        - Lines starting with '%' are treated as comments and skipped.
+        - Assumes the file contains at least three columns: source, target, and weight.
+        - Node indices in the file are assumed to be 1-based and are converted to 0-based.
+    """
     edges: EdgeList = []
     it = path.open("r", encoding="utf-8")
     with it as fh:
@@ -105,7 +186,20 @@ def _read_mtx(path: Path) -> Tuple[int, EdgeList]:
 
 
 def _write_mtx(path: Path, G: Graph) -> None:
-    """Write ``G`` as a MatrixMarket edges file."""
+    """
+    Writes the given graph `G` to a Matrix Market (.mtx) file at the specified path.
+
+    The output file will contain the graph's adjacency matrix in coordinate format,
+    where each line represents an edge with its source node, target node, and weight.
+    Node indices are written as 1-based (Matrix Market convention).
+
+    Args:
+        path (Path): The file path where the Matrix Market file will be written.
+        G (Graph): The graph object containing nodes and weighted edges.
+
+    Returns:
+        None
+    """
     edges = list(_iter_edges(G))
     with path.open("w", encoding="utf-8") as fh:
         fh.write("%%MatrixMarket matrix coordinate real general\n")
@@ -117,7 +211,7 @@ def _write_mtx(path: Path, G: Graph) -> None:
 def _read_graphml(path: Path) -> Tuple[int, EdgeList]:
     """
     Parse a GraphML file and extract the edge list.
-    
+
     Args:
         path (Path): Path to the GraphML file.
     Returns:
@@ -134,7 +228,7 @@ def _read_graphml(path: Path) -> Tuple[int, EdgeList]:
     max_id = -1
     for edge in root.findall(f".//{ns}edge"):
         u_str = edge.attrib.get("source", "")
-        v_str = edge.attrib.get("target", "")      
+        v_str = edge.attrib.get("target", "")
         # Convert string IDs to integers
         if u_str.startswith("n"):
             u = int(u_str[1:])
@@ -143,7 +237,7 @@ def _read_graphml(path: Path) -> Tuple[int, EdgeList]:
         if v_str.startswith("n"):
             v = int(v_str[1:])
         else:
-            v = int(v_str)    
+            v = int(v_str)
         w_attr = edge.attrib.get("weight")
         if w_attr is None:
             data = edge.find(f"{ns}data[@key='w']")
@@ -188,7 +282,16 @@ def _write_graphml(path: Path, G: Graph) -> None:
 
 
 def _detect_format(path: Path) -> Optional[str]:
-    """Infer graph format from ``path`` extension."""
+    """
+    Detects the file format based on the file extension.
+
+    Args:
+        path (Path): The path to the file whose format is to be detected.
+
+    Returns:
+        Optional[str]: The detected format as a string ("csv", "jsonl", "mtx", "graphml"),
+        or None if the format is not recognized.
+    """
     ext = path.suffix.lower()
     if ext in {".csv", ".tsv"}:
         return "csv"
@@ -202,7 +305,19 @@ def _detect_format(path: Path) -> Optional[str]:
 
 
 def read_graph(path: str, fmt: Optional[str] = None) -> Graph:
-    """Read a graph from ``path`` in the given format."""
+    """
+    Reads a graph from a file in the specified format.
+
+    Args:
+        path (str): The path to the graph file.
+        fmt (Optional[str], optional): The format of the graph file. If None, the format is auto-detected.
+
+    Returns:
+        Graph: The graph object constructed from the file.
+
+    Raises:
+        GraphFormatError: If the graph format is unknown or unsupported.
+    """
     p = Path(path)
     fmt = fmt or _detect_format(p)
     if fmt is None or fmt not in _FMT_READERS:
@@ -212,7 +327,17 @@ def read_graph(path: str, fmt: Optional[str] = None) -> Graph:
 
 
 def write_graph(G: Graph, path: str, fmt: Optional[str] = None) -> None:
-    """Write ``G`` to ``path`` in the given format."""
+    """
+    Writes a graph to a file in the specified format.
+
+    Parameters:
+        G (Graph): The graph object to be written.
+        path (str): The file path where the graph will be saved.
+        fmt (Optional[str], optional): The format to use for writing the graph. If None, the format is auto-detected from the file extension.
+
+    Raises:
+        GraphFormatError: If the format is unknown or unsupported.
+    """
     p = Path(path)
     fmt = fmt or _detect_format(p)
     if fmt is None or fmt not in _FMT_WRITERS:
@@ -221,7 +346,21 @@ def write_graph(G: Graph, path: str, fmt: Optional[str] = None) -> None:
 
 
 def load_graph(path: str, fmt: Optional[str] = None) -> Graph:
-    """Deprecated alias for :func:`read_graph`."""
+    """
+    Loads a graph from the specified file path.
+
+    This function is deprecated; use `read_graph` instead.
+
+    Args:
+        path (str): The path to the graph file.
+        fmt (Optional[str], optional): The format of the graph file. Defaults to None.
+
+    Returns:
+        Graph: The loaded graph object.
+
+    Deprecated:
+        Since version 0.1.0. Will be removed in version 0.2.0. Use `read_graph` instead.
+    """
     warn_once(
         "load_graph is deprecated; use read_graph",
         since="0.1.0",