feat(pathtools): Refactor method in pathtools

* Implement function to join filenames with channel suffixes.
* Suitable for Bioformats/Jython in show_list mode.
* Includes detailed docstring with parameters and return values.

Author: lguerard

src/imcflibs/imagej/bdv.py

@@ -1724,46 +1724,3 @@ def fuse_dataset_bdvp(
         "use_interpolation",
         use_interpolation,
     ).get()
-
-
-def join_files_with_channel_suffix(files, nchannels):
-    """Join filenames and append channel-suffixed copies.
-
-    For each filename in ``files``, return a list where original filenames
-    appear first followed by copies with suffixes ``_0`` .. ``_{n-2}``
-    (inserted before the file extension). This is suitable for passing
-    to Bioformats/Jython in ``show_list`` mode when each channel is stored
-    as a separate file.
-
-    Parameters
-    ----------
-    files : list or tuple
-        List or tuple of filename strings.
-    nchannels : int
-        Number of channels (>=1). If ``nchannels`` is 1 no suffixed copies
-        are added.
-
-    Returns
-    -------
-    list of str
-        Ordered list of filenames (originals then suffixed copies).
-    """
-    import os
-
-    if not files:
-        return ""
-    try:
-        x = range(int(nchannels) - 1)
-    except Exception:
-        x = [0]
-    suff = "_" + str(x)
-    out = []
-    # keep original order, then add suffixed copies
-    for f in files:
-        out.append(f)
-    for i in x:
-        suff = "_" + str(i)
-        for f in files:
-            base, ext = os.path.splitext(f)
-            out.append(base + suff + ext)
-    return out

src/imcflibs/pathtools.py

@@ -385,3 +385,46 @@ def create_directory(new_path):
     exists = jython_fiji_exists
 else:
     exists = os.path.exists
+
+
+def join_files_with_channel_suffix(files, nchannels):
+    """Join filenames and append channel-suffixed copies.
+
+    For each filename in `files`, return a list where original filenames
+    appear first followed by copies with suffixes `_0` .. `_{n-2}`
+    (inserted before the file extension). This is suitable for passing
+    to Bioformats/Jython in ``show_list`` mode when each channel is stored
+    as a separate file.
+
+    Parameters
+    ----------
+    files : list or tuple
+        List or tuple of filename strings.
+    nchannels : int
+        Number of channels (>=1). If ``nchannels`` is 1 no suffixed copies
+        are added.
+
+    Returns
+    -------
+    list of str
+        Ordered list of filenames (originals then suffixed copies).
+    """
+    import os
+
+    if not files:
+        return ""
+    try:
+        x = range(int(nchannels) - 1)
+    except Exception:
+        x = [0]
+    suff = "_" + str(x)
+    out = []
+    # Keep original order, then add suffixed copies
+    for f in files:
+        out.append(f)
+    for i in x:
+        suff = "_" + str(i)
+        for f in files:
+            base, ext = os.path.splitext(f)
+            out.append(base + suff + ext)
+    return out