pygmt.which: Find full path to specified files

[seisman]

This is the central issue to track the implementation of the pygmt.which method.

• GMT doc: https://docs.generic-mapping-tools.org/6.5/gmtwhich.html
• PyGMT doc: https://www.pygmt.org/dev/api/generated/pygmt.which.html

GMT options

Checked: Implemented; Unchecked: To be implemented/discussed; Strikethrough: Won't implement.

• <files>
• -A
• -C
• -D
• -G[a|c|l|u]: download. Long-form names are auto/cache/local/user. pygmt.which: Support long-form arguments for the 'download' parameter #4429
• -V: verbose
• --PAR=<value>: Use pygmt.config

The gmtwhich module is one of the simplest modules and has very few options:

-A: Only consider files that the user has permission to read [Default consider all files found].

I think this option is useful and should be implemented. GMT's long option name readable sound good.

-C: Instead of reporting the paths, print the confirmation Y if the file is found and N if it is not.

Currently, we raise FileNotFoundError exception if a file is not found. Sometimes, we may want to take specific actions if a file is not found, so this option is still useful. GMT's long option name is confirm and return Y/N. I think it makes little sense in Python. Instead, we can return the full path if found and None if not found? Or True/False?

-D: Instead of reporting the paths, print the directories that contains the files.

Useless. In Python, we can always use os.path.dirname or Path().parent instead.

-G[a|c|l|u]: download the file if it's a downloadable file

Already implemented but is not Pythonic. The single-letter argument (e.g., download="a") is not Pythonic. More Pythonic arguments are True, auto, cache, local, user. GMT uses user, cache, current, data instead. I feel my suggestions make more sense and we can ask for upstrem changes.

We also need to decide:

• if we want to use virtualfiles for output [xref Get rid of temporary files from pygmt functions and plotting methods #2730]
• if output type file/numpy/pandas should be supported [xref Consistent table-like output for PyGMT functions/methods #1318]

[seisman]

-A/-C/-D are not implemented yet, but I feel they're less used. We may consider supporting these options in the future.