Source code for pygmt.src.which

"""
which - Find the full path to specified files.
"""

from pygmt.clib import Session
from pygmt.helpers import build_arg_list, fmt_docstring, is_nonstr_iter, use_alias


[docs] @fmt_docstring @use_alias(G="download", V="verbose") def which(fname, **kwargs) -> str | list[str]: r""" Find the full path to specified files. Reports the full paths to the files given through ``fname``. We look for the file in (1) the current directory, (2) in $GMT_USERDIR (if defined), (3) in $GMT_DATADIR (if defined), or (4) in $GMT_CACHEDIR (if defined). ``fname`` can also be a downloadable file (either a complete URL, an @file for downloading from the GMT data server, or any of the remote datasets at https://www.pygmt.org/latest/api/index.html#datasets). In these cases, use the ``download`` parameter to set the desired behavior. If ``download`` is not used (or ``False``), the file will not be found. Full option list at :gmt-docs:`gmtwhich.html` {aliases} Parameters ---------- fname : str or list One or more file names of any data type (grids, tables, etc.). download : bool or str [**a**\|\ **c**\|\ **l**\|\ **u**]. If the ``fname`` argument is a downloadable file (either a complete URL, an @file for downloading from the GMT data server, or any of the remote datasets at https://www.pygmt.org/latest/api/index.html#datasets) we will try to download the file if it is not found in your local data or cache directories. If set to ``True`` or **l** is passed the file is downloaded to the current directory. Use **a** to place files in the appropriate folder under the user directory (this is where GMT normally places downloaded files), **c** to place it in the user cache directory, or **u** for the user data directory instead (i.e., ignoring any subdirectory structure). {verbose} Returns ------- path The path(s) to the file(s), depending on the parameters used. Raises ------ FileNotFoundError If the file is not found. """ with Session() as lib: with lib.virtualfile_out(kind="dataset") as vouttbl: lib.call_module( module="which", args=build_arg_list(kwargs, infile=fname, outfile=vouttbl), ) paths = lib.virtualfile_to_dataset(vfname=vouttbl, output_type="strings") match paths.size: case 0: _fname = "', '".join(fname) if is_nonstr_iter(fname) else fname raise FileNotFoundError(f"File(s) '{_fname}' not found.") case 1: return paths[0] case _: return paths.tolist()