Add the validate_output_table_type function to check the output_type parameter

[seisman]

Description of proposed changes

Add the validate_output_type function so it can be re-used in many modules.

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
• If adding new functionality, add an example to docstrings or tutorials.
• Use underscores (not hyphens) in names of Python files and directories.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[seisman]

Ping @GenericMappingTools/pygmt-maintainers for review.

[weiji14]

Just on the naming, should we specify that this applies to tabular outputs? E.g. use something like validate_output_table_type? There are some functions like pygmt.grdhisteq.equalize_grid that has code looking like this:

with GMTTempFile(suffix=".nc") as tmpfile:
    if isinstance(outgrid, str):
        output_type = "file"
    elif outgrid is None:
        output_type = "xarray"
        outgrid = tmpfile.name
    else:
        raise GMTInvalidInput("Must specify 'outgrid' as a string or None.")

If we ever decide to have more output_types for grids (e.g. NetCDF or TIFF or xarray or ???), then there might be a validate_output_grid_type.

[seisman]

I was thinking about adding a new parameter kind (valid values are dataset/grid) to make the function working for both tables and grids.

[weiji14]

There would a lot of if-thens, and the error/warning messages would be different between tables and grids though.

[seisman]

Ah right, tables use outfile but grids use outgrid.

[seisman]

Just on the naming, should we specify that this applies to tabular outputs? E.g. use something like validate_output_table_type?

Renamed in becbb73.