pyarrow: Check compatibility of pyarrow.array with string type

[weiji14]

Description of proposed changes

Check that pyarrow.array objects of string type can be passed to PyGMT modules/functions.

This PR also adds type hints to the docstring of the pygmt.Figure.text's text parameter.

Preview at https://pygmt-dev--2933.org.readthedocs.build/en/2933/api/generated/pygmt.Figure.text.html

TODO:

• Initial compatibility check of pyarrow.array by adding parametrized tests to pygmt.text
• Add parametrized test to test_clib_virtualfile_from_vectors.py
• Check that pa.StringArray can be passed into pygmt.Figure.text

Addresses #2800 (comment), part of #2800.

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

[weiji14]

Need to figure out how to fix the mypy type errors for an optional import 🤔

pygmt/clib/conversion.py:298: error: Item "Sequence[str]" of "Sequence[str] | Any" has no attribute "to_pylist"  [union-attr]
pygmt/clib/session.py:1004: error: Item "Sequence[str]" of "Sequence[str] | Any" has no attribute "dtype"  [union-attr]

[codspeed-hq]

CodSpeed Performance Report

Merging #2933 will not alter performance

_{Comparing pyarrow/string (ccf4eff) with main (40edcf7)}

Summary

✅ 99 untouched benchmarks

🆕 8 new benchmarks
⁉️ 2 dropped benchmarks

⚠️ Please fix the performance issues or acknowledge them on CodSpeed.

Benchmarks breakdown

	Benchmark	main	pyarrow/string	Change
⁉️	test_put_strings	3.5 ms	N/A	N/A
🆕	test_put_strings[pyarrow]	N/A	3.5 ms	N/A
🆕	test_put_strings[str]	N/A	3.5 ms	N/A
🆕	test_virtualfile_from_vectors_one_string_or_object_column[object]	N/A	8.4 ms	N/A
🆕	test_virtualfile_from_vectors_one_string_or_object_column[pyarrow]	N/A	8.5 ms	N/A
🆕	test_virtualfile_from_vectors_one_string_or_object_column[str]	N/A	8.4 ms	N/A
⁉️	test_text_multiple_lines_of_text	14.2 ms	N/A	N/A
🆕	test_text_multiple_lines_of_text[list]	N/A	14.2 ms	N/A
🆕	test_text_multiple_lines_of_text[numpy]	N/A	14.2 ms	N/A
🆕	test_text_multiple_lines_of_text[pyarrow]	N/A	14.3 ms	N/A

[seisman]

With PR #3619 and #3608 merged, pyarrow arrays with string type now can be correctly converted to numpy string array. So, we don't need to add support of pyarrow arrays in the low-level functions like Session.put_strings. Changes in pygmt/_typing.py, pygmt/clib/conversion.py and pygmt/clib/session.py can be reverted, so that this PR only focuses on adding tests for pyarrow string arrays.

[seisman]

Also need to revert changes in this PR, since the low-level function Session.put_strings only accepts numpy.str_ and everything else should be converted to numpy.str_ by the _to_numpy function before calling put_strings.

[weiji14]

Ok, just to document things, the way we are intending pyarrow.string inputs to go through high-level modules like fig.text is:

1. pygmt.Figure.text -> clib.Session.virtualfile_in -> clib.Session.virtualfile_from_vectors
2. In clib.Session.virtualfile_from_vectors:
   • First call clib.conversion.vectors_to_arrays -> clib.conversion._to_numpy -> np.ascontiguous_array to convert pyarrow.string to np.str_
   • With a list[np.str_], this is then passed to clib.Session.put_strings

For the record, the original intention in this PR, mostly in commit d379e46, was to let clib.Session.put_strings handle both np.str_ and pyarrow.string.

[seisman]

The test was moved to test_clib_virtualfile_from_vectors in #3512.

[weiji14]

Moved in 6ad6eb9

[seisman]

A possible solution to avoid the complicated param is:

try:
    import pyarrow as pa
    pa_array = pa.array
except ImportError:
    pa_array = None

@pytest.mark.parametrize(
    ("array_func", "dtype"),
    [
        pytest.param(np.array, {"dtype": np.str_}, id="str"),
        pytest.param(np.array, {"dtype": np.object_}, id="object"),
        pytest.param(pa_array, {}, marks=skip_if_no(package="pyarrow"), id="pyarrow"),
    ]
)

[weiji14]

Done at 85d2bb5 8172102

[seisman]

It's likely that pytest-codspeed v3.0 breaks our Benchmark workflow. For comparison, see the CI job on the main branch yesterday (https://github.com/GenericMappingTools/pygmt/actions/runs/11830721578/job/32964716012) and this PR (https://github.com/GenericMappingTools/pygmt/actions/runs/11849193208/job/33022039738?pr=2933).

Edit: Will explore the issue in a separate PR.