pygmt.which

pygmt.which(fname, download=False, verbose=False, **kwargs)[source]

Find full path to specified files.

Reports the full paths to the files given through fname. It looks 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 GMT remote 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 GMT docs at https://docs.generic-mapping-tools.org/6.6/gmtwhich.html.

Aliases:

  • G = download

  • V = verbose

Parameters:

  • fname (str | PathLike | Sequence[str | PathLike]) – One or more file names to find the full path.

  • download (Literal['auto', 'cache', 'local', 'user'] | bool, default: False) –

    Try to download the file if it is not found in your local data or cache directories and the file is downloadable. Here, downloadable files include:

    • a file specified by a complete URL

    • a GMT remote file on the GMT data server, specified with a leading @.

    • any of the GMT remote datasets

    Valid values are:

    • False: Do not download the file.

    • True or "local": Download the file to the current directory.

    • "cache": Download the file to the user cache directory.

    • "user": Download the file to the user data directory but ignore any subdirectory structure.

    • "auto": Download the file to appropriate folder under the user directory (this is where GMT normally places downloaded files).

  • verbose (bool or str) – Select verbosity level [Full usage].

Return type:

str | list[str]

Returns:

path – The path(s) to the file(s), depending on the parameters used.

Raises:

FileNotFoundError – If the file is not found.