Wrap the GMT API function GMT_Read_Data to read data into GMT data containers

[seisman]

Description of proposed changes

See #3318 for the motivations.

This PR wraps the GMT API functions GMT_Read_Data for reading data file into GMT data containers. Currently, only GMT_DATASET and GMT_GRID are supported, other data containers will be supported later.

The first two commits 5a56ba8 and 7ccf641 are cherry-picked from PR #3318.

Preview at https://pygmt-dev--3324.org.readthedocs.build/en/3324/api/generated/pygmt.clib.Session.read_data.html

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 command is:

• /format: automatically format and lint the code

[seisman]

Can't do xrgrid = data_ptr.contents.to_dataarray() here because data is not read yet, so grid.data is NULL. Maybe we should modify the GMT_GRID.to_dataarray() method to fill the DataArray with np.empty() if grid.data is not read yet?

Edit: I think it's not necessary after thinking twice.

[weiji14]

Can you link to where in the GMT API documentation what options there are for mode?

[seisman]

mode is explained at https://docs.generic-mapping-tools.org/dev/devdocs/api.html#import-from-a-file-stream-or-handle.

[weiji14]

Thinking on whether to make this an enum or use Literal instead of a str. Looking at https://docs.generic-mapping-tools.org/6.5/devdocs/api.html#import-from-a-file-stream-or-handle, it seems like it's possible to pass in mode as one of the variants of GMT_enum_container or GMT_enum_gridio? It also looks like mode can be None (or unset) if reading from text or table.

[seisman]

I believe the documentation is incomplete, and mode can accept specific values plus some modifiers, making it impossible to list all of them.

[weiji14]

Yeah that what I thought too, there might be other options we's unaware of. That said, should we allow for mode=None (or whatever works when we don't want to set a mode)?

[seisman]

In the GMT C API, mode has an unsigned int type, so the mode argument must be an integer number and can't be None. The C enum GMT_READ_NORMAL has a value of 0 (https://github.com/GenericMappingTools/gmt/blob/3e9fcb1f54e4e93fc1e309e0be6e2288eb79f3d2/src/gmt_resources.h#L244), which is also the default read mode.

We can define mode=None, and add one line code like:

if mode == None:
mode = "GMT_READ_NORMAL"

but I feel it's not as good as setting GMT_READ_NORMAL as the default.

[weiji14]

Ah ok then, then the GMT_READ_NORMAL default here makes sense. Maybe good to mention it in the docstring.

[weiji14]

Thanks @seisman, just one additional suggestion on documenting the default mode="GMT_READ_NORMAL". Also need to fix the W505 doc-line-too-long lint error before merging.

[weiji14]

Ah ok then, then the GMT_READ_NORMAL default here makes sense. Maybe good to mention it in the docstring.