imcflibs.pathtools

  1"""Helper functions to work with filenames, directories etc."""
  2
  3import os.path
  4import platform
  5from os import sep
  6
  7from . import strtools
  8from .log import LOG as log
  9
 10
 11def parse_path(path, prefix=""):
 12    r"""Parse a path into its components.
 13
 14    If the path doesn't end with the pathsep, it is assumed being a file!
 15    No tests based on existing files are done, as this is supposed to also work
 16    on path strings that don't exist on the system running this code.
 17
 18    The function accepts `java.io.File` objects (as retrieved by using ImageJ2's
 19    *Script Parameter* `#@ File`) for either of the parameters, so it is safe to
 20    use this in ImageJ Python scripts without additional measures.
 21
 22    Parameters
 23    ----------
 24    path : str or str-like
 25        The path to be parsed into components.
 26    prefix : str or str-like, optional
 27        An optional path component that will be prefixed to the given path using
 28        `os.path.join()`.
 29
 30    Returns
 31    -------
 32    dict
 33        The parsed (and possibly combined) path split into its components, with
 34        the following keys:
 35        - `orig` : The full string as passed into this function (possibly
 36          combined with the prefix in case one was specified).
 37        - `full` : The same as `orig` with separators adjusted to the current
 38          platform.
 39        - `path` : The same as `full`, up to (including) the last separator.
 40        - `dname` : The segment between the last two separators (directory).
 41        - `fname` : The segment after the last separator (filename).
 42        - `basename` : The filename without extension. Note that *OME-TIFF*
 43          files (having a suffix like `.ome.tif` or `.ome.tiff`) are treated as
 44          special case in the sense that the `.ome` part is also stripped from
 45          the basename and added to the `ext` key (see below).
 46        - `ext` : The filename extension, containing max 1 dot (included) with
 47          the special case of `.ome.tif` / `.ome.tiff` where 2 dots are
 48          contained to represent the full suffix.
 49
 50    Examples
 51    --------
 52
 53    POSIX-style path to a file with a suffix:
 54
 55    >>> parse_path('/tmp/foo/file.suffix')
 56    {'dname': 'foo',
 57     'ext': '',
 58     'fname': 'file',
 59     'full': '/tmp/foo/file',
 60     'basename': 'file',
 61     'orig': '/tmp/foo/file',
 62     'path': '/tmp/foo/'}
 63
 64    POSIX-style path to a directory:
 65
 66    >>> parse_path('/tmp/foo/')
 67    {'dname': 'foo',
 68     'ext': '',
 69     'fname': '',
 70     'full': '/tmp/foo/',
 71     'basename': '',
 72     'orig': '/tmp/foo/',
 73     'path': '/tmp/foo/'}
 74
 75    Windows-style path to a file:
 76
 77    >>> parse_path('C:\\Temp\\foo\\file.ext')
 78    {'dname': 'foo',
 79     'ext': '.ext',
 80     'fname': 'file.ext',
 81     'full': 'C:/Temp/foo/file.ext',
 82     'basename': 'file',
 83     'orig': 'C:\\Temp\\foo\\file.ext',
 84     'path': 'C:/Temp/foo/'}
 85
 86    Special treatment for *OME-TIFF* suffixes:
 87
 88    >>> parse_path("/path/to/some/nice.OME.tIf")
 89    {'basename': 'nice',
 90    'dname': 'some',
 91    'ext': '.OME.tIf',
 92    'fname': 'nice.OME.tIf',
 93    'full': '/path/to/some/nice.OME.tIf',
 94    'orig': '/path/to/some/nice.OME.tIf',
 95    'path': '/path/to/some/'}
 96    """
 97    path = str(path)
 98    if prefix:
 99        # remove leading slash, otherwise join() will discard the first path:
100        if path.startswith("/"):
101            path = path[1:]
102        path = os.path.join(str(prefix), path)
103    parsed = {}
104    parsed["orig"] = path
105    path = path.replace("\\", sep)
106    parsed["full"] = path
107    parsed["path"] = os.path.dirname(path) + sep
108    parsed["fname"] = os.path.basename(path)
109    parsed["dname"] = os.path.basename(os.path.dirname(parsed["path"]))
110    base, ext = os.path.splitext(parsed["fname"])
111    parsed["ext"] = ext
112    parsed["basename"] = base
113    if base.lower().endswith(".ome") and ext.lower().startswith(".tif"):
114        parsed["basename"] = base[:-4]
115        parsed["ext"] = base[-4:] + ext
116
117    return parsed
118
119
120def join2(path1, path2):
121    """Join two paths into one, much like os.path.join().
122
123    The main difference is that `join2()` takes exactly two arguments, but they
124    can be non-str (as long as they're having a `__str__()` method), so this is
125    safe to be used with stuff like `java.io.File` objects as retrieved when
126    using ImageJ2's *Script Parameter* `#@ File`.
127
128    In addition some sanitizing is done, e.g. in case one of the components is
129    containing double backslashes (`\\`), they will be replaced by the current
130    OS's path separator.
131
132    Parameters
133    ----------
134    path1 : str or str-like
135        The first component of the path to be joined.
136    path2 : str or str-like
137        The second component of the path to be joined.
138
139    Returns
140    -------
141    str
142    """
143    return parse_path(path2, prefix=path1)["full"]
144
145
146def jython_fiji_exists(path):
147    """Wrapper to work around problems with Jython 2.7 in Fiji.
148
149    In current Fiji, the Jython implementation of os.path.exists(path) raises a
150    java.lang.AbstractMethodError iff 'path' doesn't exist. This function
151    catches the exception to allow normal usage of the exists() call.
152    """
153    try:
154        return os.path.exists(path)
155    except java.lang.AbstractMethodError:
156        return False
157
158
159def listdir_matching(path, suffix, fullpath=False, sort=False):
160    """Get a list of files in a directory matching a given suffix.
161
162    Parameters
163    ----------
164    path : str
165        The directory to scan for files.
166    suffix : str
167        The suffix to match filenames against.
168    fullpath : bool, optional
169        If set to True, the list returned by the function will contain the full
170        paths to the matching files (the default is False, which will result in
171        the file names only, without path).
172    sort : bool, optional
173        If set to True, the returned list will be sorted using
174        `imcflibs.strtools.sort_alphanumerically()`.
175
176    Returns
177    -------
178    list
179        All file names in the directory matching the suffix (without path!).
180    """
181    matching_files = list()
182    for candidate in os.listdir(path):
183        if candidate.lower().endswith(suffix.lower()):
184            # log.debug("Found file %s", candidate)
185            if fullpath:
186                matching_files.append(os.path.join(path, candidate))
187            else:
188                matching_files.append(candidate)
189
190    if sort:
191        matching_files = strtools.sort_alphanumerically(matching_files)
192
193    return matching_files
194
195
196def image_basename(orig_name):
197    """Return the file name component without suffix(es).
198
199    Strip away the path and suffix of a given file name, doing a special
200    treatment for the composite suffix ".ome.tif(f)" which will be fully
201    stripped as well.
202
203    Parameters
204    ----------
205    orig_name : str
206
207    Examples
208    --------
209    >>> image_basename('/path/to/some_funny_image_file_01.png')
210    'some_funny_image_file_01'
211
212    >>> image_basename('some-more-complex-stack.ome.tif')
213    'some-more-complex-stack'
214
215    >>> image_basename('/tmp/FoObAr.OMe.tIf')
216    'FoObAr'
217    """
218    return parse_path(orig_name)["basename"]
219
220
221def gen_name_from_orig(path, orig_name, tag, suffix):
222    """Derive a file name from a given input file, an optional tag and a suffix.
223
224    Parameters
225    ----------
226    path : str or object that can be cast to a str
227        The output path.
228    orig_name : str or object that can be cast to a str
229        The input file name, may contain arbitrary path components.
230    tag : str
231        An optional tag to be added at the end of the new file name, can be used
232        to denote information like "-avg" for an average projection image.
233    suffix : str
234        The new file name suffix, which also sets the file format for BF.
235
236    Returns
237    -------
238    out_file : str
239        The newly generated file name with its full path.
240    """
241    name = os.path.join(path, image_basename(orig_name) + tag + suffix)
242    return name
243
244
245def derive_out_dir(in_dir, out_dir):
246    """Derive `out_dir` from its own value and the value of `in_dir`.
247
248    In case the supplied value of `out_dir` is one of '-' or 'NONE', the
249    returned value will be set to `in_dir`. Otherwise the value of `out_dir`
250    will be returned unchanged.
251
252    Parameters
253    ----------
254    in_dir : str
255        The full path to the input directory.
256    out_dir : str
257        Either the full path to an output directory or one of '-' or 'NONE'.
258
259    Returns
260    -------
261    str
262        The full path to the directory to be used for output and temp files.
263    """
264    if out_dir.upper() in ["-", "NONE"]:
265        out_dir = in_dir
266        log.info("No output directory given, using input dir [%s].", out_dir)
267    else:
268        log.info("Using directory [%s] for results and temp files.", out_dir)
269
270    return out_dir
271
272
273def find_dirs_containing_filetype(source, filetype):
274    """Recursively list directories containing files with a given suffix.
275
276    Parameters
277    ----------
278    source : str
279        Path to base directory to start recursive search in.
280    filetype : str
281        Filetype (string pattern) that should be matched against filenames in
282        the directories.
283
284    Returns
285    -------
286    list(str)
287        List of all dirs that contain files with the given suffix / filetype.
288    """
289    dirs_containing_filetype = []
290
291    # walk recursively through all directories
292    # list their paths and all files inside (=os.walk)
293    for dirname, _, filenames in os.walk(source):
294        # stop when encountering a directory that contains "filetype"
295        # and store the directory path
296        for filename in filenames:
297            if filetype in filename:
298                dirs_containing_filetype.append(dirname + "/")
299                break
300
301    return dirs_containing_filetype
302
303
304def folder_size(source):
305    """Get the total size of a given directory and its subdirectories.
306
307    Parameters
308    ----------
309    source : str
310        Directory for which the size should be determined.
311
312    Returns
313    -------
314    int
315        The total size of all files in the source dir and subdirs in bytes.
316    """
317    total_size = 0
318    for dirpath, _, filenames in os.walk(source):
319        for fname in filenames:
320            fpath = os.path.join(dirpath, fname)
321            # skip if it is symbolic link
322            if not os.path.islink(fpath):
323                total_size += os.path.getsize(fpath)
324
325    return total_size
326
327
328# pylint: disable-msg=C0103
329#   we use the variable name 'exists' in its common spelling (lowercase), so
330#   removing this workaround will be straightforward at a later point
331if platform.python_implementation() == "Jython":
332    # pylint: disable-msg=F0401
333    #   java.lang is only importable within Jython, pylint would complain
334    import java.lang
335
336    exists = jython_fiji_exists
337else:
338    exists = os.path.exists