"""which - Find the full path to specified files."""frompygmt.clibimportSessionfrompygmt.helpersimport(GMTTempFile,build_arg_string,fmt_docstring,kwargs_to_strings,use_alias,)
[docs]@fmt_docstring@use_alias(G="download",V="verbose")@kwargs_to_strings(fname="sequence_space")defwhich(fname,**kwargs):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 full URL, a `@file` special file for downloading from the GMT Site Cache, or `@earth_relief_*` topography grids). In these cases, use option *download* 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 @earth_relief_xxy) we will try to download the file if it is not found in your local data or cache dirs. By default [``download=True`` or ``download="l"``] we download 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). {V} Returns ------- path : str or list The path(s) to the file(s), depending on the options used. Raises ------ FileNotFoundError If the file is not found. """withGMTTempFile()astmpfile:arg_str=" ".join([fname,build_arg_string(kwargs),"->"+tmpfile.name])withSession()aslib:lib.call_module("which",arg_str)path=tmpfile.read().strip()ifnotpath:_fname=fname.replace(" ","', '")raiseFileNotFoundError(f"File(s) '{_fname}' not found.")returnpath.split("\n")if"\n"inpathelsepath